Manual de Referncia de Lua 5.

2
por Roberto Ierusalimschy, Luiz Henrique de Figueiredo, Waldemar Celes
(traduzido por Srgio Queiroz de Medeiros)
Copyright 2014 Lua.org, PUC-Rio. Disponvel livremente nos termos da licena de Lua.
1 Introduo
Lua uma linguagem de programao de extenso projetada para dar suporte programao
procedimental em geral com facilidades para a descrio de dados. Ela tambm oferece um bom
suporte para programao orientada a objetos, programao funcional, e programao
orientada a dados. Lua planejada para ser usada como uma linguagem de script poderosa,
leve, e embarcvel por qualquer programa que necessite de uma. Lua implementada como
uma biblioteca, escrita em C puro, o subconjunto comum de C Padro e C++.
Por ser uma linguagem de extenso, Lua no possui a noo de um programa "principal": ela
somente funciona embarcada em um cliente hospedeiro, chamado de programa embarcante ou
simplesmente de hospedeiro. O programa hospedeiro pode invocar funes para executar um
pedao de cdigo Lua, pode escrever e ler variveis Lua, e pode registrar funes C para serem
chamadas por cdigo Lua. Atravs do uso de funes C, Lua pode ser aumentada para lidar com
uma variedade ampla de domnios diferentes, criando assim linguagens de programao
personalizadas que compartilham um arcabouo sinttico. A distribuio Lua inclui um exemplo
de um programa hospedeiro chamado lua, o qual usa a biblioteca Lua para oferecer um
interpretador Lua de linha de comando completo, para uso interativo ou em lote.
Lua software livre, e fornecido como de praxe sem garantias, como dito em sua licena. A
implementao descrita neste manual est disponvel no site oficial de Lua, www.lua.org.
Como qualquer outro manual de referncia, este documento seco em algumas partes. Para
uma discusso das decises por trs do projeto de Lua, veja os artigos tcnicos disponveis no
site de Lua. Para uma introduo detalhada programao em Lua, veja o livro de Roberto
Ierusalimschy, Programming in Lua).
2 Conceitos Bsicos
Esta seo descreve os conceitos bsicos da linguagem.
2.1 Valores e Tipos
Lua uma linguagem dinamicamente tipada. Isso significa que variveis no possuem tipos;
somente valores possuem tipos. No h definies de tipo na linguagem. Todos os valores
carregam o seu prprio tipo.
Todos os valores em Lua so valores de primeira classe. Isso significa que todos os valores
podem ser guardados em variveis, passados como argumentos para outras funes, e
retornados como resultados.
H oito tipos bsicos em Lua: nil, boolean, number, string, function, userdata, thread, e table.
Nil o tipo do valor nil, cuja propriedade principal ser diferente de qualquer outro valor; ele
geralmente representa a ausncia de um valor til. Boolean o tipo dos valores false e true.
Tanto nil como false tornam uma condio falsa; qualquer outro valor a torna
verdadeira. Number representa tanto nmeros inteiros como nmeros reais (ponto flutuante de
preciso dupla). String representa sequncias imutveis de bytes. Lua 8 bits pura: cadeias
podem conter qualquer valor de 8 bits, incluindo zeros ('\0') dentro delas.
Lua pode chamar (e manipular) funes escritas em Lua e funes escritas em C (veja 3.4.9).
O tipo userdata oferecido para permitir que dados C arbitrrios sejam guardados em variveis
Lua. Um valor userdata um ponteiro para um bloco de memria bruta. H dois tipos de
userdata: userdata completo, onde o bloco de memria gerenciado por Lua, e userdata leve,
onde o bloco de memria gerenciado pelo hospedeiro. Userdata no possui operaes pr-
definidas em Lua, exceto atribuio e teste de identidade. Atravs do uso de metatabelas, o
programador pode definir operaes para valores userdata completos (veja 2.4). Valores
userdata no podem ser criados ou modificados em Lua, somente atravs da API C. Isso garante
a integridade de dados que pertencem ao programa hospedeiro.
O tipo thread representa fluxos de execuo independentes e usado para implementar co-
rotinas (veja 2.6). No confunda fluxos de execuo Lua com processos leves do sistema
operacional. Lua d suporte a co-rotinas em todos os sistemas, at mesmo naqueles que no
do suporte a processos leves.
O tipo table implementa arrays associativos, isto , arrays que podem ser indexados no apenas
com nmeros, mas com qualquer valor Lua exceto nil e NaN (Not a Number, um valor numrico
especial usado para representar resultados indefinidos ou no representveis, tais como 0/0).
Tabelas podem ser heterogneas; isto , elas podem conter valores de todos os tipos
(exceto nil). Qualquer chave com valor nil no considerada parte da tabela. De modo
recproco, qualquer chave que no parte da tabela possui um valor nil associado. Tabelas so o
nico mecanismo de estruturao de dados em Lua; elas podem ser usadas para representar
arrays comuns, sequncias, tabelas de smbolos, conjuntos, registros, grafos, rvores, etc. Para
representar registros, Lua usa o nome do campo como um ndice. A linguagem d suporte a essa
representao fornecendo a.nome como acar sinttico para a["nome"]. H vrias maneiras
convenientes para criar tabelas em Lua (veja 3.4.8).
Usamos o termo sequncia para denotar uma tabela onde o conjunto de todas as chaves
numricas positivas igual a {1..} para algum inteiro n, que chamado o comprimento da
sequncia (veja 3.4.6).
Assim como os ndices, os valores dos campos de uma tabela podem ser de qualquer tipo. Em
particular, por causa que funes so valores de primeira classe, campos de tabela podem
conter funes. Portanto, tabelas podem tambm conter mtodos (veja 3.4.10).
A indexao de tabelas segue a definio de igualdade primitiva na linguagem. As
expresses a[i] e a[j] denotam o mesmo elemento da tabela se e somente se i e j so iguais
primitivos (isto , iguais sem metamtodos).
Valores do tipo table, function, thread, e userdata (completo) so objetos: variveis
no contm realmente esses valores, somente referncias para eles. Atribuio, passagem de
parmetro, e retornos de funo sempre manipulam referncias para tais valores; essas
operaes no implicam em qualquer espcie de cpia.
A funo da biblioteca type retorna uma cadeia descrevendo o tipo de um dado valor (veja 6.1).
2.2 Ambientes e o Ambiente Global
Como ser discutido em 3.2 e 3.3.3, qualquer referncia a um nome global var
sintaticamente traduzido para _ENV.var. Alm disso, todo trecho compilado no escopo de uma
varivel local externa chamada _ENV (veja 3.3.2), ento o prprio _ENV nunca um nome
global em um trecho.
Apesar da existncia dessa varivel _ENV externa e da traduo de nomes globais, _ENV um
nome completamente normal. Em particular, voc pode definir novas variveis e parmetros
com esse nome. Cada referncia a um nome global usa a _ENV que visvel naquele ponto do
programa, seguindo as regras de visibilidade usuais de Lua (veja 3.5).
Qualquer tabela usada como o valor de _ENV chamada de um ambiente.
Lua mantm um ambiente distinto chamado de o ambiente global. Esse valor mantido em um
ndice especial no registro C (veja 4.5). Em Lua, a varivel _G inicializada com esse mesmo
valor.
Quando Lua compila um trecho, ela inicializa o valor de seu upvalue _ENV com o ambiente global
(veja load). Assim, por padro, variveis globais em cdigo Lua se referem a entradas no
ambiente global. Alm disso, todas as bibliotecas padro so carregadas no ambiente global e
vrias funes so operadas nesse ambiente. Voc pode usar load (ou loadfile) para carregar um
trecho com um ambiente diferente. (Em C, voc pode carregar o trecho e ento mudar o valor
de seu primeiro upvalue.)
Se voc mudar o ambiente global no registro (atravs de cdigo C ou da biblioteca de
depurao), todos os trechos carregados aps a mudana tero o novo ambiente. Trechos
carregados anteriormente no so afetados, contudo, uma vez que cada um tem sua prpria
referncia para o ambiente na sua varivel _ENV. Alm disso, a varivel _G (que guardada no
ambiente global original) nunca atualizada por Lua.
2.3 Tratamento de Erros
Por conta que Lua uma linguagem embarcada, todas as aes de Lua comeam a partir de
cdigo C no programa hospedeiro chamando uma funo da biblioteca de Lua (veja lua_pcall).
Sempre que um erro ocorre durante a compilao ou execuo de um trecho Lua, o controle
retorna para o programa hospedeiro, que pode tomar as medidas apropriadas (tais como
imprimir uma mensagem de erro).
Cdigo Lua pode explicitamente gerar um erro atravs de um chamada funo error. Se voc
precisa capturar erros em Lua, voc pode usar pcall ou xpcall para chamar uma dada funo
em modo protegido. Sempre que h um erro, um objeto de erro (tambm chamado de
uma mensagem de erro) propagado com informao a respeito do erro. Lua em si somente
gera erros onde o objeto de erro uma cadeia, mas programas podem gerar erros com qualquer
valor para o objeto de erro.
Quando voc usa xpcall ou lua_pcall, voc pode fornecer um tratador de mensagens para ser
chamado em caso de erros. Essa funo chamada com a mensagem de erro original e retorna
uma nova mensagem de erro. Ela chamada antes que o erro desenrole a pilha, de modo que
ela pode colher mais informao sobre o erro, por exemplo atravs da inspeo da pilha e da
criao de um trao (traceback) da pilha. Esse tratador de mensagens ainda protegido por
uma chamada protegida; assim, um erro dentro do tratador de mensagens chamar o tratador
de mensagens novamente. Se esse lao continua, Lua o interrompe e retorna uma mensagem de
erro apropriada.
2.4 Metatabelas e Metamtodos
Todo valor em Lua pode ter uma metatabela. Essa metatabela uma tabela Lua comum que
define o comportamento do valor original sob certas operaes especiais. Voc pode mudar
vrios aspectos do comportamento de operaes sobre um valor especificando campos
especficos em sua metatabela. Por exemplo, quando um valor no numrico o operando de
uma adio, Lua verifica se h uma funo no campo "__add" da metatabela do valor. Se ela
acha uma, Lua chama essa funo para realizar a adio.
As chaves em uma metatabela so derivadas a partir dos nomes dos eventos; os valores
correspondentes so chamados de metamtodos. No exemplo anterior, o evento "add" e o
metamtodo a funo que realiza a adio.
Voc pode consultar a metatabela de qualquer valor usando a funo getmetatable.
Voc pode substituir a metatabela de tabelas usando a funo setmetatable. Voc no pode
mudar a metatabela de outros tipos a partir de Lua (exceto usando a biblioteca de depurao);
voc deve usar a API C para isso.
Tabelas e userdatas completos tm metatabelas individuais (embora mltiplas tabelas e
userdatas possam compartilhar suas metatabelas). Valores de todos os outros tipos
compartilham uma nica metatabela por tipo; isto , h uma nica metatabela para todos os
nmeros, uma para todas as cadeias, etc. Por padro, um valor no possui metatabela, mas a
biblioteca de cadeias especifica uma metatabela para o tipo string (veja 6.4).
Uma metatabela controla como um objeto se comporta em operaes aritmticas, comparaes
de ordem, concatenao, operao de comprimento, e indexao. Uma metatabela tambm
pode definir uma funo a ser chamada quando um userdata ou uma tabela so recolhidos pelo
coletor de lixo. Quando Lua realiza uma dessas operaes sobre um valor, ela verifica se esse
valor possui uma metatabela com um evento correspondente. Se possui, o valor associado com
aquela chave (o metamtodo) controla como Lua realizar a operao.
Metatabelas controlam as operaes listadas a seguir. Cada operao identificada por seu
nome correspondente. A chave para cada operao uma cadeia com seu nome precedido por
dois sublinhados, '__'; por exemplo, a chave para a operao "add" a cadeia "__add".
A semntica dessas operaes melhor explicada por uma funo Lua descrevendo como o
interpretador executa a operao. O cdigo mostrado aqui em Lua somente ilustrativo; o
comportamento real est codificado no interpretador e muito mais eficiente do que esta
simulao. Todas as funes usadas nestas descries (rawget, tonumber, etc.) so descritas
em 6.1. Em particular, para recuperar o metamtodo de um dado objeto, usamos a expresso
metatabela(obj)[evento]
Isso deve ser lido como
rawget(getmetatable(obj) or {}, evento)
Isso significa que o acesso a um metamtodo no invoca outros metamtodos, e o acesso a
objetos que no possuem metatabelas no falha (ele simplesmente resulta em nil).
Para os operadores unrios - e #, o metamtodo chamado com um segundo
argumento dummy. Esse argumento extra somente para simplificar a implementao de Lua;
ele pode ser removido em verses futuros e portanto no est presente no cdigo a seguir. (Para
a maioria dos usos esse argumento extra irrelevante.)
"add": a + operao.
A funo getbinhandler abaixo define como Lua escolhe o tratador para uma operao
binria. Primeiro, Lua tenta o primeiro operando. Se seu tipo no define o tratador para a
operao, ento Lua tenta o segundo operando.
function getbinhandler (op1, op2, evento)
return metatable(op1)[evento] or metatable(op2)[evento]
end
Usando essa funo, o comportamento da op1 + op2
function add_event (op1, op2)
local o1, o2 = tonumber(op1), tonumber(op2)
 if o1 and o2 then -- os dois operandos so numricos?
return o1 + o2 -- '+' aqui a 'add' primitiva
else -- pelo menos um dos operandos no numrico
local h = getbinhandler(op1, op2, "__add")
if h then
-- chama o tratador com ambos os operandos
return (h(op1, op2))
else -- nenhum tratador disponvel: comportamento padro
error()
end
end
end
"sub": a operao -. Comportamento similar ao da operao "add".
"mul": a operao *. Comportamento similar ao da operao "add".
"div": a operao /. Comportamento similar ao da operao "add".
"mod": a operao %. Comportamento similar ao da operao "add", com a operao o1
- floor(o1/o2)*o2 como a operao primitiva.
"pow": a operao ^ (exponenciao). Comportamento similar ao da operao "add",
com a funo pow (da biblioteca matemtica de C) como operao primitiva.
"unm": a operao - unria.
function unm_event (op)
local o = tonumber(op)
if o then -- operando numrico?
return -o -- '-' aqui a 'unm' primitiva
else -- o operando no numrico
-- Tenta obter um tratador a partir do operando
local h = metatable(op).__unm
if h then
-- chama o tratador com o operando
return (h(op))
else -- nenhum tratador disponvel: comportamento padro
error()
end
end
end
"concat": a operao .. (concatenao).
function concat_event (op1, op2)
if (type(op1) == "string" or type(op1) == "number") and
(type(op2) == "string" or type(op2) == "number") then
return op1 .. op2 -- concatenao primitiva de cadeias
else
local h = getbinhandler(op1, op2, "__concat")
if h then
return (h(op1, op2))
else
error()
end
end
end
"len": a operao #.
function len_event (op)
if type(op) == "string" then
return strlen(op) -- comprimento de cadeias primitivo
 else
local h = metatable(op).__len
if h then
return (h(op)) -- chama tratador com o operando
elseif type(op) == "table" then
return #op -- comprimento de tabela primitivo
else -- nenhum tratador disponvel: erro
error()
end
end
end
Veja 3.4.6 para uma descrio do comprimento de uma tabela.
"eq": a operao ==. A funo getequalhandler define como Lua escolhe um
metamtodo para igualdade. Um metamtodo selecionado somente quando ambos os
valores sendo comparados possuem o mesmo tipo e o mesmo metamtodo para a
operao selecionada, e os valores so ou tabelas ou userdatas completos.
function getequalhandler (op1, op2)
if type(op1) ~= type(op2) or
(type(op1) ~= "table" and type(op1) ~= "userdata") then
return nil -- valores diferentes
end
local mm1 = metatable(op1).__eq
local mm2 = metatable(op2).__eq
if mm1 == mm2 then return mm1 else return nil end
end
O evento "eq" definido como a seguir:
function eq_event (op1, op2)
if op1 == op2 then -- igual primitivo?
return true -- valores so iguais
end
-- tenta metamtodo
local h = getequalhandler(op1, op2)
if h then
return not not h(op1, op2)
else
return false
end
end
Note que o resultado sempre um booleano.
"lt": a operao <.
function lt_event (op1, op2)
if type(op1) == "number" and type(op2) == "number" then
return op1 < op2 -- comparao numrica
elseif type(op1) == "string" and type(op2) == "string" then
return op1 < op2 -- comparao lexicogrfica
else
local h = getbinhandler(op1, op2, "__lt")
if h then
return not not h(op1, op2)
else
error()
end
end
 end
Note que o resultado sempre um booleano.
"le": a operao <=.
function le_event (op1, op2)
if type(op1) == "number" and type(op2) == "number" then
return op1 <= op2 -- comparao numrica
elseif type(op1) == "string" and type(op2) == "string" then
return op1 <= op2 -- comparao lexicogrfica
else
local h = getbinhandler(op1, op2, "__le")
if h then
return not not h(op1, op2)
else
h = getbinhandler(op1, op2, "__lt")
if h then
return not h(op2, op1)
else
error()
end
end
end
end
Note que, na ausncia de um metamtodo "le", Lua tenta o "lt", assumindo que a <= b
equivalente a not (b < a).
Como com os outros operadores de comparao, o resultado sempre um booleano.
"index": A indexao de acesso table[key]. Note que o metamtodo tentado somente
quando key no est presente em table. (Quando tableno uma tabela, nunca uma
chave est presente, ento o metamtodo sempre tentado.)
function gettable_event (table, key)
local h
if type(table) == "table" then
local v = rawget(table, key)
-- se a chave est, retorna o valor primitivo
if v ~= nil then return v end
h = metatable(table).__index
if h == nil then return nil end
else
h = metatable(table).__index
if h == nil then
error()
end
end
if type(h) == "function" then
return (h(table, key)) -- chama o tratador
else return h[key] -- ou repete a operao sobre ele
end
end
"newindex": A indexao de atribuio table[key] = value. Note que o metamtodo
tentado somente quando key no est presente em table.
function settable_event (table, key, value)
local h
if type(table) == "table" then
local v = rawget(table, key)
 -- se a chave est presente, faz a atribuio primitiva
if v ~= nil then rawset(table, key, value); return end
h = metatable(table).__newindex
if h == nil then rawset(table, key, value); return end
else
h = metatable(table).__newindex
if h == nil then
error()
end
end
if type(h) == "function" then
h(table, key,value) -- chama o tratador
else h[key] = value -- ou repete a operao sobre ele
end
end
"call": chamada quando Lua chama um valor.
function function_event (func, ...)
if type(func) == "function" then
return func(...) -- chamada primitiva
else
local h = metatable(func).__call
if h then
return h(func, ...)
else
error()
end
end
end
2.5 Coleta de Lixo
Lua realiza gerenciamento automtico de memria. Isso significa que voc no precisa se
preocupar com a alocao de memria para novos objetos nem com a liberao dela quando os
objetos no so mais necessrios. Lua gerencia memria automaticamente executando
um coletor de lixo para coletar todos os objetos mortos (isto , objetos que no so mais
acessveis a partir de Lua). Toda memria usada por Lua est sujeita ao gerenciamento
automtico: cadeias, tabelas, userdatas, funes, fluxos de execuo, estruturas internas, etc.
Lua implementa um coletor marca-e-varre (mark-and-sweep) incremental. Ele usa dois nmeros
para controlar seus ciclos de coleta de lixo: a pausa do coletor de lixo e o multiplicador de passo
do coletor de lixo. Ambos usam pontos percentuais como unidades (e.g., um valor de 100
significa um valor interno de 1).
A pausa do coletor de lixo controla quanto tempo o coletor espera antes de comear um novo
ciclo. Valores maiores fazem o coletor ser menos agressivo. Valores menores do que 100
significam que o coletor no esperar para iniciar um novo ciclo. Um valor de 200 significa que o
coletor espera a memria total em uso dobrar antes de iniciar um novo ciclo.
O multiplicador de passo do coletor de lixo controla a velocidade relativa do coletor em relao
alocao de memria. Valores maiores fazem o coletor ser mais agressivo mas tambm
aumentam o tamanho de cada passo incremental. Valores menores do que 100 tornam o coletor
muito lento e podem fazer com que o coletor nunca termine um ciclo. O padro 200, o que
significa que o coletor executa no "dobro" da velocidade de alocao de memria.
Se voc atribuir ao multiplicador de passo um nmero muito grande (maior do que 10% do
nmero mximo de bytes que o programa pode usar), o coletor se comporta como um coletor
pare-o-mundo. Se voc ento atribuir 200 pausa, o coletor se comporta como em verses
antigas de Lua, fazendo uma coleta completa toda vez que Lua dobra sua memria em uso.
Voc pode mudar esses nmeros chamando lua_gc em C ou collectgarbage em Lua. Voc pode
tambm usar essas funes para controlar o coletor diretamente (e.g., par-lo e reinici-lo).
Como uma caracterstica experimental em Lua 5.2, voc pode mudar o modo de operao do
coletor de incremental para generacional. Um coletor generacional assume que a maioria dos
objetos morre jovem, e portanto ele percorre somente objetos jovens (criados recentemente).
Esse comportamento pode reduzir o tempo usado pelo coletor, mas tambm incrementa o uso
de memria (visto que objetos mortos velhos podem se acumular). Para mitigar esse segundo
problema, de tempos em tempos o coletor generacional realiza uma coleta completa. Lembre-se
que essa uma caracterstica experimental; voc bem-vindo a experiment-la, mas verifique
seus ganhos.
2.5.1 Metamtodos de Coleta de Lixo
Voc pode especificar metamtodos do coletor de lixo para tabelas e, usando a API C, para
userdatas completos (veja 2.4). Esses metamtodos so tambm chamados finalizadores.
Finalizadores permitem voc coordenar a coleta de lixo de Lua com o gerenciamento de recursos
externos (tais como o fechamento de arquivos, conexes de rede ou de banco de dados, ou a
liberao de sua prpria memria). Para um objeto (tabela ou userdata) ser finalizada quando
coletada, voc deve marc-la para finalizao. Voc marca um objeto para finalizao quando
voc especifica sua metatabela e a metatabela possui um campo indexado pela cadeia "__gc".
Note que se voc especificar uma metatabela sem um campo __gc e depois criar esse campo na
metatabela, o objeto no ser marcado para finalizao. Contudo, aps um objeto ser marcado,
voc pode livremente mudar o campo __gc de sua metatabela.
Quando um objeto marcado torna-se lixo, ele no coletado imediatamente pelo coletor de lixo.
Ao invs disso, Lua coloca-o em uma lista. Aps a coleta, Lua faz o equivalente da funo a
seguir para cada objeto nessa lista:
function gc_event (obj)
local h = metatable(obj).__gc
if type(h) == "function" then
h(obj)
end
end
Ao fim de cada ciclo de coleta de lixo, os finalizadores para os objetos so chamados na ordem
inversa em que eles foram marcados para coleta, entre aqueles coletados naquele ciclo; isto , o
primeiro finalizador a ser chamado o associado com o objeto marcado por ltimo no programa.
A execuo de cada finalizador pode ocorrer em qualquer ponto durante a execuo do cdigo
regular.
Por causa que os objetos sendo coletados devem ainda ser usados pelo finalizador, ele (e outros
objetos acessveis somente atravs dele) deve ser ressuscitado por Lua. Geralmente, essa
ressurreio passageira, e a memria do objeto liberada no prximo ciclo de coleta de lixo.
Contudo, se o finalizador guarda o objeto em alguma espao global (e.g., uma varivel global),
ento h uma ressurreio permanente. Em todo o caso, a memria do objeto liberada
somente quando ele se torna completamente inacessvel; seu finalizador nunca ser chamado
duas vezes.
Quando voc fecha um estado (veja lua_close), Lua chama os finalizadores de todos os objetos
marcados para finalizao, seguindo a ordem inversa em que eles foram marcados. Se qualquer
finalizador marca novos objetos para coleta durante essa fase, esses novos objetos no sero
finalizados.
2.5.2 Tabelas Fracas
Uma tabela fraca uma tabela cujos elementos so referncias fracas. Uma referncia fraca
ignorada pelo coletor de lixo. Em outras palavras, se as nicas referncias para um objeto so
referncias fracas, ento o coletor de lixo coletar esse objeto.
Uma tabela fraca pode ter chaves fracas, valores fracos, ou ambos. Uma tabela com chaves
fracas permite a coleta de suas chaves, mas impede a coleta de seus valores. Uma tabela com
chaves fracas e valores fracos permite a coleta tanto das chaves como dos valores. Em todo o
caso, se a chave ou o valor coletado, o par inteiro removido da tabela. A fragilidade de uma
tabela controlada pelo campo __mode de sua metatabela. Se o campo __mode uma cadeia
contendo o caractere 'k', as chaves na tabela so fracas. Se __mode contm 'v', os valores na
tabela so fracos.
Uma tabela com chaves fracas e valores fortes tambm chamada de uma tabela efmera. Em
uma tabela efmera, um valor considerado alcanvel somente se sua chave alcanvel. Em
particular, se a nica referncia para uma chave atravs desse valor, o par removido.
Qualquer mudana na fragilidade de uma tabela ter efeito somente no prximo ciclo de coleta.
Em particular, se voc mudar a fragilidade para um modo mais forte, Lua poder ainda coletar
alguns itens dessa tabela antes da mudana fazer efeito.
Somente objetos que possuem uma construo explcita so removidos de tabelas fracas.
Valores, tais como nmeros e funes C leves, no esto sujeitos coleta de lixo, e por isso no
so removidos de tabelas fracas (a menos que seu valor associado seja coletado). Embora
cadeias estejam sujeitas coleta de lixo, elas no possuem uma construo explcita, e por isso
no so removidas de tabelas fracas.
Objetos ressuscitados (isto , objetos sendo finalizados e objetos acessveis somente atravs de
objetos sendo finalizados) tm um comportamento especial em tabelas fracas. Eles so
removidos de valores fracos antes da execuo de seus finalizadores, mas so removidos de
chaves fracas somente na prxima coleta aps a execuo de seus finalizadores, quando tais
objetos so realmente liberados. Esse comportamento permite o finalizador acessar
propriedades associadas com o objeto atravs de tabelas fracas.
Se uma tabela fraca est entre os objetos ressuscitados em um ciclo de coleta, ela pode no ser
apropriadamente limpa at o prximo ciclo.
2.6 Co-rotinas
Lua oferece suporte a co-rotinas, tambm chamadas de fluxos de execuo mltiplos
colaborativos. Uma co-rotina em Lua representa um fluxo de execuo independente. Ao
contrrio de processos leves em sistemas que do suporte a mltiplos fluxos de execuo,
contudo, uma co-rotina somente suspende sua execuo atravs de uma chamada explcita a
uma funo de cesso.
Voc cria uma co-rotina chamando coroutine.create. Seu nico argumento uma funo que a
funo principal da co-rotina. A funo create somente cria uma nova co-rotina e retorna uma
referncia para ela (um objeto do tipo thread); ela no inicia a co-rotina.
Voc executa uma co-rotina chamando coroutine.resume. Quando voc
chama coroutine.resume pela primeira vez, passando como seu primeiro argumento um fluxo de
execuo retornado por coroutine.create, a co-rotina inicia sua execuo. na primeira linha de
sua funo principal. Argumentos extras passados para coroutine.resume so passados para a
funo principal da co-rotina. Aps a co-rotina comear sua execuo, ela executa at que
termine ou ceda.
Uma co-rotina pode terminar sua execuo de duas maneiras: normalmente, quando sua funo
principal retorna (explicitamente ou implicitamente, aps a ltima instruo); e anormalmente,
se h um erro no protegido. No primeiro caso, coroutine.resume retorna true, mais quaisquer
valores retornados pela funo principal da co-rotina. Em caso de
erros, coroutine.resume retorna false mais uma mensagem de erro.
Uma co-rotina cede chamando coroutine.yield. Quando uma co-rotina cede,
a coroutine.resume correspondente retorna imediatamente, mesmo se a cesso aconteceu
dentro de chamadas de funo aninhadas (isto , no na funo principal, mas em uma funo
diretamente ou indiretamente chamada pela funo principal). No caso de uma
cesso, coroutine.resume tambm retorna true, mais quaisquer valores passados
para coroutine.yield. Da prxima vez que voc reiniciar a mesma co-rotina, ela continua sua
execuo a partir do ponto onde ela cedeu, com a chamada a coroutine.yieldretornando
quaisquer argumentos extras passados para coroutine.resume.
Como coroutine.create, a funo coroutine.wrap tambm cria uma co-rotina, mas ao invs de
retornar a prpria co-rotina, ela retorna uma funo que, quando chamada, reinicia a co-rotina.
Quaisquer argumentos passados para essa funo vo como argumentos extras
para coroutine.resume.coroutine.wrap retorna todos os valores retornados por coroutine.resume,
exceto o primeiro (o cdigo booleano de erro). Ao contrrio
de coroutine.resume, coroutine.wrap no captura erros; qualquer erro propagado para o
chamador.
Como um exemplo de como co-rotinas funcionam, considere o seguinte cdigo:
function foo (a)
print("foo", a)
return coroutine.yield(2*a)
end

co = coroutine.create(function (a,b)
print("co-body", a, b)
local r = foo(a+1)
print("co-body", r)
local r, s = coroutine.yield(a+b, a-b)
 print("co-body", r, s)
return b, "end"
end)

print("main", coroutine.resume(co, 1, 10))

print("main", coroutine.resume(co, "r"))
print("main", coroutine.resume(co, "x", "y"))
print("main", coroutine.resume(co, "x", "y"))
Quando voc o executa, ele produz a seguinte sada:
co-body 1 10
foo 2
main true 4
co-body r
main true 11 -9
co-body x y
main true 10 end
main false cannot resume dead coroutine
Voc pode tambm criar e manipular co-rotinas atravs da API C: veja as
funes lua_newthread, lua_resume, e lua_yield.
3 A Linguagem
Esta seo descreve o lxico, a sintaxe, e a semntica de Lua. Em outras palavras, esta seo
descreve quais elementos lxicos so vlidos, como eles podem ser combinados, e o que suas
combinaes significam.
As construes da linguagem sero explicadas usando a notao BNF estendida usual, na qual
{a} significa 0 ou mais a's, e [a] significa um a opcional. No-terminais so mostrados como
no-terminal, palavras-chave so mostradas como kword, e outros smbolos terminais so
mostrados como =. A sintaxe completa de Lua pode ser encontrada em 9 no fim deste
manual.
3.1 Convenes Lxicas
Lua uma linguagem de formato livre. Ela ignora espaos (incluindo quebras de linha) e
comentrios entre elementos lxicos (tokens), exceto como delimitadores entre nomes e
palavras-chave.
Nomes (tambm chamados de identificadores) em Lua podem ser qualquer cadeia de letras,
dgitos, e sublinhados, que no iniciam com um dgito. Identificadores so usados para nomear
variveis, campos de tabelas, e rtulos.
As seguintes palavras-chave so reservadas e no podem ser usadas como nomes:
and break do else elseif end
false for function goto if in
local nil not or repeat return
then true until while
Lua uma linguagem que diferencia minsculas de maisculas: and uma palavra reservada,
mas And e AND so dois nomes vlidos diferentes. Como uma conveno, nomes comeando
com um sublinhado seguido por letras maisculas (tais como _VERSION) so reservados para
variveis usadas por Lua.
As seguintes cadeias denotam outros elementos lxicos:
+ - * / % ^ #
== ~= <= >= < > =
( ) { } [ ] ::
; : , . .. ...
Cadeias literais podem ser delimitadas por aspas simples ou duplas balanceadas, e podem
conter as seguintes sequncias de escape similares s de C: '\a' (campainha), '\b' (retrocesso),
'\f' (alimentao de formulrio), '\n' (quebra de linha), '\r' (retorno de carro), '\t' (tabulao
horizontal), '\v' (tabulao vertical), '\\' (barra invertida), '\"' (citao [aspa dupla]), e '\''
(apstrofo [aspa simples]). Uma barra invertida seguida por uma quebra de linha de verdade
resulta em uma quebra de linha na cadeia. A sequncia de escape '\z' pula a extenso seguinte
de caracteres de espao em branco, incluindo quebras de linha; ela particularmente til para
quebrar e identar uma cadeia de literais longa em mltiplas linhas sem adicionar as quebras de
linha e espaos ao contedo da cadeia.
Um byte em uma cadeia literal pode tambm ser especificado atravs de seu valor numrico.
Isso pode ser feito com a sequncia de escape \xXX, onde XX uma sequncia de exatamente
dois dgitos hexadecimais, ou com a sequncia de escape \ddd, onde ddd uma sequncia de
at trs dgitos decimais. (Note que se um escape decimal deve ser seguido por um dgito, ele
deve ser expresso usando exatamente trs dgitos.) Cadeias em Lua podem conter qualquer
valor de 8 bits, incluindo zeros dentro delas, os quais podem ser especificados como '\0'.
Cadeias literais podem tambm ser definidas usando um formato longo delimitado por colchetes
longos. Definimos um colchete longo de abertura de nvel ncomo um abre colchete seguido
por n sinais de igual seguidos por outro abre colchete. Assim, um abre colchete longo de nvel 0
escrito como [[, um abre colchete longo de nvel 1 escrito como [=[, e assim por diante.
Um colchete longo de fechamento definido similarmente; por exemplo, um colchete longo de
fechamento de nvel 4 escrito como ]====]. Um literal longo comea com um colchete longo
de abertura de qualquer nvel e termina no primeiro colchete longo de fechamento do mesmo
nvel. Ele pode conter qualquer texto exceto um colchete de fechamento do nvel apropriado.
Literais expressos dessa forma podem se estender por vrias linhas, no interpretam nenhuma
sequncia de escape, e ignoram colchetes longos de qualquer outro nvel. Qualquer tipo de
sequncia de fim de linha (retorno de carro, quebra de linha, retorno de carro seguido por
quebra de linha, ou quebra de linha seguida por retorno de carro) convertida em uma quebra
de linha simples.
Qualquer byte em uma cadeia literal que no afetada explicitamente pelas regras anteriores
representa ele mesmo. Contudo, Lua abre arquivos para parsing em modo texto, e as funes de
arquivo do sistema podem ter problemas com alguns caracteres de controle. Assim, mais
seguro representar dados no-textuais como um literal entre aspas com sequncias de escape
explcitas para caracteres no-textuais.
Por convenincia, quando o colchete longo de abertura imediatamente seguido por uma
quebra de linha, a quebra de linha no includa na cadeia. Como um exemplo, em um sistema
usando ASCII (no qual 'a' codificado como 97, a quebra de linha codificada como 10, e '1'
codificado como 49), as cinco cadeias literais a seguir denotam a mesma cadeia:
a = 'alo\n123"'
a = "alo\n123\""
a = '\97lo\10\04923"'
a = [[alo
123"]]
a = [==[
alo
123"]==]
Uma constante numrica pode ser escrita com um parte fracionria opcional e um expoente
decimal opcional, marcado por uma letra 'e' ou 'E'. Lua tambm aceita constantes hexadecimais,
as quais comeam com 0x ou 0X. Constantes hexadecimais tambm aceitam uma parte
fracionria opcional mais um expoente binrio opcional, marcado por uma letra 'p' ou 'P'.
Exemplos de contantes numricas vlidas so
3 3.0 3.1416 314.16e-2 0.31416E1
0xff 0x0.1E 0xA23p-4 0X1.921FB54442D18P+1
Um comentrio comea com um hfen duplo (--) em qualquer lugar fora de uma cadeia. Se o
texto imediatamente aps -- no um colchete longo de abertura, o comentrio
um comentrio curto, que se estende at o fim da linha. Caso contrrio, ele um comentrio
longo, que se estende at o colchete longo de fechamento correspondente. Comentrios longos
so frequentemente usados para desabilitar cdigo temporariamente.
3.2 Variveis
Variveis so lugares que guardam valores. H trs tipos de variveis em Lua: variveis globais,
variveis locais, e campos de tabelas.
Um nico nome pode denotar uma varivel global ou uma varivel local (ou um parmetro
formal de uma funo, que um tipo particular de varivel local):
var ::= Nome
Nome denota identificadores, como definido em 3.1.
Qualquer nome de varivel assumido ser global a menos que explicitamente declarado como
um local (veja 3.3.7). Variveis locais possuem escopo lxico: variveis locais podem ser
acessadas livremente por funes definidas dentro do seu escopo (veja 3.5).
Antes da primeira atribuio a uma varivel, seu valor nil.
Colchetes so usados para indexar uma tabela:
var ::= expprefixo [ exp ]
O significado de acessos aos campos de uma tabela podem ser modificados por metatabelas.
Um acesso a um varivel indexada t[i] equivalente a uma chamada gettable_event(t,i).
(Veja 2.4 para uma descrio completa da funo gettable_event. Essa funo no definida
nem pode ser chamada em Lua. Usamos ela aqui somente para fins didticos.)
A sintaxe var.Nome apenas acar sinttico para var["Nome"]:
var ::= expprefixo . Nome
Um acesso a uma varivel global x equivalente a _ENV.x. Devido ao modo que um trecho
compilado, _ENV nunca um nome global (veja 2.2).
3.3 Comandos
Lua oferece suporte a um conjunto quase convencional de comandos, similar a aqueles em
Pascal ou C. Esse conjunto inclui atribuies, estruturas de controle, chamadas de funo, e
declaraes de variveis.
3.3.1 Blocos
Um bloco uma lista de comandos, que so executados sequencialmente:
bloco ::= {comando}
Lua possui comandos vazios que permitem voc separar comandos com ponto-e-vrgula,
comear um bloco com um ponto-e-vrgula ou escrever dois ponto-e-vrgula em sequncia:
comando ::= ;
Chamadas de funo e atribuies podem comear com um abre parntese. Essa possibilidade
leva a uma ambiguidade na gramtica de Lua. Considere o seguinte fragmento:
a=b+c
(print or io.write)('done')
A gramtica poderia v-lo de duas maneiras:
a = b + c(print or io.write)('done')

a = b + c; (print or io.write)('done')
O parser corrente sempre v tais construes da primeira maneira, interpretando o abre
parntese como o comeo dos argumentos de uma chamada. Para evitar essa ambiguidade,
uma boa prtica sempre preceder com um ponto-e-vrgula comandos que comeam com um
parntese:
;(print or io.write)('done')
Um bloco pode ser explicitamente delimitado para produzir um nico comando:
comando ::= do bloco end
Blocos explcitos so teis para controlar o escopo de declaraes de variveis. Blocos explcitos
so tambm algumas vezes usados para adicionar um comando return no meio de outro bloco
(veja 3.3.4).
3.3.2 Trechos
A unidade de compilao de Lua chamada de um trecho. Sintaticamente, um trecho
simplesmente um bloco:
trecho ::= bloco
Lua trata um trecho como o corpo de uma funo annima com um nmero varivel de
argumentos (veja 3.4.10). Dessa forma, trechos podem definir variveis locais, receber
argumentos, e retornar valores. Alm disso, tal funo annima compilada no escopo de uma
varivel local externa chamada _ENV (veja 2.2). A funo resultante sempre tem _ENV como
seu nico upvalue, mesmo se ele no usar essa varivel.
Um trecho pode ser armazenado em um arquivo ou em uma cadeia dentro do programa
hospedeiro. Para executar um trecho, Lua primeiro pr-compila o trecho para instrues de uma
mquina virtual, e ento executa o cdigo compilado com um interpretador para a mquina
virtual.
Trechos podem tambm ser pr-compilados para uma forma binria; veja o programa luac para
detalhes. Programas na forma de cdigo fonte e na forma compilada so intercambiveis; Lua
detecta automaticamente o tipo do arquivo e age de acordo.
3.3.3 Atribuio
Lua permite atribuies mltiplas. Por isso, a sintaxe para atribuio define uma lista de
variveis no lado esquerdo e uma lista de expresses no lado direito. Os elementos em ambas as
listas so separados por vrgulas:
comando ::= listavars = listaexps
listavars ::= var {, var}
listaexps ::= exp {, exp}
Expresses so discutidas em 3.4.
Antes da atribuio, a lista de valores ajustada para o comprimento da lista de variveis. Se h
mais valores do que o necessrio, os valores em excesso so descartados. Se h menos valores
do que o necessrio a lista estendida com tantos nil's quantos sejam necessrios. Se a lista de
expresses termina com uma chamada de funo, ento todos os valores retornados por essa
chamada entram na lista de valores, antes do ajuste (exceto quando a chamada delimitada por
parnteses; veja 3.4).
O comando de atribuio primeiro avalia todas as suas expresses e somente ento as
atribuies so realizadas. Assim o cdigo
i=3
i, a[i] = i+1, 20
atribui 20 a a[3], sem afetar a[4] porque o i em a[i] avaliado (como 3) antes de receber 4.
Similarmente, a linha
x, y = y, x
troca os valores de x e y, e
x, y, z = y, z, x
permuta de maneira cclica os valores de x, y, e z.
A semntica de atribuies para variveis globais e campos de tabelas pode ser modificada por
metatabelas. Uma atribuio a uma varivel indexada t[i] = val equivalente
a settable_event(t,i,val). (Veja 2.4 para uma descrio completa da funo settable_event. Essa
funo no definida nem pode ser chamada em Lua. Usamos ela aqui somente para fins
didticos.)
Uma atribuio a uma varivel global x = val equivalente atribuio _ENV.x = val (veja 2.2).
3.3.4 Estruturas de Controle
As estruturas de controle if, while, e repeat possuem o significado usual e a sintaxe familiar:
comando ::= while exp do bloco end
comando ::= repeat bloco until exp
comando ::= if exp then bloco {elseif exp then bloco} [else bloco] end
Lua tambm possui um comando for, em duas variaes (veja 3.3.5).
A expresso da condio de uma estrutura de controle pode retornar qualquer valor.
Tanto false quanto nil so considerados falso. Todos os valores diferentes de nil e false so
considerados verdadeiro (em particular, o nmero 0 e a cadeia vazia so tambm verdadeiro).
No lao repeatuntil, o bloco interno no termina na palavra chave until, mas somente aps a
condio. Assim, a condio pode se referir a variveis locais declaradas dentro do corpo do
lao.
O comando goto transfere o controle do programa para um rtulo. Por razes sintticas, rtulos
em Lua so considerados comandos tambm:
comando ::= goto Nome
comando ::= rtulo
rtulo ::= :: Nome ::
Um rtulo visvel em todo o bloco onde ele definido, exceto dentro de blocos aninhados onde
um rtulo com o mesmo nome definido e dentro de funes aninhadas. Um goto pode fazer
um desvio para qualquer rtulo visvel desde que ele no entre no escopo de uma varivel local.
Rtulos e comandos vazios so chamados de comandos nulos, uma vez que eles no realizam
aes.
O comando break termina a execuo de um lao while, repeat, ou for, fazendo um desvio
para o prximo comando aps o lao:
comando ::= break
Um break termina o lao mais interno.
O comando return usado para retornar valores de uma funo ou de um trecho (que uma
funo disfarada). Funes podem retornar mais do que um valor, assim a sintaxe para o
comando return
comando ::= return [listaexps] [;]
O comando return pode somente ser escrito como o ltimo comando de um bloco. Se for
realmente necessrio um return no meio de um bloco, ento um bloco interno explcito pode
ser usado, como na expresso idiomtica do return end, porque agora return o ltimo
comando de seu bloco (interno).
3.3.5 Comando for
O comando for possui duas formas: um numrica e outra genrica.
O lao for numrico repete um bloco de cdigo enquanto uma varivel de controle varia de
acordo com uma progresso aritmtica. Ele tem a seguinte sintaxe:
comando ::= for Nome = exp , exp [, exp] do bloco end
O bloco repetido para nome comeando com o valor da primeira exp, at que ele passe a
segunda exp atravs de passos da terceira exp. Mais precisamente, um comando for como
for v = e1, e2, e3 do bloco end
equivalente ao cdigo:
do
local var, limite, passo = tonumber(e1), tonumber(e2), tonumber(e3)
if not (var and limite and passo) then error() end
while (passo > 0 and var <= limite) or (passo <= 0 and var >= limite) do
local v = var
bloco
var = var + passo
end
end
Note o seguinte:
Todas as trs expresses de controle so avaliadas somente uma vez, antes do lao
comear. Elas devem todas resultar em nmeros.
var, limite, e passo so variveis invisveis. Os nomes mostrados aqui so para fins
didticos somente.
Se a terceira expresso (o passo) est ausente, ento um passo de 1 usado.
Voc pode usar break para sair de um lao for.
A varivel de lao v local ao lao; voc no pode usar o valor dela aps o for terminar
ou ser interrompido. Se voc precisa desse valor, atribua-o a outra varivel antes de
interromper ou sair do lao.
O comando for genrico funciona usando funes, chamadas de iteradores. A cada iterao, a
funo iteradora chamada para produzir um novo valor, parando quando esse novo valor nil.
O lao for genrico tem a seguinte sintaxe:
comando ::= for listanomes in listaexps do bloco end
listanomes ::= Nome {, Nome}
Um comando for como
for var_1, , var_n in listaexps do bloco end
equivalente ao cdigo:
do
local f, s, var = listaexps
while true do
local var_1, , var_n = f(s, var)
if var_1 == nil then break end
var = var_1
bloco
end
end
Note o seguinte:
listaexps avaliada somente uma vez. Seus resultados so uma funo iteradora,
um estado, e um valor inicial para a primeira varivel iteradora.
f, s, e var so variveis invisveis. Os nomes esto aqui para fins didticos somente.
 Voc pode usar break para sair de um lao for.
As variveis de lao var_i so locais ao lao; voc no pode usar o valor delas aps
o for terminar. Se voc precisa desses valores, ento atribua-os a outras variveis antes
de interromper ou sair do lao.
3.3.6 Chamadas de Funo como Comandos
Para permitir possveis efeitos colaterais, chamadas de funo podem ser executadas como
comandos:
comando ::= chamadafuno
Nesse caso, todos os valores retornados so descartados. Chamadas de funo so explicadas
em 3.4.9.
3.3.7 Declaraes Locais
Variveis locais podem ser declaradas em qualquer lugar dentro de um bloco. A declarao pode
incluir uma atribuio inicial:
comando ::= local listanomes [= listaexps]
Se presente, uma atribuio inicial tem a mesma semntica de uma atribuio mltipla
(veja 3.3.3). Caso contrrio, todas as variveis so inicializadas com nil.
Um trecho tambm um bloco (veja 3.3.2), e dessa forma variveis locais podem ser
declaradas em um trecho fora de qualquer bloco explcito.
As regras de visibilidade para variveis locais so explicadas em 3.5.
3.4 Expresses
As expresses bsicas em Lua so as seguintes:
exp ::= expprefixo
exp ::= nil | false | true
exp ::= Nmero
exp ::= Cadeia
exp ::= deffuno
exp ::= construtortabela
exp ::= ...
exp ::= exp opbin exp
exp ::= opunrio exp
prefixexp ::= var | chamadafuno | ( exp )
Nmeros e cadeias de literais so explicados em 3.1; variveis so explicadas em 3.2;
definies de funes so explicadas em 3.4.10; chamadas de funes so explicadas
em 3.4.9; construtores de tabelas so explicados em 3.4.8. Expresses vararg, denotadas por
trs pontos (Char{...}), somente podem ser usadas quando diretamente dentro de uma funo
vararg; elas so explicadas em 3.4.10.
Operadores binrios compreendem operadores aritmticos (veja 3.4.1), operadores relacionais
(veja 3.4.3), operadores lgicos (veja 3.4.4), e o operador de concatenao (veja 3.4.5).
Operadores unrios compreendem o menos unrio (veja 3.4.1), o not unrio (veja 3.4.4), e
o operador de comprimento unrio (veja 3.4.6). Tanto chamadas de funo como expresses
vararg podem resultar em mltiplos valores. Se uma chamada de funo usada como um
comando (veja 3.3.6), ento sua lista de retorno ajustada para zero elementos, descartando
portanto todos os valores retornados. Se uma expresso usada como o ltimo (ou o nico)
elemento de uma lista de expresses, ento nenhum ajuste feito (a menos que a expresso
esteja entre parnteses). Em todos os outros contextos, Lua ajusta a lista de resultados para um
elemento, ou descartando todos os valores exceto o primeiro ou adicionando um nico nil se
no h nenhum valor.
Aqui esto alguns exemplos:
f() -- ajusta para 0 resultados
g(f(), x) -- f() ajustada para um resultado
g(x, f()) -- g recebe x mais todos os resultados de f()
a,b,c = f(), x -- f() ajustada para 1 resultado (c recebe nil)
a,b = ... -- a recebe o primeiro parmetro de vararg, b recebe
-- o segundo (tanto a quanto b podem receber nil caso
-- no exista um parmetro de vararg correspondente)
 a,b,c = x, f() -- f() ajustada para 2 resultados
a,b,c = f() -- f() ajustada para 3 resultados
return f() -- retorna todos os resultados de f()
return ... -- retorna todos os parmetros de vararg recebidos
return x,y,f() -- retorna x, y, e todos os resultados de f()
{f()} -- cria uma lista com todos os resultados de f()
{...} -- cria uma lista com todos os parmetros vararg
{f(), nil} -- f() ajustada para 1 resultado
Qualquer expresso entre parnteses sempre resulta em um nico valor. Portanto, (f(x,y,z))
sempre um nico valor, mesmo se f retorna vrios valores. (O valor de (f(x,y,z)) o primeiro
valor retornado por f ou nil se f no retorna nenhum valor.)
3.4.1 Operadores Aritmticos
Lua oferece suporte aos operadores aritmticos usuais: os
binrios + (adio), - (subtrao), * (multiplicao), / (diviso), % (mdulo), e ^ (exponenciao);
e o unrio - (negao matemtica). Se os operandos so nmeros, ou cadeias que podem ser
convertidas em nmeros (veja 3.4.2), ento todas as operaes possuem o significado usual. A
exponenciao funciona para qualquer expoente. Por exemplo, x^(-0.5) computa o inverso da
raiz quadrada de x. Mdulo definido como
a % b == a - math.floor(a/b)*b
Ou seja, o resto de uma diviso que arredonda o quociente para menos infinito.
3.4.2 Coero
Lua prov converso automtica entre valores string e number em tempo de execuo. Qualquer
operao aritmtica aplicada a uma cadeia tenta converter essa cadeia para um nmero,
seguindo as regras do analisador lxico de Lua. (A cadeia pode ter espaos esquerda e
direita e um sinal.) Inversamente, sempre que um nmero usado onde uma cadeia esperada,
o nmero convertido em uma cadeia, em um formato razovel. Para um controle completo
sobre como nmeros so convertidos em cadeias, use a funo format da biblioteca de cadeias
(veja string.format).
3.4.3 Operadores Relacionais
Os operadores relacionais em Lua so
== ~= < > <= >=
Esses operadores sempre resultam em false ou true.
A igualdade (==) primeiro compara o tipo de seus operandos. Se os tipos so diferentes, ento o
resultado false. Caso contrrio, os valores dos operandos so comparados. Nmeros e cadeias
so comparados da maneira usual. Tabelas, userdatas, e fluxos de execuo so comparados por
referncia: dois objetos so considerados iguais somente se eles so o mesmo objeto. Toda vez
que voc cria um novo objeto (uma tabela, um userdata, ou um fluxo de execuo), esse novo
objeto diferente de qualquer objeto existente anteriormente. Fechos com a mesma referncia
so sempre iguais. Fechos com qualquer diferena detectvel (comportamento diferente,
definio diferente) so sempre diferentes.
Voc pode mudar a maneira que Lua compara tabelas e userdatas usando o metamtodo "eq"
(veja 2.4).
As regras de converso 3.4.2 no se aplicam a comparaes de igualdade.
Assim, "0"==0 avalia para false, e t[0] e t["0"] denotam entradas diferentes em uma tabela.
O operador ~= exatamente a negao da igualdade (==).
Os operadores de ordem funcionam como a seguir. Se ambos os argumentos so nmeros, ento
eles so comparados como tais. Caso contrrio, se ambos os argumentos so cadeias, ento os
valores delas so comparados de acordo com o idioma (locale) atual. Caso contrrio, Lua tenta
chamar o metamtodo "lt" ou o metamtodo "le" (veja 2.4). Uma comparao a > b traduzida
para b < a e a >= b traduzida para b <= a.
3.4.4 Operadores Lgicos
Os operadores lgicos em Lua so and, or, e not. Assim como as estruturas de controle
(veja 3.3.4), todos os operadores lgicos consideram false e nilcomo falso e qualquer coisa
diferente como verdeiro.
O operador de negao not sempre retorna false ou true. O operador de
conjuno and retorna seu primeiro argumento se este valor false ou nil; caso
contrrio, and retorna seu segundo argumento. O operador de disjuno or retorna seu primeiro
argumento se este valor diferente de nil e false; caso contrrio, or retorna seu segundo
argumento. Tanto and como or usam avaliao de curto-circuito; isto , o segundo operando
avaliado somente se necessrio. Aqui esto alguns exemplos:
10 or 20 --> 10
10 or error() --> 10
nil or "a" --> "a"
nil and 10 --> nil
false and error() --> false
false and nil --> false
false or nil --> nil
10 and 20 --> 20
(Neste manual, --> indica o resultado da expresso precedente.)
3.4.5 Concatenao
O operador de concatenao de cadeias em Lua denotado por ponto ponto ('..'). Se ambos os
operandos so cadeias ou nmeros, ento eles so convertidos para cadeias de acordo com as
regras mencionadas em 3.4.2. Caso contrrio, o metamtodo __concat chamado (veja 2.4).
3.4.6 O Operador de Comprimento
O operador de comprimento denotado pelo operador unrio prefixo #. O comprimento de uma
cadeia o seu nmero de bytes (isto , o significado usual de comprimento de cadeia quando
cada caractere um byte).
Um programa pode modificar o comportamento do operador de comprimento para qualquer
valor exceto cadeias atravs do metamtodo __len (veja 2.4).
A menos que o metamtodo __len seja fornecido, o comprimento de uma tabela t definido
somente se a tabela uma sequncia, isto , o conjunto de suas chaves numricas positivas
igual a {1..n} para algum inteiro no negativo n. Nesse caso, n seu comprimento. Note que
uma tabela como
{10, 20, nil, 40}
no uma sequncia, pois ela tem a chave 4 mas no no tem a chave 3. (Assim, no existe
um n tal que o conjunto {1..n} seja igual ao conjunto de chaves numricas positivas dessa
tabela.) Note, contudo, que chaves no numricas no interferem no fato de uma tabela ser uma
sequncia.
3.4.7 Precedncia
A precedncia dos operadores em Lua segue a tabela a seguir, da menor prioridade para a
maior:
or
and
< > <= >= ~= ==
..
+ -
* / %
not # - (unrio)
^
Como de costume, voc pode usar parnteses para mudar as precedncias de uma expresso.
Os operadores de concatenao ('..') e de exponenciao ('^') so associativos direita. Todos
os outros operadores binrios so associativos esquerda.
3.4.8 Construtores de Tabelas
Construtores de tabelas so expresso que criam tabelas. Toda vez que um construtor
avaliado, uma nova tabela criada. Um construtor pode ser usado para criar uma tabela vazia
ou para criar uma tabela e inicializar alguns de seus campos. A sintaxe geral para construtores
construtortabela ::= { [listacampos] }
listacampos ::= campo {sepcampos campo} [sepcampos]
campo ::= [ exp ] = exp | Nome = exp | exp
sepcampos ::= , | ;
Cada campo da forma [exp1] = exp2 adiciona nova tabela uma entrada com chave exp1 e
valor exp2. Um campo da forma nome = exp equivalente a["nome"] = exp. Finalmente,
campos da forma exp so equivalentes a [i] = exp, onde i so nmeros inteiros consecutivos,
comeando com 1. Campos nos outros formatos no afetam essa contagem. Por exemplo,
 a = { [f(1)] = g; "x", "y"; x = 1, f(x), [30] = 23; 45 }
equivalente a
do
local t = {}
t[f(1)] = g
t[1] = "x" -- primeira exp
t[2] = "y" -- segunda exp
t.x = 1 -- t["x"] = 1
t[3] = f(x) -- terceira exp
t[30] = 23
t[4] = 45 -- quarta exp
a=t
end
Se o ltimo campo na lista tem a forma exp e a expresso uma chamada de funo ou uma
expresso vararg, ento todos os valores retornados por essa expresso entram na lista
consecutivamente (veja 3.4.9).
A lista de campos pode ter um separador a mais no fim, como uma convenincia para cdigo
gerado por mquina.
3.4.9 Chamadas de Funo
Uma chamada de funo em Lua tem a seguinte sintaxe:
chamadafuno ::= expprefixo args
Em uma chamada de funo, primeiro expprefixo e args so avaliados. Se o valor de expprefixo
tem tipo function, ento essa funo chamada com os argumentos fornecidos. Caso contrrio,
o metamtodo "call" de expprefixo chamado, tendo como primeiro parmetro o valor de
expprefixo, seguido pelos argumentos da chamada original (veja 2.4).
A forma
chamadafuno ::= expprefixo : Nome args
pode ser usada para chamar "mtodos". Uma chamada v:nome(args) acar sinttico
para v.nome(v,args), exceto pelo fato de que v avaliado somente uma vez.
Argumentos possuem a seguinte sintaxe:
args ::= ( [listaexps] )
args ::= construtortabela
args ::= Cadeia
Todas as expresses de argumentos so avaliadas antes da chamada. Uma chamada da
forma f{campos} acar sinttico para f({campos}); isto , a lista de argumentos somente
uma nova tabela. Uma chamada da forma f'cadeia' (ou f"cadeia" ou f[[cadeia]]) acar
sinttico para f('cadeia'); isto , a lista de argumentos somente uma cadeia literal.
Uma chamada da forma return chamadafuno denominada de chamada final. Lua
implementa chamadas finais prprias (ou recurses finais prprias): em uma chamada final, a
funo chamada reusa a entrada na pilha da funo chamadora. Logo, no h limite no nmero
de chamadas finais aninhadas que um programa pode executar. Contudo, uma chamada final
apaga qualquer informao de depurao a respeito da funo chamadora. Note que uma
chamada final somente acontece com uma sintaxe particular, onde o return possui uma nica
chamada de funo como argumento; essa sintaxe faz a funo chamadora retornar exatamente
os valores retornados pela funo chamada. Assim, nenhum dos exemplos a seguir uma
chamada final:
return (f(x)) -- resultados ajustados para 1
return 2 * f(x)
return x, f(x) -- resultados adicionais
f(x); return -- resultados descartados
return x or f(x) -- resultados ajustados para 1
3.4.10 Definies de Funes
A sintaxe para uma definio de funo
deffuno ::= funo corpofuno
corpofuno ::= ( [listapars] ) bloco end
O seguinte acar sinttico simplifica definies de funes:
 comando ::= function nomefuno corpofuno
comando ::= local function Nome corpofuno
nomefuno ::= Nome {. Nome} [: Nome]
O comando
function f () corpo end
traduzido para
f = function () corpo end
O comando
function t.a.b.c.f () corpo end
traduzido para
t.a.b.c.f = function () corpo end
O comando
local function f () corpo end
traduzido para
local f; f = function () corpo end
no para
local f = function () corpo end
(Isso somente faz diferena quando o corpo da funo contm referncias para f.)
Uma definio de funo uma expresso executvel, cujo valor tem tipo function. Quando Lua
pr-compila um trecho, todos os corpos de funes do trecho so pr-compilados tambm.
Ento, sempre que Lua executa a definio de uma funo, a funo instanciada (ou fechada).
Essa instncia de funo (ou fecho) o valor final da expresso.
Parmetros agem como variveis locais que so inicializadas com os valores dos argumentos:
listapars ::= listanomes [, ...] | ...
Quando uma funo chamada, a lista de argumentos ajustada para o comprimento da lista
de parmetros, a menos que a funo seja uma funo vararg, a qual indicada por trs pontos
('...') no fim de sua lista de parmetros. Uma funo vararg no ajusta sua lista de argumentos;
ao invs disso, ela coleta todos os argumentos extras e os fornece funo atravs de
uma expresso vararg, que tambm denotada por trs pontos. O valor desta expresso uma
lista de todos os argumentos extras de fato, similar a uma funo com mltiplos resultados. Se
uma expresso vararg usada dentro de outra expresso ou no meio de uma lista de
expresses, ento sua lista de retorno ajustada para um elemento. Se a expresso usada
como o ltimo elemento de uma lista de expresses, ento nenhum ajuste feito (a menos que
a ltima expresso esteja entre parnteses).
Como um exemplo, considere as seguintes definies:
function f(a, b) end
function g(a, b, ...) end
function r() return 1,2,3 end
Em seguida, temos o seguinte mapeamento de argumentos para parmetros e para expresses
vararg:
CHAMADA PARMETROS

f(3) a=3, b=nil

f(3, 4) a=3, b=4
f(3, 4, 5) a=3, b=4
f(r(), 10) a=1, b=10
f(r()) a=1, b=2

g(3) a=3, b=nil, ... --> (nada)

g(3, 4) a=3, b=4, ... --> (nada)
g(3, 4, 5, 8) a=3, b=4, ... --> 5 8
g(5, r()) a=5, b=1, ... --> 2 3
Resultados so retornados usando o comando return (veja 3.3.4). Se o controle alcana o fim
de uma funo sem encontrar um comando return, ento a funo retorna sem nenhum
resultado.
H um limite que depende do sistema para o nmero de valores que uma funo pode retornar.
Esse limite garantidamente maior do que 1000.
A sintaxe de dois pontos usada para definir mtodos, isto , funes que possuem um
parmetro extra self implcito. Assim, o comando
function t.a.b.c:f (params) corpo end
acar sinttico para
t.a.b.c.f = function (self, params) corpo end
3.5 Regras de Visibilidade
Lua uma linguagem com escopo lxico. O escopo de uma varivel local comea no primeiro
comando aps a sua declarao e vai at o ltimo comando no nulo do bloco mais interno que
inclui a declarao. Considere o seguinte exemplo:
x = 10 -- varivel global
do -- novo bloco
local x = x -- novo 'x', com valor 10
print(x) --> 10
x = x+1
do -- outro bloco
local x = x+1 -- outro 'x'
print(x) --> 12
end
print(x) --> 11
end
print(x) --> 10 (o x global)
Note que, em uma declarao como local x = x, o novo x sendo declarado no est no escopo
ainda, e portanto o segundo x se refere a uma varivel externa.
Por conta das regras de escopo lxico, variveis locais podem ser livremente acessadas por
funes definidas dentro de seu escopo. Uma varivel local usada por uma funo mais interna
chamada de upvalue, ou de varivel local externa, dentro da funo mais interna.
Note que cada execuo de um comando local define novas variveis locais. Considere o
seguinte exemplo:
a = {}
local x = 20
for i=1,10 do
local y = 0
a[i] = function () y=y+1; return x+y end
end
O lao cria dez fechos (isto , dez instncias da funo annima). Cada um desses fechos usa
uma varivel y diferente, enquanto todos eles compartilham o mesmo x.
4 A Interface de Programao da Aplicao
Esta seo descreve a API C para Lua, isto , o conjunto de funes C disponveis para o
programa hospedeiro se comunicar com Lua. Todas as funes da API e os tipos e constantes
relacionados esto declarados no arquivo de cabealho lua.h.
Mesmo quando usamos o termo "funo", qualquer facilidade na API pode ser provida como uma
macro ao invs. Exceto onde dito de outra maneira, todas essas macros usam cada um de seus
argumentos exatamente uma vez (exceto o primeiro argumento, que sempre um estado Lua),
e assim no geram qualquer efeito colateral oculto.
Como na maioria das bibliotecas C, as funes da API Lua no verificam a validade ou a
consistncia de seus argumentos. Contudo, voc pode mudar esse comportamento compilando
Lua com a macro LUA_USE_APICHECK definida.
4.1 A Pilha
Lua usa uma pilha virtual para passar e receber valores de C. Cada elemento nessa pilha
representa um valor Lua (nil, nmero, cadeia, etc.).
Sempre que Lua chama C, a funo chamada recebe uma nova pilha, que independente de
pilhas anteriores e de pilhas de funes C que ainda esto ativas. Essa pilha inicialmente contm
quaisquer argumentos para a funo C e onde a funo C empilha seus resultados para serem
retornados para o chamador (veja lua_CFunction).
Por convenincia, a maioria das operaes de consulta na API no seguem uma disciplina de
pilha estrita. Em vez disso, elas podem se referir a qualquer elemento na pilha usando
um ndice: Um ndice positivo representa um posio absoluta na pilha (comeando de 1); um
ndice negativo representa uma posio relativa ao topo da pilha. Mais especificamente, se a
pilha tem n elementos, ento o ndice 1 representa o primeiro elemento (isto , o elemento que
foi empilhado primeiro) e o ndice n representa o ltimo elemento; o ndice -1 tambm
representa o ltimo elemento (isto , o elemento no topo) e o ndice -nrepresenta o primeiro
elemento.
4.2 Tamanho da Pilha
Quando voc interage com a API de Lua, voc responsvel por assegurar consistncia.. Em
particular, voc responsvel por controlar o estourou da pilha. Voc pode usar a
funo lua_checkstack para assegurar que a pilha possui espaos extras ao empilhar novos
elementos.
Sempre que Lua chama C, ela assegura que a pilha possui pelo menos LUA_MINSTACK espaos
extras. LUA_MINSTACK definida como 20, assim geralmente voc no precisa se preocupar
com espaos extras a menos que seu cdigo tenha laos empilhando elementos na pilha.
Quando voc chama uma funo Lua sem um nmero fixo de resultados (veja lua_call), Lua
garante que a pilha tem espao suficiente para todos os resultados, mas ela no garante
qualquer espao extra. Assim, antes de empilhar qualquer coisa na pilha aps uma chamada
desse tipo voc deve usar lua_checkstack.
4.3 ndices Vlidos e Aceitveis
Qualquer funo na API que recebe ndices da pilha funciona somente com ndices
vlidos ou ndices aceitveis.
Um ndice vlido um ndice que se refere a uma posio real dentro da pilha, isto , sua
posio est entre 1 e o topo da pilha (1 abs(ndice) topo). Geralmente, funes que podem
modificar os valores em um ndice exigem ndices vlidos.
A menos que dito de outra maneira, qualquer funo que aceita ndices vlidos tambm
aceita pseudo-ndices, os quais representam alguns valores de Lua que so acessveis para
cdigo C mas que no esto na pilha. Pseudo-ndices so usados para acessar o registro e os
upvalues de uma funo C (veja 4.4).
Funes que no precisam de uma posio na pilha especfica, mas somente de um valor na
pilha (e.g., funes de consulta), podem ser chamadas com ndices aceitveis. Um ndice
aceitvel pode ser qualquer ndice vlido, incluindo os pseudo-ndices, mas tambm pode ser
qualquer inteiro positivo aps o topo da pilha dentro do espao alocado para a pilha, isto ,
ndices at o tamanho da pilha. (Note que 0 nunca um ndice aceitvel.) Exceto quando dito de
outra maneira, funes na API funcionam com ndices aceitveis.
ndices aceitveis servem para evitar testes extras relacionados ao topo da pilha ao consultar a
pilha. Por exemplo, um funo C pode consultar seu terceiro argumento sem a necessidade de
primeiro verificar se h um terceiro argumento, isto , sem a necessidade de verificar se 3 um
ndice vlido.
Para funes que podem ser chamadas com ndices aceitveis, qualquer ndice no vlido
tratado como se ele contivesse um valor de um tipo virtual LUA_TNONE, o qual comporta-se
como um valor nil.
4.4 Fechos C
Quando uma funo C criada, possvel associar alguns valores a ela, criando assim
um fecho C (veja lua_pushcclosure); esses valores so chamados de upvalues e so acessveis
funo sempre que ela chamada.
Sempre que uma funo C chamada, seus upvalues so posicionados em pseudo-ndices
especficos. Esses pseudo-ndices so produzidos pela macrolua_upvalueindex. O primeiro valor
associado com uma funo est na posio lua_upvalueindex(1), e assim por diante. Qualquer
acesso a lua_upvalueindex(n), onde n maior do que o nmero de upvalues da funo corrente
(mas no maior do que 256), produz um ndice aceitvel, porm invlido.
4.5 Registro
Lua prov um registro, uma tabela pr-definida que pode ser usada por qualquer cdigo C para
armazenar quaisquer valores Lua que ele precise armazenar . A tabela de registro est sempre
localizada no pseudo-ndice LUA_REGISTRYINDEX, que um ndice vlido. Qualquer biblioteca C
pode armazenar dados nessa tabela, mas ela deve tomar cuidado para escolher chaves que
sejam diferentes daquelas usadas por outras bibliotecas, para evitar colises. Tipicamente, voc
deve usar como chave uma cadeia contendo o nome de sua biblioteca, ou um userdata leve com
o endereo de um objeto C no seu cdigo, ou qualquer objeto Lua criado por seu cdigo. Assim
como com nomes globais, chaves que so cadeias comeando com um sublinhando seguido por
letras maisculas so reservadas para Lua.
As chaves inteiras no registro so usadas pelo mecanismo de referncia, implementado pela
biblioteca auxiliar, e por alguns valores pr-definidos. Portanto, chaves inteiras no devem ser
usadas para outros propsitos.
Quando voc cria um novo estado Lua, o registro dele vem com alguns valores pr-definidos.
Esses valores pr-definidos so indexados com chaves inteiras definidas como constantes
em lua.h. As seguintes constantes so definidas:
LUA_RIDX_MAINTHREAD: Nesse ndice o registro tem o fluxo de execuo principal do
estado. (O fluxo de execuo principal aquele criado junto com o estado.)
LUA_RIDX_GLOBALS: Nesse ndice o registro tem o ambiente global.
4.6 Tratamento de Erros em C
Internamente, Lua usa a facilidade longjmp de C para tratar erros. (Voc pode tambm escolher
usar excees se voc compilar Lua como C++; procure por LUAI_THROW no cdigo fonte.)
Quando Lua enfrenta qualquer erro (como um erro de alocao de memria, erros de tipo, erros
sintticos, e erros de tempo de execuo) ela lana um erro; isto , ela faz um desvio longo.
Um ambiente protegido usa setjmp para estabelecer um ponto de recuperao; qualquer erro
desvia para o ponto de recuperao ativo mais recente.
Se um erro acontece fora de qualquer ambiente protegido, Lua chama uma funo de
pnico (veja lua_atpanic) e ento chama abort, saindo portanto da aplicao hospedeira. Sua
funo de pnico pode evitar essa sada nunca retornando (e.g., fazendo um desvio longo para
seu prprio ponto de recuperao fora de Lua).
A funo de pnico roda como se ela fosse um tratador de mensagens (veja 2.3); em particular,
a mensagem de erro est no topo da pilha. Contudo, no h garantias sobre o espao da pilha.
Para empilhar qualquer coisa na pilha, a funo de pnico deve primeiro verificar o espao
disponvel (veja 4.2).
A maioria das funes na API pode lanar um erro, por exemplo devido a um erro de alocao de
memria. A documentao para cada funo indica se ela pode lanar erros.
Dentro de uma funo C voc pode lanar um erro chamando lua_error.
4.7 Tratando Cesses em C
Internamente, Lua usa a facilidade longjmp de C para ceder uma co-rotina. Logo, se uma
funo foo chama uma funo da API e essa funo da API cede (diretamente ou indiretamente
atravs da chamada a outra funo que cede), Lua no pode retornar mais para foo,
pois longjmp remove seu frame da pilha de C.
Para evitar esse tipo de problema, Lua lana um erro sempre que ela tenta ceder atravs de uma
chamada da API, exceto para trs funes: lua_yieldk, lua_callk, e lua_pcallk. Todas essas
funes recebem uma funo de continuao (como um parmetro chamado k) para continuar a
execuo aps uma cesso.
Precisamos estabelecer alguma terminologia para explicar continuaes. Temos uma funo C
chamada a partir de Lua que chamaremos de funo original. Essa funo original ento chama
uma dessas trs funes da API C, as quais chamaremos de funes chamadas, que ento
cedem o fluxo de execuo corrente. (Isso pode acontecer quando a funo chamada
lua_yieldk, ou quando a funo chamada lua_callk ou lua_pcallk e a funo chamada por elas
cede.)
Suponha que o fluxo de execuo rodando ceda enquanto executa a funo chamada. Aps o
fluxo de execuo recomear, ele em algum momento terminar executando a funo chamada.
Contudo, a funo chamada no pode retornar para a funo original, pois seu frame na pilha de
C foi destrudo pela cesso. Ao invs disso, Lua chama uma funo de continuao, que foi
fornecida como um argumento para a funo chamada. Como o nome indica, a funo de
continuao deve continuar a tarefa da funo original.
Lua trata a funo de continuao como se ela fosse a funo original. A funo de continuao
recebe a mesma pilha Lua da funo original, no mesmo estado que ela estaria se a funo
chamada tivesse retornado. (Por exemplo, aps um lua_callk a funo e seus argumentos so
removidos da pilha e substitudos pelos resultados da chamada.) Ela tambm tem os mesmos
upvalues. Seja qual for o retorno, ele tratado por Lua como se fosse o retorno da funo
original.
A nica diferena no estado Lua entre a funo original e sua continuao o resultado de uma
chamada a lua_getctx.
4.8 Funes e Tipos
Aqui listamos todas as funes e tipos da API C em ordem alfabtica. Cada funo possui um
indicador como este:[-o, +p, x]
O primeiro campo, o, quantos elementos a funo desempilha da pilha. O segundo campo, p,
quantos elementos a funo empilha na pilha. (Qualquer funo sempre empilha seus resultados
aps desempilhar seus argumentos.) Um campo da forma x|y significa que a funo pode
empilhar (ou desempilhar) x ou y elementos, dependendo da situao; um ponto de interrogao
'?' significa que no podemos saber quantos elementos a funo desempilha/empilha olhando
somente seus argumentos (e.g., eles podem depender do que est na pilha). O terceiro
campo, x, diz se a funo pode lanar erros: '-' significa que a funo nunca lana nenhum erro;
'e' significa que a funo pode lanar erros; 'v' significa que a funo pode lanar um erro de
propsito.
lua_absindex
[-0, +0, ]
int lua_absindex (lua_State *L, int idx);
Converte o ndice aceitvel idx em um ndice absoluto (isto , um que no depende do topo da
pilha).
lua_Alloc
typedef void * (*lua_Alloc) (void *ud,
void *ptr,
size_t osize,
size_t nsize);
O tipo da funo de alocao de memria usada por estados Lua. A funo alocadora deve
prover uma funcionalidade similar a realloc, mas no exatamente a mesma. Seus argumentos
so ud, um ponteiro opaco passado para lua_newstate; ptr, um ponteiro para o bloco sendo
alocado/realocado/liberado; osize, o tamanho original do bloco ou algum cdigo sobre o que est
sendo alocado; nsize, o novo tamanho do bloco.
Quando ptr no NULL, osize o tamanho do bloco apontado por ptr, isto , o tamanho
fornecido quando ele foi alocado ou realocado.
Quando ptr NULL, osize codifica o tipo de objeto que Lua est
alocando. osize LUA_TSTRING, LUA_TTABLE, LUA_TFUNCTION, LUA_TUSERDATA,
ou LUA_TTHREAD quando (e somente quando) Lua est criando um novo objeto desse tipo.
Quando osize algum outro valor, Lua est alocando memria para outra coisa.
Lua assume o seguinte comportamento da funo alocadora:
Quando nsize zero, o alocador deve comportar-se como free e retornar NULL.
Quando nsize no zero, o alocador deve comportar-se como realloc. O alocador
retorna NULL se e somente se ele no pode cumprir a requisio. Lua assume que o alocador
nunca falha quando osize >= nsize.
Aqui est uma implementao simples para a funo alocadora. Ela usada na biblioteca
auxiliar por luaL_newstate.
static void *l_alloc (void *ud, void *ptr, size_t osize,
size_t nsize) {
(void)ud; (void)osize; /* no utilizados */
if (nsize == 0) {
free(ptr);
return NULL;
}
else
return realloc(ptr, nsize);
}
Note que C Padro assegura que free(NULL) no tem efeito e que realloc(NULL, size)
equivalente a malloc(size). Esse cdigo assume que realloc no falha ao encolher um bloco.
(Embora C Padro no assegure esse comportamento, parece ser uma suposio segura.)
lua_arith
[-(2|1), +1, e]
void lua_arith (lua_State *L, int op);
Realiza uma operao aritmtica sobre os dois valores (ou um, no caso de negao) no topo da
pilha, com o valor no topo sendo o segundo operando, desempilha esses valores, e empilha o
resultado da operao. A funo segue a semntica do operador Lua correspondente (isto , ela
pode chamar metamtodos).
O valor de op deve ser uma das seguintes constantes:
LUA_OPADD: faz adio (+)
LUA_OPSUB: faz subtrao (-)
LUA_OPMUL: faz multiplicao (*)
LUA_OPDIV: faz diviso (/)
LUA_OPMOD: faz mdulo (%)
LUA_OPPOW: faz exponenciao (^)
LUA_OPUNM: faz negao matemtica (- unrio)
lua_atpanic
[-0, +0, ]
lua_CFunction lua_atpanic (lua_State *L, lua_CFunction panicf);
Estabelece uma nova funo de pnico e retorna a antiga (veja 4.6).
lua_call
[-(nargs+1), +nresults, e]
void lua_call (lua_State *L, int nargs, int nresults);
Chama uma funo.
Para chamar uma funo voc deve usar o seguinte protocolo: primeiro, a funo a ser chamada
empilhada na pilha; em seguida, os argumentos para a funo so empilhados em ordem
direta; isto , o primeiro argumento empilhado primeiro. Finalmente voc
chama lua_call; nargs o nmero de argumentos que voc empilhou na pilha. Todos os
argumentos e o valor da funo so retirados da pilha quando a funo chamada. Os
resultados da funo so colocados na pilha quando a funo retorna. O nmero de resultados
ajustado para nresults, a menos que nresults seja LUA_MULTRET. Nesse caso, todos os resultados
da funo so empilhados. Lua cuida para que os valores retornados se ajustem no espao da
pilha. Os resultados da funo so colocados na pilha em ordem direta (o primeiro resultado
empilhado primeiro), de modo que aps a chamada o ltimo resultado est no topo da pilha.
Qualquer erro dentro da funo chamada propagado para cima (com um longjmp).
O seguinte exemplo mostra como o programa hospedeiro pode fazer o equivalente a este cdigo
Lua:
a = f("how", t.x, 14)
Aqui est ele em C:
lua_getglobal(L, "f"); /* funo a ser chamada */
lua_pushstring(L, "how"); /* 1o argumento */
lua_getglobal(L, "t"); /* tabela a ser indexada */
lua_getfield(L, -1, "x"); /* empilha resultado de t.x (2o arg) */
lua_remove(L, -2); /* remove 't' da pilha */
lua_pushinteger(L, 14); /* 3o argumento */
lua_call(L, 3, 1); /* chama 'f' com 3 argumentos e 1 resultado */
lua_setglobal(L, "a"); /* estabelece 'a' global */
Note que o cdigo acima "balanceado": ao seu final, a pilha est de volta sua configurao
original. Isto considerado uma boa prtica de programao.
lua_callk
[-(nargs + 1), +nresults, e]
void lua_callk (lua_State *L, int nargs, int nresults, int ctx,
lua_CFunction k);
Esta funo comporta-se exatamente como lua_call, mas permite a funo chamada ceder
(veja 4.7).
lua_CFunction
typedef int (*lua_CFunction) (lua_State *L);
Tipo para funes C.
A fim de se comunicar apropriadamente com Lua, uma funo C deve usar o seguinte protocolo,
que define o modo como parmetros e resultados so passados: uma funo C recebe seus
argumentos de Lua na sua pilha em ordem direta (o primeiro argumento empilhado primeiro).
Assim, quando a funo comea, lua_gettop(L) retorna o nmero de argumentos recebidos pela
funo. O primeiro argumento (se houver) est no ndice 1 e seu ltimo argumento est no
ndice lua_gettop(L). Para retornar valores para Lua, uma funo C apenas os empilha na pilha,
em ordem direta (o primeiro resultado empilhado primeiro), e retorna o nmero de resultados.
Qualquer outro valor na pilha abaixo dos resultados ser apropriadamente descartado por Lua.
Como uma funo Lua, uma funo C chamada por Lua tambm pode retornar muitos
resultados.
Como um exemplo, a funo a seguir recebe um nmero varivel de argumentos numricos e
retorna a mdia e a soma deles:
static int foo (lua_State *L) {
int n = lua_gettop(L); /* nmero de argumentos */
lua_Number sum = 0;
int i;
for (i = 1; i <= n; i++) {
if (!lua_isnumber(L, i)) {
lua_pushstring(L, "incorrect argument");
lua_error(L);
}
sum += lua_tonumber(L, i);
}
lua_pushnumber(L, sum/n); /* primeiro resultado */
lua_pushnumber(L, sum); /* segundo resultado */
return 2; /* nmero de resultados */
}
lua_checkstack
[-0, +0, ]
int lua_checkstack (lua_State *L, int extra);
Assegura que h no mnimo extra espaos de pilha disponveis na pilha. Retorna falso se no
pode cumprir a requisio, pois faria com que a pilha fosse maior do que um tamanho mximo
fixo (tipicamente pelo menos uns poucos milhares de elementos) ou porque no pode alocar
memria para o novo tamanho da pilha. Essa funo nunca encolhe a pilha; se a pilha j maior
do que o novo tamanho, ela no modificada.
lua_close
[-0, +0, ]
void lua_close (lua_State *L);
Destri todos os objetos no estado Lua fornecido (chamando os metamtodos de coleta de lixo
correspondentes, se houver) e libera toda memria dinmica usada por esse estado. Em vrias
plataformas, voc pode no precisar chamar essa funo, pois todos os recursos so
naturalmente liberados quando o programa hospedeiro termina. Por outro lado, programas que
executam por muito tempo e que criam mltiplos estados, tais como daemons ou servidores
web, podem precisar fechar estados assim que eles no sejam necessrios.
lua_compare
[-0, +0, e]
int lua_compare (lua_State *L, int index1, int index2, int op);
Compara dois valores Lua. Retorna 1 se o valor no ndice index1 satisfaz op quando comparado
com o valor no ndice index2, seguindo a semntica do operador Lua correspondente (isto ,
pode chamar metamtodos). Caso contrrio retorna 0. Tambm retorna 0 se algum dos ndices
no vlido.
O valor de op deve ser uma das seguintes constantes:
LUA_OPEQ: comparao de igualdade (==)
LUA_OPLT: comparao de menor que (<)
LUA_OPLE: comparao de menor ou igual (<=)
lua_concat
[-n, +1, e]
void lua_concat (lua_State *L, int n);
Concatena os n valores no topo da pilha, desempilha-os, e deixa o resultado no topo. Se n 1, o
resultado o nico valor no topo da pilha (isto , a funo no faz nada); se n 0, o resultado
a cadeia vazia. A concatenao realizada seguindo a semntica usual de Lua (veja 3.4.5).
lua_copy
[-0, +0, ]
void lua_copy (lua_State *L, int fromidx, int toidx);
Move o elemento no ndice fromidx para o ndice vlido toidx sem deslocar nenhum elemento
(substituindo portanto o valor naquela posio).
lua_createtable
[-0, +1, e]
void lua_createtable (lua_State *L, int narr, int nrec);
Cria uma nova tabela vazia e a empilha na pilha. O parmetro narr uma dica de quantos
elementos a tabela ter como uma sequncia; o parmetro nrec uma dica de quantos outros
elementos a tabela ter. Lua pode usar essas dicas para pr-alocar memria para a nova tabela.
Essa pr-alocao til para desempenho quando voc sabe de antemo quantos elementos a
tabela ter. Caso contrrio voc pode usar a funo lua_newtable.
lua_dump
[-0, +0, e]
int lua_dump (lua_State *L, lua_Writer writer, void *data);
Descarrega uma funo como um trecho binrio. Recebe uma funo Lua no topo da pilha e
produz um trecho binrio que, se carregado novamente, resulta em uma funo equivalente
que foi descarregada. Como ela produz partes do trecho, lua_dump chama a
funo writer (veja lua_Writer) com o datafornecido para escrev-lo.
O valor retornado o cdigo de erro retornado pela ltima chamada a writer; 0 significa que no
houve erros.
Esta funo no desempilha a funo Lua da pilha.
lua_error
[-1, +0, v]
int lua_error (lua_State *L);
Gera um erro Lua. A mensagem de erro (a qual pode efetivamente ser um valor Lua de qualquer
tipo) deve estar no topo da pilha. Esta funo faz um desvio longo, e portanto nunca retorna
(veja luaL_error).
lua_gc
[-0, +0, e]
int lua_gc (lua_State *L, int what, int data);
Controla o coletor de lixo.
Esta funo realiza vrias tarefas, de acordo com o valor do parmetro what:
LUA_GCSTOP: para o coletor de lixo.
LUA_GCRESTART: reinicia o coletor de lixo.
LUA_GCCOLLECT: realiza um ciclo de coleta de lixo completo.
LUA_GCCOUNT: retorna a quantidade de memria (em Kbytes) correntemente usada por
Lua.
LUA_GCCOUNTB: retorna o resto da diviso da quantidade de bytes de memria
correntemente usada por Lua por 1024.
LUA_GCSTEP: realiza um passo incremental de coleta de lixo. O "tamanho" do passo
controlado por data (valores maiores significam mais passos) de um modo no
especificado. Se voc quiser controlar o tamanho do passo voc deve ajustar
experimentalmente o valor de data. A funo retorna 1 se o passo terminou um ciclo de
coleta de lixo.
LUA_GCSETPAUSE: estabelece data como o novo valor para a pausa do coletor
(veja 2.5). A funo retorna o valor anterior da pausa.
LUA_GCSETSTEPMUL: estabelece data como o novo valor para o multiplicador de
passo do coletor (veja 2.5). A funo retorna o valor anterior do multiplicador de passo.
LUA_GCISRUNNING: retorna um booleano que diz se o coletor est executando (i.e., no
parou).
LUA_GCGEN: muda o coletor para o modo generacional (veja 2.5).
LUA_GCINC: muda o coletor para o modo incremental. Este o modo padro.
Para mais detalhes sobre essas opes, veja collectgarbage.
lua_getallocf
[-0, +0, ]
lua_Alloc lua_getallocf (lua_State *L, void **ud);
Retorna a funo de alocao de memria de um dado estado. Se ud no NULL, Lua armazena
em *ud o ponteiro opaco passado para lua_newstate.
lua_getctx
[-0, +0, ]
int lua_getctx (lua_State *L, int *ctx);
Esta funo chamada por uma funo de continuao (veja 4.7) para recuperar o estado do
fluxo de execuo e uma informao de contexto.
Quando chamada na funo original, lua_getctx sempre retorna LUA_OK e no modifica o valor
de seu argumento ctx. Quando chamada dentro de uma funo de
continuao, lua_getctx retorna LUA_YIELD e atribui o valor de ctx para a informao de contexto
(o valor passado como o argumento ctx para a funo chamada junto com a funo de
continuao).
Quando a funo chamada lua_pcallk, Lua pode tambm chamar sua funo de continuao
para tratar erros durante a chamada. Isto , em consequncia de um erro na funo chamada
por lua_pcallk, Lua pode no retornar para a funo original mas ao invs disso pode chamar a
funo de continuao. Nesse caso, uma chamada a lua_getctx retornar o cdigo de erro (o
valor que seria retornado por lua_pcallk); o valor de ctx ser atribudo informao de contexto,
como no caso de uma cesso.
lua_getfield
[-0, +1, e]
void lua_getfield (lua_State *L, int index, const char *k);
Coloca na pilha o valor t[k], onde t o valor no ndice fornecido. Como em Lua, esta funo pode
disparar um metamtodo para o evento "ndice" (veja 2.4).
lua_getglobal
[-0, +1, e]
void lua_getglobal (lua_State *L, const char *name);
Coloca na pilha o valor da global name.
lua_getmetatable
[-0, +(0|1), ]
int lua_getmetatable (lua_State *L, int index);
Coloca na pilha a metatabela do valor no ndice fornecido. Se o valor no possui uma
metatabela, a funo retorna 0 e no coloca nada na pilha.
lua_gettable
[-1, +1, e]
void lua_gettable (lua_State *L, int index);
Coloca na pilha o valor t[k], onde t o valor no ndice fornecido e k o valor no topo da pilha.
Esta funo desempilha a chave da pilha (colocando o valor resultante em seu lugar). Como em
Lua, esta funo pode disparar um metamtodo para o "ndice" do evento (veja 2.4).
lua_gettop
[-0, +0, ]
int lua_gettop (lua_State *L);
Retorna o ndice do elemento no topo da pilha. Como os ndices comeam em 1, esse resultado
igual ao nmero de elementos na pilha (e portanto 0 significa uma pilha vazia).
lua_getuservalue
[-0, +1, ]
void lua_getuservalue (lua_State *L, int index);
Coloca na pilha o valor Lua associado com o userdata no ndice fornecido. Esse valor Lua deve
ser uma tabela ou nil.
lua_insert
[-1, +1, ]
void lua_insert (lua_State *L, int index);
Move o elemento no topo para ndice vlido fornecido, deslocando os elementos acima desse
ndice para abrir espao. Esta funo no pode ser chamada com um pseudo-ndice, pois um
pseudo-ndice no uma posio na pilha de verdade.
lua_Integer
typedef ptrdiff_t lua_Integer;
O tipo usado pela API de Lua para representar valores inteiros com sinal.
Por padro ele um ptrdiff_t, que usualmente o maior tipo inteiro com sinal que a mquina
manipula "confortavelmente".
lua_isboolean
[-0, +0, ]
int lua_isboolean (lua_State *L, int index);
Retorna 1 se o valor no ndice fornecido um booleano, e 0 caso contrrio.
lua_iscfunction
[-0, +0, ]
int lua_iscfunction (lua_State *L, int index);
Retorna 1 se o valor no ndice fornecido uma funo C, e 0 caso contrrio.
lua_isfunction
[-0, +0, ]
int lua_isfunction (lua_State *L, int index);
Retorna 1 se o valor no ndice fornecido uma funo (C ou Lua), e 0 caso contrrio.
lua_islightuserdata
[-0, +0, ]
int lua_islightuserdata (lua_State *L, int index);
Retorna 1 se o valor no ndice fornecido um userdata leve, e 0 caso contrrio.
lua_isnil
[-0, +0, ]
int lua_isnil (lua_State *L, int index);
Retorna 1 se o valor no ndice fornecido nil, e 0 caso contrrio.
lua_isnone
[-0, +0, ]
int lua_isnone (lua_State *L, int index);
Retorna 1 se o ndice fornecido no vlido, e 0 caso contrrio.
lua_isnoneornil
[-0, +0, ]
int lua_isnoneornil (lua_State *L, int index);
Retorna 1 se o ndice fornecido no vlido ou se o valor nesse ndice nil, e 0 caso contrrio.
lua_isnumber
[-0, +0, ]
int lua_isnumber (lua_State *L, int index);
Retorna 1 se o valor no ndice fornecido um nmero ou uma cadeia que pode ser convertida
para um nmero, e 0 caso contrrio.
lua_isstring
[-0, +0, ]
int lua_isstring (lua_State *L, int index);
Retorna 1 se o valor no ndice fornecido uma cadeia ou um nmero (o qual sempre pode ser
convertido para uma cadeia), e 0 caso contrrio.
lua_istable
[-0, +0, ]
int lua_istable (lua_State *L, int index);
Retorna 1 se o valor no ndice fornecido uma tabela, e 0 caso contrrio.
lua_isthread
[-0, +0, ]
int lua_isthread (lua_State *L, int index);
Retorna 1 se o valor no ndice fornecido um fluxo de execuo, e 0 caso contrrio.
lua_isuserdata
[-0, +0, ]
int lua_isuserdata (lua_State *L, int index);
Retorna 1 se o valor no ndice fornecido um userdata (completo ou leve), e 0 caso contrrio.
lua_len
[-0, +1, e]
void lua_len (lua_State *L, int index);
Retorna o "comprimento" do valor no ndice fornecido; equivalente ao operador '#' em Lua
(veja 3.4.6). O resultado colocado na pilha.
lua_load
[-0, +1, ]
int lua_load (lua_State *L,
lua_Reader reader,
void *data,
const char *source,
const char *mode);
Carrega um trecho Lua (sem execut-lo). Se no h erros, lua_load coloca o trecho compilado
como uma funo Lua no topo da pilha. Caso contrrio, empilha uma mensagem de erro.
Os valores retornados por lua_load so:
LUA_OK: sem erros;
LUA_ERRSYNTAX: erro de sintaxe durante a pr-compilao;
LUA_ERRMEM: erro de alocao de memria;
LUA_ERRGCMM: erro ao executar um metamtodo __gc. (Este erro no tem relao com
o trecho sendo carregado. Ele gerado pelo coletor de lixo.)
A funo lua_load usa uma funo reader fornecida pelo usurio para ler o trecho
(veja lua_Reader). O argumento data um valor opaco passado para a funo de leitura.
O argumento source d um nome para o trecho, o qual usado para mensagens de erro e em
informaes de depurao (veja 4.9).
lua_load automaticamente detecta se o trecho texto ou binrio e o carrega de acordo (veja o
programa luac). A cadeia mode funciona como na funo load, com a adio que um
valor NULL equivalente cadeia "bt".
lua_load usa a pilha internamente, assim a funo de leitura deve sempre deixar a pilha
inalterada ao retornar.
Se a funo resultante tem um upvalue, o valor atribudo a esse upvalue o ambiente global
armazenado no ndice LUA_RIDX_GLOBALS no registro (veja 4.5). Ao carregar trechos principais,
esse upvalue ser a varivel _ENV (veja 2.2).
lua_newstate
[-0, +0, ]
lua_State *lua_newstate (lua_Alloc f, void *ud);
Cria um novo fluxo de execuo rodando em um novo estado, independente. Retorna NULL se
no pode criar o fluxo ou o estado (devido falta de memria). O argumento f a funo
alocadora; Lua faz toda alocao de memria para esse estado atravs dessa funo. O segundo
argumento, ud, um ponteiro opaco que Lua passa para o alocador em cada chamada.
lua_newtable
[-0, +1, e]
void lua_newtable (lua_State *L);
Cria uma nova tabela vazia e a coloca na pilha. equivalente a lua_createtable(L, 0, 0).
lua_newthread
[-0, +1, e]
lua_State *lua_newthread (lua_State *L);
Cria um novo fluxo de execuo, coloca-o na pilha, e retorna um ponteiro para um lua_State que
representa esse novo fluxo. O novo fluxo de execuo retornado por essa funo compartilha
com o fluxo original seu ambiente global, mas possui uma pilha de execuo independente.
No h uma funo explcita para fechar ou destruir um fluxo de execuo. Fluxos de execuo
esto sujeitos coleta de lixo, como qualquer objeto Lua.
lua_newuserdata
[-0, +1, e]
void *lua_newuserdata (lua_State *L, size_t size);
Esta funo aloca um novo bloco de memria com o tamanho fornecido, coloca na pilha um novo
userdata completo com o endereo do bloco, e retorna esse endereo. O programa hospedeiro
pode usar livremente essa memria.
lua_next
[-1, +(2|0), e]
int lua_next (lua_State *L, int index);
Desempilha uma chave da pilha, e empilha um par chavevalor da tabela no ndice fornecido (o
"prximo" par aps o ndice fornecido). Se no h mais elementos na tabela ,
ento lua_next retorna 0 (e no empilha nada).
Um percorrimento tpico parece com este:
/* tabela est na pilha no ndice 't' */
lua_pushnil(L); /* primeira chave */
while (lua_next(L, t) != 0) {
/* usa 'key' (no ndice -2) e 'value' (no ndice -1) */
printf("%s - %s\n",
lua_typename(L, lua_type(L, -2)),
lua_typename(L, lua_type(L, -1)));
/* remove 'value'; mantm 'key' para a prxima iterao */
lua_pop(L, 1);
}
Ao percorrer uma tabela, no chame lua_tolstring diretamente sobre uma chave, a menos que
voc saiba que a chave realmente uma cadeia. Lembre que lua_tolstring pode modificar o
valor no ndice fornecido; isso confunde a prxima chamada a lua_next.
Veja a funo next para os cuidados que se deve ter ao modificar a tabela durante seu
percorrimento.
lua_Number
typedef double lua_Number;
O tipo de nmeros em Lua. Por padro, ele double, mas isso pode ser modificado em luaconf.h.
Atravs desse arquivo de configurao voc pode mudar Lua para operar com outro tipo para
nmeros (e.g., float ou long).
lua_pcall
[-(nargs + 1), +(nresults|1), ]
int lua_pcall (lua_State *L, int nargs, int nresults, int msgh);
Chama uma funo em modo protegido.
Tanto nargs quanto nresults possuem o mesmo significado que tinham em lua_call. Se no h
erros durante a chamada, lua_pcall comporta-se exatamente como lua_call. Contudo, se h
qualquer erro, lua_pcall o captura, coloca um nico valor na pilha (a mensagem de erro), e
retorna um cdigo de erro. Como lua_call, lua_pcall sempre remove a funo e seus argumentos
da pilha.
Se msgh 0, ento a mensagem de erro retornada na pilha exatamente a mensagem de erro
original. Caso contrrio, msgh o ndice na pilha de umtratador de mensagens. (Na
implementao corrente, esse ndice no pode ser um pseudo-ndice.) Em caso de erros de
tempo de execuo, essa funo ser chamada com a mensagem de erro e seu valor de retorno
ser a mensagem retornada na pilha por lua_pcall.
Tipicamente, o tratador de mensagens usado para adicionar mais informao de depurao
mensagem de erro, tal como um trao da pilha. Tal informao no pode ser obtida aps o
retorno de lua_pcall, pois nesse ponto a pilha foi desenrolada.
A funo lua_pcall retorna um dos seguintes cdigos (definidos em lua.h):
LUA_OK (0): sucesso.
LUA_ERRRUN: um erro de tempo de execuo.
LUA_ERRMEM: erro de alocao de memria. Para tais erros, Lua no chama o tratador
de mensagens.
LUA_ERRERR: erro ao executar o tratador de mensagens.
LUA_ERRGCMM: erro ao executar um metamtodo __gc. (Este erro tipicamente no tem
relao com a funo sendo chamada. Ele gerado pelo coletor de lixo.)
lua_pcallk
[-(nargs + 1), +(nresults|1), ]
int lua_pcallk (lua_State *L,
int nargs,
int nresults,
int errfunc,
int ctx,
lua_CFunction k);
Esta funo comporta-se exatamente como lua_pcall, mas permite a funo chamada ceder
(veja 4.7).
lua_pop
[-n, +0, ]
void lua_pop (lua_State *L, int n);
Desempilha n elementos da pilha.
lua_pushboolean
[-0, +1, ]
void lua_pushboolean (lua_State *L, int b);
Empilha um valor booleano com valor b na pilha.
lua_pushcclosure
[-n, +1, e]
void lua_pushcclosure (lua_State *L, lua_CFunction fn, int n);
Empilha um novo fecho C na pilha.
Quando uma funo C criada, possvel associar alguns valores a ela, criando assim um
fecho C (veja 4.4); esses valores so ento acessveis funo sempre que ela chamada. Para
associar valores com uma funo C, primeiro esses valores devem ser colocados na pilha
(quando h mltiplos valores, o primeiro valor colocado primeiro). Em
seguida lua_pushcclosure chamada para criar e colocar a funo C na pilha, com o
argumento n dizendo quantos valores devem ser associados com a
funo. lua_pushcclosure tambm retira valores da pilha.
O valor mximo para n 255.
Quando n zero, esta funo cria uma funo C leve, que apenas um ponteiro para a
funo C. Nesse caso, ela nunca lana um erro de memria.
lua_pushcfunction
[-0, +1, ]
void lua_pushcfunction (lua_State *L, lua_CFunction f);
Coloca uma funo C na pilha. Esta funo recebe um ponteiro para uma funo C e coloca na
pilha um valor Lua do tipo function que, quando chamado, invoca a funo C correspondente.
Qualquer funo a ser registrada em Lua deve seguir o protocolo correto para receber seus
parmetros e retornar seus resultados (veja lua_CFunction).
lua_pushcfunction definida como uma macro:
#define lua_pushcfunction(L,f) lua_pushcclosure(L,f,0)
Note que f usado duas vezes.
lua_pushfstring
[-0, +1, e]
const char *lua_pushfstring (lua_State *L, const char *fmt, ...);
Coloca na pilha uma cadeia formatada e retorna um ponteiro para essa cadeia. similar a
ANSI C function sprintf, mas tem algumas diferenas importantes:
Voc no precisa alocar espao para o resultado: o resultado uma cadeia Lua e Lua
cuida da alocao de memria (e da desalocao, atravs da coleta de lixo).
Os especificadores de converso so bastante restritos. No h flags, comprimentos, ou
precises. Os especificadores de converso podem ser somente '%%' (insere um '%' na
cadeia), '%s' (insere uma cadeia terminada por zero, sem restries de tamanho), '%f'
(insere um lua_Number), '%p' (insere um ponteiro como um nmero hexadecimal), '%d'
(insere um int), e '%c' (insere um int como um byte).
lua_pushglobaltable
[-0, +1, ]
void lua_pushglobaltable (lua_State *L);
Coloca o ambiente global na pilha.
lua_pushinteger
[-0, +1, ]
void lua_pushinteger (lua_State *L, lua_Integer n);
Coloca um nmero com valor n na pilha.
lua_pushlightuserdata
[-0, +1, ]
void lua_pushlightuserdata (lua_State *L, void *p);
Colocar um userdata leve na pilha.
Um userdata representa valores C em Lua. Um userdata leve representa um ponteiro, um void*.
Ele um valor (como um nmero): voc no o cria, ele no possui metatabela individual, e no
coletado (pois nunca foi criado). Um userdata leve igual a "qualquer" userdata leve com o
mesmo endereo C.
lua_pushliteral
[-0, +1, e]
const char *lua_pushliteral (lua_State *L, const char *s);
Esta macro equivalente a lua_pushlstring, mas pode ser usada somente quando s uma
cadeia literal. Ela prov automaticamente o comprimento da cadeia.
lua_pushlstring
[-0, +1, e]
const char *lua_pushlstring (lua_State *L, const char *s, size_t len);
Coloca a cadeia apontada por s com tamanho len na pilha. Lua faz (ou reusa) uma cpia interna
da cadeia fornecida, de modo que a memria de s pode ser liberada ou reusada imediatamente
aps a funo retornar. A cadeia pode conter qualquer dado binrio, incluindo zeros dentro dela.
Retorna um ponteiro para a cpia interna da cadeia.
lua_pushnil
[-0, +1, ]
void lua_pushnil (lua_State *L);
Coloca um valor nil na pilha.
lua_pushnumber
[-0, +1, ]
void lua_pushnumber (lua_State *L, lua_Number n);
Coloca um nmero com valor n na pilha.
lua_pushstring
[-0, +1, e]
const char *lua_pushstring (lua_State *L, const char *s);
Coloca a cadeia terminada por zero apontada por s na pilha. Lua faz (ou reusa) uma cpia
interna da cadeia fornecida, de modo que a memria apontada por s pode ser liberada ou
reusada imediatamente aps a funo retornar.
Retorna um ponteiro para a cpia interna da cadeia.
Se s NULL, empilha nil e retorna NULL.
lua_pushthread
[-0, +1, ]
int lua_pushthread (lua_State *L);
Coloca o fluxo de execuo representado por L na pilha. Retorna 1 se esse fluxo o fluxo
principal de seu estado.
lua_pushunsigned
[-0, +1, ]
void lua_pushunsigned (lua_State *L, lua_Unsigned n);
Coloca um nmero com valor n na pilha.
lua_pushvalue
[-0, +1, ]
void lua_pushvalue (lua_State *L, int index);
Coloca uma cpia do elemento no ndice fornecido na pilha.
lua_pushvfstring
[-0, +1, e]
const char *lua_pushvfstring (lua_State *L,
const char *fmt,
va_list argp);
Equivalente a lua_pushfstring, exceto que ela recebe uma va_list ao invs de um nmero
varivel de argumentos.
lua_rawequal
[-0, +0, ]
int lua_rawequal (lua_State *L, int index1, int index2);
Retorna 1 se os dois valores nos ndices index1 e index2 so iguais primitivamente (isto , sem
chamar metamtodos). Caso contrrio retorna 0. Tambm retorna 0 se algum dos ndices no
vlido.
lua_rawget
[-1, +1, ]
void lua_rawget (lua_State *L, int index);
Similar a lua_gettable, mas faz um acesso primitivo (i.e., sem metamtodos).
lua_rawgeti
[-0, +1, ]
void lua_rawgeti (lua_State *L, int index, int n);
Coloca na pilha o valor t[n], onde t a tabela no ndice fornecido. O acesso primitivo; isto ,
no invoca metamtodos.
lua_rawgetp
[-0, +1, ]
void lua_rawgetp (lua_State *L, int index, const void *p);
Coloca na pilha o valor t[k], onde t a tabela no ndice fornecido e k o ponteiro p representado
como um userdata leve. O acesso primitivo; isto , no invoca metamtodos.
lua_rawlen
[-0, +0, ]
size_t lua_rawlen (lua_State *L, int index);
Retorna o "comprimento" primitivo do valor no ndice fornecido: para cadeias, isso o
comprimento da cadeia; para tabelas, isso o resultado do operador de comprimento ('#') sem
metamtodos; para userdatas, isso o tamanho do bloco de memria alocado para o userdata;
para outros valores, 0.
lua_rawset
[-2, +0, e]
void lua_rawset (lua_State *L, int index);
Similar a lua_settable, mas faz uma atribuio primitiva (i.e., sem metamtodos).
lua_rawseti
[-1, +0, e]
void lua_rawseti (lua_State *L, int index, int n);
Faz o equivalente de t[n] = v, onde t a tabela no ndice fornecido e v o valor no topo da pilha.
Esta funo desempilha o valor da pilha. A atribuio primitiva; isto , ela no invoca
metamtodos.
lua_rawsetp
[-1, +0, e]
void lua_rawsetp (lua_State *L, int index, const void *p);
Faz o equivalente de t[k] = v, onde t a tabela no ndice fornecido, k o
ponteiro p representado como um userdata leve, e v o valor no topo da pilha.
Esta funo desempilha o valor da pilha. A atribuio primitiva; isto , ela no invoca
metamtodos.
lua_Reader
typedef const char * (*lua_Reader) (lua_State *L,
void *data,
size_t *size);
A funo de leitura usada por lua_load. Toda vez que ela precisa de outro pedao do
trecho, lua_load chama a funo de leitura, passando junto seu parmetro data. A funo de
leitura deve retornar um ponteiro para um bloco de memria com um novo pedao do trecho e
atribuir a size o tamanho do bloco. O bloco deve existir at que a funo de leitura seja chamada
novamente. Para sinalizar o fim do trecho, a funo de leitura deve retornar NULL ou atribuir
zero a size. A funo de leitura pode retornar pedaos de qualquer tamanho maior do que zero.
lua_register
[-0, +0, e]
void lua_register (lua_State *L, const char *name, lua_CFunction f);
Estabelece a funo C f como o novo valor da global name. Ela definida como uma macro:
#define lua_register(L,n,f) \
(lua_pushcfunction(L, f), lua_setglobal(L, n))
lua_remove
[-1, +0, ]
void lua_remove (lua_State *L, int index);
Remove o elemento no ndice vlido fornecido, deslocando para baixo os elementos acima desse
ndice para preencher o buraco. Esta funo no pode ser chamada com um pseudo-ndice, pois
um pseudo-ndice no uma posio na pilha de verdade.
lua_replace
[-1, +0, ]
void lua_replace (lua_State *L, int index);
u
Move o elemento no topo para o ndice vlido fornecido sem deslocar nenhum elemento
(substituindo portanto o valor no topo da pilha), e ento desempilha o elemento no topo.
lua_resume
[-?, +?, ]
int lua_resume (lua_State *L, lua_State *from, int nargs);
Comea e retoma uma co-rotina em um dado fluxo de execuo.
Para comear uma co-rotina, voc deve colocar na pilha do fluxo de execuo a funo principal
mais quaisquer argumentos; em seguida voc chama lua_resume, com nargs sendo o nmero de
argumentos. Essa chamada retorna quando a co-rotina suspende ou termina sua execuo.
Quando ela retorna, a pilha contm todos os valores passados para lua_yield, ou todos os
valores retornados pela funo do corpo. lua_resume retorna LUA_YIELD se a co-rotina
cede, LUA_OK se a co-rotina termina sua execuo sem erros, ou um cdigo de erro em caso de
erros (veja lua_pcall).
Em caso de erros, a pilha no desenrolada, de modo que voc pode usar a API de depurao
sobre ela. A mensagem de erro est no topo da pilha.
Para retomar uma co-rotina, voc remove quaisquer resultados da ltima lua_yield, coloca na
sua pilha somente os valores a serem passados como resultados de yield, e ento
chama lua_resume.
O parmetro from representa a co-rotina que est retomando L. Se no h tal co-rotina, esse
parmetro pode ser NULL.
lua_setallocf
[-0, +0, ]
void lua_setallocf (lua_State *L, lua_Alloc f, void *ud);
Muda a funo alocadora de um dado estado para f com userdata ud.
lua_setfield
[-1, +0, e]
void lua_setfield (lua_State *L, int index, const char *k);
Faz o equivalente de t[k] = v, onde t o valor no ndice fornecido e v o valor no topo da pilha.
Esta funo retira o valor do topo da pilha. Como em Lua, esta funo pode disparar um
metamtodo para o evento "newindex" (veja 2.4).
lua_setglobal
[-1, +0, e]
void lua_setglobal (lua_State *L, const char *name);
Desempilha um valor da pilha e o estabelece como o novo valor da global name.
lua_setmetatable
[-1, +0, ]
void lua_setmetatable (lua_State *L, int index);
Desempilha uma tabela da pilha e a estabelece como a nova metatabela para o valor no ndice
fornecido.
lua_settable
[-2, +0, e]
void lua_settable (lua_State *L, int index);
Faz o equivalente de t[k] = v, onde t valor no ndice fornecido, v o valor no topo da pilha,
e k valor logo abaixo do topo.
Esta funo desempilha tanto a chave quanto o valor da pilha. Como em Lua, esta funo pode
disparar um metamtodo para o evento "newindex" (veja 2.4).
lua_settop
[-?, +?, ]
void lua_settop (lua_State *L, int index);
Aceita qualquer ndice, ou 0, e estabelece esse ndice como o topo da pilha. Se o novo topo
maior do que o antigo, ento os novos elementos so preenchidos com nil. Se index 0, ento
todos os elementos da pilha so removidos.
lua_setuservalue
[-1, +0, ]
void lua_setuservalue (lua_State *L, int index);
Desempilha uma tabela ou nil da pilha e a estabelece como o novo valor associado ao userdata
no ndice fornecido.
lua_State
typedef struct lua_State lua_State;
Uma estrutura opaca que aponta para um fluxo de execuo e indiretamente (atravs do fluxo)
para o estado inteiro de uma interpretador Lua. A biblioteca Lua totalmente reentrante: ela no
possui variveis globais. Toda informao sobre um estado acessvel atravs desta estrutura.
Um ponteiro para esta estrutura deve ser passado como primeiro argumento para toda funo
na biblioteca, exceto para lua_newstate, que cria um estado Lua a partir do zero.
lua_status
[-0, +0, ]
int lua_status (lua_State *L);
Retorna o estado do fluxo de execuo L.
O estado pode ser 0 (LUA_OK) para um fluxo normal, um cdigo de erro se o fluxo terminou a
execuo de um lua_resume com um erro, ou LUA_YIELD se o fluxo est suspenso.
Voc pode chamar funes somente em fluxos de execuo com estado LUA_OK. Voc pode
retomar fluxos com estado LUA_OK (para comear uma nova co-rotina) ou LUA_YIELD (para
retomar uma co-rotina).
lua_toboolean
[-0, +0, ]
int lua_toboolean (lua_State *L, int index);
Converte um valor Lua no ndice fornecido para um valor booleano C (0 ou 1). Como todos os
testes em Lua, lua_toboolean retorna verdadeiro para qualquer valor Lua diferente
de false e nil; caso contrrio ela retorna falso. (Se voc quiser aceitar somente valores
booleanos de verdade, use lua_isboolean para testar o tipo do valor.)
lua_tocfunction
[-0, +0, ]
lua_CFunction lua_tocfunction (lua_State *L, int index);
Converte um valor no ndice fornecido para uma funo C. Esse valor deve ser uma funo C;
caso contrrio, retorna NULL.
lua_tointeger
[-0, +0, ]
lua_Integer lua_tointeger (lua_State *L, int index);
Equivalente a lua_tointegerx com isnum igual a NULL.
lua_tointegerx
[-0, +0, ]
lua_Integer lua_tointegerx (lua_State *L, int index, int *isnum);
Converte o valor Lua no ndice fornecido para o tipo inteiro com sinal lua_Integer. O valor Lua
deve ser um nmero ou uma cadeia que pode ser convertida para um nmero (veja 3.4.2); caso
contrrio, lua_tointegerx retorna 0.
Se o nmero no um inteiro, ele truncado de alguma maneira no especificada.
Se isnum no NULL, seu referente recebe um valor booleano que indica se a operao foi bem
sucedida.
lua_tolstring
[-0, +0, e]
const char *lua_tolstring (lua_State *L, int index, size_t *len);
Converte o valor Lua no ndice fornecido para uma cadeia C. Se len no NULL, tambm atribui
a *len o comprimento da cadeia. O valor Lua deve ser uma cadeia ou um nmero; caso
contrrio, a funo retorna NULL. Se o valor um nmero, ento lua_tolstring tambm muda o
valor de fato na pilha para uma cadeia. (Essa mudana confunde lua_next quando lua_tolstring
aplicada a chaves durante um percorrimento de tabela.)
lua_tolstring retorna um ponteiro totalmente alinhado para uma cadeia dentro do estado Lua.
Essa cadeia sempre tem um zero ('\0') aps seu ltimo caractere (como em C), mas pode conter
outros zeros em seu corpo. Como Lua tem coleta de lixo, no h garantia de que o ponteiro
retornado por lua_tolstring ser vlido aps o valor correspondente ser removido da pilha.
lua_tonumber
[-0, +0, ]
lua_Number lua_tonumber (lua_State *L, int index);
Equivalente a lua_tonumberx com isnum igual a NULL.
lua_tonumberx
[-0, +0, ]
lua_Number lua_tonumberx (lua_State *L, int index, int *isnum);
Converte o valor Lua no ndice fornecido para o tipo C lua_Number (veja lua_Number). O valor
Lua deve ser um nmero ou uma cadeia que pode ser convertida para um nmero (veja 3.4.2);
caso contrrio, lua_tonumberx retorna 0.
Se isnum no NULL, seu referente recebe um valor booleano que indica se a operao foi bem
sucedida.
lua_topointer
[-0, +0, ]
const void *lua_topointer (lua_State *L, int index);
Converte o valor no ndice fornecido para um ponteiro C genrico (void*). O valor pode ser um
userdata, uma tabela, um fluxo de execuo, ou uma funo; caso
contrrio, lua_topointer retorna NULL. Objetos diferentes iro fornecer ponteiros diferentes. No
h maneira de converter o ponteiro de volta para seu valor original.
Tipicamente esta funo usada somente para informao de depurao.
lua_tostring
[-0, +0, e]
const char *lua_tostring (lua_State *L, int index);
Equivalente a lua_tolstring com len igual a NULL.
lua_tothread
[-0, +0, ]
lua_State *lua_tothread (lua_State *L, int index);
Converte o valor no ndice fornecido para um fluxo de execuo Lua (representado
como lua_State*). Esse valor deve ser um fluxo de execuo; caso contrrio, a funo
retorna NULL.
lua_tounsigned
[-0, +0, ]
lua_Unsigned lua_tounsigned (lua_State *L, int index);
Equivalente a lua_tounsignedx com isnum igual a NULL.
lua_tounsignedx
[-0, +0, ]
lua_Unsigned lua_tounsignedx (lua_State *L, int index, int *isnum);
Converte o valor Lua no ndice fornecido para o tipo inteiro sem sinal lua_Unsigned. O valor Lua
deve ser um nmero ou uma cadeia que pode ser convertida para um nmero. (veja 3.4.2);
caso contrrio, lua_tounsignedx retorna 0.
Se o nmero no um inteiro, ele truncado de alguma maneira no especificada. Se o nmero
est fora do intervalo de valores representveis, ele normalizado para o resto de sua diviso
por um a mais do que o valor representvel mximo.
Se isnum no NULL, seu referente recebe um valor booleano que indica se a operao foi bem
sucedida.
lua_touserdata
[-0, +0, ]
void *lua_touserdata (lua_State *L, int index);
Se o valor no ndice fornecido um userdata completo, retorna o endereo de seu bloco. Se o
valor um userdata leve, retorna seu ponteiro. Caso contrrio, retorna NULL.
lua_type
[-0, +0, ]
int lua_type (lua_State *L, int index);
Retorna o tipo do valor no ndice vlido fornecido, ou LUA_TNONE para um ndice no-vlido
(porm aceitvel). Os tipos retornados por lua_type so codificados pelas seguintes constantes
definidas
em lua.h: LUA_TNIL, LUA_TNUMBER, LUA_TBOOLEAN, LUA_TSTRING, LUA_TTABLE, LUA_TFUNCTIO
N,LUA_TUSERDATA, LUA_TTHREAD, e LUA_TLIGHTUSERDATA.
lua_typename
[-0, +0, ]
const char *lua_typename (lua_State *L, int tp);
Retorna o nome do tipo codificado pelo valor tp, o qual deve ser um dos valores retornados
por lua_type.
lua_Unsigned
typedef unsigned long lua_Unsigned;
O tipo usado pela API de Lua para representar valores inteiros sem sinal. Ele deve ter no mnimo
32 bits.
Por padro ele um unsigned int ou um unsigned long, que podem ambos guardar valores de 32
bits.
lua_upvalueindex
[-0, +0, ]
int lua_upvalueindex (int i);
Retorna o pseudo-ndice que representa o i-simo upvalue da funo que est executando
(veja 4.4).
lua_version
[-0, +0, v]
const lua_Number *lua_version (lua_State *L);
Retorna o endereo do nmero da verso armazenado no ncleo de Lua. Quando chamada com
um lua_State vlido, retorna o endereo da verso usada para criar aquele estado. Quando
chamada com NULL, retorna o endereo da verso executando a chamada.
lua_Writer
typedef int (*lua_Writer) (lua_State *L,
const void* p,
size_t sz,
void* ud);
O tipo da funo de escrita usada por lua_dump. Toda vez que ela produz outro pedao de
trecho, lua_dump chama a funo de escrita, passando junto o buffer a ser escrito (p), seu
tamanho (sz), e o parmetro data fornecido para lua_dump.
A funo de escrita retorna um cdigo de erro: 0 significa sem erros; qualquer outro valor
significa um erro e impede lua_dump de chamar a funo de escrita novamente.
lua_xmove
[-?, +?, ]
void lua_xmove (lua_State *from, lua_State *to, int n);
Troca valores entre diferentes fluxos de execuo do mesmo estado.
Esta funo retira n valores da pilha from, e os coloca na pilha to.
lua_yield
[-?, +?, ]
int lua_yield (lua_State *L, int nresults);
Esta funo equivalente a lua_yieldk, mas ela no possui uma continuao (veja 4.7). Assim,
quando o fluxo de execuo recomea, ela retorna para a funo que chamou a funo
chamando lua_yield.
lua_yieldk
[-?, +?, ]
int lua_yieldk (lua_State *L, int nresults, int ctx, lua_CFunction k);
Cede uma co-rotina.
Esta funo somente deve ser chamada como a expresso de retorno de uma funo C, como a
seguir:
return lua_yieldk (L, n, i, k);
Quando uma funo C chama lua_yieldk dessa maneira, a co-rotina que est executando
suspende sua execuo, e a chamada a lua_resume que iniciou essa co-rotina retorna. O
parmetro nresults o nmero de valores da pilha que so passados como resultados
para lua_resume.
Quando a co-rotina retomada novamente, Lua chama a funo de continuao
fornecida k para continuar a execuo da funo C que cedeu (veja 4.7). Essa funo de
continuao recebe a mesma pilha da funo anterior, com os resultados removidos e
substitudos pelos argumentos passados para lua_resume. Alm disso, a funo de continuao
pode acessar o valor ctx chamando lua_getctx.
4.9 A Interface de Depurao
Lua no possui facilidades de depurao pr-definidas. Ao invs disso, ela oferece uma interface
especial por meio de funes e ganchos. Essa interface permite a construo de diferentes tipos
de depuradores, analisadores dinmicos de programas, e outras ferramentas que precisam de
"informao interna" do interpretador.
lua_Debug
typedef struct lua_Debug {
int event;
const char *name; /* (n) */
const char *namewhat; /* (n) */
const char *what; /* (S) */
const char *source; /* (S) */
int currentline; /* (l) */
int linedefined; /* (S) */
int lastlinedefined; /* (S) */
unsigned char nups; /* (u) nmero de upvalues */
unsigned char nparams; /* (u) nmero de parmetros */
char isvararg; /* (u) */
char istailcall; /* (t) */
char short_src[LUA_IDSIZE]; /* (S) */
/* parte privada */
outros campos
} lua_Debug;
Uma estrutura usada para guardar pedaos diferentes de informao sobre uma funo ou um
registro de ativao. lua_getstack preenche somente a parte privada dessa estrutura, para uso
posterior. Para preencher os outros campos de lua_Debug com informao til,
chame lua_getinfo.
Os campos de lua_Debug possuem o seguinte significado:
source: a fonte do trecho que criou a funo. Se source comea com um '@', significa
que a funo foi definida em um arquivo onde o nome do arquivo vem depois do '@'.
Se source comea com um '=', o resto de seu contedo descreve a fonte de uma maneira
que depende do usurio. Caso contrrio, a funo foi definida em uma cadeia
 onde source essa cadeia.
short_src: uma verso "imprimvel" de source, para ser usada em mensagens de erro.
linedefined: o nmero da linha onde a definio da funo comea.
lastlinedefined: o nmero da linha onde a definio da funo termina.
what: a cadeia "Lua" se a funo uma funo Lua, "C" se ela uma funo C, "main" se
ela a parte principal de um trecho.
currentline: a linha corrente onde a funo dada est executando. Quando nenhuma
informao sobre a linha est disponvel, currentline recebe -1.
name: um nome razovel para a funo dada. Como funes em Lua so valores de
primeira classe, elas no possuem um nome fixo: algumas funes podem ser o valor de
mltiplas variveis globais, enquanto outras podem estar armazenadas somente em um
campo de uma tabela. A funo lua_getinfo verifica como a funo foi chamada para
encontrar um nome adequado. Se ela no consegue encontrar um nome,
ento name recebe NULL.
namewhat: explica o campo name. O valor de namewhat pode
ser "global", "local", "method", "field", "upvalue", ou "" (a cadeia vazia), de acordo com
como a funo foi chamada. (Lua usa a cadeia vazia quando nenhum outra opo parece
se aplicar.)
istailcall: verdadeiro se esta invocao de funo foi chamada por uma chamada final.
Nesse caso, o chamador deste nvel no est na pilha.
nups: o nmero de upvalues da funo.
nparams: o nmero de parmetros fixo da funo (sempre 0 para funes C).
isvararg: verdadeiro se a funo uma funo vararg. (sempre verdadeiro para
funes C).
lua_gethook
[-0, +0, ]
lua_Hook lua_gethook (lua_State *L);
Retorna a funo de gancho corrente.
lua_gethookcount
[-0, +0, ]
int lua_gethookcount (lua_State *L);
Retorna a contagem do gancho corrente.
lua_gethookmask
[-0, +0, ]
int lua_gethookmask (lua_State *L);
Retorna a mscara do gancho corrente.
lua_getinfo
[-(0|1), +(0|1|2), e]
int lua_getinfo (lua_State *L, const char *what, lua_Debug *ar);
Obtm informao sobre uma funo ou invocao de funo especfica.
Para obter informao sobre uma invocao de funo, o parmetro ar deve ser um registro de
ativao vlido que foi preenchido por uma chamada anterior a lua_getstack ou fornecido como
argumento para um gancho (veja lua_Hook).
Para obter informao sobre uma funo voc a coloca na pilha e inicia a cadeia what com o
caractere '>'. (Nesse caso, lua_getinfo desempilha a funo do topo da pilha.) Por exemplo, para
saber em qual linha uma funo f foi definida, voc pode escrever o cdigo a seguir:
lua_Debug ar;
lua_getglobal(L, "f"); /* obtm 'f' global */
lua_getinfo(L, ">S", &ar);
printf("%d\n", ar.linedefined);
Cada caractere na cadeia what seleciona alguns campos da estrutura ar a serem preenchidos ou
um valor a ser colocado na pilha:
'n': preenche os campos name e namewhat;
'S': preenche os campos source, short_src, linedefined, lastlinedefined, e what;
'l': preenche o campo currentline;
't': preenche o campo istailcall;
 'u': preenche os campos nups, nparams, e isvararg;
'f': coloca na pilha a funo que est executando no nvel fornecido;
'L': coloca na pilha uma tabela cujos ndices so os nmeros das linhas que so vlidas na
funo. (Uma linha vlida uma linha com algum cdigo associado, isto , uma linha onde
voc pode colocar um ponto de parada. Linhas no vlidas incluem linhas vazias e
comentrios.)
Esta funo retorna 0 em caso de erro (por exemplo, um opo invlida em what).
lua_getlocal
[-0, +(0|1), ]
const char *lua_getlocal (lua_State *L, lua_Debug *ar, int n);
Obtm informao sobre uma varivel local de um dado registro de ativao ou de uma dada
funo.
No primeiro caso, o parmetro ar dever ser um registro de ativao vlido que foi preenchido por
uma chamada anterior a lua_getstack ou fornecido como um argumento para um gancho
(veja lua_Hook). O ndice n seleciona qual varivel local inspecionar; veja debug.getlocal para
detalhes sobre ndices e nomes de variveis.
lua_getlocal coloca o valor da varivel na pilha e retorna o nome dela.
No segundo caso, ar deve ser NULL e a funo a ser inspecionada deve estar no topo da pilha.
Nesse caso, somente parmetros de funes Lua so visveis (pois no h informao sobre
quais variveis esto ativas) e nenhum valor colocado na pilha.
Retorna NULL (e no empilha nada) quando o ndice maior do que o nmero de variveis locais
ativas.
lua_getstack
[-0, +0, ]
int lua_getstack (lua_State *L, int level, lua_Debug *ar);
Obtm informao sobre a pilha de tempo de execuo do interpretador.
Esta funo preenche partes de uma estrutura lua_Debug com uma identificao do registro de
ativao da funo executando em um dado nvel. O nvel 0 a funo executando atualmente,
enquanto que o nvel n+1 a funo que chamou o nvel n (exceto para chamadas finais, que
no contam com a pilha). Quando no h erros, lua_getstack retorna 1; quando chamada com
um nvel maior do que a profundidade da pilha, retorna 0.
lua_getupvalue
[-0, +(0|1), ]
const char *lua_getupvalue (lua_State *L, int funcindex, int n);
Obtm informao sobre um upvalue de um fecho. (Para funes Lua, upvalues so as variveis
locais externas que a funo usa, e que so consequentemente includas em seu
fecho.) lua_getupvalue obtm o ndice n de um upvalue, coloca o valor do upvalue na pilha, e
retorna o nome dele.funcindex aponta para o fecho na pilha. (Upvalues no possuem uma ordem
particular, pois eles esto ativos durante a funo inteira. Assim, eles so numerados em uma
ordem arbitrria.)
Retorna NULL (e no empilha nada) quando o ndice maior do que o nmero de upvalues. Para
funes C, esta funo usa a cadeia vazia "" como um nome para todos os upvalues.
lua_Hook
typedef void (*lua_Hook) (lua_State *L, lua_Debug *ar);
O tipo para funes de gancho de depurao.
Sempre que um gancho chamado, o campo event de seu argumento ar recebe o evento
especfico que disparou o gancho. Lua identifica esses eventos com as seguintes
constantes: LUA_HOOKCALL, LUA_HOOKRET, LUA_HOOKTAILCALL, LUA_HOOKLINE,
e LUA_HOOKCOUNT. Alm disso, para eventos de linha, o campo currentline tambm
determinado. Para obter o valor de qualquer outro campo em ar, o gancho deve
chamar lua_getinfo.
Para eventos de chamada, event pode ser LUA_HOOKCALL, o valor normal,
ou LUA_HOOKTAILCALL, para uma recurso final; neste caso, no haver nenhum evento de
retorno correspondente.
Enquanto Lua est executando um gancho, ela desabilita outras chamadas a ganchos. Assim, se
um gancho chama Lua de volta para executar uma funo ou um gancho, essa execuo ocorre
sem quaisquer chamadas a ganchos.
Funes de gancho no podem ter continuaes, isto , elas no podem
chamar lua_yieldk, lua_pcallk, ou lua_callk com um k no nulo.
Funes de gancho podem ceder sob as seguintes condies: Somente eventos de contagem e
de linha podem ceder e eles no podem produzir nenhum valor; para ceder uma funo de
gancho deve terminar sua execuo chamando lua_yield com nresults igual a zero.
lua_sethook
[-0, +0, ]
int lua_sethook (lua_State *L, lua_Hook f, int mask, int count);
Estabelece a funo de gancho de depurao.
O argumento f a funo de gancho. mask especifica sobre quais eventos o gancho ser
chamado: ele formado por uma conjuno bit a bit das
contantesLUA_MASKCALL, LUA_MASKRET, LUA_MASKLINE, e LUA_MASKCOUNT. O
argumento count somente possui significado quando a mscara inclui LUA_MASKCOUNT. Para
cada evento, o gancho chamado como explicado abaixo:
O gancho de chamada: chamado quando o interpretador chama uma funo. O
gancho chamado logo aps Lua entrar na nova funo, antes da funo receber seus
argumentos.
O gancho de retorno: chamado quando o interpretador retorna de uma funo. O
gancho chamado logo antes de Lua sair da funo. No h uma maneira padro de
acessar os valores retornados pela funo.
O gancho de linha: chamado quando o interpretador est para comear a execuo de
uma nova linha de cdigo, ou quando ele faz um desvio para trs no cdigo (mesmo que
seja para a mesma linha). (Este evento somente acontece quando Lua est executando
uma funo Lua.)
O gancho de contagem: chamado aps o interpretador executar cada uma das
instrues count. (Este evento somente acontece quando Lua est executando uma
funo Lua.)
Um gancho desabilitado atribuindo-se zero a mask.
lua_setlocal
[-(0|1), +0, ]
const char *lua_setlocal (lua_State *L, lua_Debug *ar, int n);
Estabelece o valor de uma varivel local de um dado registro de ativao. Os
parmetros ar e n so como em lua_getlocal (veja lua_getlocal).lua_setlocal atribui o valor no
topo da pilha varivel e retorna o nome dela. Tambm desempilha o valor da pilha.
Retorna NULL (e no desempilha nada) quando o ndice maior do que o nmero de variveis
locais ativas.
lua_setupvalue
[-(0|1), +0, ]
const char *lua_setupvalue (lua_State *L, int funcindex, int n);
Estabelece o valor de um upvalue de um fecho. Atribui o valor no topo da pilha ao upvalue e
retorna o nome dele. Tambm desempilha o valor da pilha. Os parmetros funcindex e n so
como em lua_getupvalue (veja lua_getupvalue).
Retorna NULL (e no desempilha nada) quando o ndice maior que o nmero de upvalues.
lua_upvalueid
[-0, +0, ]
void *lua_upvalueid (lua_State *L, int funcindex, int n);
Retorna um identificador nico para o upvalue de nmero n do fecho no ndice funcindex. Os
parmetros funcindex e n so como em lua_getupvalue(veja lua_getupvalue) (mas n no pode
ser maior do que o nmero de upvalues).
Esses identificadores nicos permitem ao programa verificar se fechos diferentes compartilham
upvalues. Fechos Lua que compartilham um upvalue (isto , que acessam a mesma varivel
local externa) retornaro identificadores idnticos para esses ndices de upvalue.
lua_upvaluejoin
[-0, +0, ]
void lua_upvaluejoin (lua_State *L, int funcindex1, int n1,
int funcindex2, int n2);
Faz o n1-simo upvalue do fecho Lua no ndice funcindex1 se referir ao n2-simo upvalue do
fecho Lua no ndice funcindex2.
5 A Biblioteca Auxiliar
A biblioteca auxiliar oferece vrias funes convenientes para interfacear C com Lua. Enquanto a
API bsica oferece funes primitivas para todas as interaes entre C e Lua, a biblioteca auxiliar
oferece funes de mais alto nvel para algumas tarefas comuns.
Todas as funes e tipos da biblioteca auxiliar esto definidos no arquivo de
cabealho lauxlib.h e possuem um prefixo luaL_.
Todas as funes na biblioteca auxiliar so construdas em cima da API bsica, e portanto elas
no oferecem nada que no possa ser feito com essa API. Apesar disso, o uso da biblioteca
auxiliar garante mais consistncia para seu cdigo.
Vrias funes na biblioteca auxiliar usam internamente alguns espaos extras de pilha. Quando
uma funo na biblioteca auxiliar usa menos do que cinco espaos, ela no verifica o tamanho
da pilha; ela simplesmente assume que h espaos suficientes.
Vrias funes na biblioteca auxiliar so usadas para verificar argumentos de funes C. Como a
mensagem de erro formatada para argumentos (e.g., "argumento ruim #1"), voc no deve
usar essas funes para outros valores da pilha.
Funes chamadas luaL_check* sempre lanam um erro se a verificao no satisfeita.
5.1 Funes e Tipos
Aqui listamos todas as funes e tipos da biblioteca auxiliar em ordem alfabtica.
luaL_addchar
[-?, +?, e]
void luaL_addchar (luaL_Buffer *B, char c);
Adiciona o byte c ao buffer B (veja luaL_Buffer).
luaL_addlstring
[-?, +?, e]
void luaL_addlstring (luaL_Buffer *B, const char *s, size_t l);
Adiciona a cadeia apontada por s com comprimento l ao buffer B (veja luaL_Buffer). A cadeia
pode conter zeros dentro dela.
luaL_addsize
[-?, +?, e]
void luaL_addsize (luaL_Buffer *B, size_t n);
Adiciona ao buffer B (veja luaL_Buffer) uma cadeia de comprimento n copiada anteriormente
para a rea do buffer (veja luaL_prepbuffer).
luaL_addstring
[-?, +?, e]
void luaL_addstring (luaL_Buffer *B, const char *s);
Adiciona a cadeia terminada por zero apontada por s ao buffer B (veja luaL_Buffer). A cadeia no
pode conter zeros dentro dela.
luaL_addvalue
[-1, +?, e]
void luaL_addvalue (luaL_Buffer *B);
Adiciona o valor no topo da pilha ao buffer B (veja luaL_Buffer). Desempilha o valor.
Esta a nica funo sobre buffers de cadeias que pode (e deve) ser chamada com um
elemento extra na pilha, o qual o valor a ser adicionado ao buffer.
luaL_argcheck
[-0, +0, v]
void luaL_argcheck (lua_State *L,
int cond,
int arg,
const char *extramsg);
Verifica se cond verdadeira. Se no, lana um erro com uma mensagem padro.
luaL_argerror
[-0, +0, v]
int luaL_argerror (lua_State *L, int arg, const char *extramsg);
Lana um erro com uma mensagem de erro padro que inclui extramsg como um comentrio.
Esta funo nunca retorna, mas idiomtico us-la em funes C como return
luaL_argerror(args).
luaL_Buffer
typedef struct luaL_Buffer luaL_Buffer;
O tipo para um buffer de cadeia.
Um buffer de cadeia permite cdigo C construir cadeias Lua pouco a pouco. Seu padro de uso
como a seguir:
Primeiro declare uma varivel b do tipo luaL_Buffer.
Em seguida inicialize-a com uma chamada luaL_buffinit(L, &b).
Depois adicione pedaos da cadeia ao buffer chamando qualquer uma das
funes luaL_add*.
Finalmente chame luaL_pushresult(&b). Essa chamada deixa a cadeia final no topo da
pilha.
Se voc sabe de antemo o tamanho total da cadeia resultante, voc pode usar o buffer assim:
Primeiro declare uma varivel b do tipo luaL_Buffer.
Em seguida inicialize-a e pr-aloque um espao de tamanho sz com uma
chamada luaL_buffinitsize(L, &b, sz).
Depois copie a cadeia para esse espao.
Termine chamando luaL_pushresultsize(&b, sz), onde sz o tamanho total da cadeia
resultante copiada para esse espao.
Durante sua operao normal, um buffer de cadeia usa um nmero varivel de espaos de pilha.
Assim, ao usar um buffer, voc no pode assumir que voc sabe onde o topo da pilha est. Voc
pode usar a pilha entre chamadas sucessivas s operaes de buffer desde que esse uso seja
balanceado; isto , quando voc chama uma operao de buffer, a chamada est no mesmo
nvel que ela estava imediatamente aps a operao de buffer anterior. (A nica exceo a esta
regra luaL_addvalue.) Aps chamar luaL_pushresult a pilha volta ao nvel que ela estava
quando o buffer foi inicializado, mais a cadeia final no seu topo.
luaL_buffinit
[-0, +0, ]
void luaL_buffinit (lua_State *L, luaL_Buffer *B);
Inicializa um buffer B. Esta funo no alocar nenhum espao; o buffer deve ser declarado como
uma varivel (veja luaL_Buffer).
luaL_buffinitsize
[-?, +?, e]
char *luaL_buffinitsize (lua_State *L, luaL_Buffer *B, size_t sz);
Equivalente sequncia luaL_buffinit, luaL_prepbuffsize.
luaL_callmeta
[-0, +(0|1), e]
int luaL_callmeta (lua_State *L, int obj, const char *e);
Chama um metamtodo.
Se o objeto no ndice obj tem uma metatabela e essa metatabela tem um campo e, esta funo
chama esse campo passando o objeto como seu nico argumento. Nesse caso esta funo
retorna verdadeiro e coloca na pilha o valor retornado pela chamada. Se no h metatabela ou
metamtodo, esta funo retorna falso (sem colocar nenhum valor na pilha).
luaL_checkany
[-0, +0, v]
void luaL_checkany (lua_State *L, int arg);
Verifica se a funo possui um argumento de qualquer tipo (incluindo nil) na posio arg.
luaL_checkint
[-0, +0, v]
int luaL_checkint (lua_State *L, int arg);
Verifica se o argumento arg da funo um nmero e retorna esse nmero convertido para
um int.
luaL_checkinteger
[-0, +0, v]
lua_Integer luaL_checkinteger (lua_State *L, int arg);
Verifica se o argumento arg da funo um nmero e retorna esse nmero convertido para
um lua_Integer.
luaL_checklong
[-0, +0, v]
long luaL_checklong (lua_State *L, int arg);
Verifica se o argumento arg da funo um nmero e retorna esse nmero convertido para
um long.
luaL_checklstring
[-0, +0, v]
const char *luaL_checklstring (lua_State *L, int arg, size_t *l);
Verifica se o argumento arg da funo uma cadeia e retorna essa cadeia; se l no
NULL preenche *l com o comprimento da cadeia.
Esta funo usa lua_tolstring para obter seu resultado, assim todas as converses e cuidados
dessa funo se aplicam aqui.
luaL_checknumber
[-0, +0, v]
lua_Number luaL_checknumber (lua_State *L, int arg);
Verifica se o argumento arg da funo um nmero e retorna esse nmero.
luaL_checkoption
[-0, +0, v]
int luaL_checkoption (lua_State *L,
int arg,
const char *def,
const char *const lst[]);
Verifica se o argumento arg da funo uma cadeia e procura por essa cadeia no array lst (que
deve ser terminado por NULL). Retorna o ndice no array onde a cadeia foi encontrada. Lana um
erro se o argumento no uma cadeia ou se a cadeia no pode ser encontrada.
Se def no NULL, a funo usa def como um valor padro quando no h argumento arg ou
quando esse argumento nil.
Esta uma funo til para mapear cadeias para enumeraes de C. (A conveno usual em
bibliotecas Lua usar cadeias ao invs de nmeros para selecionar opes.)
luaL_checkstack
[-0, +0, v]
void luaL_checkstack (lua_State *L, int sz, const char *msg);
Aumenta o tamanho da pilha para top + sz elementos, lanando um erro se a pilha no pode
aumentar para esse tamanho. msg um texto adicional a ser colocado na mensagem de erro
(ou NULL para nenhum texto adicional).
luaL_checkstring
[-0, +0, v]
const char *luaL_checkstring (lua_State *L, int arg);
Verifica se o argumento arg da funo uma cadeia e retorna essa cadeia.
Esta funo usa lua_tolstring para obter seu resultado, assim todas as converses e cuidados
relacionados a essa funo se aplicam aqui.
luaL_checktype
[-0, +0, v]
void luaL_checktype (lua_State *L, int arg, int t);
Verifica se o argumento arg da funo tem tipo t. Veja lua_type para a codificao de tipos
para t.
luaL_checkudata
[-0, +0, v]
void *luaL_checkudata (lua_State *L, int arg, const char *tname);
Verifica se o argumento arg da funo um userdata do tipo tname (veja luaL_newmetatable) e
retorna o endereo do userdata (veja lua_touserdata).
luaL_checkunsigned
[-0, +0, v]
lua_Unsigned luaL_checkunsigned (lua_State *L, int arg);
Verifica se o argumento arg da funo um nmero e retorna esse nmero convertido para
um lua_Unsigned.
luaL_checkversion
[-0, +0, ]
void luaL_checkversion (lua_State *L);
Verifica se o ncleo executando a chamada, o ncleo que criou o estado Lua, e o cdigo fazendo
a chamada esto todos usando a mesma verso de Lua. Tambm verifica se o ncleo
executando a chamada e o ncleo que criou o estado Lua esto usando o mesmo espao de
endereos.
luaL_dofile
[-0, +?, e]
int luaL_dofile (lua_State *L, const char *filename);
Carrega e executa o arquivo fornecido. Ela definida como a seguinte macro:
(luaL_loadfile(L, filename) || lua_pcall(L, 0, LUA_MULTRET, 0))
Retorna falso se no h erros ou verdadeiro em caso de erros.
luaL_dostring
[-0, +?, ]
int luaL_dostring (lua_State *L, const char *str);
Carrega e executa a cadeia fornecida. Ela definida como a seguinte macro:
(luaL_loadstring(L, str) || lua_pcall(L, 0, LUA_MULTRET, 0))
Retorna false se no h erros ou verdadeiro em caso de erros.
luaL_error
[-0, +0, v]
int luaL_error (lua_State *L, const char *fmt, ...);
Lana um erro. O formato da mensagem de erro dado por fmt mais quaisquer argumentos
extras, seguindo as mesmas regras de lua_pushfstring. Tambm adiciona no comeo da
mensagem de erro o nome do arquivo e o nmero da linha onde o erro ocorreu, se essa
informao est disponvel.
Esta funo nunca retorna, mas idiomtico us-la em funes C como return luaL_error(args).
luaL_execresult
[-0, +3, e]
int luaL_execresult (lua_State *L, int stat);
Esta funo produz os valores retornados por funes relacionadas a processos na biblioteca
padro (os.execute e io.close).
luaL_fileresult
[-0, +(1|3), e]
int luaL_fileresult (lua_State *L, int stat, const char *fname);
Esta funo produz os valores retornados por funes relacionadas a arquivos na biblioteca
padro (io.open, os.rename, file:seek, etc.).
luaL_getmetafield
[-0, +(0|1), e]
int luaL_getmetafield (lua_State *L, int obj, const char *e);
Coloca na pilha o campo e da metatabela do objeto no ndice obj. Se o objeto no tem uma
metatabela, ou se a metatabela no tem esse campo, retorna falso e no empilha nada.
luaL_getmetatable
[-0, +1, ]
void luaL_getmetatable (lua_State *L, const char *tname);
Coloca na pilha a metatabela associada com o nome tname no registro
(veja luaL_newmetatable).
luaL_getsubtable
[-0, +1, e]
int luaL_getsubtable (lua_State *L, int idx, const char *fname);
Garante que o valor t[fname], onde t o valor no ndice idx, uma tabela, e coloca essa tabela
na pilha. Retorna verdadeiro se encontra uma tabela anterior l e falso se cria uma nova tabela.
luaL_gsub
[-0, +1, e]
const char *luaL_gsub (lua_State *L,
const char *s,
const char *p,
const char *r);
Cria uma cpia da cadeia s substituindo qualquer ocorrncia da cadeia p com a cadeia r. Coloca
a cadeia resultante na pilha e a retorna.
luaL_len
[-0, +0, e]
int luaL_len (lua_State *L, int index);
Retorna o "comprimento" do valor no ndice fornecido como um nmero; equivalente ao
operador '#' em Lua (veja 3.4.6). Lana um erro se o resultado da operao no um nmero.
(Esse caso somente pode acontecer atravs de metamtodos.)
luaL_loadbuffer
[-0, +1, ]
int luaL_loadbuffer (lua_State *L,
const char *buff,
size_t sz,
const char *name);
Equivalente a luaL_loadbufferx com mode igual a NULL.
luaL_loadbufferx
[-0, +1, ]
int luaL_loadbufferx (lua_State *L,
const char *buff,
size_t sz,
const char *name,
const char *mode);
Carrega um buffer como um trecho Lua. Esta funo usa lua_load para carregar o trecho no
buffer apontado por buff com tamanho sz.
Esta funo retorna os mesmos resultados de lua_load. name o nome do trecho, usado para
informao de depurao e mensagens de erro. A cadeia mode funciona como na
funo lua_load.
luaL_loadfile
[-0, +1, e]
int luaL_loadfile (lua_State *L, const char *filename);
Equivalente a luaL_loadfilex com mode igual a NULL.
luaL_loadfilex
[-0, +1, e]
int luaL_loadfilex (lua_State *L, const char *filename,
const char *mode);
Carrega um arquivo como um trecho Lua. Esta funo usa lua_load para carregar o trecho no
arquivo chamado filename. Se filename NULL, ento ela carrega a partir da entrada padro. A
primeira linha no arquivo ignorada se ela comea com um #.
A cadeia mode funciona como na funo lua_load.
Esta funo retorna os mesmos resultados de lua_load, mas ela possui um cdigo de erro
extra LUA_ERRFILE se ela no pode abrir/ler o arquivo ou o arquivo tem um modo errado.
Como lua_load, esta funo somente carrega o trecho; ela no o executa.
luaL_loadstring
[-0, +1, ]
int luaL_loadstring (lua_State *L, const char *s);
Carrega uma cadeia como um trecho Lua. Esta funo usa lua_load para carregar o trecho na
cadeia terminada por zero s.
Esta funo retorna os mesmos resultados de lua_load.
Tambm como lua_load, esta funo somente carrega o trecho; ela no o executa.
luaL_newlib
[-0, +1, e]
void luaL_newlib (lua_State *L, const luaL_Reg *l);
Cria uma nova tabela e registra l as funes na lista l. Ela implementada como a seguinte
macro:
(luaL_newlibtable(L,l), luaL_setfuncs(L,l,0))
luaL_newlibtable
[-0, +1, e]
void luaL_newlibtable (lua_State *L, const luaL_Reg l[]);
Cria uma nova tabela com um tamanho otimizado para armazenar todas as entradas no
array l (mas no as armazena de fato). planejada para ser usada em conjuno
com luaL_setfuncs (veja luaL_newlib).
implementada como uma macro. O array l deve ser o array de fato, no um ponteiro para ele.
luaL_newmetatable
[-0, +1, e]
int luaL_newmetatable (lua_State *L, const char *tname);
Se o registro j tem a chave tname, retorna 0. Caso contrrio, cria uma nova tabela para ser
usada como uma metatabela para userdata, adiciona-a ao registro com chave tname, e retorna
1.
Em ambos os casos coloca na pilha o valor final associado com tname no registro.
luaL_newstate
[-0, +0, ]
lua_State *luaL_newstate (void);
Cria um novo estado Lua. Chama lua_newstate com um alocador baseado na funo realloc de
C padro e ento estabelece uma funo de pnico (veja 4.6) que imprime uma mensagem de
erro para a sada de erro padro em caso de erros fatais.
Retorna o novo estado, ou NULL se h um erro de alocao de memria.
luaL_openlibs
[-0, +0, e]
void luaL_openlibs (lua_State *L);
Abre todas as bibliotecas Lua padro no estado fornecido.
luaL_optint
[-0, +0, v]
int luaL_optint (lua_State *L, int arg, int d);
Se o argumento arg da funo um nmero, retorna esse nmero convertido para um int. Se
esse argumento est ausente ou nil, retorna d. Caso contrrio, lana um erro.
luaL_optinteger
[-0, +0, v]
lua_Integer luaL_optinteger (lua_State *L,
int arg,
lua_Integer d);
Se o argumento arg da funo um nmero, retorna esse nmero convertido para
um lua_Integer. Se esse argumento est ausente ou nil, retorna d. Caso contrrio, lana um
erro.
luaL_optlong
[-0, +0, v]
long luaL_optlong (lua_State *L, int arg, long d);
Se o argumento arg da funo um nmero, retorna esse nmero convertido para um long. Se
esse argumento est ausente ou nil, retorna d. Caso contrrio, lana um erro.
luaL_optlstring
[-0, +0, v]
const char *luaL_optlstring (lua_State *L,
int arg,
const char *d,
size_t *l);
Se o argumento arg da funo uma cadeia, retorna essa cadeia. Se esse argumento est
ausente ou nil, retorna d. Caso contrrio, lana um erro.
Se l no NULL, preenche a posio *l com o comprimento do resultado.
luaL_optnumber
[-0, +0, v]
lua_Number luaL_optnumber (lua_State *L, int arg, lua_Number d);
Se o argumento arg da funo um nmero, retorna esse nmero. Se esse argumento est
ausente ou nil, retorna d. Caso contrrio, lana um erro.
luaL_optstring
[-0, +0, v]
const char *luaL_optstring (lua_State *L,
int arg,
const char *d);
Se o argumento arg da funo uma cadeia, retorna essa cadeia. Se esse argumento est
ausente ou nil, retorna d. Caso contrrio, lana um erro.
luaL_optunsigned
[-0, +0, v]
lua_Unsigned luaL_optunsigned (lua_State *L,
int arg,
lua_Unsigned u);
Se o argumento arg da funo um nmero, retorna esse nmero convertido para
um lua_Unsigned. Se esse argumento est ausente ou nil, retorna u. Caso contrrio, lana um
erro.
luaL_prepbuffer
[-?, +?, e]
char *luaL_prepbuffer (luaL_Buffer *B);
Equivalente a luaL_prepbuffsize com o tamanho pr-definido LUAL_BUFFERSIZE.
luaL_prepbuffsize
[-?, +?, e]
char *luaL_prepbuffsize (luaL_Buffer *B, size_t sz);
Retorna um endereo para um espao de tamanho sz onde voc pode copiar uma cadeia a ser
adicionada ao buffer B (veja luaL_Buffer). Aps copiar a cadeia nesse espao voc deve
chamar luaL_addsize com o tamanho da cadeia para realmente adicion-la ao buffer.
luaL_pushresult
[-?, +1, e]
void luaL_pushresult (luaL_Buffer *B);
Finaliza o uso do buffer B deixando a cadeia final no topo da pilha.
luaL_pushresultsize
[-?, +1, e]
void luaL_pushresultsize (luaL_Buffer *B, size_t sz);
Equivalente sequncia luaL_addsize, luaL_pushresult.
luaL_ref
[-1, +0, e]
int luaL_ref (lua_State *L, int t);
Cria e retorna uma referncia, na tabela no ndice t, para o objeto no topo da pilha (e
desempilha o objeto).
Uma referncia uma chave inteira nica. Contanto que voc no adicione manualmente
chaves inteiras na tabela t, luaL_ref garante a unicidade da chave que ela retorna. Voc pode
recuperar um objeto referenciado pela referncia r chamando lua_rawgeti(L, t, r). A
funo luaL_unref libera uma referncia e o objeto associado a ela.
Se o objeto no topo da pilha nil, luaL_ref retorna a constante LUA_REFNIL. A
constante LUA_NOREF garantidamente diferente de qualquer referncia retornada por luaL_ref.
luaL_Reg
typedef struct luaL_Reg {
const char *name;
 lua_CFunction func;
} luaL_Reg;
O tipo para arrays de funes a serem registradas por luaL_setfuncs. name o nome da funo
e func um ponteiro para a funo. Qualquer array de luaL_Reg deve terminar com uma entrada
sentinela na qual tanto name como func so NULL.
luaL_requiref
[-0, +1, e]
void luaL_requiref (lua_State *L, const char *modname,
lua_CFunction openf, int glb);
Chama a funo openf com a cadeia modname como um argumento e atribui
a package.loaded[modname] o resultado da chamada, como se essa funo tivesse sido
chamada atravs de require.
Se glb verdadeiro, tambm armazena o resultado na global modname.
Deixa uma cpia desse resultado na pilha.
luaL_setfuncs
[-nup, +0, e]
void luaL_setfuncs (lua_State *L, const luaL_Reg *l, int nup);
Registra todas as funes no array l (veja luaL_Reg) na tabela no topo da pilha (abaixo de
upvalues opcionais, veja a seguir).
Quando nup no zero, todas as funes so criadas compartilhando nup upvalues, os quais
devem ser colocados previamente no topo da pilha da tabela da biblioteca. Esses valores so
retirados da pilha aps o registro.
luaL_setmetatable
[-0, +0, ]
void luaL_setmetatable (lua_State *L, const char *tname);
Estabelece a metatabela do objeto no topo da pilha como a metatabela associada com o
nome tname no registro (veja luaL_newmetatable).
luaL_testudata
[-0, +0, e]
void *luaL_testudata (lua_State *L, int arg, const char *tname);
Esta funo funciona como luaL_checkudata, exceto pelo fato de que, quando o teste falha, ela
retorna NULL ao invs de lanar um erro.
luaL_tolstring
[-0, +1, e]
const char *luaL_tolstring (lua_State *L, int idx, size_t *len);
Converte qualquer valor Lua no ndice fornecido para uma cadeia C em um formato razovel. A
cadeia resultante colocada na pilha e tambm retornada pela funo. Se len no NULL, a
funo tambm atribui a *len o comprimento da cadeia.
Se o valor possui uma metatabela com um campo "__tostring", ento luaL_tolstring chama o
metamtodo correspondente com o valor como argumento, e usa o resultado da chamada como
resultado dela.
luaL_traceback
[-0, +1, e]
void luaL_traceback (lua_State *L, lua_State *L1, const char *msg,
int level);
Cria e coloca um trao na pilha L1. Se msg no NULL ela acrescentada ao incio do trao. O
parmetro level diz em qual nvel comear o trao.
luaL_typename
[-0, +0, ]
const char *luaL_typename (lua_State *L, int index);
Retorna o nome do tipo do valor no ndice fornecido.
luaL_unref
[-0, +0, ]
void luaL_unref (lua_State *L, int t, int ref);
Libera a referncia ref da tabela no ndice t (veja luaL_ref). A entrada removida da tabela, de
modo que o objeto referenciado pode ser coletado. A referncia ref tambm liberada para ser
usada novamente.
Se ref LUA_NOREF ou LUA_REFNIL, luaL_unref no faz nada.
luaL_where
[-0, +1, e]
void luaL_where (lua_State *L, int lvl);
Coloca na pilha uma cadeia identificando a posio corrente do controle no nvel lvl na pilha de
chamadas. Tipicamente essa cadeia possui o seguinte formato:
nometrecho:linhacorrente:
O Nvel 0 a funo executando, o Nvel 1 a funo que chamou a funo executando, etc.
Esta funo usada para construir um prefixo para mensagens de erro.
6 Bibliotecas Padro
As bibliotecas padro de Lua oferecem funes teis que so implementadas diretamente
atravs da API C. Algumas dessas funes oferecem servios essenciais para a linguagem
(e.g., type e getmetatable); outras oferecem acesso a servios "externos" (e.g., I/O); e outras
poderiam ser implementadas em Lua mesmo, mas so bastante teis ou possuem exigncias de
desempenho crticas que merecem uma implementao em C (e.g., table.sort).
Todas as bibliotecas so implementadas atravs da API C oficial e so oferecidas como
mdulos C separados. Atualmente, Lua possui as seguintes bibliotecas padro:
biblioteca bsica (6.1);
biblioteca de co-rotinas (6.2);
biblioteca de pacotes (6.3);
manipulao de cadeias (6.4);
manipulao de tabelas (6.5);
funes matemticas (6.6) (sin, log, etc.);
operaes bit a bit (6.7);
entrada e sada (6.8);
facilidades do sistema operacional (6.9);
facilidades de depurao (6.10).
Exceto pelas bibliotecas bsica e de pacotes, cada biblioteca oferece todas as suas funes
como campos de uma tabela global ou como mtodos de seus objetos.
Para ter acesso a essas bibliotecas, o programa hospedeiro C deve chamar a
funo luaL_openlibs, que abre todas as bibliotecas padro. Alternativamente, o programa
hospedeiro pode abri-las individualmente usando luaL_requiref para chamar luaopen_base (para
a biblioteca bsica),luaopen_package (para a biblioteca de pacotes), luaopen_coroutine (para a
biblioteca de co-rotinas), luaopen_string (para a biblioteca de cadeias),luaopen_table (para a
biblioteca de tabelas), luaopen_math (para a biblioteca matemtica), luaopen_bit32 (para a
biblioteca de bits), luaopen_io (para a biblioteca de E/S), luaopen_os (para a biblioteca do
Sistema Operacional), e luaopen_debug (para a biblioteca de depurao). Essas funes esto
declaradas em lualib.h.
6.1 Funes Bsicas
A biblioteca bsica oferece funes essenciais para Lua. Se voc no incluir esta biblioteca em
sua aplicao, voc deve verificar cuidadosamente se voc precisa oferecer implementaes
para algumas de suas facilidades.
assert (v [, message])
Produz um erro quando o valor de seu argumento v falso (i.e., nil ou false); caso contrrio,
retorna todos os seus argumentos. message uma mensagem de erro; quando ausente, a
mensagem padro "assertion failed!"
collectgarbage ([opt [, arg]])
Esta funo interface genrica para o coletor de lixo. Ela realiza funes diferentes de acordo
com o seu primeiro argumento, opt:
"collect": realiza um ciclo de coleta de lixo completo. Esta a opo padro.
"stop": para a execuo automtica do coletor de lixo. O coletor executar somente
quando explicitamente invocado, at uma chamada para reinici-lo.
"restart": reinicia a execuo automtica do coletor de lixo.
"count": retorna a memria total em uso por Lua (em Kbytes) e uma segundo valor com
a memria total em bytes mdulo 1024. O primeiro valor tem uma parte fracionria,
 assim a seguinte igualdade sempre verdadeira:
k, b = collectgarbage("count")
assert(k*1024 == math.floor(k)*1024 + b)
(O segundo resultado til quando Lua compilada com um tipo diferente de ponto
flutuante para nmeros.)
"step": realiza um passo de coleta de lixo. O passo "size" controlado por arg (valores
maiores significam passos maiores) de maneira no especificada. Se voc quiser controlar
o tamanho do passo voc deve experimentalmente ajustar o valor de arg. Retorna true se
o passo terminou um ciclo de coleta.
"setpause": estabelece arg como o novo valor da pausa do coletor (veja 2.5). Retorna o
valor anterior da pausa.
"setstepmul": estabelece arg como o novo valor do multiplicador de passo do coletor
(veja 2.5). Retorna o valor anterior do passo.
"isrunning": retorna um booleano que diz se o coletor est executando (i.e., no parado).
"generational": muda o coletor para o modo generacional. Esta uma caracterstica
experimental (veja 2.5).
"incremental": muda o coletor para o modo incremental. Este o modo padro.
dofile ([filename])
Abre o arquivo indicado e executa seu contedo como um trecho Lua. Quando chamada sem
argumentos, dofile executa o contedo da entrada padro (stdin). Retorna todos os valores
retornados pelo trecho. Em caso de erros, dofile propaga o erro para seu chamador (isto
, dofile no executa em modo protegido).
error (message [, level])
Termina a ltima funo protegida chamada e retorna message como a mensagem de erro. A
funo error nunca retorna.
Geralmente, error adiciona alguma informao sobre a posio do erro ao comeo da
mensagem, se a mensagem uma cadeia. O argumento levelespecifica como obter a posio do
erro. Quando level 1 (o padro), a posio do erro onde a funo error foi chamada. O
level 2 aponta o erro para onde a funo que chamou error foi chamada; e assim por diante.
Passar um level 0 evita a adio de informao da posio do erro mensagem.
_G
Uma varivel global (no uma funo) que guarda o ambiente global (veja 2.2). Lua em si no
usa esta varivel; mudar o valor dela no afeta nenhum ambiente, e vice-versa.
getmetatable (object)
Se object no tem uma metatabela, retorna nil. Caso contrrio, se a metatabela do objeto tem
um campo "__metatable", retorna o valor associado. Caso contrrio, retorna a metatabela do
objeto fornecido.
ipairs (t)
Se t tem um metamtodo __ipairs, chama-o com t como argumento e retorna os primeiros trs
resultados da chamada.
Caso contrrio, retorna trs valores: uma funo iteradora, a tabela t, e 0, de modo que a
construo
for i,v in ipairs(t) do corpo end
ir iterar sobre os pares (1,t[1]), (2,t[2]), ..., at a primeira chave inteira ausente da tabela.
load (ld [, source [, mode [, env]]])
Carrega um trecho.
Se ld uma cadeia, o trecho essa cadeia. Se ld uma funo, load a chama repetidamente
para obter os pedaos do trecho. Cada chamada a ld deve retornar uma cadeia que concatena
com resultados anteriores. Um retorno de uma cadeia vazia, nil, ou nenhum valor sinaliza o fim
do trecho.
Se no h erros sintticos, retorna o trecho compilado como uma funo; caso contrrio,
retorna nil mais a mensagem de erro.
Se a funo resultante tem upvalues, o primeiro upvalue recebe o valor de env, se esse
parmetro fornecido, ou o valor do ambiente global. (Quando voc carrega um trecho
principal, a funo resultante sempre ter exatamente um upvalue, a varivel _ENV (veja 2.2).
Quando voc carrega um trecho binrio criado a partir de uma funo (veja string.dump), a
funo resultante pode ter upvalues arbitrrios.)
source usada como a fonte do trecho para mensagens de erro e informao de depurao
(veja 4.9). Quando ausente, o padro ld, se ld uma cadeia, ou "=(load)" caso contrrio.
A cadeia mode controla se o trecho pode ser texto ou binrio (isto , um trecho pr-compilado).
Ela pode ser a cadeia "b" (somente trechos binrios), "t" (somente trechos textuais), ou "bt"
(tanto binrio como texto). O padro "bt".
loadfile ([filename [, mode [, env]]])
Similar a load, mas obtm o trecho do arquivo filename ou da entrada padro, se nenhum nome
de arquivo fornecido.
next (table [, index])
Permite um programa percorrer todos os campos de um tabela. Seu primeiro argumento uma
tabela e seu segundo argumento um ndice nessa tabela.next retorna o prximo ndice da
tabela e seu valor associado. Quando chamada com nil como seu segundo
argumento, next retorna um ndice inicial e seu valor associado. Quando chamada com o ltimo
ndice, ou com nil em uma tabela vazia, next retorna nil. Se o segundo argumento est ausente,
ento ele interpretado como nil. Em particular, voc pode usar next(t) para verificar se uma
tabela vazia.
A ordem na qual os ndices so enumerados no especificada, mesmo para ndices numricos.
(Para percorrer uma tabela em ordem numrica, use um for numrico.)
O comportamento de next indefinido se, durante o percorrimento, voc atribuir qualquer valor
a um campo no existente na tabela. Voc pode contudo modificar campos existentes. Em
particular, voc pode limpar campos existentes.
pairs (t)
Se t tem um metamtodo __pairs, chama-o com t como argumento e retorna os primeiros trs
resultados da chamada.
Caso contrrio, retorna trs valores: a funo next, a tabela t, e nil, de modo que a construo
for k,v in pairs(t) do corpo end
ir iterar sobre todos os pares chavevalor da tabela t.
Veja a funo next para os cuidados que se deve ter ao modificar a tabela durante seu
percorrimento.
pcall (f [, arg1, ])
Chama a funo f com os argumentos dados em modo protegido. Isso significa que qualquer
erro dentro de f no propagado; ao invs disso, pcallcaptura o erro e retorna um cdigo de
estado. Seu primeiro resultado o cdigo de estado (um booleano), o qual verdadeiro se a
chamada aconteceu sem erros. Em tal caso, pcall tambm retorna todos os resultados da
chamada, aps esse primeiro resultado. Em caso de qualquer erro, pcall retorna falsemais a
mensagem de erro.
print ()
Recebe qualquer nmero de argumentos e imprime seus valores para stdout, usando a
funo tostring para converter cada argumento para uma cadeia.print no projetada para
sada formatada, mas somente como uma maneira rpida de mostrar um valor, por exemplo
para depurao. Para um controle completo sobre a sada, use string.format e io.write.
rawequal (v1, v2)
Verifica se v1 igual a v2, sem invocar nenhum metamtodo. Retorna um booleano.
rawget (table, index)
Obtm o valor real de table[index], sem invocar nenhum metamtodo. table deve ser um
tabela; index pode ser qualquer valor.
rawlen (v)
Retorna o comprimento do objeto v, o qual deve ser uma tabela ou uma cadeia, sem invocar
qualquer metamtodo. Retorna um nmero inteiro.
rawset (table, index, value)
Estabelece value como o valor real de table[index], sem invocar nenhum
metamtodo. table deve ser uma tabela, index qualquer valor diferente de nile NaN,
e value qualquer valor Lua.
Esta funo retorna table.
select (index, )
Se index um nmero, retorna todos os argumentos aps o argumento nmero index; um
nmero negativo indexa a partir do fim (-1 o ltimo argumento). Caso contrrio, index deve ser
a cadeia "#", e select retorna o nmero total de argumentos extras que ela recebeu.
setmetatable (table, metatable)
Estabelece a metatabela para a tabela fornecida. (Voc no pode modificar a metatabela de
outros tipos a partir de Lua, somente a partir de C.) Se metatable nil, remove a metatabela da
tabela fornecida. Se a metatabela original tem um campo "__metatable", lana um erro.
Esta funo retorna table.
tonumber (e [, base])
Quando chamada sem base, tonumber tenta converter seu argumento para um nmero. Se o
argumento j um nmero ou uma cadeia que pode ser convertida para um nmero
(veja 3.4.2), ento tonumber retorna esse nmero; caso contrrio, retorna nil.
Quando chamada com base, ento e deve ser uma cadeia a ser interpretada como um nmero
inteiro nessa base. A base pode ser qualquer inteiro entre 2 e 36, inclusive. Em bases
acima de 10, a letra 'A' (maiscula ou minscula) representa 10, 'B' representa 11, e assim por
diante, com 'Z' representando 35. Se a cadeia e no um nmero vlido na base fornecida, a
funo retorna nil.
tostring (v)
Recebe um valor de qualquer tipo e o converte para uma cadeia em um formato razovel. (Para
um controle completo de como nmeros so convertidos, use string.format.)
Se a metatabela de v tem um campo "__tostring", ento tostring chama o valor correspondente
com v como argumento, e usa o resultado da chamada como seu resultado.
type (v)
Retorna o tipo de seu nico argumento, codificado como uma cadeia. Os resultados possveis
desta funo so "nil" (uma cadeia, no o valor nil), "number", "string", "boolean", "table",
"function", "thread", e "userdata".
_VERSION
Uma varivel global (no uma funo) que guarda uma cadeia contendo a verso do
interpretador corrente. O contedo corrente desta varivel "Lua 5.2".
xpcall (f, msgh [, arg1, ])
Esta funo similar a pcall, exceto pelo fato de que ela estabelece um novo tratador de
mensagens msgh.
6.2 Manipulao de Co-rotinas
As operaes relacionadas a co-rotinas compreendem uma sub-biblioteca da biblioteca bsica e
vm dentro da tabela coroutine. Veja 2.6 para uma descrio geral de co-rotinas.
coroutine.create (f)
Cria uma nova co-rotina, com corpo f. @{f} deve ser uma funo Lua. Retorna essa nova co-
rotina, um objeto com tipo "thread".
coroutine.resume (co [, val1, ])
Comea ou continua a execuo da co-rotina co. Da primeira vez que voc retoma uma co-
rotina, ela comea executando o corpo dela. Os valores val1, ... so passados como os
argumentos para a funo do corpo. Se a co-rotina cedeu, resume a recomea; os
valores val1, ... so passados como os resultados da cesso.
Se a co-rotina executa sem nenhum erro, resume retorna true mais quaisquer valores passados
para yield (se a co-rotina cede) ou quaisquer valores retornados pela funo do corpo (se a co-
rotina termina). Se h qualquer erro, resume retorna false mais a mensagem de erro.
coroutine.running ()
Retorna a co-rotina executando mais um booleano, verdadeiro quando a co-rotina executando
a principal.
coroutine.status (co)
Retorna o estado da co-rotina co, como uma cadeia: "running", se a co-rotina est executando
(isto , ela chamou status); "suspended", se a co-rotina est suspensa em uma chamada a yield,
ou se ela no comeou a executar ainda; "normal" se a co-rotina est ativa mas no est
executando (isto , ela retomou outra co-rotina); e "dead" se a co-rotina finalizou a funo do
corpo dela, ou se ela parou com um erro.
coroutine.wrap (f)
Cria uma nova co-rotina, com corpo f. f deve ser uma funo Lua. Retorna uma funo que
retoma a co-rotina cada vez que ela chamada. Quaisquer argumentos extras passados para a
funo comportam-se como os argumentos extras para resume. Retorna os mesmos valores
retornados por resume, exceto o primeiro booleano. Em caso de erro, propaga o erro.
coroutine.yield ()
Suspende a execuo da co-rotina chamadora. Quaisquer argumentos para yield so passados
como resultados extras para resume.
6.3 Mdulos
A biblioteca de pacotes oferece facilidades bsicas para carregar mdulos em Lua. Ela exporta
uma funo diretamente no ambiente global: require. Todo o resto exportado em um
tabela package.
require (modname)
Carrega o mdulo fornecido. A funo comea investigando a tabela package.loaded para
determinar se modname j est carregado. Se est, ento require retorna o valor armazenado
em package.loaded[modname]. Caso contrrio, tenta encontrar um carregador para o mdulo.
Para encontrar um carregador, require guiada pela sequncia de package.searchers.
Modificando essa sequncia, podemos modificar como requireprocura por um mdulo. A
explicao a seguir baseada na configurao padro de package.searchers.
Primeiro require consulta package.preload[modname]. Se ela tem um valor, esse valor (que deve
ser uma funo) o carregador. Caso contrrio requireprocura por um carregador Lua usando o
caminho armazenado em package.path. Se isso tambm falha, ela procura por um carregador C
usando o caminho armazenado em package.cpath. Se isso tambm falha, ela tenta um
carregador tudo-em-um (veja package.searchers).
Uma vez que um carregador encontrado, require chama o carregador com dois
argumentos: modname e um valor extra dependente de como ela obteve o carregador. (Se o
carregador veio de um arquivo, esse valor extra o nome do arquivo.) Se o carregador retorna
qualquer valor diferente de nil, require atribui o valor retornado a package.loaded[modname]. Se
o carregador no retorna um valor diferente de nil e no atribuiu nenhum valor
a package.loaded[modname], ento require atribui true a essa entrada. Em todo
caso, require retorna o valor final de package.loaded[modname].
Se h qualquer erro ao carregar ou executar o mdulo, ou se ela no encontrou nenhum
carregador para o mdulo, ento require lana um erro.
package.config
Uma cadeia descrevendo algumas configuraes de tempo de compilao para pacotes. Esta
cadeia uma sequncia de linhas:
A primeira linha a cadeia separadora de diretrios. O padro '\' para Windows e '/' para
todos os outros sistemas.
A segunda linha o caractere que separa modelos em um caminho. O padro ';'.
A terceira linha a cadeia que marca os pontos de substituio em um modelo. O padro
'?'.
A quarta linha uma cadeia que, em um caminho no Windows, substituda pelo diretrio
do executvel. O padro '!'.
A quinta linha uma marca para ignorar todo o texto antes dela ao construir o nome da
funo luaopen_. O padro '-'.
package.cpath
O caminho usado por require para procurar por um carregador C.
Lua inicializa o caminho C package.cpath da mesma maneira que inicializa o caminho
Lua package.path, usando a varivel de ambiente LUA_CPATH_5_2ou a varivel de
ambiente LUA_CPATH ou um caminho padro definido em luaconf.h.
package.loaded
Uma tabela usada por require para controlar quais mdulos j esto carregados. Quando voc
requisita um mdulo modname e package.loaded[modname]no falso, require simplesmente
retorna o valor armazenado l.
Essa varivel somente uma referncia para a tabela real; atribuies a essa varivel no
modificam a tabela usada por require.
package.loadlib (libname, funcname)
Dinamicamente liga o programa hospedeiro com a biblioteca C libname.
Se a funo funcname "*", ento somente liga com a biblioteca, tornando os smbolos
exportados pela biblioteca disponveis para outras bibliotecas ligadas dinamicamente. Caso
contrrio, procura por uma funo funcname dentro da biblioteca e retorna essa funo como
uma funo C. Assim, funcname deve seguir o prottipo lua_CFunction (veja lua_CFunction).
Essa uma funo de baixo nvel. Ela ignora completamente o sistema de pacotes e mdulos.
Ao contrrio de require, ela no realiza nenhuma busca de caminho e no adiciona extenses
automaticamente. libname deve ser o nome completo do arquivo da biblioteca C, incluindo se
necessrio um caminho e uma extenso. funcname deve ser o nome exato exportado pela
biblioteca C (o qual pode depender do compilador e do ligador C usados).
Esta funo no suportada por C Padro. Dessa forma, ela est disponvel somente em
algumas plataformas (Windows, Linux, Mac OS X, Solaris, BSD, alm de outros sistemas Unix que
suportam o padro dlfcn).
package.path
O caminho usado por require para procurar por um carregador Lua.
Ao iniciar, Lua inicializa esta varivel com o valor da varivel de ambiente LUA_PATH_5_2 ou da
varivel de ambiente LUA_PATH ou com um valor padro definido em luaconf.h, se essas
variveis de ambiente no esto definidas. Qualquer ";;" no valor da varivel de ambiente
substitudo pelo caminho padro.
package.preload
Uma tabela para guardar carregadores para mdulos especficos (veja require).
Esta varivel somente uma referncia para a tabela real; atribuies a esta varivel no
modificam a tabela usada por require.
package.searchers
Uma tabela usada por require para controlar como carregar mdulos.
Cada entrada nesta tabela uma funo buscadora. Ao procurar por um mdulo, require chama
cada uma dessas buscadoras em ordem ascendente, com o nome do mdulo (o argumento
fornecido para require) como seu nico argumento. A funo pode retornar outra funo
(o carregador do mdulo) mais um valor extra que ser passado para esse carregador, ou uma
cadeia explicando por que ela no encontrou esse mdulo (ou nil se ela no tem nada a dizer).
Lua inicializa esta tabela com quatro funes buscadoras.
A primeira buscadora simplesmente procura por um carregador na tabela package.preload.
A segunda buscadora procura por um carregador como uma biblioteca Lua, usando o caminho
armazenado em package.path. A busca feita como descrito na funo package.searchpath.
A terceira buscadora procura por um carregador como uma biblioteca C, usando o caminho
fornecido pela varivel package.cpath. Novamente, a busca feita como descrito na
funo package.searchpath. Por exemplo, se o caminho C a cadeia
"./?.so;./?.dll;/usr/local/?/init.so"
a buscadora para o mdulo foo tentar abrir os arquivos ./foo.so, ./foo.dll, e /usr/local/foo/init.so,
nessa ordem. Uma vez que ela encontra uma biblioteca C, essa buscadora primeiro usa uma
facilidade de ligao dinmica para ligar a aplicao com a biblioteca. Em seguida ela tenta
encontrar uma funo C dentro da biblioteca a ser usada como carregador. O nome dessa
funo C a cadeia "luaopen_" concatenada com uma cpia do nome do mdulo onde cada
ponto substitudo por um sublinhado. Alm disso, se o nome do mdulo tem um hfen, seu
prefixo at (e incluindo) o primeiro hfen removido. Por exemplo, se o nome do mdulo a.v1-
b.c, o nome da funo ser luaopen_b_c.
A quarta buscadora tenta um carregador tudo-em-um. Ela busca o caminho C para uma
biblioteca pela raiz do nome do mdulo fornecido. Por exemplo, ao requisitar a.b.c, ela procurar
por uma biblioteca C para a. Se encontrar, busca dentro dela por uma funo de abertura para o
submdulo; no nosso exemplo, essa seria luaopen_a_b_c. Com essa facilidade, um pacote pode
empacotar vrios submdulos C dentro de uma nica biblioteca, com cada submdulo mantendo
sua funo de abertura original.
Todas as buscadoras exceto a primeira (preload) retorna como valor extra o nome do arquivo
onde o mdulo foi encontrado, como retornado por package.searchpath. A primeira buscadora
no retorna valor extra.
package.searchpath (name, path [, sep [, rep]])
Procura pelo name fornecido no path fornecido.
Um caminho uma cadeia contendo uma sequncia de modelos separados por ponto-e-vrgula.
Para cada modelo, a funo substitui cada ponto de interrogao (se houver) no modelo por uma
cpia de name onde todas as ocorrncias de sep (um ponto, por padro) foram substitudas
por rep (o separador de diretrios do sistema, por padro), e em seguida tenta abrir o nome do
arquivo resultante.
Por exemplo, se o caminho a cadeia
"./?.lua;./?.lc;/usr/local/?/init.lua"
a busca pelo nome foo.a tentar abrir os arquivos ./foo/a.lua, ./foo/a.lc, e /usr/local/foo/a/init.lua,
nessa ordem.
Retorna o nome resultante do primeiro arquivo que ela conseguiu abrir em modo de leitura (aps
fechar o arquivo), ou nil mais uma mensagem de erro se nada foi bem sucedido. (Essa
mensagem de erro lista todos os nomes de arquivo que ela tentou abrir.)
6.4 Manipulao de Cadeias
Esta biblioteca oferece funes genricas para manipulao de cadeias, tais como encontrar e
extrair subcadeias, e casamento de padres. Ao indexar uma cadeia em Lua, o primeiro
caractere est na posio 1 (no na 0, como em C). ndices podem ser negativos e so
interpretados como uma indexao de trs pra frente, a partir do fim da cadeia. Dessa forma, o
ltimo caractere est na posio -1, e assim por diante.
A biblioteca de cadeias oferece todas as suas funes dentro da tabela string. Ela tambm
estabelece uma metatabela para cadeias onde o campo __index aponta para a tabela string.
Logo, voc pode usar as funes de cadeias em um estilo orientado a objetos. Por
exemplo, string.byte(s,i)pode ser escrito como s:byte(i).
A biblioteca de cadeias assume codificaes de caracteres de um byte.
string.byte (s [, i [, j]])
Retorna os cdigos numricos internos dos caracteres s[i], s[i+1], ..., s[j]. O valor padro
para i 1; o valor padro para j i. Esses ndices so corrigidos seguindo as mesmas regras da
funo string.sub.
Cdigos numricos no so necessariamente portveis entre plataformas.
string.char ()
Recebe zero ou mais inteiros. Retorna uma cadeia com comprimento igual ao nmero de
argumentos, na qual cada caractere tem um cdigo numrico interno igual a seu argumento
correspondente.
Cdigos numricos no so necessariamente portveis entre plataformas.
string.dump (function)
Retorna uma cadeia contendo uma representao binria da funo fornecida, de modo que
um load posterior sobre essa cadeia retorna uma cpia da funo (mas com novos upvalues).
string.find (s, pattern [, init [, plain]])
Procura pelo primeiro casamento de pattern na cadeia s. Se encontra um casamento,
ento find retorna os ndices de s onde essa ocorrncia comeou e terminou; caso contrrio,
retorna nil. Um terceiro argumento numrico opcional init especifica onde comear a busca; o
valor padro dele 1 e pode ser negativo. Um valor true para o quarto argumento
opcional plain desabilita as facilidades de casamento de padro, de modo que a funo faz uma
operao de "busca de subcadeia" simples, sem que os caracteres de pattern sejam
considerados mgicos. No que se plain fornecido, ento init deve ser fornecido tambm.
Se o padro possui capturas, ento em um casamento bem sucedido os valores capturados
tambm so retornados, aps os dois ndices.
string.format (formatstring, )
Retorna uma verso formatada de seu nmero varivel de argumentos seguindo a descrio
dada em seu primeiro argumento (que deve ser uma cadeia). A cadeia de formatao segue as
mesmas regras de ANSI C function sprintf. As nicas diferenas so que as
opes/modificadores *, h, L, l, n, e p no so suportadas e que h uma opo extra, q. A
opo q formata uma cadeia entre aspas duplas, usando sequncias de escape quando
necessrio para garantir que ela possa ser lida de volta de modo seguro pelo interpretador Lua.
Por exemplo, a chamada
string.format('%q', 'a string with "quotes" and \n new line')
pode produzir a cadeia:
"a string with \"quotes\" and \
new line"
As opes A e a (quando disponveis), E, e, f, G, e g esperam todas um nmero como argumento.
As opes c, d, i, o, u, X, e x tambm esperam um nmero, mas o intervalo desse nmero pode
ser limitado pela implementao C subjacente. Para as opes o, u, X, e x, o nmero no pode
ser negativo. A opo q espera uma cadeia; a opo s espera uma cadeia sem zeros dentro dela.
Se o argumento para a opo s no uma cadeia, ele convertido para uma seguindo as
mesmas regras de tostring.
string.gmatch (s, pattern)
Retorna uma funo iteradora que, cada vez que chamada, retorna as prximas capturas
de pattern na cadeia s. Se pattern no especifica capturas, ento o casamento inteiro
produzido a cada chamada.
Como um exemplo, o seguinte lao ir iterar sobre todas as palavras da cadeia s, imprimindo
uma por linha:
s = "hello world from Lua"
for w in string.gmatch(s, "%a+") do
print(w)
end
O prximo exemplo coleta todos os pares key=value da cadeia fornecida dentro de uma tabela:
t = {}
s = "from=world, to=Lua"
for k, v in string.gmatch(s, "(%w+)=(%w+)") do
t[k] = v
end
Para esta funo, um circunflexo '^' no incio do padro no funciona como uma ncora, pois
isso impediria a iterao.
string.gsub (s, pattern, repl [, n])
Retorna uma cpia de s na qual todas (ou as primeiras n, se fornecido) ocorrncias
de pattern foram substitudas por uma cadeia de substituio especificada por repl, que pode
ser uma cadeia, uma tabela, ou uma funo. gsub tambm retorna, como seu segundo valor, o
nmero total de casamentos que ocorreram. O nome gsub vem de Global SUBstitution.
Se repl uma cadeia, ento seu valor usado para a substituio. O caractere % funciona como
um caractere de escape: qualquer sequncia em repl da forma %d, com d entre 1 e 9,
representa o valor da d-sima subcadeia capturada. A sequncia %0 representa o casamento
inteiro. A sequncia %% representa um % simples.
Se repl uma tabela, ento a tabela consultada a cada casamento, usando a primeira captura
como a chave.
Se repl uma funo, ento essa funo chamada toda vez que um casamento ocorre, com
todas as subcadeias capturadas passadas como argumentos, em ordem.
Em todo caso, se o padro no especifica capturas, ento ela comporta-se como se o padro
inteiro estivesse dentro de uma captura.
Se o valor retornado pela consulta tabela ou pela chamada de funo uma cadeia ou um
nmero, ento ele usado como a cadeia de substituio; caso contrrio, se ele false ou nil,
ento no h substituio (isto , o casamento original mantido na cadeia).
Aqui esto alguns exemplos:
x = string.gsub("hello world", "(%w+)", "%1 %1")
--> x="hello hello world world"

x = string.gsub("hello world", "%w+", "%0 %0", 1)

--> x="hello hello world"

x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1")

--> x="world hello Lua from"

x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv)

--> x="home = /home/roberto, user = roberto"

x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s)

return load(s)()
end)
--> x="4+5 = 9"

local t = {name="lua", version="5.2"}

x = string.gsub("$name-$version.tar.gz", "%$(%w+)", t)
--> x="lua-5.2.tar.gz"
string.len (s)
Recebe uma cadeia e retorna seu comprimento. A cadeia vazia "" possui comprimento 0. Zeros
dentro da cadeia so contados, assim "a\000bc\000"possui comprimento 5.
string.lower (s)
Recebe uma cadeia e retorna uma cpia dessa cadeia com todas as letras maisculas
convertidas para minsculas. Todos os demais caracteres no so modificados. A definio de o
que uma letra maiscula depende do idioma (locale) corrente.
string.match (s, pattern [, init])
Procura pelo primeiro casamento de pattern na cadeia s. Se encontra um, ento match retorna
as capturas do padro; caso contrrio retorna nil. Se patten no especifica capturas, ento o
casamento inteiro retornado. Um terceiro argumento numrico, opcional, init especifica onde
comear a busca; seu valor padro 1 e pode ser negativo.
string.rep (s, n [, sep])
Retorna uma cadeia que a concatenao de n cpias da cadeia s separadas pela cadeia sep. O
valor padro para sep a cadeia vazia (isto , nenhum separador).
string.reverse (s)
Retorna uma cadeia que a cadeia s invertida.
string.sub (s, i [, j])
Retorna a subcadeia de s que comea em i e continua at j; i e j podem ser negativos. Se j est
ausente, ento assume-se que ele igual a -1 (que o mesmo que o comprimento da cadeia
vazia). Em particular, a chamada string.sub(s,1,j) retorna um prefixo s com comprimento j,
e string.sub(s, -i) retorna um sufixo de s com comprimento i.
Se, aps a traduo de ndices negativos, i menor do que 1, ele corrigido para 1. Se j maior
do que o comprimento da cadeia, ele corrigido para esse comprimento. Se, aps essas
correes, i maior do que j, a funo retorna a cadeia vazia.
string.upper (s)
Recebe uma cadeia e retorna uma cpia dessa cadeia com todas as letras minsculas
convertidas para maisculas. Todos os demais caracteres no so modificados. A definio de o
que uma letra minscula depende do idioma (locale) corrente.
6.4.1 Padres
Classes de Caracteres:
Uma classe de caracteres usada para representar um conjunto de caracteres. As seguintes
combinaes so permitidas ao descrever uma classe de caracteres:
x: (onde x no um dos caracteres mgicos ^$()%.[]*+-?) representa o prprio
caractere x.
.: (um ponto) representa todos os caracteres.
%a: representa todas as letras.
%c: representa todos os caracteres de controle.
%d: representa todos os dgitos.
%g: representa todos os caracteres que podem ser impressos exceto o espao.
%l: representa todas as letras minsculas.
%p: representa todos os caracteres de pontuao.
%s: representa todos os caracteres de espao.
%u: representa todas as letras maisculas.
%w: representa todos os caracteres alfanumricos.
%x: representa todos os dgitos hexadecimais.
%x: (onde x qualquer caractere no-alfanumrico) representa o caractere x. Esta a
maneira padro de escapar caracteres mgicos. Qualquer caractere de pontuao
(mesmo os no mgicos) podem ser precedidos por um '%' quando usado para
representar a si mesmo em um padro.
[set]: representa a classe que a unio de todos os caracteres em set. Um intervalo de
caracteres pode ser especificado separando os caracteres das extremidades do intervalo,
em ordem ascendente, com um '-'. Todas as classes %x descritas acima tambm podem
ser usadas como componentes em set. Todos os outros caracteres em set representam
eles mesmos. Por exemplo, [%w_] (ou [_%w]) representa todos os caracteres
alfanumricos mais o sublinhado, [0-7] representa os dgitos octais, e [0-7%l
%-] representa os dgitos octais mais as letras minsculas mais o caractere '-'.
A interao entre intervalos e classes no definida. Assim, padres como [%a-z] ou [a-%
 %] no possuem significado.
[^set]: representa o complemento de set, onde set interpretado como acima.
Para todas as classes representadas por letras simples (%a, %c, etc.), a letra maiscula
correspondente representa o complemento da classe. Por exemplo, %S representa todos os
caracteres que no so de espao.
As definies de letra, espao, e outros grupos de caracteres depende do idioma corrente. Em
particular, a classe [a-z] pode no ser equivalente a %l.
Item de Padro:
Um item de padro pode ser
uma classe de caracteres simples, que casa qualquer caractere simples na classe;
uma classe de caracteres simples seguida por '*', que casa 0 ou mais repeties de
caracteres na classe. Esses itens de repetio sempre casaro a maior sequncia possvel;
uma classe de caracteres simples seguida por '+', que casa 1 ou mais repeties de
caracteres na classe. Esses itens de repetio sempre casaro a maior sequncia possvel;
uma classe de caracteres simples seguida por '-', que tambm casa 0 ou mais repeties
de caracteres na classe. Ao contrrio de '*', esses itens de repetio sempre casaro a
menor sequncia possvel;
uma classe de caracteres simples seguida por '?', que casa 0 ou 1 ocorrncia de um
caractere na classe.
%n, para n entre 1 e 9; tal item casa uma subcadeia igual n-sima cadeia capturada
(veja abaixo);
%bxy, onde x e y so dois caracteres distintos; tal item casa cadeias que comeam com x,
terminam com y, e onde os x e y so balanceados. Isso significa que, se voc ler a cadeia
da esquerda para a direita, contando +1 para um x e -1 para um y, o ltimo y o
primeiro y onde o contador alcana 0. Por exemplo, o item %b() casa expresses com
parnteses balanceados.
%f[set], um padro de fronteira; tal item casa uma cadeia vazia em qualquer posio
desde que o prximo caractere pertena a set e o caractere anterior no pertena a set. O
conjunto set interpretado como descrito anteriormente. O incio e o fim da cadeia
principal so tratados como se eles fossem o caractere '\0'.
Padro:
Um padro uma sequncia de itens de padro. Um circunflexo '^' no incio de um padro
ancora o casamento no incio do texto principal. Um '$' no fim de um padro ancora o
casamento no fim do texto principal. Em outras posies, '^' e '$' no possuem significado
especial e representam eles mesmos.
Capturas:
Um padro pode conter subpadres delimitados por parnteses; eles descrevem capturas.
Quando um casamento bem sucedido, as subcadeias da cadeia principal que casam capturas
so armazenadas (capturadas) para uso futuro. Capturas so numeradas de acordo com seu
parntese esquerdo. Por exemplo, no padro "(a*(.)%w(%s*))", a parte da cadeia casando "a*(.)
%w(%s*)" armazenada como a primeira captura (e por isso tem o nmero 1); o caractere
casando "." capturado com o nmero 2, e a parte casando "%s*" tem o nmero 3.
Como um caso especial, a captura vazia () captura a posio da cadeia corrente (um nmero).
Por exemplo, se aplicarmos o padro "()aa()" sobre a cadeia "flaaap", haver duas capturas:
3 and 5.
6.5 Manipulao de Tabelas
Esta biblioteca oferece funes genricas para manipulao de tabelas. Ela oferece todas as
suas funes dentro da tabela table.
Lembre-se que, sempre que uma operao precisa do comprimento de uma tabela, a tabela
deve ser uma sequncia de fato ou ter um metamtodo __len (veja 3.4.6). Todas as funes
ignoram chaves no numricas em tabelas fornecidas como argumentos.
Por razes de desempenho, todas os acessos (get/set) a tabelas realizados por estas funes so
primitivos.
table.concat (list [, sep [, i [, j]]])
Dada uma lista onde todos os elementos so cadeias ou nmeros, retorna a
cadeia list[i]..sep..list[i+1] sep..list[j]. O valor padro para sep a cadeia vazia, o padro
para i 1, e o padro para j #list. Se i maior do que j, retorna a cadeia vazia.
table.insert (list, [pos,] value)
Insere o elemento value na posio pos de list, deslocando os elementos list[pos], list[pos+1],
, list[#list]. O valor padro para pos #list+1, assim uma chamada table.insert(t,x) insere x no
fim da lista t.
table.pack ()
Retorna uma nova tabela com todos os parmetros armazenados nas chaves 1, 2, etc. e com um
campo "n" com o nmero total de parmetros. Note que a tabela resultante pode no ser uma
sequncia.
table.remove (list [, pos])
Remove de list o elemento na posio pos, retornando o valor do elemento removido.
Quando pos um inteiro entre 1 e #list, desloca os elementoslist[pos+1], list[pos+2], ,
list[#list] e apaga o elemento list[#list]; O ndice pos pode tambm ser 0 quando #list 0,
ou #list + 1; nesses casos, a funo apaga o elemento list[pos].
O valor padro para pos #list, assim uma chamada table.remove(l) remove o ltimo elemento
da lista l.
table.sort (list [, comp])
Ordena os elementos da lista em uma dada ordem, in-place, de list[1] at list[#list]. Se comp
fornecido, ento ela deve ser uma funo que recebe dois elementos da lista e retorna
verdadeiro quando o primeiro elemento deve vir antes do segundo na ordem final (de modo
que not comp(list[i+1],list[i]) ser verdadeiro aps a ordenao). Se comp no fornecido, ento
o operador Lua padro < usado ao invs.
O algoritmo de ordenao no estvel; isto , elementos considerados iguais pela ordem
fornecida podem ter suas posies relativas alteradas aps a ordenao.
table.unpack (list [, i [, j]])
Retorna os elementos da lista fornecida. Esta funo equivalente a
return list[i], list[i+1], , list[j]
Por padro, i 1 e j #list.
6.6 Funes Matemticas
Esta biblioteca uma interface para a biblioteca matemtica de C padro. Ela oferece todas as
suas funes dentro da tabela math.
math.abs (x)
Retorna o valor absoluto de x.
math.acos (x)
Retorna o arco co-seno de x (em radianos).
math.asin (x)
Retorna o arco seno de x (em radianos).
math.atan (x)
Retorna o arco tangente de x (em radianos).
math.atan2 (y, x)
Retorna o arco tangente de y/x (em radianos), mas usa os sinais de ambos os parmetros para
encontrar o quadrante do resultado. (Tambm trata corretamente o caso quando x zero.)
math.ceil (x)
Retorna o menor inteiro maior ou igual a x.
math.cos (x)
Retorna o co-seno de x (que se assume estar em radianos).
math.cosh (x)
Retorna o co-seno hiperblico de x.
math.deg (x)
Retorna o ngulo x (dado em radianos) em graus.
math.exp (x)
Retorna o valor ex.
math.floor (x)
Retorna o maior inteiro menor ou igual a x.
math.fmod (x, y)
Retorna o resto da diviso de x por y que arredonda o quociente em direo a zero.
math.frexp (x)
Retorna m e e tais que x = m2e, e um inteiro e o valor absoluto de m est no intervalo [0.5,
1) (ou zero quando x zero).
math.huge
O valor HUGE_VAL, um valor maior ou igual a qualquer outro valor numrico.
math.ldexp (m, e)
Retorna m2e (e deve ser um inteiro).
math.log (x [, base])
Retorna o logaritmo de x na base dada. O valor padro para base e (de modo que a funo
retorna o logaritmo natural de x).
math.max (x, )
Retorna o valor mximo entre seus argumentos.
math.min (x, )
Retorna o valor mnimo entre seus argumentos.
math.modf (x)
Retorna dois nmeros, a parte integral de x e a parte fracionria de x.
math.pi
O valor de .
math.pow (x, y)
Retorna xy. (Voc tambm pode usar a expresso x^y para computar esse valor.)
math.rad (x)
Retorna o ngulo x (dado em graus) em radianos.
math.random ([m [, n]])
Esta funo um interface para a funo geradora pseudo-randmica rand simples oferecida
por C Padro. (Nenhuma garantia pode ser dada para suas propriedades estatsticas.)
Quando chamada sem argumentos, retorna um nmero real pseudo-randmico uniforme no
intervalo [0,1). Quando chamada com um nmero inteiro m,math.random retorna um inteiro
pseudo-randmico uniforme no intervalo [1, m]. Quando chamada com dois nmeros
inteiros m e n, math.random retorna um inteiro pseudo-randmico uniforme no intervalo [m, n].
math.randomseed (x)
Estabelece x como a "semente" para o gerador pseudo-randmico: sementes iguais produzem
sequncias iguais de nmeros.
math.sin (x)
Retorna o seno de x (que se assume estar em radianos).
math.sinh (x)
Retorna o seno hiperblico de x.
math.sqrt (x)
Retorna a raiz quadrada de x. (Voc tambm pode usar a expresso x^0.5 para computar esse
valor.)
math.tan (x)
Retorna a tangente de x (que se assume estar em radianos).
math.tanh (x)
Retorna a tangente hiperblica de x.
6.7 Operaes Bit a Bit
Esta biblioteca oferece operaes bit a bit. Ela oferece todas as suas funes dentro da
tabela bit32.
A menos que dito de outra maneira, todas as funes aceitam argumentos numricos no
intervalo (-251,+251); cada argumento normalizado para o resto dessa diviso por 232 e truncado
para um inteiro (de algum modo no especificado), de modo que seu valor final cabe no
intervalo [0,232 - 1]. De maneira similar, todos os resultados esto no intervalo [0,232 - 1]. Note
que bit32.bnot(0) 0xFFFFFFFF, o que diferente de -1.
bit32.arshift (x, disp)
Retorna o nmero x deslocado disp bits para a direita. O nmero disp pode ser qualquer inteiro
representvel. Deslocamentos negativos deslocam para a esquerda.
Esta operao de deslocamento o que chamado de deslocamento aritmtico. Bits vagos
esquerda so preenchidos com cpias do bit mais significativo de x; bits vagos direita so
preenchidos com zeros. Em particular, deslocamentos com valores absolutos maiores do que 31
resultam em zero ou 0xFFFFFFFF (todos os bits originais so deslocados para fora).
bit32.band ()
Retorna o and bit a bit de seus operandos.
bit32.bnot (x)
Retorna a negao bit a bit de x. Para qualquer inteiro x, a seguinte identidade vale:
assert(bit32.bnot(x) == (-1 - x) % 2^32)
bit32.bor ()
Retorna o or bit a bit de seus operandos.
bit32.btest ()
Retorna um booleano sinalizando se o and bit a bit de seus operandos diferente de zero.
bit32.bxor ()
Retorna o ou exclusivo de seus operandos.
bit32.extract (n, field [, width])
Retorna o nmero sem sinal formado pelos bits field a field + width - 1 de n. Bits so numerados
de 0 (menos significativo) a 31 (mais significativo). Todos os bits acessados deve estar no
intervalo [0, 31].
O padro para width 1.
bit32.replace (n, v, field [, width])
Retorna uma cpia de n com os bits de field a field + width - 1 substitudos pelo valor v.
Veja bit32.extract para detalhes sobre field e width.
bit32.lrotate (x, disp)
Retorna o nmero x rotacionado disp bits para a esquerda. O nmero disp pode ser qualquer
inteiro representvel.
Para qualquer deslocamento vlido, a seguinte identidade vale:
assert(bit32.lrotate(x, disp) == bit32.lrotate(x, disp % 32))
Em particular, deslocamentos negativos rotacionam para a direita.
bit32.lshift (x, disp)
Retorna o nmero x deslocado disp bits para a esquerda. O nmero disp pode ser qualquer
inteiro representvel. Deslocamentos negativos deslocam para a direita. Em qualquer direo,
bits vagos so preenchidos com zeros. Em particular, deslocamentos com valores absolutos
maiores do que 31 resultam em zero (todos os bits so deslocados para fora).
Para deslocamentos positivos, a seguinte igualdade vale:
assert(bit32.lshift(b, disp) == (b * 2^disp) % 2^32)
bit32.rrotate (x, disp)
Retorna o nmero x rotacionado disp bits para a direita. O nmero disp pode ser qualquer inteiro
representvel.
Para qualquer deslocamento vlido, a seguinte identidade vale:
assert(bit32.rrotate(x, disp) == bit32.rrotate(x, disp % 32))
Em particular, deslocamentos negativos rotacionam para a esquerda.
bit32.rshift (x, disp)
Retorna o nmero x deslocado disp bits para a direita. O nmero disp pode ser qualquer inteiro
representvel. Deslocamentos negativos deslocam para a esquerda. Em qualquer direo, bits
vagos so preenchidos com zeros. Em particular, deslocamentos com valores absolutos maiores
do que 31 resultam em zero (todos os bits so deslocados para fora).
Para deslocamentos positivos, a seguinte igualdade vale:
assert(bit32.rshift(b, disp) == math.floor(b % 2^32 / 2^disp))
Esta operao de deslocamento o que chamado de deslocamento lgico.
6.8 Facilidades de Entrada e Sada
A biblioteca de E/S oferece dois estilos diferentes para manipulao de arquivos. O primeiro usa
descritores de arquivos implcitos; isto , h operaes para estabelecer um arquivo de entrada
padro e um arquivo de sada padro, e todas as operaes de entrada/sada so sobre esses
arquivos padro. O segundo estilo usa descritores de arquivos explcitos.
Ao usar descritores de arquivos implcitos, todas as operaes so fornecidas pela tabela io. Ao
usar descritores de arquivos explcitos, a operao io.openretorna um descritor de arquivo e
ento todas as operaes so fornecidas como mtodos do descritor de arquivo.
A tabela io tambm oferece trs descritores de arquivos pr-definidos com seus significados
usuais de C: io.stdin, io.stdout, e io.stderr. A biblioteca de E/S nunca fecha esses arquivos.
A menos que dito de outra maneira, todas as funes de E/S retornam nil em caso de falha
(mais uma mensagem de erro como um segundo resultado e um cdigo de erro dependente do
sistema como um terceiro resultado) e algum valor diferente de nil em caso de sucesso. Em
sistemas no Posix, a computao da mensagem de erro e do cdigo de erro em caso de erros
pode no ser segura se h mltiplos fluxos de execuo, pois ela depende da varivel C
global errno.
io.close ([file])
Equivalente a file:close(). Sem um file, fecha o arquivo de sada padro.
io.flush ()
Equivalente a io.output():flush().
io.input ([file])
Quando chamada com um nome de arquivo, abre o arquivo nomeado (em modo texto), e
estabelece seu manipulador como o arquivo de sada padro. Quando chamada com um
manipulador de arquivo, simplesmente estabelece esse manipulador de arquivo como o arquivo
de entrada padro. Quando chamada sem parmetros, retorna o arquivo de entrada padro
corrente.
Em caso de erros esta funo lana o erro, ao invs de retornar um cdigo de erro.
io.lines ([filename ])
Abre o nome do arquivo fornecido em modo de leitura e retorna uma funo iteradora que
funciona como file:lines() sobre o arquivo aberto. Quando a funo iteradora detecta o fim do
arquivo, retorna nil (para finalizar o lao) e automaticamente fecha o arquivo.
A chamada io.lines() (sem nome de arquivo) equivalente a io.input():lines(); isto , ela itera
sobre as linhas do arquivo de entrada padro. Nesse caso ela no fecha o arquivo quando o lao
termina.
Em caso de erros esta funo lana o erro, ao invs de retornar um cdigo de erro.
io.open (filename [, mode])
Esta funo abre um arquivo, no modo especificado na cadeia mode. Retorna um novo
manipulador de arquivo, ou, em caso de erros, nil mais uma mensagem de erro.
A cadeia mode pode ser qualquer uma das seguintes:
"r": modo de leitura (o padro);
"w": modo de escrita;
"a": modo de adio;
"r+": modo de atualizao, todos os dados anteriores so preservados;
"w+": modo de atualizao, todos os dados anteriores so apagados;
"a+": modo de atualizao de adio, todos os dados anteriores so preservados, a
escrita somente permitida no fim do arquivo.
A cadeia mode tambm pode ter um 'b' no fim, que necessrio em alguns sistemas para abrir
o arquivo em modo binrio.
io.output ([file])
Similar a io.input, mas opera sobre o arquivo de sada padro.
io.popen (prog [, mode])
Esta funo dependente do sistema e no est disponvel em todas as plataformas.
Comea o programa prog em um processo separado e retorna um manipulador de arquivo que
voc pode usar para ler dados desse programa (se mode "r", o padro) ou para escrever dados
para esse programa (se mode "w").
io.read ()
Equivalente a io.input():read().
io.tmpfile ()
Retorna um manipulador para um arquivo temporrio. Esse arquivo aberto em modo de
atualizao e automaticamente removido quando o programa termina.
io.type (obj)
Verifica se obj um manipulador de arquivo vlido. Retorna a cadeia "file" se obj um
manipulador de arquivo aberto, "closed file" se obj um manipulador de arquivo fechado,
ou nil se obj no um manipulador de arquivo.
io.write ()
Equivalente a io.output():write().
file:close ()
Fecha file. Note que arquivos so automaticamente fechados quando seus manipuladores so
coletados pelo coletor de lixo, mas isso leva uma quantidade imprevisvel de tempo para
acontecer.
Ao fechar um manipulador de arquivo criado com io.popen, file:close retorna os mesmos valores
retornados por os.execute.
file:flush ()
Salva qualquer dado escrito para file.
file:lines ()
Retorna uma funo iteradora que, cada vez que chamada, l o arquivo de acordo com os
formatos fornecidos. Quando nenhum formato fornecido, usa "*l" como um padro. Como um
exemplo, a construo
for c in file:lines(1) do corpo end
ir iterar sobre todos os caracteres do arquivo, comeando na posio corrente. Diferente
de io.lines, esta funo no fecha o arquivo quando o lao termina.
Em caso de erros esta funo lana o erro, ao invs de retornar um cdigo de erro.
file:read ()
L o arquivo file, de acordo com os formatos fornecidos, os quais especificam o que ler. Para
cada formato, a funo retorna uma cadeia (ou um nmero) com os caracteres lidos, ou nil se
ela no conseguiu ler dados com o formato especificado. Quando chamada sem formatos, usa o
formato padro que l a prxima linha (veja abaixo).
Os formatos disponveis so
"*n": l um nmero; este o nico formato que retorna um nmero ao invs de uma
cadeia.
"*a": l o arquivo inteiro, comeando na posio corrente. no fim do arquivo, retorna a
cadeia vazia.
"*l": l a prxima linha pulando o fim de linha, retornando nil no fim do arquivo. Este o
formato padro.
"*L": l a prxima linha mantendo o fim de linha (se presente), retornando nil no fim do
arquivo.
number: l uma cadeia com at esse nmero de bytes, retornando nil no fim do arquivo.
Se number zero, no l nada e retorna uma cadeia vazia, ou nil no fim do arquivo.
file:seek ([whence [, offset]])
Estabelece e obtm a posio do arquivo, medida a partir do incio do arquivo, at a posio
dada por offset mais uma base especificada pela cadeia whence, como segue:
"set": base a posio 0 (incio do arquivo);
"cur": base a posio corrente;
"end": base o fim do arquivo;
Em caso de sucesso, seek retorna a posio final do arquivo, medida em bytes a partir do incio
do arquivo. Se seek falha, retorna nil, mais uma cadeia descrevendo o erro.
O valor padro para whence "cur", e para offset 0. Por isso, a chamada file:seek() retorna a
posio corrente do arquivo, sem modific-la; a chamada file:seek("set") ajusta a posio para o
incio do arquivo (e retorna 0); e a chamada file:seek("end") ajusta a posio para o fim do
arquivo, e retorna seu tamanho.
file:setvbuf (mode [, size])
Estabelece o modo de bufferizao para um arquivo de sada. H trs modos disponveis:
"no": sem bufferizao; o resultado de qualquer operao de sada aparece
imediatamente.
"full": bufferizao completa; a operao realizada somente quando o buffer est cheio
ou quando voc explicitamente descarrega o arquivo (veja io.flush).
"line": bufferizao de linha; a sada bufferizada at que uma quebra de linha seja
produzida ou haja qualquer entrada de alguns arquivos especiais (tal como um dispositivo
terminal).
Para os ltimos dois casos, size especifica o tamanho do buffer, em bytes. O padro um
tamanho apropriado.
file:write ()
Escreve o valor de cada um de seus argumentos para file. Os argumentos devem ser cadeias ou
nmeros.
Em caso de sucesso, esta funo retorna file. Caso contrrio retorna nil mais uma cadeia
descrevendo o erro.
6.9 Facilidades do Sistema Operacional
Esta biblioteca implementada atravs da tabela os.
os.clock ()
Retorna uma aproximao da quantidade em segundos de tempo de CPU usada por um
programa.
os.date ([format [, time]])
Retorna uma cadeia ou uma tabela contendo data e hora, formatada de acordo com a
cadeia format fornecida.
Se o argumento time est presente, essa a hora a ser formatada (veja a funo os.time para
uma descrio desse valor). Caso contrrio, date formata a hora corrente.
Se format comea com '!', ento a data est formatada no Tempo Universal Coordenado. Aps
esse caractere opcional, se format a cadeia "*t", ento date retorna uma tabela com os
seguintes campos: year (quatro dgitos), month (112), day (131), hour (023), min (0
59), sec (061), wday (dia da semana, domingo 1), yday (dia do ano), and isdst (flag do horrio
de vero, um booleano). Esse ltimo campo pode estar ausente se a informao no est
disponvel.
Se format no "*t", ento date retorna a data como uma cadeia, formatada de acordo com as
mesmas regras de ANSI C function strftime.
Quando chamada sem argumentos, date retorna uma representao razovel de data e hora
que depende do sistema hospedeiro e do idioma corrente (isto , os.date() equivalente
a os.date("%c")).
Em sistemas no Posix, esta funo pode no ser segura se h mltiplos fluxos de execuo por
causa de sua dependncia de C function gmtime e C function localtime.
os.difftime (t2, t1)
Retorna o nmero de segundos da hora t1 para a hora t2. Em POSIX, Windows, e alguns outros
sistemas, esse valor exatamente t2-t1.
os.execute ([command])
Esta funo equivalente a ANSI C function system. Ela passa command para ser executado por
um interpretador de comandos de sistema operacional. Seu primeiro resultado true se o
comando terminou com sucesso, ou nil caso contrrio. Aps esse primeiro resultado a funo
retorna uma cadeia e um nmero, como segue:
"exit": o comando terminou normalmente; o nmero seguinte o estado de sada do
comando.
"signal": o comando foi terminado por um sinal; o nmero seguinte o sinal que
terminou o comando.
Quando chamada sem um command, os.execute retorna um booleano que verdadeiro se um
interpretador de comandos est disponvel.
os.exit ([code [, close])
Chama ANSI C function exit para terminar o programa hospedeiro. Se code true, o estado
retornado EXIT_SUCCESS; se code false, o cdigo retornado EXIT_FAILURE; se code um
nmero, o estado retornado esse nmero. O valor padro para code true.
Se o segundo argumento opcional close verdadeiro, fecha o estado Lua antes de sair.
os.getenv (varname)
Retorna o valor da varivel de ambiente do processo varname, ou nil se a varivel no est
definida.
os.remove (filename)
Apaga o arquivo (ou diretrio vazio, em sistemas POSIX) com o nome fornecido. Se esta funo
falha, ela retorna nil, mais uma cadeia descrevendo o erro e o cdigo do erro.
os.rename (oldname, newname)
Renomeia o arquivo ou diretrio chamado oldname para newname. Se esta funo falha, ela
retorna nil, mais uma cadeia descrevendo o erro e o cdigo do erro.
os.setlocale (locale [, category])
Estabelece o idioma (locale) corrente do programa. locale uma cadeia dependente do sistema
especificando um idioma: category uma cadeia opcional descrevendo qual categoria
mudar: "all", "collate", "ctype", "monetary", "numeric", ou "time"; a categoria padro "all". A
funo retorna o nome do novo idioma, ou nil se a requisio no pode ser honrada.
Se locale a cadeia vazia, o idioma corrente definido como uma idioma nativo definido pela
implementao. Se locale a cadeia "C", o idioma corrente definido como o idioma de C
padro.
Quando chamada com nil como primeiro argumento, esta funo somente retorna o nome do
idioma corrente para a categoria fornecida.
Esta funo pode no ser segura se h mltiplos fluxos de execuo por causa de sua
dependncia de C function setlocale.
os.time ([table])
Retorna o tempo corrente quando chamada sem argumentos, ou um tempo representando a
data e a hora especificados pela tabela dada. Esta tabela deve ter campos year, month, e day, e
pode ter campos hour (o padro 12), min (o padro 0), sec (o padro 0), e isdst (o padro
nil). Para uma descrio desses campos, veja a funo os.date.
O valor retornado um nmero, cujo significado depende de seu sistema. Em POSIX, Windows, e
alguns outros sistemas, este nmero conta o nmero de segundos desde algum dado tempo de
incio (a "poca"). Em outros sistemas, o significado no especificado, e o nmero retornado
por time por ser usado somente como um argumento para os.date e os.difftime.
os.tmpname ()
Retorna uma cadeia com um nome de arquivo que pode ser usado para um arquivo temporrio.
O arquivo deve ser explicitamente aberto antes de seu uso e explicitamente removido quando
no mais necessrio.
Em sistemas POSIX, esta funo tambm cria um arquivo com esse nome, para evitar riscos de
segurana. (Alguma outra pessoa poderia criar o arquivo com permisses erradas no tempo
entre obter o nome e criar o arquivo.) Voc ainda tem que abrir o arquivo para us-lo e para
remov-lo (mesmo se voc no us-lo).
Quando possvel, voc pode preferir usar io.tmpfile, que automaticamente remove o arquivo
quando o programa termina.
6.10 A Biblioteca de Depurao
Esta biblioteca oferece a funcionalidade da interface de depurao (4.9) para programas Lua.
Voc deve ter cuidado ao usar esta biblioteca. Vrias de suas funes violam suposies bsicas
a respeito de cdigo Lua (e.g., que variveis locais a uma funo no podem ser acessadas de
fora; que metatabelas de userdatas no podem ser modificadas por cdigo Lua; que programas
Lua no quebram) e por isso podem comprometer cdigo que de outro modo seria seguro. Alm
disso, algumas funes desta biblioteca podem ser lentas.
Todas as funes desta biblioteca so oferecidas dentro da tabela debug. Todas as funes que
operam sobre um fluxo de execuo possuem um primeiro argumento opcional que o fluxo
sobre o qual operar. O padro sempre o fluxo corrente.
debug.debug ()
Entra em um modo interativo com o usurio, executando cada cadeia que o usurio entra.
Usando comandos simples e outras facilidades de depurao, o usurio pode inspecionar
variveis globais e locais, modificar seus valores, avaliar expresses, e assim por diante. Uma
linha contendo somente a palavra cont finaliza esta funo, de modo que a chamadora continua
sua execuo.
Note que comandos para debug.debug no esto lexicamente aninhados dentro de nenhuma
funo e assim no possuem acesso direto a variveis locais.
debug.gethook ([thread])
Retorna as configuraes de gancho correntes do fluxo, como trs valores: a funo de gancho
corrente, a mscara de gancho corrente, e o contador de gancho corrente (como definido pela
funo debug.sethook).
debug.getinfo ([thread,] f [, what])
Retorna uma tabela com informao sobre uma funo. Voc pode fornecer a funo
diretamente ou voc pode fornecer um nmero como o valor de f, o qual significa a funo
executando no nvel f da pilha de chamadas do fluxo fornecido: o nvel 0 a funo corrente (a
prpria getinfo); o nvel 1 a funo que chamou getinfo (exceto para chamadas finais, que no
contam na pilha); e assim por diante. Se f um nmero maior do que o nmero de funes
ativas, ento getinfo retorna nil.
A tabela retornada pode conter todos os campos retornados por lua_getinfo, com a
cadeia what descrevendo quais campos preencher. O padro para what obter toda informao
disponvel, exceto a tabela de linhas vlidas. Se presente, a opo 'f' adiciona um campo
chamado func com a prpria funo. Se presente, a opo 'L' adiciona um campo
chamado activelines com a tabela de linhas vlidas.
Por exemplo, a expresso debug.getinfo(1,"n").name retorna uma tabela com um nome para a
funo corrente, se um nome razovel puder ser encontrado. e a
expresso debug.getinfo(print) retorna uma tabela com toda informao disponvel sobre a
funo print.
debug.getlocal ([thread,] f, local)
Esta funo retorna o nome e o valor da varivel local com ndice local da funo no nvel f da
pilha. Esta funo acessa no somente variveis locais explcitas, mas tambm parmetros,
temporrios, etc.
O primeiro parmetro ou varivel local possui ndice 1, e assim por diante, at a ltima varivel
ativa. ndices negativos se referem a parmetros vararg; -1 o primeiro parmetro vararg. A
funo retorna nil se no h nenhuma varivel com o ndice fornecido, e lana um erro quando
chamada com um nvel fora do intervalo. (Voc pode chamar debug.getinfo para verificar se o
nvel vlido.)
Nomes de variveis comeando com '(' (abre parntese) representam variveis internas
(variveis de controle de lao, temporrios, varargs, e locais de funes C).
O parmetro f tambm pode ser uma funo. Nesse caso, getlocal retorna somente o nome dos
parmetros da funo.
debug.getmetatable (value)
Retorna a metatabela do value fornecido ou nil se ele no possui uma metatabela.
debug.getregistry ()
Retorna a tabela de registro (veja 4.5).
debug.getupvalue (f, up)
Esta funo retorna o nome e o valor do upvalue com ndice up da funo f. A funo
retorna nil se no h upvalue com o ndice fornecido.
debug.getuservalue (u)
Retorna o valor Lua associado a u. Se u no um userdata, retorna nil.
debug.sethook ([thread,] hook, mask [, count])
Estabelece a funo fornecida como um gancho. A cadeia mask e o nmero count descrevem
quando o gancho ser chamado. A cadeia mask pode ter qualquer combinao dos seguintes
caracteres, com o significado dado:
'c': o gancho chamado toda vez que Lua chama uma funo;
'r': o gancho chamado toda vez que retorna de uma funo;
'l': o gancho chamado toda vez que Lua entra uma nova linha de cdigo.
Alm disso, com um count diferente de zero, o gancho chamado tambm aps
cada count instrues.
Quando chamada sem argumentos, debug.sethook desabilita o gancho.
Quando o gancho chamado, seu primeiro parmetro uma cadeia descrevendo o evento que
disparou sua chamada: "call" (ou "tail call"),"return", "line", e "count". Para eventos de linha, o
gancho tambm recebe o novo nmero de linha como seu segundo parmetro. Dentro de um
gancho, voc pode chamar getinfo com nvel 2 para obter mais informao sobre a funo
executando. (o nvel 0 a funo getinfo, e o nvel 1 a funo de gancho).
debug.setlocal ([thread,] level, local, value)
Esta funo atribui o valor value varivel local com ndice local da funo no nvel level da
pilha. A funo retorna nil se no h nenhuma varivel local com o ndice fornecido, e lana um
erro quando chamada com um level fora do intervalo. (Voc pode chamar getinfo para verificar
se o nvel vlido.) Caso contrrio, retorna o nome da varivel local.
Veja debug.getlocal para mais informaes sobre ndices e nomes de variveis.
debug.setmetatable (value, table)
Estabelece a table fornecida (que pode ser nil) como a metatabela para o value fornecido.
Retorna value.
debug.setupvalue (f, up, value)
Esta funo atribui o valor value ao upvalue com ndice up da funo f. A funo retorna nil se
no h nenhum upvalue com o ndice fornecido. Caso contrrio, retorna o nome do upvalue.
debug.setuservalue (udata, value)
Estabelece o value fornecido como o valor Lua associado ao udata dado. value deve ser uma
tabela ou nil; udata deve ser um userdata completo.
Retorna udata.
debug.traceback ([thread,] [message [, level]])
Se message est presente mas no uma cadeia nem nil, esta funo retorna message sem
processamento adicional. Caso contrrio, retorna uma cadeia com um trao da pilha de
chamadas. Uma cadeia opcional message adicionada ao incio do trao. Um nmero
opcional level diz em qual nvel comear o trao (o padro 1, a funo chamando traceback).
debug.upvalueid (f, n)
Retorna um identificador nico (como um userdata leve) para o upvalue com nmero n da
funo fornecida.
Esses identificadores nicos permitem um programa verificar se diferentes fechos compartilham
upvalues. Fechos Lua que compartilham um upvalue (isto , que acessam uma mesma varivel
local externa) retornaro identificadores idnticos para esses ndices de upvalues.
debug.upvaluejoin (f1, n1, f2, n2)
Faz o n1-simo upvalue do fecho Lua f1 se referir ao n2-simo upvalue do fecho Lua f2.
7 O Interpretador de Linha de Comando Lua
Embora Lua tenha sido projetada como uma linguagem de extenso, para ser embarcada em um
programa C hospedeiro, ela tambm frequentemente usada como uma linguagem auto-
suficiente. Um interpretador para Lua como uma linguagem auto-suficiente, chamado
simplesmente de lua, fornecido com a distribuio padro. O interpretador de linha de
comando inclui todas as bibliotecas padro, incluindo a biblioteca de depurao. Seu uso :
lua [options] [script [args]]
As opes so:
-e comando: executa a cadeia comando;
-l mod: "requisita" mod;
-i: entra em modo interativo aps executar script;
-v: imprime informaes da verso;
-E: ignora variveis de ambiente;
--: para de tratar opes;
-: executa stdin como um arquivo e para de tratar opes.
Aps tratar suas opes, lua executa o script fornecido, passando pra ele os args fornecidos
como argumentos do tipo cadeia. Quando chamado sem argumentos, lua comporta-se como lua
-v -i quando a entrada padro (stdin) um terminal, e como lua - caso contrrio.
Quando chamado sem a opo -E, o interpretador verifica se h uma varivel de
ambiente LUA_INIT_5_2 (ou LUA_INIT se ela no est definida) antes de executar ser argumento.
Se o contedo da varivel possui o formato @nomearquivo, ento lua executa o arquivo. Caso
contrrio, lua executa a prpria cadeia.
Quando chamado com a opo -E, alm de ignorar LUA_INIT, Lua tambm ignora os valores
de LUA_PATH e LUA_CPATH, estabelecendo os valores depackage.path e package.cpath com os
caminhos padro definidos em luaconf.h.
Todas as opes so tratadas em ordem, exceto -i e -E. Por exemplo, uma invocao como
$ lua -e'a=1' -e 'print(a)' script.lua
ir primeiro atribuir 1 a a, em seguida imprimir o valor de a, e finalmente executar o
arquivo script.lua sem argumentos. (Aqui $ o prompt do interpretador de comandos. Seu
prompt pode ser diferente.)
Antes de comear a executar o script, lua junta todos os argumentos na linha de comando em
uma tabela global chamada arg. O nome do script armazenado no ndice 0, o primeiro
argumento aps o nome do script vai para o ndice 1, e assim por diante. Quaisquer argumentos
antes do nome do script (isto , o nome do interpretador mais as opes) vo para ndices
negativos. Por exemplo, na chamada
$ lua -la b.lua t1 t2
o interpretador primeiro executa o arquivo a.lua, em seguida cria uma tabela
arg = { [-2] = "lua", [-1] = "-la",
[0] = "b.lua",
[1] = "t1", [2] = "t2" }
e finalmente executa o arquivo b.lua. O script chamado com arg[1], arg[2], ... como
argumentos; ele tambm pode acessar esses argumentos com a expresso vararg '...'.
Em modo interativo, se voc escrever um comando incompleto, o interpretador espera que ele
seja completado mostrando um prompt diferente.
Em caso de erros no protegidos no script, o interpretador reporta o erro para o fluxo de sada
padro. Se o objeto de erro uma cadeia, o interpretador adiciona um trao de pilha a ela. Caso
contrrio, se o objeto de erro possui um metamtodo __tostring, o interpretador chama esse
metamtodo para produzir a mensagem final. Finalmente, se o objeto de erro nil, o
interpretador no reporta o erro.
Ao terminar normalmente, o interpretador fecha seu estado Lua principal (veja lua_close). O
script pode evitar esse passo chamando os.exit para terminar.
Para permitir o uso de Lua como um interpretador de scripts em sistemas Unix, o interpretador
de linha de comando pula a primeira linha de um trecho se ela comea com #. Assim, scripts
Lua podem virar programas executveis usando chmod +x e a forma #!, como em
#!/usr/local/bin/lua
(Obviamente, a localizao do interpretador Lua pode ser diferente em sua mquina. Se lua est
no seu PATH, ento
#!/usr/bin/env lua
uma soluo mais portvel.)
8 Incompatibilidades com a Verso Anterior
Aqui listamos as incompatibilidades que voc pode encontrar ao migrar um programa de Lua 5.1
para Lua 5.2. Voc pode evitar algumas incompatibilidades compilando Lua com opes
apropriadas (veja o arquivo luaconf.h). Contudo, todas essas opes de compatibilidade sero
removidas na prxima verso de Lua. De modo similar, todas as caractersticas marcadas como
obsoletas em Lua 5.1 foram removidas em Lua 5.2.
8.1 Mudanas na Linguagem
O conceito de ambiente mudou. Somente funes Lua possuem ambientes. Para
estabelecer o ambiente de uma funo Lua, use a varivel _ENV ou a funo load.
Funes C no possuem mais ambientes. Use um upvalue com uma tabela compartilhada
se voc precisa manter estado compartilhado entre vrias funes C. (Voc pode
usar luaL_setfuncs para abrir uma biblioteca C com todas as funes compartilhando um
upvalue comum.)
Para manipular o "ambiente" de um userdata (o qual agora chamado de valor do
usurio), use as novas funes lua_getuservalue and lua_setuservalue.
Identificadores Lua no podem usar letras dependentes do idioma.
Fazer um passo ou uma coleta completa do coletor de lixo no reinicia o coletor se ele
tiver sido parado.
Tabelas fracas com chaves fracas agora agem como tabelas efmeras.
O evento de retorno final em ganchos de depurao foi removido. Ao invs disso,
chamadas finais geram um evento novo especial, chamada final, de modo que o
depurador pode saber que no haver um evento de retorno correspondente.
A igualdade entre valores do tipo funo foi modificada. Agora, uma definio de funo
pode no criar um novo valor; ela pode reusar algum valor anterior se no h uma
diferena observvel para a nova funo.
8.2 Mudanas nas Bibliotecas
A funo module est obsoleta. fcil montar um mdulo com cdigo Lua normal. No se
espera que mdulos sejam variveis globais.
As funes setfenv e getfenv foram removidas, por causa das mudanas em ambientes.
A funo math.log10 est obsoleta. Use math.log com 10 como seu segundo argumento,
ao invs.
A funo loadstring est obsoleta. Use load ao invs; ela agora aceita cadeias como
argumentos e exatamente equivalente a loadstring.
A funo table.maxn est obsoleta. Escreva-a em Lua se voc realmente precisa dela.
A funo os.execute agora retorna true quando o comando termina com sucesso
e nil mais informao de erro caso contrrio.
A funo unpack foi movida para a biblioteca de tabelas e desse modo deve ser chamada
como table.unpack.
A classe de caracteres %z em padres est obsoleta, pois agora padres podem conter
 '\0' como um caractere normal.
A tabela package.loaders foi renomeada para package.searchers.
Lua no tem mais verificao de bytecode. Assim, todas as funes que carregam cdigo
(load e loadfile) so potencialmente inseguras ao carregar dados binrios no confiveis.
(Na verdade, essas funes j eram inseguras por causa de falhas no algoritmo de
verificao.) Quando em dvida, use o argumento mode dessas funes para restringi-las
a carregar trechos textuais.
Os caminhos padro na distribuio oficial podem mudar entre verses.
8.3 Mudanas na API
O pseudo-ndice LUA_GLOBALSINDEX foi removido. Voc deve obter o ambiente global do
registro (veja 4.5).
O pseudo-ndice LUA_ENVIRONINDEX e as funes lua_getfenv/lua_setfenv foram
removidas, pois funes C no possuem mais ambientes.
A funo luaL_register est obsoleta. Use luaL_setfuncs de modo que seu mdulo no crie
globais. (No se espera mais que mdulos estabeleam variveis globais.)
O argumento osize da funo de alocao pode no ser zero ao criar um novo bloco, isto
, quando ptr NULL (veja lua_Alloc). Use somente o teste ptr == NULL para verificar se o
bloco novo.
Os finalizadores (metamtodos __gc) para userdatas so chamados na ordem reversa em
que eles foram marcados para finalizao, no na que eles foram criados (veja 2.5.1). (A
maioria dos userdatas so marcados imediatamente aps eles serem criados.) Alm disso,
se a metatabela no possui um campo __gc quando definida, o finalizador no ser
chamado, mesmo se ele for definido depois.
luaL_typerror foi removida. Escreva sua prpria verso se voc precisar.
A funo lua_cpcall est obsoleta. Voc pode simplesmente empilhar a funo
com lua_pushcfunction e cham-la com lua_pcall.
As funes lua_equal e lua_lessthan esto obsoletas. Use a nova lua_compare com opes
apropriadas ao invs.
A funo lua_objlen foi renomeada para lua_rawlen.
A funo lua_load tem um parmetro extra, mode. Passe NULL para simular o
comportamento antigo.
A funo lua_resume tem um parmetro extra, from. Passe NULL ou o fluxo fazendo a
chamada.
9 A Sintaxe Completa de Lua
Aqui est a sintaxe completa de Lua em BNF estendido. (Ela no descreve as precedncias dos
operadores.)
trecho ::= bloco
bloco ::= {comando} [comandoret]
comando ::= ; |
listavars = listaexps |
chamadafuno |
rtulo |
break |
goto Nome |
do bloco end |
while exp do bloco end |
repeat bloco until exp |
if exp then bloco {elseif exp then bloco} [else bloco] end |
for Nome = exp , exp [, exp] do bloco end |
for listanomes in listaexps do bloco end |
function nomefuno corpofuno |
local funo Nome corpofuno |
local listanomes [= listaexps]
comandoret ::= return [listaexps] [;]
rtulo ::= :: Nome ::
nomefuno ::= Nome {. Nome} [: Nome]
listavars ::= var {, var}
var ::= Nome | prefixexp [ exp ] | prefixexp . Nome
listanomes ::= Nome {, Nome}
listaexps ::= exp {, exp}
exp ::= nil | false | true | Nmero | Cadeia | ... | deffuno |
expprefixo | construtortabela | exp opbin exp | opunria exp
expprefixo ::= var | chamadafuno | ( exp )
chamadafuno ::= expprefixo args | expprefixo : Nome args
args ::= ( [listaexps] ) | construtortabela | Cadeia
deffuno ::= function corpofuno
corpofuno ::= ( [listapars] ) bloco end
listapars ::= listanomes [, ...] | ...
construtortabela ::= { [listacampos] }
listacampos ::= campo {sepcampos campo} [sepcampos]
campo ::= [ exp ] = exp | Nome = exp | exp
sepcampos ::= , | ;
opbin ::= + | - | * | / | ^ | % | .. |
< | <= | > | >= | == | ~= |
and | or
opunria ::= - | not | #