📦 Biblioteca: Pacote

Gerencie módulos e carregamento de bibliotecas!

📦

O que é a biblioteca de pacote?

A biblioteca de pacote controla como módulos são carregados e encontrados. Ela gerencia o caminho de busca e o carregamento de bibliotecas Sol e nativas (DLL/SO).

💡 Dica: A tabela pacote está disponível globalmente. Não precisa importar!

Variáveis do Pacote

pacote.caminho

String com os caminhos de busca para módulos Sol (.sol).

Formato

Caminhos separados por ; com ? sendo substituído pelo nome do módulo.

Exemplo 
-- Ver caminho atual
exiba(pacote.caminho)
-- Saída: ./?.sol;./lib/?.sol;...

-- Adicionar novo caminho
pacote.caminho = pacote.caminho .. ";./meus_modulos/?.sol"

-- Agora importe("utils") procura em:
-- ./utils.sol
-- ./lib/utils.sol
-- ./meus_modulos/utils.sol

pacote.caminho_c

String com os caminhos de busca para bibliotecas nativas (.dll no Windows, .so no Linux).

Exemplo 
-- Verificar se existe
se obtenha_tipo(pacote.caminho_c) ~= "texto" então
    pacote.caminho_c = ""
fim

-- Adicionar caminho para DLLs
pacote.caminho_c = pacote.caminho_c .. ";./libs/?.dll"

pacote.carregados

Tabela com todos os módulos já carregados. Chave = nome do módulo, valor = módulo retornado.

Uso

Verificar se um módulo já foi carregado ou forçar recarregamento.

Exemplo 
-- Verificar se módulo está carregado
se pacote.carregados["meu_modulo"] então
    exiba("Módulo já carregado!")
fim

-- Forçar recarregamento
pacote.carregados["meu_modulo"] = nulo
local m = importe("meu_modulo")  -- Carrega novamente

pacote.precarga

Tabela de módulos pré-carregados. Permite registrar módulos sem arquivos físicos.

Exemplo 
-- Registrar módulo virtual
pacote.precarga["meu_modulo"] = função()
    local M = {}
    função M.saudacao(nome)
        retorne "Olá, " .. nome
    fim
    retorne M
fim

-- Agora pode importar normalmente
local meu = importe("meu_modulo")
exiba(meu.saudacao("Maria"))  -- Olá, Maria

pacote.buscadores

Tabela com funções que procuram módulos. A ordem define a prioridade de busca.

Buscadores padrão
  1. preload - Busca em pacote.precarga
  2. Sol - Busca arquivos .sol usando pacote.caminho
  3. C - Busca bibliotecas nativas usando pacote.caminho_c
  4. C root - Busca submódulos em bibliotecas C
Exemplo: Buscador personalizado 
-- Adicionar buscador customizado
tabela.insira(pacote.buscadores, 2, função(nome)
    se nome == "especial" então
        retorne função()
            retorne {versao = "1.0"}
        fim
    fim
fim)

pacote.config

String com informações de configuração do sistema, separadas por linhas.

Conteúdo
  1. Separador de diretório (\ Windows, / Unix)
  2. Separador de caminhos (;)
  3. Marcador de substituição (?)
  4. Diretório do executável
  5. Marcador de ignorar

Funções do Pacote

importe (nome_modulo)

Carrega e retorna um módulo. Se já carregado, retorna do cache.

Parâmetros
  • nome_modulo: Texto - Nome do módulo (use . para submódulos).
Retorno

O módulo carregado (geralmente uma tabela) e dados do carregador.

Exemplo 
-- Importar biblioteca padrão
local texto = importe("texto")
local matematica = importe("matemática")

-- Importar módulo local
local utils = importe("lib.utils")

-- Importar submódulo
local json = importe("dependencias.json.parser")

pacote.carregue_biblioteca (caminho, funcao_init)

Carrega uma biblioteca nativa (DLL/SO) manualmente.

Parâmetros
  • caminho: Texto - Caminho completo da biblioteca.
  • funcao_init: Texto - Nome da função de inicialização (ex: solopen_meumodulo).
Retorno

Função de inicialização ou falha, mensagem de erro, e onde falhou.

Exemplo 
local f, erro = pacote.carregue_biblioteca("./libs/http.dll", "solopen_http")
se f então
    local modulo = f()  -- Inicializa o módulo
fim

se não f então
    exiba("Erro:", erro)
fim

pacote.busque_caminho (nome, caminho, [separador], [separador_dir])

Busca um arquivo usando um template de caminho.

Parâmetros
  • nome: Texto - Nome do módulo.
  • caminho: Texto - Template de busca (com ?).
  • separador: Texto (opcional) - Caractere que separa partes do nome (padrão: .).
  • separador_dir: Texto (opcional) - Separador de diretórios (padrão: sistema).
Retorno

Caminho do arquivo encontrado ou nulo e mensagem de erro.

Exemplo 
local arquivo = pacote.busque_caminho("utils", "./?.sol;./lib/?.sol")
se arquivo então
    exiba("Encontrado:", arquivo)
fim

se não arquivo então
    exiba("Não encontrado")
fim

Como funciona a busca de módulos

Quando você chama importe("modulo"), Sol faz:

  1. Verifica cache - Se pacote.carregados["modulo"] existe, retorna ele.
  2. Executa buscadores - Chama cada função em pacote.buscadores até encontrar.
  3. Carrega e executa - Executa o arquivo/função encontrado.
  4. Armazena no cache - Guarda em pacote.carregados.

Conversão de nomes

Nome do MóduloArquivo .solArquivo .dll
"utils"./utils.sol./utils.dll
"lib.utils"./lib/utils.sol./lib/utils.dll
"a.b.c"./a/b/c.sol./a/b/c.dll

Criando um módulo

-- meu_modulo.sol
local M = {}  -- Tabela do módulo

-- Funções públicas
função M.saudacao(nome)
    retorne "Olá, " .. nome
fim

-- Constantes
M.VERSAO = "1.0.0"

-- Retornar módulo
retorne M
-- Usando o módulo
local meu = importe("meu_modulo")
exiba(meu.saudacao("Maria"))  -- "Olá, Maria"
exiba(meu.VERSAO)  -- "1.0.0"

Erros comuns

module not found
O módulo não foi encontrado nos caminhos configurados. Verifique pacote.caminho.
loop or previous error loading module
Importação circular detectada (A importa B, B importa A). Reorganize o código.
A biblioteca de pacote torna fácil organizar e distribuir código em módulos reutilizáveis!
Próximo: Depuração
```