🐛 Biblioteca: Depuração

Ferramentas para inspecionar e depurar seu código!

🐛

O que é depuração?

A biblioteca de depuração permite inspecionar o estado do programa, pilha de chamadas, variáveis locais, etc. Essencial para encontrar bugs e entender como o código funciona.

💡 Dica: Importe com local dep = importe("depuração")

Funções Disponíveis

entre_depuração ()

Entra no modo de depuração interativo. Permite executar comandos Sol diretamente.

Uso

Digite comandos e pressione Enter. Digite cont para continuar a execução.

Exemplo

depuração.entre_depuração()  -- Abre o prompt interativo

obtenha_informação (filamento, função_ou_nível, [opções])

Retorna uma tabela com informações sobre uma função ou nível da pilha de chamadas.

Parâmetros

filamento: Filamento (opcional) - O filamento a inspecionar.
função_ou_nível: Função ou Inteiro - Função ou nível da pilha (1 = função atual).
opções: Texto (opcional) - Quais informações retornar:
- "f" - Inclui a função
- "l" - Linha atual
- "n" - Nome da função
- "S" - Fonte (arquivo)
- "t" - Tail call
- "u" - Upvalues
- "L" - Linhas ativas

Retorno

Tabela com campos: source, short_src, linedefined, lastlinedefined, what, currentline, name, namewhat, nups, nparams, isvararg, etc.

Exemplo

função teste()
    local info = depuração.obtenha_informação(1, "Sln")
    exiba("Função:", info.name)
    exiba("Linha:", info.currentline)
    exiba("Arquivo:", info.short_src)
fim
teste()

obtenha_local (filamento, nível, índice)

Retorna o nome e valor de uma variável local em um nível específico da pilha.

Parâmetros

filamento: Filamento (opcional) - O filamento a inspecionar.
nível: Inteiro - Nível da pilha (1 = função atual).
índice: Inteiro - Índice da variável local (começa em 1).

Retorno

Nome (texto) e valor da variável, ou nulo se não existir.

Exemplo

função teste()
    local x = 42
    local nome, valor = depuração.obtenha_local(1, 1)
    exiba(nome, "=", valor)  -- x = 42
fim
teste()

defina_local (filamento, nível, índice, valor)

Define o valor de uma variável local em um nível específico da pilha.

Parâmetros

filamento: Filamento (opcional) - O filamento a modificar.
nível: Inteiro - Nível da pilha.
índice: Inteiro - Índice da variável local.
valor: Qualquer - Novo valor para a variável.

Retorno

Nome da variável ou nulo se não existir.

obtenha_valor_acima (função, índice)

Retorna o nome e valor de um upvalue (variável capturada) de uma função.

Parâmetros

função: Função - A função a inspecionar.
índice: Inteiro - Índice do upvalue (começa em 1).

Retorno

Nome e valor do upvalue, ou nulo se não existir.

Exemplo

local x = 10
local f = função() retorne x fim

local nome, valor = depuração.obtenha_valor_acima(f, 1)
exiba(nome, "=", valor)  -- x = 10

defina_valor_acima (função, índice, valor)

Define o valor de um upvalue de uma função.

Parâmetros

função: Função - A função a modificar.
índice: Inteiro - Índice do upvalue.
valor: Qualquer - Novo valor.

obtenha_metatabela (valor)

Retorna a metatabela de qualquer valor, mesmo se protegida.

Parâmetros

valor: Qualquer - O valor a inspecionar.

Retorno

Metatabela ou nulo.

Exemplo

local t = {}
defina_metatabela(t, {__índice = {}})
local mt = depuração.obtenha_metatabela(t)
exiba(mt)  -- Mostra a metatabela

defina_metatabela (valor, metatabela)

Define a metatabela de qualquer valor.

Parâmetros

valor: Qualquer - O valor a modificar.
metatabela: Tabela/Nulo - A nova metatabela.

Retorno

O próprio valor.

obtenha_registro ()

Retorna a tabela de registro (registry) do interpretador Sol.

Retorno

Tabela de registro.

obtenha_rastreio ([filamento], [mensagem], [nível])

Gera uma string de rastreamento de pilha (stack trace).

Parâmetros

filamento: Filamento (opcional) - O filamento a rastrear.
mensagem: Texto (opcional) - Mensagem a prefixar.
nível: Inteiro (opcional) - Nível inicial do rastreamento.

Retorno

Texto com o rastreamento da pilha.

Exemplo

função a() retorne b() fim
função b() retorne c() fim
função c() retorne depuração.obtenha_rastreio("Erro!", 1) fim

exiba(a())
-- Saída:
-- Erro!
-- stack traceback:
--     [string "..."]:3: in function 'c'
--     [string "..."]:2: in function 'b'
--     [string "..."]:1: in function 'a'

defina_gancho ([filamento], gancho, máscara, [contagem])

Define uma função de gancho (hook) para depuração.

Parâmetros

filamento: Filamento (opcional) - O filamento a monitorar.
gancho: Função - Função chamada em cada evento.
máscara: Texto - Eventos a monitorar:
- "c" - Chamadas de função
- "r" - Retornos de função
- "l" - Novas linhas
contagem: Inteiro (opcional) - Chamar a cada N instruções.

Exemplo

depuração.defina_gancho(função(evento, linha)
    exiba("Evento:", evento, "Linha:", linha)
fim, "l")

-- Cada linha executada mostrará uma mensagem

obtenha_gancho ([filamento])

Retorna as configurações atuais do gancho de depuração.

Retorno

Três valores: função de gancho, máscara (texto), contagem.

obtenha_valor_usuário (userdata, [índice])

Retorna o valor de usuário associado a um userdata.

defina_valor_usuário (userdata, valor, [índice])

Define o valor de usuário associado a um userdata.

id_valor_acima (função, índice)

Retorna um identificador único para um upvalue.

junte_valor_acima (f1, n1, f2, n2)

Faz com que o upvalue n1 da função f1 compartilhe o mesmo valor que o upvalue n2 da função f2.

Tabela Resumo

Função	Descrição
`entre_depuração`	Modo interativo de depuração
`obtenha_informação`	Informações sobre função/pilha
`obtenha_local`	Nome e valor de variável local
`defina_local`	Modifica variável local
`obtenha_valor_acima`	Nome e valor de upvalue
`defina_valor_acima`	Modifica upvalue
`obtenha_metatabela`	Metatabela de qualquer valor
`defina_metatabela`	Define metatabela
`obtenha_registro`	Tabela de registro
`obtenha_rastreio`	Stack trace
`defina_gancho`	Define hook de depuração
`obtenha_gancho`	Configurações do hook
`obtenha_valor_usuário`	Valor de userdata
`defina_valor_usuário`	Define valor de userdata
`id_valor_acima`	ID único de upvalue
`junte_valor_acima`	Compartilha upvalues

Use a biblioteca de depuração apenas durante desenvolvimento. Ela pode tornar o código mais lento e não é segura para uso em produção.

Com depuração, você pode entender exatamente o que seu código está fazendo!

Próximo: Corrotinas