Manual de Refer�ncia de Lua 5.2
Manual de Refer�ncia de Lua 5.2
por Roberto Ierusalimschy, Luiz Henrique de Figueiredo, Waldemar Celes
(traduzido por Sérgio Queiroz de Medeiros)
Copyright © 2014 Lua.org, PUC-Rio. Dispon�vel livremente nos termos da licen�a de Lua.
Lua � uma linguagem de programa��o de extens�o projetada para dar suporte � programa��o procedimental em geral com facilidades para a descri��o de dados. Ela tamb�m oferece um bom suporte para programa��o orientada a objetos, programa��o funcional, e programa��o orientada a dados. Lua � planejada para ser usada como uma linguagem de script poderosa, leve, e embarc�vel por qualquer programa que necessite de uma. Lua � implementada como uma biblioteca, escrita em C puro, o subconjunto comum de C Padr�o e C++.
Por ser uma linguagem de extens�o, Lua n�o possui a no��o 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 fun��es para executar um peda�o de c�digo Lua,
pode escrever e ler vari�veis Lua,
e pode registrar fun��es C para serem chamadas por c�digo Lua.
Atrav�s do uso de fun��es C, Lua pode ser aumentada para lidar com
uma variedade ampla de dom�nios diferentes,
criando assim linguagens de programa��o personalizadas que compartilham um arcabou�o sint�tico.
A distribui��o 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 licen�a.
A implementa��o descrita neste manual est� dispon�vel
no site oficial de Lua, www.lua.org.
Como qualquer outro manual de refer�ncia, este documento � seco em algumas partes. Para uma discuss�o das decis�es por tr�s do projeto de Lua, veja os artigos t�cnicos dispon�veis no site de Lua. Para uma introdu��o detalhada � programa��o em Lua, veja o livro de Roberto Ierusalimschy, Programming in Lua).
Esta se��o descreve os conceitos b�sicos da linguagem.
Lua � uma linguagem dinamicamente tipada. Isso significa que vari�veis n�o possuem tipos; somente valores possuem tipos. N�o h� defini��es de tipo na linguagem. Todos os valores carregam o seu pr�prio tipo.
Todos os valores em Lua s�o valores de primeira classe. Isso significa que todos os valores podem ser guardados em vari�veis, passados como argumentos para outras fun��es, e retornados como resultados.
H� oito tipos b�sicos 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 aus�ncia de um valor �til.
Boolean � o tipo dos valores false e true.
Tanto nil como false tornam uma condi��o falsa;
qualquer outro valor a torna verdadeira.
Number representa tanto n�meros inteiros como
n�meros reais (ponto flutuante de precis�o dupla).
String representa sequ�ncias imut�veis de bytes.
Lua � 8 bits pura:
cadeias podem conter qualquer valor de 8 bits,
incluindo zeros ('\0') dentro delas.
Lua pode chamar (e manipular) fun��es escritas em Lua e fun��es escritas em C (veja §3.4.9).
O tipo userdata � oferecido para permitir que dados C arbitr�rios sejam guardados em vari�veis Lua. Um valor userdata � um ponteiro para um bloco de mem�ria bruta. H� dois tipos de userdata: userdata completo, onde o bloco de mem�ria � gerenciado por Lua, e userdata leve, onde o bloco de mem�ria � gerenciado pelo hospedeiro. Userdata n�o possui opera��es pr�-definidas em Lua, exceto atribui��o e teste de identidade. Atrav�s do uso de metatabelas, o programador pode definir opera��es para valores userdata completos (veja §2.4). Valores userdata n�o podem ser criados ou modificados em Lua, somente atrav�s da API C. Isso garante a integridade de dados que pertencem ao programa hospedeiro.
O tipo thread representa fluxos de execu��o independentes e � usado para implementar co-rotinas (veja §2.6). N�o confunda fluxos de execu��o Lua com processos leves do sistema operacional. Lua d� suporte a co-rotinas em todos os sistemas, at� mesmo naqueles que n�o d�o suporte a processos leves.
O tipo table implementa arrays associativos,
isto �, arrays que podem ser indexados n�o apenas com n�meros,
mas com qualquer valor Lua exceto nil e NaN
(Not a Number, um valor num�rico especial usado para representar
resultados indefinidos ou n�o represent�veis, tais como 0/0).
Tabelas podem ser heterog�neas;
isto �, elas podem conter valores de todos os tipos (exceto nil).
Qualquer chave com valor nil n�o � considerada parte da tabela.
De modo rec�proco, qualquer chave que n�o � parte da tabela possui
um valor nil associado.
Tabelas s�o o �nico mecanismo de estrutura��o de dados em Lua;
elas podem ser usadas para representar arrays comuns, sequ�ncias,
tabelas de s�mbolos, conjuntos, registros, grafos, �rvores, etc.
Para representar registros, Lua usa o nome do campo como um �ndice.
A linguagem d� suporte a essa representa��o
fornecendo a.nome como a��car sint�tico para a["nome"].
H� v�rias maneiras convenientes para criar tabelas em Lua
(veja §3.4.8).
Usamos o termo sequ�ncia para denotar uma tabela onde o conjunto de todas as chaves num�ricas positivas � igual a {1..} para algum inteiro n, que � chamado o comprimento da sequ�ncia (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 fun��es s�o valores de primeira classe, campos de tabela podem conter fun��es. Portanto, tabelas podem tamb�m conter m�todos (veja §3.4.10).
A indexa��o de tabelas segue
a defini��o de igualdade primitiva na linguagem.
As express�es a[i] e a[j]
denotam o mesmo elemento da tabela
se e somente se i e j s�o iguais primitivos
(isto �, iguais sem metam�todos).
Valores do tipo table, function, thread, e userdata (completo) s�o objetos: vari�veis n�o cont�m realmente esses valores, somente refer�ncias para eles. Atribui��o, passagem de par�metro, e retornos de fun��o sempre manipulam refer�ncias para tais valores; essas opera��es n�o implicam em qualquer esp�cie de c�pia.
A fun��o da biblioteca type retorna uma cadeia descrevendo o tipo
de um dado valor (veja §6.1).
Como ser� discutido em §3.2 e §3.3.3,
qualquer refer�ncia a um nome global var � sintaticamente traduzido
para _ENV.var.
Al�m disso, todo trecho � compilado no escopo de
uma vari�vel local externa chamada _ENV (veja §3.3.2),
ent�o o pr�prio _ENV nunca � um nome global em um trecho.
Apesar da exist�ncia dessa vari�vel _ENV externa e
da tradu��o de nomes globais,
_ENV � um nome completamente normal.
Em particular,
voc� pode definir novas vari�veis e par�metros com esse nome.
Cada refer�ncia a um nome global usa a _ENV que �
vis�vel 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 mant�m um ambiente distinto chamado de o ambiente global.
Esse valor � mantido em um �ndice especial no registro C (veja §4.5).
Em Lua, a vari�vel _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 padr�o,
vari�veis globais em c�digo Lua se referem a entradas no ambiente global.
Al�m disso, todas as bibliotecas padr�o s�o carregadas no ambiente global
e v�rias fun��es s�o 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 ent�o mudar o valor
de seu primeiro upvalue.)
Se voc� mudar o ambiente global no registro
(atrav�s de c�digo C ou da biblioteca de depura��o),
todos os trechos carregados ap�s a mudan�a ter�o o novo ambiente.
Trechos carregados anteriormente n�o s�o afetados, contudo,
uma vez que cada um tem sua pr�pria refer�ncia para o ambiente na sua vari�vel _ENV.
Al�m disso, a vari�vel _G
(que � guardada no ambiente global original)
nunca � atualizada por Lua.
Por conta que Lua � uma linguagem embarcada,
todas as a��es de Lua come�am a partir de c�digo C no programa hospedeiro
chamando uma fun��o da biblioteca de Lua (veja lua_pcall).
Sempre que um erro ocorre durante
a compila��o ou execu��o de um trecho Lua,
o controle retorna para o programa hospedeiro,
que pode tomar as medidas apropriadas
(tais como imprimir uma mensagem de erro).
C�digo Lua pode explicitamente gerar um erro atrav�s de um chamada
� fun��o error.
Se voc� precisa capturar erros em Lua,
voc� pode usar pcall ou xpcall
para chamar uma dada fun��o em modo protegido.
Sempre que h� um erro,
um objeto de erro (tamb�m chamado de uma mensagem de erro)
� propagado com informa��o 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 fun��o � 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 informa��o sobre o erro,
por exemplo atrav�s da inspe��o da pilha e da cria��o de um tra�o (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 la�o continua, Lua o interrompe e retorna uma mensagem de erro apropriada.
Todo valor em Lua pode ter uma metatabela.
Essa metatabela � uma tabela Lua comum
que define o comportamento do valor original
sob certas opera��es especiais.
Voc� pode mudar v�rios aspectos do comportamento
de opera��es sobre um valor especificando campos espec�ficos em sua metatabela.
Por exemplo, quando um valor n�o num�rico � o operando de uma adi��o,
Lua verifica se h� uma fun��o no campo "__add" da metatabela do valor.
Se ela acha uma,
Lua chama essa fun��o para realizar a adi��o.
As chaves em uma metatabela s�o derivadas a partir dos nomes dos eventos;
os valores correspondentes s�o chamados de metam�todos.
No exemplo anterior, o evento � "add"
e o metam�todo � a fun��o que realiza a adi��o.
Voc� pode consultar a metatabela de qualquer valor
usando a fun��o getmetatable.
Voc� pode substituir a metatabela de tabelas
usando a fun��o setmetatable.
Voc� n�o pode mudar a metatabela de outros tipos a partir de Lua
(exceto usando a biblioteca de depura��o);
voc� deve usar a API C para isso.
Tabelas e userdatas completos t�m metatabelas individuais (embora m�ltiplas 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 n�meros, uma para todas as cadeias, etc. Por padr�o, um valor n�o 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 opera��es aritm�ticas, compara��es de ordem, concatena��o, opera��o de comprimento, e indexa��o. Uma metatabela tamb�m pode definir uma fun��o a ser chamada quando um userdata ou uma tabela s�o recolhidos pelo coletor de lixo. Quando Lua realiza uma dessas opera��es sobre um valor, ela verifica se esse valor possui uma metatabela com um evento correspondente. Se possui, o valor associado com aquela chave (o metam�todo) controla como Lua realizar� a opera��o.
Metatabelas controlam as opera��es listadas a seguir.
Cada opera��o � identificada por seu nome correspondente.
A chave para cada opera��o � uma cadeia com seu nome precedido por
dois sublinhados, '__';
por exemplo, a chave para a opera��o "add" � a
cadeia "__add".
A sem�ntica dessas opera��es � melhor explicada por uma fun��o Lua
descrevendo como o interpretador executa a opera��o.
O c�digo mostrado aqui em Lua � somente ilustrativo;
o comportamento real est� codificado no interpretador
e � muito mais eficiente do que esta simula��o.
Todas as fun��es usadas nestas descri��es
(rawget, tonumber, etc.)
s�o descritas em §6.1.
Em particular, para recuperar o metam�todo de um dado objeto,
usamos a express�o
metatabela(obj)[evento]
Isso deve ser lido como
rawget(getmetatable(obj) or {}, evento)
Isso significa que o acesso a um metam�todo n�o invoca outros metam�todos, e o acesso a objetos que n�o possuem metatabelas n�o falha (ele simplesmente resulta em nil).
Para os operadores un�rios - e #,
o metam�todo � chamado com um segundo argumento dummy.
Esse argumento extra � somente para simplificar a implementa��o de Lua;
ele pode ser removido em vers�es futuros e portanto n�o est� presente
no c�digo a seguir.
(Para a maioria dos usos esse argumento extra � irrelevante.)
+ opera��o.
A fun��o getbinhandler abaixo define como Lua escolhe o tratador
para uma opera��o bin�ria.
Primeiro, Lua tenta o primeiro operando.
Se seu tipo n�o define o tratador para a opera��o,
ent�o Lua tenta o segundo operando.
function getbinhandler (op1, op2, evento)
return metatable(op1)[evento] or metatable(op2)[evento]
end
Usando essa fun��o,
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 s�o num�ricos?
return o1 + o2 -- '+' aqui � a 'add' primitiva
else -- pelo menos um dos operandos n�o � num�rico
local h = getbinhandler(op1, op2, "__add")
if h then
-- chama o tratador com ambos os operandos
return (h(op1, op2))
else -- nenhum tratador dispon�vel: comportamento padr�o
error(···)
end
end
end
-.
Comportamento similar ao da opera��o "add".
*.
Comportamento similar ao da opera��o "add".
/.
Comportamento similar ao da opera��o "add".
%.
Comportamento similar ao da opera��o "add",
com a opera��o
o1 - floor(o1/o2)*o2 como a opera��o primitiva.
^ (exponencia��o).
Comportamento similar ao da opera��o "add",
com a fun��o pow (da biblioteca matem�tica de C)
como opera��o primitiva.
- un�ria.
function unm_event (op)
local o = tonumber(op)
if o then -- operando � num�rico?
return -o -- '-' aqui � a 'unm' primitiva
else -- o operando n�o � num�rico
-- 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 dispon�vel: comportamento padr�o
error(···)
end
end
end
.. (concatena��o).
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 -- concatena��o primitiva de cadeias
else
local h = getbinhandler(op1, op2, "__concat")
if h then
return (h(op1, op2))
else
error(···)
end
end
end
#.
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 dispon�vel: erro
error(···)
end
end
end
Veja §3.4.6 para uma descri��o do comprimento de uma tabela.
==.
A fun��o getequalhandler define como Lua escolhe um metam�todo
para igualdade.
Um metam�todo � selecionado somente quando ambos os valores
sendo comparados possuem o mesmo tipo
e o mesmo metam�todo para a opera��o selecionada,
e os valores s�o 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 s�o iguais
end
-- tenta metam�todo
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.
<.
function lt_event (op1, op2)
if type(op1) == "number" and type(op2) == "number" then
return op1 < op2 -- compara��o num�rica
elseif type(op1) == "string" and type(op2) == "string" then
return op1 < op2 -- compara��o lexicogr�fica
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.
<=.
function le_event (op1, op2)
if type(op1) == "number" and type(op2) == "number" then
return op1 <= op2 -- compara��o num�rica
elseif type(op1) == "string" and type(op2) == "string" then
return op1 <= op2 -- compara��o lexicogr�fica
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 aus�ncia de um metam�todo "le",
Lua tenta o "lt", assumindo que a <= b �
equivalente a not (b < a).
Como com os outros operadores de compara��o, o resultado � sempre um booleano.
table[key].
Note que o metam�todo � tentado somente
quando key n�o est� presente em table.
(Quando table n�o � uma tabela,
nunca uma chave est� presente,
ent�o o metam�todo � 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 opera��o sobre ele
end
end
table[key] = value.
Note que o metam�todo � tentado somente
quando key n�o 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 atribui��o 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 opera��o sobre ele
end
end
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
Lua realiza gerenciamento autom�tico de mem�ria. Isso significa que voc� n�o precisa se preocupar com a aloca��o de mem�ria para novos objetos nem com a libera��o dela quando os objetos n�o s�o mais necess�rios. Lua gerencia mem�ria automaticamente executando um coletor de lixo para coletar todos os objetos mortos (isto �, objetos que n�o s�o mais acess�veis a partir de Lua). Toda mem�ria usada por Lua est� sujeita ao gerenciamento autom�tico: cadeias, tabelas, userdatas, fun��es, fluxos de execu��o, estruturas internas, etc. Lua implementa um coletor marca-e-varre (mark-and-sweep) incremental. Ele usa dois n�meros 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 come�ar um novo ciclo. Valores maiores fazem o coletor ser menos agressivo. Valores menores do que 100 significam que o coletor n�o esperar� para iniciar um novo ciclo. Um valor de 200 significa que o coletor espera a mem�ria 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 rela��o � aloca��o de mem�ria. Valores maiores fazem o coletor ser mais agressivo mas tamb�m 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 padr�o � 200, o que significa que o coletor executa no "dobro" da velocidade de aloca��o de mem�ria.
Se voc� atribuir ao multiplicador de passo um n�mero muito grande (maior do que 10% do n�mero m�ximo de bytes que o programa pode usar), o coletor se comporta como um coletor pare-o-mundo. Se voc� ent�o atribuir 200 � pausa, o coletor se comporta como em vers�es antigas de Lua, fazendo uma coleta completa toda vez que Lua dobra sua mem�ria em uso.
Voc� pode mudar esses n�meros chamando lua_gc em C
ou collectgarbage em Lua.
Voc� pode tamb�m usar essas fun��es para controlar
o coletor diretamente (e.g., par�-lo e reinici�-lo).
Como uma caracter�stica experimental em Lua 5.2, voc� pode mudar o modo de opera��o 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 tamb�m incrementa o uso de mem�ria (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 caracter�stica experimental; voc� � bem-vindo a experiment�-la, mas verifique seus ganhos.
Voc� pode especificar metam�todos do coletor de lixo para tabelas
e, usando a API C,
para userdatas completos (veja §2.4).
Esses metam�todos s�o tamb�m chamados finalizadores.
Finalizadores permitem voc� coordenar a coleta de lixo de Lua
com o gerenciamento de recursos externos
(tais como o fechamento de arquivos, conex�es de rede ou de banco de dados,
ou a libera��o de sua pr�pria mem�ria).
Para um objeto (tabela ou userdata) ser finalizada quando coletada,
voc� deve marc�-la para finaliza��o.
Voc� marca um objeto para finaliza��o 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 n�o ser� marcado para finaliza��o.
Contudo, ap�s um objeto ser marcado,
voc� pode livremente mudar o campo __gc de sua metatabela.
Quando um objeto marcado torna-se lixo, ele n�o � coletado imediatamente pelo coletor de lixo. Ao inv�s disso, Lua coloca-o em uma lista. Ap�s a coleta, Lua faz o equivalente da fun��o 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 s�o 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 execu��o de cada finalizador pode ocorrer em qualquer ponto durante a execu��o do c�digo regular.
Por causa que os objetos sendo coletados devem ainda ser usados pelo finalizador, ele (e outros objetos acess�veis somente atrav�s dele) deve ser ressuscitado por Lua. Geralmente, essa ressurrei��o � passageira, e a mem�ria do objeto � liberada no pr�ximo ciclo de coleta de lixo. Contudo, se o finalizador guarda o objeto em alguma espa�o global (e.g., uma vari�vel global), ent�o h� uma ressurrei��o permanente. Em todo o caso, a mem�ria do objeto � liberada somente quando ele se torna completamente inacess�vel; 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 finaliza��o,
seguindo a ordem inversa em que eles foram marcados.
Se qualquer finalizador marca novos objetos para coleta durante essa fase,
esses novos objetos n�o ser�o finalizados.
Uma tabela fraca � uma tabela cujos elementos s�o refer�ncias fracas. Uma refer�ncia fraca � ignorada pelo coletor de lixo. Em outras palavras, se as �nicas refer�ncias para um objeto s�o refer�ncias fracas, ent�o 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 s�o fracas.
Se __mode cont�m 'v',
os valores na tabela s�o fracos.
Uma tabela com chaves fracas e valores fortes � tamb�m chamada de uma tabela ef�mera. Em uma tabela ef�mera, um valor � considerado alcan��vel somente se sua chave � alcan��vel. Em particular, se a �nica refer�ncia para uma chave � atrav�s desse valor, o par � removido.
Qualquer mudan�a na fragilidade de uma tabela ter� efeito somente no pr�ximo 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 mudan�a fazer efeito.
Somente objetos que possuem uma constru��o expl�cita s�o removidos de tabelas fracas. Valores, tais como n�meros e fun��es C leves, n�o est�o sujeitos � coleta de lixo, e por isso n�o s�o removidos de tabelas fracas (a menos que seu valor associado seja coletado). Embora cadeias estejam sujeitas � coleta de lixo, elas n�o possuem uma constru��o expl�cita, e por isso n�o s�o removidas de tabelas fracas.
Objetos ressuscitados (isto �, objetos sendo finalizados e objetos acess�veis somente atrav�s de objetos sendo finalizados) t�m um comportamento especial em tabelas fracas. Eles s�o removidos de valores fracos antes da execu��o de seus finalizadores, mas s�o removidos de chaves fracas somente na pr�xima coleta ap�s a execu��o de seus finalizadores, quando tais objetos s�o realmente liberados. Esse comportamento permite o finalizador acessar propriedades associadas com o objeto atrav�s de tabelas fracas.
Se uma tabela fraca est� entre os objetos ressuscitados em um ciclo de coleta, ela pode n�o ser apropriadamente limpa at� o pr�ximo ciclo.
Lua oferece suporte a co-rotinas, tamb�m chamadas de fluxos de execu��o m�ltiplos colaborativos. Uma co-rotina em Lua representa um fluxo de execu��o independente. Ao contr�rio de processos leves em sistemas que d�o suporte a m�ltiplos fluxos de execu��o, contudo, uma co-rotina somente suspende sua execu��o atrav�s de uma chamada expl�cita a uma fun��o de cess�o.
Voc� cria uma co-rotina chamando coroutine.create.
Seu �nico argumento � uma fun��o
que � a fun��o principal da co-rotina.
A fun��o create somente cria uma nova co-rotina e
retorna uma refer�ncia para ela (um objeto do tipo thread);
ela n�o 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 execu��o retornado por coroutine.create,
a co-rotina inicia sua execu��o.
na primeira linha de sua fun��o principal.
Argumentos extras passados para coroutine.resume s�o passados
para a fun��o principal da co-rotina.
Ap�s a co-rotina come�ar sua execu��o,
ela executa at� que termine ou ceda.
Uma co-rotina pode terminar sua execu��o de duas maneiras:
normalmente, quando sua fun��o principal retorna
(explicitamente ou implicitamente, ap�s a �ltima instru��o);
e anormalmente, se h� um erro n�o protegido.
No primeiro caso, coroutine.resume retorna true,
mais quaisquer valores retornados pela fun��o 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 cess�o aconteceu dentro de chamadas de fun��o aninhadas
(isto �, n�o na fun��o principal,
mas em uma fun��o diretamente ou indiretamente chamada pela fun��o principal).
No caso de uma cess�o, coroutine.resume tamb�m retorna true,
mais quaisquer valores passados para coroutine.yield.
Da pr�xima vez que voc� reiniciar a mesma co-rotina,
ela continua sua execu��o a partir do ponto onde ela cedeu,
com a chamada a coroutine.yield retornando quaisquer
argumentos extras passados para coroutine.resume.
Como coroutine.create,
a fun��o coroutine.wrap tamb�m cria uma co-rotina,
mas ao inv�s de retornar a pr�pria co-rotina,
ela retorna uma fun��o que, quando chamada, reinicia a co-rotina.
Quaisquer argumentos passados para essa fun��o
v�o como argumentos extras para coroutine.resume.
coroutine.wrap retorna todos os valores retornados por coroutine.resume,
exceto o primeiro (o c�digo booleano de erro).
Ao contr�rio de coroutine.resume,
coroutine.wrap n�o captura erros;
qualquer erro � propagado para o chamador.
Como um exemplo de como co-rotinas funcionam, considere o seguinte c�digo:
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 sa�da:
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 tamb�m criar e manipular co-rotinas atrav�s da API C:
veja as fun��es lua_newthread, lua_resume,
e lua_yield.
Esta se��o descreve o l�xico, a sintaxe, e a sem�ntica de Lua. Em outras palavras, esta se��o descreve quais elementos l�xicos s�o v�lidos, como eles podem ser combinados, e o que suas combina��es significam.
As constru��es da linguagem ser�o explicadas usando a nota��o BNF estendida usual, na qual {a} significa 0 ou mais a's, e [a] significa um a opcional. N�o-terminais s�o mostrados como n�o-terminal, palavras-chave s�o mostradas como kword, e outros s�mbolos terminais s�o mostrados como ‘=’. A sintaxe completa de Lua pode ser encontrada em §9 no fim deste manual.
Lua � uma linguagem de formato livre. Ela ignora espa�os (incluindo quebras de linha) e coment�rios entre elementos l�xicos (tokens), exceto como delimitadores entre nomes e palavras-chave.
Nomes (tamb�m chamados de identificadores) em Lua podem ser qualquer cadeia de letras, d�gitos, e sublinhados, que n�o iniciam com um d�gito. Identificadores s�o usados para nomear vari�veis, campos de tabelas, e r�tulos.
As seguintes palavras-chave s�o reservadas e n�o 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 min�sculas de mai�sculas:
and � uma palavra reservada, mas And e AND
s�o dois nomes v�lidos diferentes.
Como uma conven��o, nomes come�ando com um sublinhado seguido por
letras mai�sculas (tais como _VERSION)
s�o reservados para vari�veis usadas por Lua.
As seguintes cadeias denotam outros elementos l�xicos:
+ - * / % ^ #
== ~= <= >= < > =
( ) { } [ ] ::
; : , . .. ...
Cadeias literais
podem ser delimitadas por aspas simples ou duplas balanceadas,
e podem conter as seguintes sequ�ncias de escape similares �s de C:
'\a' (campainha),
'\b' (retrocesso),
'\f' (alimenta��o de formul�rio),
'\n' (quebra de linha),
'\r' (retorno de carro),
'\t' (tabula��o horizontal),
'\v' (tabula��o vertical),
'\\' (barra invertida),
'\"' (cita��o [aspa dupla]),
e '\'' (ap�strofo [aspa simples]).
Uma barra invertida seguida por uma quebra de linha de verdade
resulta em uma quebra de linha na cadeia.
A sequ�ncia de escape '\z' pula a extens�o seguinte
de caracteres de espa�o em branco,
incluindo quebras de linha;
ela � particularmente �til para quebrar e identar uma cadeia de literais longa
em m�ltiplas linhas sem adicionar as quebras de linha e espa�os
ao conte�do da cadeia.
Um byte em uma cadeia literal pode tamb�m ser especificado atrav�s de seu valor num�rico.
Isso pode ser feito com a sequ�ncia de escape \xXX,
onde XX � uma sequ�ncia de exatamente dois d�gitos hexadecimais,
ou com a sequ�ncia de escape \ddd,
onde ddd � uma sequ�ncia de at� tr�s d�gitos decimais.
(Note que se um escape decimal deve ser seguido por um d�gito,
ele deve ser expresso usando exatamente tr�s d�gitos.)
Cadeias em Lua podem conter qualquer valor de 8 bits, incluindo zeros dentro delas,
os quais podem ser especificados como '\0'.
Cadeias literais podem tamb�m ser definidas usando um formato longo
delimitado por colchetes longos.
Definimos um colchete longo de abertura de n�vel n como um abre
colchete seguido por n sinais de igual seguidos por outro
abre colchete.
Assim, um abre colchete longo de n�vel 0 � escrito como [[,
um abre colchete longo de n�vel 1 � escrito como [=[,
e assim por diante.
Um colchete longo de fechamento � definido similarmente;
por exemplo, um colchete longo de fechamento de n�vel 4 � escrito como ]====].
Um literal longo come�a com um colchete longo de abertura de qualquer n�vel e
termina no primeiro colchete longo de fechamento do mesmo n�vel.
Ele pode conter qualquer texto exceto um colchete de fechamento do n�vel apropriado.
Literais expressos dessa forma podem se estender por v�rias linhas,
n�o interpretam nenhuma sequ�ncia de escape,
e ignoram colchetes longos de qualquer outro n�vel.
Qualquer tipo de sequ�ncia 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 n�o � afetada explicitamente pelas regras anteriores representa ele mesmo. Contudo, Lua abre arquivos para parsing em modo texto, e as fun��es de arquivo do sistema podem ter problemas com alguns caracteres de controle. Assim, � mais seguro representar dados n�o-textuais como um literal entre aspas com sequ�ncias de escape expl�citas para caracteres n�o-textuais.
Por conveni�ncia,
quando o colchete longo de abertura � imediatamente seguido por uma quebra de linha,
a quebra de linha n�o � inclu�da 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 num�rica pode ser escrita com um parte fracion�ria opcional
e um expoente decimal opcional,
marcado por uma letra 'e' ou 'E'.
Lua tamb�m aceita constantes hexadecimais,
as quais come�am com 0x ou 0X.
Constantes hexadecimais tamb�m aceitam uma parte fracion�ria opcional
mais um expoente bin�rio opcional,
marcado por uma letra 'p' ou 'P'.
Exemplos de contantes num�ricas v�lidas s�o
3 3.0 3.1416 314.16e-2 0.31416E1
0xff 0x0.1E 0xA23p-4 0X1.921FB54442D18P+1
Um coment�rio come�a com um h�fen duplo (--)
em qualquer lugar fora de uma cadeia.
Se o texto imediatamente ap�s -- n�o � um colchete longo de abertura,
o coment�rio � um coment�rio curto,
que se estende at� o fim da linha.
Caso contr�rio, ele � um coment�rio longo,
que se estende at� o colchete longo de fechamento correspondente.
Coment�rios longos s�o frequentemente usados para desabilitar c�digo temporariamente.
Vari�veis s�o lugares que guardam valores. H� tr�s tipos de vari�veis em Lua: vari�veis globais, vari�veis locais, e campos de tabelas.
Um �nico nome pode denotar uma vari�vel global ou uma vari�vel local (ou um par�metro formal de uma fun��o, que � um tipo particular de vari�vel local):
var ::= Nome
Nome denota identificadores, como definido em §3.1.
Qualquer nome de vari�vel � assumido ser global a menos que explicitamente declarado como um local (veja §3.3.7). Vari�veis locais possuem escopo l�xico: vari�veis locais podem ser acessadas livremente por fun��es definidas dentro do seu escopo (veja §3.5).
Antes da primeira atribui��o a uma vari�vel, seu valor � nil.
Colchetes s�o 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 vari�vel indexada t[i] � equivalente a
uma chamada gettable_event(t,i).
(Veja §2.4 para uma descri��o completa da
fun��o gettable_event.
Essa fun��o n�o � definida nem pode ser chamada em Lua.
Usamos ela aqui somente para fins did�ticos.)
A sintaxe var.Nome � apenas a��car sint�tico para
var["Nome"]:
var ::= expprefixo ‘.’ Nome
Um acesso a uma vari�vel global x
� equivalente a _ENV.x.
Devido ao modo que um trecho � compilado,
_ENV nunca � um nome global (veja §2.2).
Lua oferece suporte a um conjunto quase convencional de comandos, similar a aqueles em Pascal ou C. Esse conjunto inclui atribui��es, estruturas de controle, chamadas de fun��o, e declara��es de vari�veis.
Um bloco � uma lista de comandos, que s�o executados sequencialmente:
bloco ::= {comando}
Lua possui comandos vazios que permitem voc� separar comandos com ponto-e-v�rgula, come�ar um bloco com um ponto-e-v�rgula ou escrever dois ponto-e-v�rgula em sequ�ncia:
comando ::= ‘;’
Chamadas de fun��o e atribui��es podem come�ar com um abre par�ntese. Essa possibilidade leva a uma ambiguidade na gram�tica de Lua. Considere o seguinte fragmento:
a = b + c
(print or io.write)('done')
A gram�tica 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 constru��es da primeira maneira, interpretando o abre par�ntese como o come�o dos argumentos de uma chamada. Para evitar essa ambiguidade, � uma boa pr�tica sempre preceder com um ponto-e-v�rgula comandos que come�am com um par�ntese:
;(print or io.write)('done')
Um bloco pode ser explicitamente delimitado para produzir um �nico comando:
comando ::= do bloco end
Blocos expl�citos s�o �teis para controlar o escopo de declara��es de vari�veis. Blocos expl�citos s�o tamb�m algumas vezes usados para adicionar um comando return no meio de outro bloco (veja §3.3.4).
A unidade de compila��o de Lua � chamada de um trecho. Sintaticamente, um trecho � simplesmente um bloco:
trecho ::= bloco
Lua trata um trecho como o corpo de uma fun��o an�nima
com um n�mero vari�vel de argumentos
(veja §3.4.10).
Dessa forma, trechos podem definir vari�veis locais,
receber argumentos, e retornar valores.
Al�m disso, tal fun��o an�nima � compilada no
escopo de uma vari�vel local externa chamada _ENV (veja §2.2).
A fun��o resultante sempre tem _ENV como seu �nico upvalue,
mesmo se ele n�o usar essa vari�vel.
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 instru��es de uma m�quina virtual, e ent�o executa o c�digo compilado com um interpretador para a m�quina virtual.
Trechos podem tamb�m ser pr�-compilados para uma forma bin�ria;
veja o programa luac para detalhes.
Programas na forma de c�digo fonte e na forma compilada s�o intercambi�veis;
Lua detecta automaticamente o tipo do arquivo e age de acordo.
Lua permite atribui��es m�ltiplas. Por isso, a sintaxe para atribui��o define uma lista de vari�veis no lado esquerdo e uma lista de express�es no lado direito. Os elementos em ambas as listas s�o separados por v�rgulas:
comando ::= listavars ‘=’ listaexps
listavars ::= var {‘,’ var}
listaexps ::= exp {‘,’ exp}
Express�es s�o discutidas em §3.4.
Antes da atribui��o, a lista de valores � ajustada para o comprimento da lista de vari�veis. Se h� mais valores do que o necess�rio, os valores em excesso s�o descartados. Se h� menos valores do que o necess�rio a lista � estendida com tantos nil's quantos sejam necess�rios. Se a lista de express�es termina com uma chamada de fun��o, ent�o todos os valores retornados por essa chamada entram na lista de valores, antes do ajuste (exceto quando a chamada � delimitada por par�nteses; veja §3.4).
O comando de atribui��o primeiro avalia todas as suas express�es e somente ent�o as atribui��es s�o realizadas. Assim o c�digo
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 c�clica os valores de x, y, e z.
A sem�ntica de atribui��es para vari�veis globais
e campos de tabelas pode ser modificada por metatabelas.
Uma atribui��o a uma vari�vel indexada t[i] = val � equivalente a
settable_event(t,i,val).
(Veja §2.4 para uma descri��o completa da
fun��o settable_event.
Essa fun��o n�o � definida nem pode ser chamada em Lua.
Usamos ela aqui somente para fins did�ticos.)
Uma atribui��o a uma vari�vel global x = val
� equivalente � atribui��o
_ENV.x = val (veja §2.2).
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 tamb�m possui um comando for, em duas varia��es (veja §3.3.5).
A express�o da condi��o de uma estrutura de controle pode retornar qualquer valor. Tanto false quanto nil s�o considerados falso. Todos os valores diferentes de nil e false s�o considerados verdadeiro (em particular, o n�mero 0 e a cadeia vazia s�o tamb�m verdadeiro).
No la�o repeat–until, o bloco interno n�o termina na palavra chave until, mas somente ap�s a condi��o. Assim, a condi��o pode se referir a vari�veis locais declaradas dentro do corpo do la�o.
O comando goto transfere o controle do programa para um r�tulo. Por raz�es sint�ticas, r�tulos em Lua s�o considerados comandos tamb�m:
comando ::= goto Nome comando ::= r�tulo r�tulo ::= ‘::’ Nome ‘::’
Um r�tulo � vis�vel em todo o bloco onde ele � definido, exceto dentro de blocos aninhados onde um r�tulo com o mesmo nome � definido e dentro de fun��es aninhadas. Um goto pode fazer um desvio para qualquer r�tulo vis�vel desde que ele n�o entre no escopo de uma vari�vel local.
R�tulos e comandos vazios s�o chamados de comandos nulos, uma vez que eles n�o realizam a��es.
O comando break termina a execu��o de um la�o while, repeat, ou for, fazendo um desvio para o pr�ximo comando ap�s o la�o:
comando ::= break
Um break termina o la�o mais interno.
O comando return � usado para retornar valores de uma fun��o ou de um trecho (que � uma fun��o disfar�ada). Fun��es 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 necess�rio um return no meio de um bloco,
ent�o um bloco interno expl�cito pode ser usado,
como na express�o idiom�tica do return end,
porque agora return � o �ltimo comando de seu bloco (interno).
O comando for possui duas formas: um num�rica e outra gen�rica.
O la�o for num�rico repete um bloco de c�digo enquanto uma vari�vel de controle varia de acordo com uma progress�o aritm�tica. Ele tem a seguinte sintaxe:
comando ::= for Nome ‘=’ exp ‘,’ exp [‘,’ exp] do bloco end
O bloco � repetido para nome come�ando com o valor da primeira exp, at� que ele passe a segunda exp atrav�s de passos da terceira exp. Mais precisamente, um comando for como
for v = e1, e2, e3 do bloco end
� equivalente ao c�digo:
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:
var, limite, e passo s�o vari�veis invis�veis.
Os nomes mostrados aqui s�o para fins did�ticos somente.
v � local ao la�o;
voc� n�o pode usar o valor dela ap�s o for terminar ou ser interrompido.
Se voc� precisa desse valor,
atribua-o a outra vari�vel antes de interromper ou sair do la�o.
O comando for gen�rico funciona usando fun��es, chamadas de iteradores. A cada itera��o, a fun��o iteradora � chamada para produzir um novo valor, parando quando esse novo valor � nil. O la�o for gen�rico 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 c�digo:
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 s�o uma fun��o iteradora,
um estado,
e um valor inicial para a primeira vari�vel iteradora.
f, s, e var s�o vari�veis invis�veis.
Os nomes est�o aqui para fins did�ticos somente.
var_i s�o locais ao la�o;
voc� n�o pode usar o valor delas ap�s o for terminar.
Se voc� precisa desses valores,
ent�o atribua-os a outras vari�veis antes de interromper ou sair do la�o.
Para permitir poss�veis efeitos colaterais, chamadas de fun��o podem ser executadas como comandos:
comando ::= chamadafun��o
Nesse caso, todos os valores retornados s�o descartados. Chamadas de fun��o s�o explicadas em §3.4.9.
Vari�veis locais podem ser declaradas em qualquer lugar dentro de um bloco. A declara��o pode incluir uma atribui��o inicial:
comando ::= local listanomes [‘=’ listaexps]
Se presente, uma atribui��o inicial tem a mesma sem�ntica de uma atribui��o m�ltipla (veja §3.3.3). Caso contr�rio, todas as vari�veis s�o inicializadas com nil.
Um trecho � tamb�m um bloco (veja §3.3.2), e dessa forma vari�veis locais podem ser declaradas em um trecho fora de qualquer bloco expl�cito.
As regras de visibilidade para vari�veis locais s�o explicadas em §3.5.
As express�es b�sicas em Lua s�o as seguintes:
exp ::= expprefixo exp ::= nil | false | true exp ::= N�mero exp ::= Cadeia exp ::= deffun��o exp ::= construtortabela exp ::= ‘...’ exp ::= exp opbin exp exp ::= opun�rio exp prefixexp ::= var | chamadafun��o | ‘(’ exp ‘)’
N�meros e cadeias de literais s�o explicados em §3.1; vari�veis s�o explicadas em §3.2; defini��es de fun��es s�o explicadas em §3.4.10; chamadas de fun��es s�o explicadas em §3.4.9; construtores de tabelas s�o explicados em §3.4.8. Express�es vararg, denotadas por tr�s pontos (Char{...}), somente podem ser usadas quando diretamente dentro de uma fun��o vararg; elas s�o explicadas em §3.4.10.
Operadores bin�rios compreendem operadores aritm�ticos (veja §3.4.1), operadores relacionais (veja §3.4.3), operadores l�gicos (veja §3.4.4), e o operador de concatena��o (veja §3.4.5). Operadores un�rios compreendem o menos un�rio (veja §3.4.1), o not un�rio (veja §3.4.4), e o operador de comprimento un�rio (veja §3.4.6). Tanto chamadas de fun��o como express�es vararg podem resultar em m�ltiplos valores. Se uma chamada de fun��o � usada como um comando (veja §3.3.6), ent�o sua lista de retorno � ajustada para zero elementos, descartando portanto todos os valores retornados. Se uma express�o � usada como o �ltimo (ou o �nico) elemento de uma lista de express�es, ent�o nenhum ajuste � feito (a menos que a express�o esteja entre par�nteses). 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 n�o h� nenhum valor.
Aqui est�o 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 par�metro de vararg, b recebe
-- o segundo (tanto a quanto b podem receber nil caso
-- n�o exista um par�metro 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 par�metros 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 par�metros vararg
{f(), nil} -- f() � ajustada para 1 resultado
Qualquer express�o entre par�nteses sempre resulta em um �nico valor.
Portanto,
(f(x,y,z)) � sempre um �nico valor,
mesmo se f retorna v�rios valores.
(O valor de (f(x,y,z)) � o primeiro valor retornado por f
ou nil se f n�o retorna nenhum valor.)
Lua oferece suporte aos operadores aritm�ticos usuais:
os bin�rios + (adi��o),
- (subtra��o), * (multiplica��o),
/ (divis�o), % (m�dulo), e ^ (exponencia��o);
e o un�rio - (nega��o matem�tica).
Se os operandos s�o n�meros, ou cadeias que podem ser convertidas em
n�meros (veja §3.4.2),
ent�o todas as opera��es possuem o significado usual.
A exponencia��o funciona para qualquer expoente.
Por exemplo, x^(-0.5) computa o inverso da raiz quadrada de x.
M�dulo � definido como
a % b == a - math.floor(a/b)*b
Ou seja, � o resto de uma divis�o que arredonda o quociente para menos infinito.
Lua prov� convers�o autom�tica entre
valores string e number em tempo de execu��o.
Qualquer opera��o aritm�tica aplicada a uma cadeia tenta converter
essa cadeia para um n�mero, seguindo as regras do analisador l�xico de Lua.
(A cadeia pode ter espa�os � esquerda e � direita e um sinal.)
Inversamente, sempre que um n�mero � usado onde uma cadeia � esperada,
o n�mero � convertido em uma cadeia, em um formato razo�vel.
Para um controle completo sobre como n�meros s�o convertidos em cadeias,
use a fun��o format da biblioteca de cadeias
(veja string.format).
Os operadores relacionais em Lua s�o
== ~= < > <= >=
Esses operadores sempre resultam em false ou true.
A igualdade (==) primeiro compara o tipo de seus operandos.
Se os tipos s�o diferentes, ent�o o resultado � false.
Caso contr�rio, os valores dos operandos s�o comparados.
N�meros e cadeias s�o comparados da maneira usual.
Tabelas, userdatas, e fluxos de execu��o
s�o comparados por refer�ncia:
dois objetos s�o considerados iguais somente se eles s�o o mesmo objeto.
Toda vez que voc� cria um novo objeto
(uma tabela, um userdata, ou um fluxo de execu��o),
esse novo objeto � diferente de qualquer objeto existente anteriormente.
Fechos com a mesma refer�ncia s�o sempre iguais.
Fechos com qualquer diferen�a detect�vel
(comportamento diferente, defini��o diferente) s�o sempre diferentes.
Voc� pode mudar a maneira que Lua compara tabelas e userdatas usando o metam�todo "eq" (veja §2.4).
As regras de convers�o §3.4.2
n�o se aplicam a compara��es de igualdade.
Assim, "0"==0 avalia para false,
e t[0] e t["0"] denotam entradas
diferentes em uma tabela.
O operador ~= � exatamente a nega��o da igualdade (==).
Os operadores de ordem funcionam como a seguir.
Se ambos os argumentos s�o n�meros, ent�o eles s�o comparados como tais.
Caso contr�rio, se ambos os argumentos s�o cadeias,
ent�o os valores delas s�o comparados de acordo com o idioma (locale) atual.
Caso contr�rio, Lua tenta chamar o metam�todo "lt"
ou o metam�todo "le" (veja §2.4).
Uma compara��o a > b � traduzida para b < a
e a >= b � traduzida para b <= a.
Os operadores l�gicos em Lua s�o and, or, e not. Assim como as estruturas de controle (veja §3.3.4), todos os operadores l�gicos consideram false e nil como falso e qualquer coisa diferente como verdeiro.
O operador de nega��o not sempre retorna false ou true. O operador de conjun��o and retorna seu primeiro argumento se este valor � false ou nil; caso contr�rio, and retorna seu segundo argumento. O operador de disjun��o or retorna seu primeiro argumento se este valor � diferente de nil e false; caso contr�rio, or retorna seu segundo argumento. Tanto and como or usam avalia��o de curto-circuito; isto �, o segundo operando � avaliado somente se necess�rio. Aqui est�o 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 express�o precedente.)
O operador de concatena��o de cadeias em Lua �
denotado por ponto ponto ('..').
Se ambos os operandos s�o cadeias ou n�meros, ent�o eles s�o convertidos para
cadeias de acordo com as regras mencionadas em §3.4.2.
Caso contr�rio, o metam�todo __concat � chamado (veja §2.4).
O operador de comprimento � denotado pelo operador un�rio prefixo #.
O comprimento de uma cadeia � o seu n�mero 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 atrav�s do metam�todo __len (veja §2.4).
A menos que o metam�todo __len seja fornecido,
o comprimento de uma tabela t � definido somente se a
tabela � uma sequ�ncia,
isto �,
o conjunto de suas chaves num�ricas positivas � igual a {1..n}
para algum inteiro n�o negativo n.
Nesse caso, n � seu comprimento.
Note que uma tabela como
{10, 20, nil, 40}
n�o � uma sequ�ncia, pois ela tem a chave 4
mas n�o n�o tem a chave 3.
(Assim, n�o existe um n tal que o conjunto {1..n} seja igual
ao conjunto de chaves num�ricas positivas dessa tabela.)
Note, contudo, que chaves n�o num�ricas n�o interferem
no fato de uma tabela ser uma sequ�ncia.
A preced�ncia dos operadores em Lua segue a tabela a seguir, da menor prioridade para a maior:
or
and
< > <= >= ~= ==
..
+ -
* / %
not # - (un�rio)
^
Como de costume,
voc� pode usar par�nteses para mudar as preced�ncias de uma express�o.
Os operadores de concatena��o ('..') e de exponencia��o ('^')
s�o associativos � direita.
Todos os outros operadores bin�rios s�o associativos � esquerda.
Construtores de tabelas s�o express�o 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 s�o equivalentes a
[i] = exp, onde i s�o n�meros inteiros consecutivos,
come�ando com 1.
Campos nos outros formatos n�o 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 express�o � uma chamada de fun��o ou uma express�o vararg,
ent�o todos os valores retornados por essa express�o entram na lista consecutivamente
(veja §3.4.9).
A lista de campos pode ter um separador a mais no fim, como uma conveni�ncia para c�digo gerado por m�quina.
Uma chamada de fun��o em Lua tem a seguinte sintaxe:
chamadafun��o ::= expprefixo args
Em uma chamada de fun��o, primeiro expprefixo e args s�o avaliados. Se o valor de expprefixo tem tipo function, ent�o essa fun��o � chamada com os argumentos fornecidos. Caso contr�rio, o metam�todo "call" de expprefixo � chamado, tendo como primeiro par�metro o valor de expprefixo, seguido pelos argumentos da chamada original (veja §2.4).
A forma
chamadafun��o ::= expprefixo ‘:’ Nome args
pode ser usada para chamar "m�todos".
Uma chamada v:nome(args)
� a��car sint�tico 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 express�es de argumentos s�o avaliadas antes da chamada.
Uma chamada da forma f{campos} �
a��car sint�tico para f({campos});
isto �, a lista de argumentos � somente uma nova tabela.
Uma chamada da forma f'cadeia'
(ou f"cadeia" ou f[[cadeia]])
� a��car sint�tico para f('cadeia');
isto �, a lista de argumentos � somente uma cadeia literal.
Uma chamada da forma return chamadafun��o � denominada
de chamada final.
Lua implementa chamadas finais pr�prias
(ou recurs�es finais pr�prias):
em uma chamada final,
a fun��o chamada reusa a entrada na pilha da fun��o chamadora.
Logo, n�o h� limite no n�mero de chamadas finais aninhadas que
um programa pode executar.
Contudo, uma chamada final apaga qualquer informa��o de depura��o a respeito da
fun��o chamadora.
Note que uma chamada final somente acontece com uma sintaxe particular,
onde o return possui uma �nica chamada de fun��o como argumento;
essa sintaxe faz a fun��o chamadora retornar exatamente
os valores retornados pela fun��o 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
A sintaxe para uma defini��o de fun��o �
deffun��o ::= fun��o corpofun��o corpofun��o ::= ‘(’ [listapars] ‘)’ bloco end
O seguinte a��car sint�tico simplifica defini��es de fun��es:
comando ::= function nomefun��o corpofun��o
comando ::= local function Nome corpofun��o
nomefun��o ::= 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
n�o para
local f = function () corpo end
(Isso somente faz diferen�a quando o corpo da fun��o
cont�m refer�ncias para f.)
Uma defini��o de fun��o � uma express�o execut�vel, cujo valor tem tipo function. Quando Lua pr�-compila um trecho, todos os corpos de fun��es do trecho s�o pr�-compilados tamb�m. Ent�o, sempre que Lua executa a defini��o de uma fun��o, a fun��o � instanciada (ou fechada). Essa inst�ncia de fun��o (ou fecho) � o valor final da express�o.
Par�metros agem como vari�veis locais que s�o inicializadas com os valores dos argumentos:
listapars ::= listanomes [‘,’ ‘...’] | ‘...’
Quando uma fun��o � chamada,
a lista de argumentos � ajustada para
o comprimento da lista de par�metros,
a menos que a fun��o seja uma fun��o vararg,
a qual � indicada por tr�s pontos ('...')
no fim de sua lista de par�metros.
Uma fun��o vararg n�o ajusta sua lista de argumentos;
ao inv�s disso, ela coleta todos os argumentos extras e os fornece
� fun��o atrav�s de uma express�o vararg,
que tamb�m � denotada por tr�s pontos.
O valor desta express�o � uma lista de todos os argumentos extras de fato,
similar a uma fun��o com m�ltiplos resultados.
Se uma express�o vararg � usada dentro de outra express�o
ou no meio de uma lista de express�es,
ent�o sua lista de retorno � ajustada para um elemento.
Se a express�o � usada como o �ltimo elemento de uma lista de express�es,
ent�o nenhum ajuste � feito
(a menos que a �ltima express�o esteja entre par�nteses).
Como um exemplo, considere as seguintes defini��es:
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 par�metros e para express�es vararg:
CHAMADA PAR�METROS
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 s�o retornados usando o comando return (veja §3.3.4). Se o controle alcan�a o fim de uma fun��o sem encontrar um comando return, ent�o a fun��o retorna sem nenhum resultado.
H� um limite que depende do sistema para o n�mero de valores que uma fun��o pode retornar. Esse limite � garantidamente maior do que 1000.
A sintaxe de dois pontos
� usada para definir m�todos,
isto �, fun��es que possuem um par�metro extra self impl�cito.
Assim, o comando
function t.a.b.c:f (params) corpo end
� a��car sint�tico para
t.a.b.c.f = function (self, params) corpo end
Lua � uma linguagem com escopo l�xico. O escopo de uma vari�vel local come�a no primeiro comando ap�s a sua declara��o e vai at� o �ltimo comando n�o nulo do bloco mais interno que inclui a declara��o. Considere o seguinte exemplo:
x = 10 -- vari�vel 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 declara��o como local x = x,
o novo x sendo declarado n�o est� no escopo ainda,
e portanto o segundo x se refere a uma vari�vel externa.
Por conta das regras de escopo l�xico, vari�veis locais podem ser livremente acessadas por fun��es definidas dentro de seu escopo. Uma vari�vel local usada por uma fun��o mais interna � chamada de upvalue, ou de vari�vel local externa, dentro da fun��o mais interna.
Note que cada execu��o de um comando local define novas vari�veis 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 la�o cria dez fechos
(isto �, dez inst�ncias da fun��o an�nima).
Cada um desses fechos usa uma vari�vel y diferente,
enquanto todos eles compartilham o mesmo x.
Esta se��o descreve a API C para Lua, isto �,
o conjunto de fun��es C dispon�veis para o programa hospedeiro se comunicar
com Lua.
Todas as fun��es da API e os tipos e constantes relacionados
est�o declarados no arquivo de cabe�alho lua.h.
Mesmo quando usamos o termo "fun��o", qualquer facilidade na API pode ser provida como uma macro ao inv�s. 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 n�o geram qualquer efeito colateral oculto.
Como na maioria das bibliotecas C,
as fun��es da API Lua n�o verificam a validade ou a consist�ncia de seus argumentos.
Contudo, voc� pode mudar esse comportamento compilando Lua
com a macro LUA_USE_APICHECK definida.
Lua usa uma pilha virtual para passar e receber valores de C. Cada elemento nessa pilha representa um valor Lua (nil, n�mero, cadeia, etc.).
Sempre que Lua chama C, a fun��o chamada recebe uma nova pilha,
que � independente de pilhas anteriores e de pilhas de
fun��es C que ainda est�o ativas.
Essa pilha inicialmente cont�m quaisquer argumentos para a fun��o C
e � onde a fun��o C empilha seus resultados
para serem retornados para o chamador (veja lua_CFunction).
Por conveni�ncia, a maioria das opera��es de consulta na API n�o 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 posi��o absoluta na pilha (come�ando de 1); um �ndice negativo representa uma posi��o relativa ao topo da pilha. Mais especificamente, se a pilha tem n elementos, ent�o 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 tamb�m representa o �ltimo elemento (isto �, o elemento no topo) e o �ndice -n representa o primeiro elemento.
Quando voc� interage com a API de Lua,
voc� � respons�vel por assegurar consist�ncia..
Em particular,
voc� � respons�vel por controlar o estourou da pilha.
Voc� pode usar a fun��o lua_checkstack
para assegurar que a pilha possui espa�os extras ao empilhar novos elementos.
Sempre que Lua chama C,
ela assegura que a pilha possui pelo menos LUA_MINSTACK espa�os extras.
LUA_MINSTACK � definida como 20,
assim geralmente voc� n�o precisa se preocupar com espa�os extras
a menos que seu c�digo tenha la�os empilhando elementos na pilha.
Quando voc� chama uma fun��o Lua
sem um n�mero fixo de resultados (veja lua_call),
Lua garante que a pilha tem espa�o suficiente para todos os resultados,
mas ela n�o garante qualquer espa�o extra.
Assim, antes de empilhar qualquer coisa na pilha ap�s uma chamada desse tipo
voc� deve usar lua_checkstack.
Qualquer fun��o na API que recebe �ndices da pilha funciona somente com �ndices v�lidos ou �ndices aceit�veis.
Um �ndice v�lido � um �ndice que se refere a uma
posi��o real dentro da pilha, isto �,
sua posi��o est� entre 1 e o topo da pilha
(1 ≤ abs(�ndice) ≤ topo).
Geralmente, fun��es que podem modificar os valores em um �ndice
exigem �ndices v�lidos.
A menos que dito de outra maneira, qualquer fun��o que aceita �ndices v�lidos tamb�m aceita pseudo-�ndices, os quais representam alguns valores de Lua que s�o acess�veis para c�digo C mas que n�o est�o na pilha. Pseudo-�ndices s�o usados para acessar o registro e os upvalues de uma fun��o C (veja §4.4).
Fun��es que n�o precisam de uma posi��o na pilha espec�fica, mas somente de um valor na pilha (e.g., fun��es de consulta), podem ser chamadas com �ndices aceit�veis. Um �ndice aceit�vel pode ser qualquer �ndice v�lido, incluindo os pseudo-�ndices, mas tamb�m pode ser qualquer inteiro positivo ap�s o topo da pilha dentro do espa�o alocado para a pilha, isto �, �ndices at� o tamanho da pilha. (Note que 0 nunca � um �ndice aceit�vel.) Exceto quando dito de outra maneira, fun��es na API funcionam com �ndices aceit�veis.
�ndices aceit�veis servem para evitar testes extras relacionados ao topo da pilha ao consultar a pilha. Por exemplo, um fun��o 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 v�lido.
Para fun��es que podem ser chamadas com �ndices aceit�veis,
qualquer �ndice n�o v�lido � tratado como se ele
contivesse um valor de um tipo virtual LUA_TNONE,
o qual comporta-se como um valor nil.
Quando uma fun��o C � criada,
� poss�vel associar alguns valores a ela,
criando assim um fecho C
(veja lua_pushcclosure);
esses valores s�o chamados de upvalues e s�o
acess�veis � fun��o sempre que ela � chamada.
Sempre que uma fun��o C � chamada,
seus upvalues s�o posicionados em pseudo-�ndices espec�ficos.
Esses pseudo-�ndices s�o produzidos pela macro
lua_upvalueindex.
O primeiro valor associado com uma fun��o est� na posi��o
lua_upvalueindex(1), e assim por diante.
Qualquer acesso a lua_upvalueindex(n),
onde n � maior do que o n�mero de upvalues da
fun��o corrente (mas n�o maior do que 256),
produz um �ndice aceit�vel, por�m inv�lido.
Lua prov� um registro,
uma tabela pr�-definida que pode ser usada por qualquer c�digo 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 v�lido.
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 colis�es.
Tipicamente, voc� deve usar como chave uma cadeia contendo o nome de sua biblioteca,
ou um userdata leve com o endere�o de um objeto C no seu c�digo,
ou qualquer objeto Lua criado por seu c�digo.
Assim como com nomes globais,
chaves que s�o cadeias come�ando com um sublinhando seguido por
letras mai�sculas s�o reservadas para Lua.
As chaves inteiras no registro s�o usadas pelo mecanismo de refer�ncia, implementado pela biblioteca auxiliar, e por alguns valores pr�-definidos. Portanto, chaves inteiras n�o devem ser usadas para outros prop�sitos.
Quando voc� cria um novo estado Lua,
o registro dele vem com alguns valores pr�-definidos.
Esses valores pr�-definidos s�o indexados com chaves inteiras
definidas como constantes em lua.h.
As seguintes constantes s�o definidas:
LUA_RIDX_MAINTHREAD: Nesse �ndice o registro tem
o fluxo de execu��o principal do estado.
(O fluxo de execu��o principal � aquele criado junto com o estado.)
LUA_RIDX_GLOBALS: Nesse �ndice o registro tem
o ambiente global.
Internamente, Lua usa a facilidade longjmp de C para tratar erros.
(Voc� pode tamb�m escolher usar exce��es se voc� compilar Lua como C++;
procure por LUAI_THROW no c�digo fonte.)
Quando Lua enfrenta qualquer erro
(como um erro de aloca��o de mem�ria, erros de tipo, erros sint�ticos,
e erros de tempo de execu��o)
ela lan�a um erro;
isto �, ela faz um desvio longo.
Um ambiente protegido usa setjmp
para estabelecer um ponto de recupera��o;
qualquer erro desvia para o ponto de recupera��o ativo mais recente.
Se um erro acontece fora de qualquer ambiente protegido,
Lua chama uma fun��o de p�nico (veja lua_atpanic)
e ent�o chama abort,
saindo portanto da aplica��o hospedeira.
Sua fun��o de p�nico pode evitar essa sa�da
nunca retornando
(e.g., fazendo um desvio longo para seu pr�prio ponto de recupera��o fora de Lua).
A fun��o de p�nico roda como se ela fosse um tratador de mensagens (veja §2.3); em particular, a mensagem de erro est� no topo da pilha. Contudo, n�o h� garantias sobre o espa�o da pilha. Para empilhar qualquer coisa na pilha, a fun��o de p�nico deve primeiro verificar o espa�o dispon�vel (veja §4.2).
A maioria das fun��es na API pode lan�ar um erro, por exemplo devido a um erro de aloca��o de mem�ria. A documenta��o para cada fun��o indica se ela pode lan�ar erros.
Dentro de uma fun��o C voc� pode lan�ar um erro chamando lua_error.
Internamente, Lua usa a facilidade longjmp de C para ceder uma co-rotina.
Logo, se uma fun��o foo chama uma fun��o da API
e essa fun��o da API cede
(diretamente ou indiretamente atrav�s da chamada a outra fun��o que cede),
Lua n�o pode retornar mais para foo,
pois longjmp remove seu frame da pilha de C.
Para evitar esse tipo de problema,
Lua lan�a um erro sempre que ela tenta ceder atrav�s de uma chamada da API,
exceto para tr�s fun��es:
lua_yieldk, lua_callk, e lua_pcallk.
Todas essas fun��es recebem uma fun��o de continua��o
(como um par�metro chamado k) para continuar a execu��o ap�s uma cess�o.
Precisamos estabelecer alguma terminologia para explicar continua��es.
Temos uma fun��o C chamada a partir de Lua que chamaremos
de fun��o original.
Essa fun��o original ent�o chama uma dessas tr�s fun��es da API C,
as quais chamaremos de fun��es chamadas,
que ent�o cedem o fluxo de execu��o corrente.
(Isso pode acontecer quando a fun��o chamada � lua_yieldk,
ou quando a fun��o chamada � lua_callk ou lua_pcallk
e a fun��o chamada por elas cede.)
Suponha que o fluxo de execu��o rodando ceda enquanto executa a fun��o chamada. Ap�s o fluxo de execu��o recome�ar, ele em algum momento terminar� executando a fun��o chamada. Contudo, a fun��o chamada n�o pode retornar para a fun��o original, pois seu frame na pilha de C foi destru�do pela cess�o. Ao inv�s disso, Lua chama uma fun��o de continua��o, que foi fornecida como um argumento para a fun��o chamada. Como o nome indica, a fun��o de continua��o deve continuar a tarefa da fun��o original.
Lua trata a fun��o de continua��o como se ela fosse a fun��o original.
A fun��o de continua��o recebe a mesma pilha Lua
da fun��o original,
no mesmo estado que ela estaria se a fun��o chamada tivesse retornado.
(Por exemplo,
ap�s um lua_callk a fun��o e seus argumentos s�o
removidos da pilha e substitu�dos pelos resultados da chamada.)
Ela tamb�m tem os mesmos upvalues.
Seja qual for o retorno, ele � tratado por Lua como se fosse o retorno
da fun��o original.
A �nica diferen�a no estado Lua entre a fun��o original
e sua continua��o � o resultado de uma chamada a lua_getctx.
Aqui listamos todas as fun��es e tipos da API C em ordem alfab�tica. Cada fun��o possui um indicador como este: [-o, +p, x]
O primeiro campo, o,
� quantos elementos a fun��o desempilha da pilha.
O segundo campo, p,
� quantos elementos a fun��o empilha na pilha.
(Qualquer fun��o sempre empilha seus resultados ap�s desempilhar seus argumentos.)
Um campo da forma x|y significa que a fun��o pode empilhar (ou desempilhar)
x ou y elementos,
dependendo da situa��o;
um ponto de interroga��o '?' significa que
n�o podemos saber quantos elementos a fun��o desempilha/empilha
olhando somente seus argumentos
(e.g., eles podem depender do que est� na pilha).
O terceiro campo, x,
diz se a fun��o pode lan�ar erros:
'-' significa que a fun��o nunca lan�a nenhum erro;
'e' significa que a fun��o pode lan�ar erros;
'v' significa que a fun��o pode lan�ar um erro de prop�sito.
lua_absindex[-0, +0, –]
int lua_absindex (lua_State *L, int idx);
Converte o �ndice aceit�vel idx em um �ndice absoluto
(isto �, um que n�o depende do topo da pilha).
lua_Alloctypedef void * (*lua_Alloc) (void *ud,
void *ptr,
size_t osize,
size_t nsize);
O tipo da fun��o de aloca��o de mem�ria usada por estados Lua.
A fun��o alocadora deve prover uma
funcionalidade similar a realloc,
mas n�o exatamente a mesma.
Seus argumentos s�o
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 c�digo sobre o que
est� sendo alocado;
nsize, o novo tamanho do bloco.
Quando ptr n�o � 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 mem�ria para outra coisa.
Lua assume o seguinte comportamento da fun��o alocadora:
Quando nsize � zero,
o alocador deve comportar-se como free
e retornar NULL.
Quando nsize n�o � zero,
o alocador deve comportar-se como realloc.
O alocador retorna NULL
se e somente se ele n�o pode cumprir a requisi��o.
Lua assume que o alocador nunca falha quando
osize >= nsize.
Aqui est� uma implementa��o simples para a fun��o 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; /* n�o utilizados */
if (nsize == 0) {
free(ptr);
return NULL;
}
else
return realloc(ptr, nsize);
}
Note que C Padr�o assegura
que free(NULL) n�o tem efeito e que
realloc(NULL, size) � equivalente a malloc(size).
Esse c�digo assume que realloc n�o falha ao encolher um bloco.
(Embora C Padr�o n�o assegure esse comportamento,
parece ser uma suposi��o segura.)
lua_arith[-(2|1), +1, e]
void lua_arith (lua_State *L, int op);
Realiza uma opera��o aritm�tica sobre os dois valores (ou um, no caso de nega��o) no topo da pilha, com o valor no topo sendo o segundo operando, desempilha esses valores, e empilha o resultado da opera��o. A fun��o segue a sem�ntica do operador Lua correspondente (isto �, ela pode chamar metam�todos).
O valor de op deve ser uma das seguintes constantes:
LUA_OPADD: faz adi��o (+)LUA_OPSUB: faz subtra��o (-)LUA_OPMUL: faz multiplica��o (*)LUA_OPDIV: faz divis�o (/)LUA_OPMOD: faz m�dulo (%)LUA_OPPOW: faz exponencia��o (^)LUA_OPUNM: faz nega��o matem�tica (- un�rio)lua_atpanic[-0, +0, –]
lua_CFunction lua_atpanic (lua_State *L, lua_CFunction panicf);
Estabelece uma nova fun��o de p�nico 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 fun��o.
Para chamar uma fun��o voc� deve usar o seguinte protocolo:
primeiro, a fun��o a ser chamada � empilhada na pilha;
em seguida, os argumentos para a fun��o s�o empilhados
em ordem direta;
isto �, o primeiro argumento � empilhado primeiro.
Finalmente voc� chama lua_call;
nargs � o n�mero de argumentos que voc� empilhou na pilha.
Todos os argumentos e o valor da fun��o s�o retirados da pilha
quando a fun��o � chamada.
Os resultados da fun��o s�o colocados na pilha quando a fun��o retorna.
O n�mero de resultados � ajustado para nresults,
a menos que nresults seja LUA_MULTRET.
Nesse caso, todos os resultados da fun��o s�o empilhados.
Lua cuida para que os valores retornados se ajustem no espa�o da pilha.
Os resultados da fun��o s�o colocados na pilha em ordem direta
(o primeiro resultado � empilhado primeiro),
de modo que ap�s a chamada o �ltimo resultado est� no topo da pilha.
Qualquer erro dentro da fun��o chamada � propagado para cima
(com um longjmp).
O seguinte exemplo mostra como o programa hospedeiro pode fazer o equivalente a este c�digo Lua:
a = f("how", t.x, 14)
Aqui est� ele em C:
lua_getglobal(L, "f"); /* fun��o 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 c�digo acima � "balanceado": ao seu final, a pilha est� de volta � sua configura��o original. Isto � considerado uma boa pr�tica de programa��o.
lua_callk[-(nargs + 1), +nresults, e]
void lua_callk (lua_State *L, int nargs, int nresults, int ctx,
lua_CFunction k);
Esta fun��o comporta-se exatamente como lua_call,
mas permite a fun��o chamada ceder (veja §4.7).
lua_CFunctiontypedef int (*lua_CFunction) (lua_State *L);
Tipo para fun��es C.
A fim de se comunicar apropriadamente com Lua,
uma fun��o C deve usar o seguinte protocolo,
que define o modo como par�metros e resultados s�o passados:
uma fun��o C recebe seus argumentos de Lua na sua pilha
em ordem direta (o primeiro argumento � empilhado primeiro).
Assim, quando a fun��o come�a,
lua_gettop(L) retorna o n�mero de argumentos recebidos pela fun��o.
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 fun��o C apenas os empilha na pilha,
em ordem direta (o primeiro resultado � empilhado primeiro),
e retorna o n�mero de resultados.
Qualquer outro valor na pilha abaixo dos resultados ser� apropriadamente
descartado por Lua.
Como uma fun��o Lua, uma fun��o C chamada por Lua tamb�m pode retornar
muitos resultados.
Como um exemplo, a fun��o a seguir recebe um n�mero vari�vel de argumentos num�ricos e retorna a m�dia e a soma deles:
static int foo (lua_State *L) {
int n = lua_gettop(L); /* n�mero 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; /* n�mero de resultados */
}
lua_checkstack[-0, +0, –]
int lua_checkstack (lua_State *L, int extra);
Assegura que h� no m�nimo extra espa�os de pilha dispon�veis na pilha.
Retorna falso se n�o pode cumprir a requisi��o,
pois faria com que a pilha fosse maior do que um tamanho m�ximo fixo
(tipicamente pelo menos uns poucos milhares de elementos) ou
porque n�o pode alocar mem�ria para o novo tamanho da pilha.
Essa fun��o nunca encolhe a pilha;
se a pilha j� � maior do que o novo tamanho,
ela n�o � modificada.
lua_close[-0, +0, –]
void lua_close (lua_State *L);
Destr�i todos os objetos no estado Lua fornecido (chamando os metam�todos de coleta de lixo correspondentes, se houver) e libera toda mem�ria din�mica usada por esse estado. Em v�rias plataformas, voc� pode n�o precisar chamar essa fun��o, pois todos os recursos s�o naturalmente liberados quando o programa hospedeiro termina. Por outro lado, programas que executam por muito tempo e que criam m�ltiplos estados, tais como daemons ou servidores web, podem precisar fechar estados assim que eles n�o sejam necess�rios.
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 sem�ntica do operador Lua correspondente
(isto �, pode chamar metam�todos).
Caso contr�rio retorna 0.
Tamb�m retorna 0 se algum dos �ndices n�o � v�lido.
O valor de op deve ser uma das seguintes constantes:
LUA_OPEQ: compara��o de igualdade (==)LUA_OPLT: compara��o de menor que (<)LUA_OPLE: compara��o 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 fun��o n�o faz nada);
se n � 0, o resultado � a cadeia vazia.
A concatena��o � realizada seguindo a sem�ntica 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 v�lido toidx
sem deslocar nenhum elemento
(substituindo portanto o valor naquela posi��o).
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 par�metro narr � uma dica de quantos elementos a tabela
ter� como uma sequ�ncia;
o par�metro nrec � uma dica de quantos outros elementos
a tabela ter�.
Lua pode usar essas dicas para pr�-alocar mem�ria para a nova tabela.
Essa pr�-aloca��o � �til para desempenho quando voc� sabe de antem�o
quantos elementos a tabela ter�.
Caso contr�rio voc� pode usar a fun��o lua_newtable.
lua_dump[-0, +0, e]
int lua_dump (lua_State *L, lua_Writer writer, void *data);
Descarrega uma fun��o como um trecho bin�rio.
Recebe uma fun��o Lua no topo da pilha
e produz um trecho bin�rio que,
se carregado novamente,
resulta em uma fun��o equivalente � que foi descarregada.
Como ela produz partes do trecho,
lua_dump chama a fun��o writer (veja lua_Writer)
com o data fornecido
para escrev�-lo.
O valor retornado � o c�digo de erro retornado pela �ltima
chamada a writer;
0 significa que n�o houve erros.
Esta fun��o n�o desempilha a fun��o 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 fun��o 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 fun��o realiza v�rias tarefas,
de acordo com o valor do par�metro 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 mem�ria (em Kbytes) correntemente usada por Lua.
LUA_GCCOUNTB:
retorna o resto da divis�o da quantidade de bytes de mem�ria
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 n�o especificado.
Se voc� quiser controlar o tamanho do passo
voc� deve ajustar experimentalmente o valor de data.
A fun��o 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 fun��o 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 fun��o retorna o valor anterior do multiplicador de passo.
LUA_GCISRUNNING:
retorna um booleano que diz se o coletor est� executando
(i.e., n�o 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 padr�o.
Para mais detalhes sobre essas op��es,
veja collectgarbage.
lua_getallocf[-0, +0, –]
lua_Alloc lua_getallocf (lua_State *L, void **ud);
Retorna a fun��o de aloca��o de mem�ria de um dado estado.
Se ud n�o � 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 fun��o � chamada por uma fun��o de continua��o (veja §4.7) para recuperar o estado do fluxo de execu��o e uma informa��o de contexto.
Quando chamada na fun��o original,
lua_getctx sempre retorna LUA_OK
e n�o modifica o valor de seu argumento ctx.
Quando chamada dentro de uma fun��o de continua��o,
lua_getctx retorna LUA_YIELD e atribui
o valor de ctx para a informa��o de contexto
(o valor passado como o argumento ctx
para a fun��o chamada junto com a fun��o de continua��o).
Quando a fun��o chamada � lua_pcallk,
Lua pode tamb�m chamar sua fun��o de continua��o
para tratar erros durante a chamada.
Isto �, em consequ�ncia de um erro na fun��o chamada por lua_pcallk,
Lua pode n�o retornar para a fun��o original
mas ao inv�s disso pode chamar a fun��o de continua��o.
Nesse caso, uma chamada a lua_getctx retornar� o c�digo de erro
(o valor que seria retornado por lua_pcallk);
o valor de ctx ser� atribu�do � informa��o de contexto,
como no caso de uma cess�o.
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 fun��o pode disparar um metam�todo
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 n�o possui uma metatabela, a fun��o retorna 0 e n�o 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 fun��o desempilha a chave da pilha (colocando o valor resultante em seu lugar). Como em Lua, esta fun��o pode disparar um metam�todo 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 come�am em 1, esse resultado � igual ao n�mero 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 v�lido fornecido, deslocando os elementos acima desse �ndice para abrir espa�o. Esta fun��o n�o pode ser chamada com um pseudo-�ndice, pois um pseudo-�ndice n�o � uma posi��o na pilha de verdade.
lua_Integertypedef ptrdiff_t lua_Integer;
O tipo usado pela API de Lua para representar valores inteiros com sinal.
Por padr�o ele � um ptrdiff_t,
que � usualmente o maior tipo inteiro com sinal que a m�quina
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 contr�rio.
lua_iscfunction[-0, +0, –]
int lua_iscfunction (lua_State *L, int index);
Retorna 1 se o valor no �ndice fornecido � uma fun��o C, e 0 caso contr�rio.
lua_isfunction[-0, +0, –]
int lua_isfunction (lua_State *L, int index);
Retorna 1 se o valor no �ndice fornecido � uma fun��o (C ou Lua), e 0 caso contr�rio.
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 contr�rio.
lua_isnil[-0, +0, –]
int lua_isnil (lua_State *L, int index);
Retorna 1 se o valor no �ndice fornecido � nil, e 0 caso contr�rio.
lua_isnone[-0, +0, –]
int lua_isnone (lua_State *L, int index);
Retorna 1 se o �ndice fornecido n�o � v�lido, e 0 caso contr�rio.
lua_isnoneornil[-0, +0, –]
int lua_isnoneornil (lua_State *L, int index);
Retorna 1 se o �ndice fornecido n�o � v�lido ou se o valor nesse �ndice � nil, e 0 caso contr�rio.
lua_isnumber[-0, +0, –]
int lua_isnumber (lua_State *L, int index);
Retorna 1 se o valor no �ndice fornecido � um n�mero ou uma cadeia que pode ser convertida para um n�mero, e 0 caso contr�rio.
lua_isstring[-0, +0, –]
int lua_isstring (lua_State *L, int index);
Retorna 1 se o valor no �ndice fornecido � uma cadeia ou um n�mero (o qual sempre pode ser convertido para uma cadeia), e 0 caso contr�rio.
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 contr�rio.
lua_isthread[-0, +0, –]
int lua_isthread (lua_State *L, int index);
Retorna 1 se o valor no �ndice fornecido � um fluxo de execu��o, e 0 caso contr�rio.
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 contr�rio.
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 n�o h� erros,
lua_load coloca o trecho compilado como uma fun��o
Lua no topo da pilha.
Caso contr�rio, empilha uma mensagem de erro.
Os valores retornados por lua_load s�o:
LUA_OK: sem erros;LUA_ERRSYNTAX:
erro de sintaxe durante a pr�-compila��o;LUA_ERRMEM:
erro de aloca��o de mem�ria;LUA_ERRGCMM:
erro ao executar um metam�todo __gc.
(Este erro n�o tem rela��o com o trecho sendo carregado.
Ele � gerado pelo coletor de lixo.)
A fun��o lua_load usa uma fun��o reader fornecida pelo usu�rio
para ler o trecho (veja lua_Reader).
O argumento data � um valor opaco passado para a fun��o de leitura.
O argumento source d� um nome para o trecho,
o qual � usado para mensagens de erro e em informa��es de depura��o (veja §4.9).
lua_load automaticamente detecta se o trecho � texto ou bin�rio
e o carrega de acordo (veja o programa luac).
A cadeia mode funciona como na fun��o load,
com a adi��o que
um valor NULL � equivalente � cadeia "bt".
lua_load usa a pilha internamente,
assim a fun��o de leitura deve sempre deixar a pilha
inalterada ao retornar.
Se a fun��o resultante tem um upvalue,
o valor atribu�do 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 vari�vel _ENV (veja §2.2).
lua_newstate[-0, +0, –]
lua_State *lua_newstate (lua_Alloc f, void *ud);
Cria um novo fluxo de execu��o rodando em um novo estado, independente.
Retorna NULL se n�o pode criar o fluxo ou o estado
(devido � falta de mem�ria).
O argumento f � a fun��o alocadora;
Lua faz toda aloca��o de mem�ria para esse estado atrav�s dessa fun��o.
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 execu��o, coloca-o na pilha,
e retorna um ponteiro para um lua_State que representa esse novo fluxo.
O novo fluxo de execu��o retornado por essa fun��o compartilha com o fluxo original
seu ambiente global,
mas possui uma pilha de execu��o independente.
N�o h� uma fun��o expl�cita para fechar ou destruir um fluxo de execu��o. Fluxos de execu��o est�o sujeitos � coleta de lixo, como qualquer objeto Lua.
lua_newuserdata[-0, +1, e]
void *lua_newuserdata (lua_State *L, size_t size);
Esta fun��o aloca um novo bloco de mem�ria com o tamanho fornecido, coloca na pilha um novo userdata completo com o endere�o do bloco, e retorna esse endere�o. O programa hospedeiro pode usar livremente essa mem�ria.
lua_next[-1, +(2|0), e]
int lua_next (lua_State *L, int index);
Desempilha uma chave da pilha,
e empilha um par chave–valor da tabela no �ndice fornecido
(o "pr�ximo" par ap�s o �ndice fornecido).
Se n�o h� mais elementos na tabela ,
ent�o lua_next retorna 0 (e n�o empilha nada).
Um percorrimento t�pico 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'; mant�m 'key' para a pr�xima itera��o */
lua_pop(L, 1);
}
Ao percorrer uma tabela,
n�o 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 pr�xima chamada a lua_next.
Veja a fun��o next para os cuidados que se deve ter ao modificar
a tabela durante seu percorrimento.
lua_Numbertypedef double lua_Number;
O tipo de n�meros em Lua.
Por padr�o, ele � double, mas isso pode ser modificado em luaconf.h.
Atrav�s desse arquivo de configura��o voc� pode mudar
Lua para operar com outro tipo para n�meros (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 fun��o em modo protegido.
Tanto nargs quanto nresults possuem o mesmo significado que
tinham em lua_call.
Se n�o 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 c�digo de erro.
Como lua_call,
lua_pcall sempre remove a fun��o
e seus argumentos da pilha.
Se msgh � 0,
ent�o a mensagem de erro retornada na pilha
� exatamente a mensagem de erro original.
Caso contr�rio, msgh � o �ndice na pilha de um
tratador de mensagens.
(Na implementa��o corrente, esse �ndice n�o pode ser um pseudo-�ndice.)
Em caso de erros de tempo de execu��o,
essa fun��o 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 informa��o
de depura��o � mensagem de erro, tal como um tra�o da pilha.
Tal informa��o n�o pode ser obtida ap�s o retorno de lua_pcall,
pois nesse ponto a pilha foi desenrolada.
A fun��o lua_pcall retorna um dos seguintes c�digos
(definidos em lua.h):
LUA_OK (0):
sucesso.LUA_ERRRUN:
um erro de tempo de execu��o.
LUA_ERRMEM:
erro de aloca��o de mem�ria.
Para tais erros, Lua n�o chama o tratador de mensagens.
LUA_ERRERR:
erro ao executar o tratador de mensagens.
LUA_ERRGCMM:
erro ao executar um metam�todo __gc.
(Este erro tipicamente n�o tem rela��o com a fun��o 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 fun��o comporta-se exatamente como lua_pcall,
mas permite a fun��o 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 fun��o C � criada,
� poss�vel associar alguns valores a ela,
criando assim um fecho C (veja §4.4);
esses valores s�o ent�o acess�veis � fun��o sempre que ela � chamada.
Para associar valores com uma fun��o C,
primeiro esses valores devem ser colocados na pilha
(quando h� m�ltiplos valores, o primeiro valor � colocado primeiro).
Em seguida lua_pushcclosure
� chamada para criar e colocar a fun��o C na pilha,
com o argumento n dizendo quantos valores devem ser
associados com a fun��o.
lua_pushcclosure tamb�m retira valores da pilha.
O valor m�ximo para n � 255.
Quando n � zero,
esta fun��o cria uma fun��o C leve,
que � apenas um ponteiro para a fun��o C.
Nesse caso, ela nunca lan�a um erro de mem�ria.
lua_pushcfunction[-0, +1, –]
void lua_pushcfunction (lua_State *L, lua_CFunction f);
Coloca uma fun��o C na pilha.
Esta fun��o recebe um ponteiro para uma fun��o C
e coloca na pilha um valor Lua do tipo function que,
quando chamado, invoca a fun��o C correspondente.
Qualquer fun��o a ser registrada em Lua deve
seguir o protocolo correto para receber seus par�metros
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 diferen�as importantes:
%%' (insere um '%' na cadeia),
'%s' (insere uma cadeia terminada por zero, sem restri��es de tamanho),
'%f' (insere um lua_Number),
'%p' (insere um ponteiro como um n�mero 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 n�mero 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 n�mero):
voc� n�o o cria, ele n�o possui metatabela individual,
e n�o � coletado (pois nunca foi criado).
Um userdata leve � igual a "qualquer"
userdata leve com o mesmo endere�o 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 c�pia interna da cadeia fornecida,
de modo que a mem�ria de s pode ser liberada ou reusada imediatamente ap�s
a fun��o retornar.
A cadeia pode conter qualquer dado bin�rio,
incluindo zeros dentro dela.
Retorna um ponteiro para a c�pia 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 n�mero 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 c�pia interna da cadeia fornecida,
de modo que a mem�ria apontada por s pode ser liberada ou reusada imediatamente ap�s
a fun��o retornar.
Retorna um ponteiro para a c�pia 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 execu��o 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 n�mero com valor n na pilha.
lua_pushvalue[-0, +1, –]
void lua_pushvalue (lua_State *L, int index);
Coloca uma c�pia 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 inv�s de um n�mero vari�vel 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 s�o iguais primitivamente
(isto �, sem chamar metam�todos).
Caso contr�rio retorna 0.
Tamb�m retorna 0 se algum dos �ndices n�o � v�lido.
lua_rawget[-1, +1, –]
void lua_rawget (lua_State *L, int index);
Similar a lua_gettable, mas faz um acesso primitivo
(i.e., sem metam�todos).
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 �, n�o invoca metam�todos.
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 �, n�o invoca metam�todos.
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 metam�todos;
para userdatas, isso � o tamanho do bloco de mem�ria 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 atribui��o primitiva
(i.e., sem metam�todos).
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 fun��o desempilha o valor da pilha. A atribui��o � primitiva; isto �, ela n�o invoca metam�todos.
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 fun��o desempilha o valor da pilha. A atribui��o � primitiva; isto �, ela n�o invoca metam�todos.
lua_Readertypedef const char * (*lua_Reader) (lua_State *L,
void *data,
size_t *size);
A fun��o de leitura usada por lua_load.
Toda vez que ela precisa de outro peda�o do trecho,
lua_load chama a fun��o de leitura,
passando junto seu par�metro data.
A fun��o de leitura deve retornar um ponteiro para um bloco de mem�ria
com um novo peda�o do trecho
e atribuir a size o tamanho do bloco.
O bloco deve existir at� que a fun��o de leitura seja chamada novamente.
Para sinalizar o fim do trecho,
a fun��o de leitura deve retornar NULL ou atribuir zero a size.
A fun��o de leitura pode retornar peda�os 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 fun��o 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 v�lido fornecido, deslocando para baixo os elementos acima desse �ndice para preencher o buraco. Esta fun��o n�o pode ser chamada com um pseudo-�ndice, pois um pseudo-�ndice n�o � uma posi��o 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 v�lido fornecido sem deslocar nenhum elemento (substituindo portanto o valor no topo da pilha), e ent�o desempilha o elemento no topo.
lua_resume[-?, +?, –]
int lua_resume (lua_State *L, lua_State *from, int nargs);
Come�a e retoma uma co-rotina em um dado fluxo de execu��o.
Para come�ar uma co-rotina,
voc� deve colocar na pilha do fluxo de execu��o a fun��o principal mais quaisquer argumentos;
em seguida voc� chama lua_resume,
com nargs sendo o n�mero de argumentos.
Essa chamada retorna quando a co-rotina suspende ou termina sua execu��o.
Quando ela retorna, a pilha cont�m todos os valores passados para lua_yield,
ou todos os valores retornados pela fun��o do corpo.
lua_resume retorna
LUA_YIELD se a co-rotina cede,
LUA_OK se a co-rotina termina sua execu��o
sem erros,
ou um c�digo de erro em caso de erros (veja lua_pcall).
Em caso de erros, a pilha n�o � desenrolada, de modo que voc� pode usar a API de depura��o 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 ent�o chama lua_resume.
O par�metro from representa a co-rotina que est� retomando L.
Se n�o h� tal co-rotina,
esse par�metro pode ser NULL.
lua_setallocf[-0, +0, –]
void lua_setallocf (lua_State *L, lua_Alloc f, void *ud);
Muda a fun��o 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 fun��o retira o valor do topo da pilha. Como em Lua, esta fun��o pode disparar um metam�todo 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 fun��o desempilha tanto a chave quanto o valor da pilha. Como em Lua, esta fun��o pode disparar um metam�todo 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,
ent�o os novos elementos s�o preenchidos com nil.
Se index � 0, ent�o todos os elementos da pilha s�o 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_Statetypedef struct lua_State lua_State;
Uma estrutura opaca que aponta para um fluxo de execu��o e indiretamente (atrav�s do fluxo) para o estado inteiro de uma interpretador Lua. A biblioteca Lua � totalmente reentrante: ela n�o possui vari�veis globais. Toda informa��o sobre um estado � acess�vel atrav�s desta estrutura.
Um ponteiro para esta estrutura deve ser passado como primeiro argumento para
toda fun��o 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 execu��o L.
O estado pode ser 0 (LUA_OK) para um fluxo normal,
um c�digo de erro se o fluxo terminou a execu��o
de um lua_resume com um erro,
ou LUA_YIELD se o fluxo est� suspenso.
Voc� pode chamar fun��es somente em fluxos de execu��o com estado LUA_OK.
Voc� pode retomar fluxos com estado LUA_OK
(para come�ar 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 contr�rio 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 fun��o C.
Esse valor deve ser uma fun��o C;
caso contr�rio, 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 n�mero ou uma cadeia que pode ser convertida para um n�mero
(veja §3.4.2);
caso contr�rio, lua_tointegerx retorna 0.
Se o n�mero n�o � um inteiro, ele � truncado de alguma maneira n�o especificada.
Se isnum n�o � NULL,
seu referente recebe um valor booleano que
indica se a opera��o 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 n�o � NULL,
tamb�m atribui a *len o comprimento da cadeia.
O valor Lua deve ser uma cadeia ou um n�mero;
caso contr�rio, a fun��o retorna NULL.
Se o valor � um n�mero,
ent�o lua_tolstring tamb�m
muda o valor de fato na pilha para uma cadeia.
(Essa mudan�a 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')
ap�s seu �ltimo caractere (como em C),
mas pode conter outros zeros em seu corpo.
Como Lua tem coleta de lixo,
n�o h� garantia de que o ponteiro retornado por lua_tolstring
ser� v�lido ap�s 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 n�mero ou uma cadeia que pode ser convertida para um n�mero
(veja §3.4.2);
caso contr�rio, lua_tonumberx retorna 0.
Se isnum n�o � NULL,
seu referente recebe um valor booleano que
indica se a opera��o 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 gen�rico (void*).
O valor pode ser um userdata, uma tabela, um fluxo de execu��o, ou uma fun��o;
caso contr�rio, lua_topointer retorna NULL.
Objetos diferentes ir�o fornecer ponteiros diferentes.
N�o h� maneira de converter o ponteiro de volta para seu valor original.
Tipicamente esta fun��o � usada somente para informa��o de depura��o.
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 execu��o Lua
(representado como lua_State*).
Esse valor deve ser um fluxo de execu��o;
caso contr�rio, a fun��o 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 n�mero ou uma cadeia que pode ser convertida para um n�mero.
(veja §3.4.2);
caso contr�rio, lua_tounsignedx retorna 0.
Se o n�mero n�o � um inteiro, ele � truncado de alguma maneira n�o especificada. Se o n�mero est� fora do intervalo de valores represent�veis, ele � normalizado para o resto de sua divis�o por um a mais do que o valor represent�vel m�ximo.
Se isnum n�o � NULL,
seu referente recebe um valor booleano que
indica se a opera��o 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 endere�o de seu bloco.
Se o valor � um userdata leve,
retorna seu ponteiro.
Caso contr�rio, retorna NULL.
lua_type[-0, +0, –]
int lua_type (lua_State *L, int index);
Retorna o tipo do valor no �ndice v�lido fornecido,
ou LUA_TNONE para um �ndice n�o-v�lido (por�m aceit�vel).
Os tipos retornados por lua_type s�o codificados pelas seguintes constantes
definidas em lua.h:
LUA_TNIL,
LUA_TNUMBER,
LUA_TBOOLEAN,
LUA_TSTRING,
LUA_TTABLE,
LUA_TFUNCTION,
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_Unsignedtypedef unsigned long lua_Unsigned;
O tipo usado pela API de Lua para representar valores inteiros sem sinal. Ele deve ter no m�nimo 32 bits.
Por padr�o 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 fun��o que est� executando (veja §4.4).
lua_version[-0, +0, v]
const lua_Number *lua_version (lua_State *L);
Retorna o endere�o do n�mero da vers�o armazenado no n�cleo de Lua.
Quando chamada com um lua_State v�lido,
retorna o endere�o da vers�o usada para criar aquele estado.
Quando chamada com NULL,
retorna o endere�o da vers�o executando a chamada.
lua_Writertypedef int (*lua_Writer) (lua_State *L,
const void* p,
size_t sz,
void* ud);
O tipo da fun��o de escrita usada por lua_dump.
Toda vez que ela produz outro peda�o de trecho,
lua_dump chama a fun��o de escrita,
passando junto o buffer a ser escrito (p),
seu tamanho (sz),
e o par�metro data fornecido para lua_dump.
A fun��o de escrita retorna um c�digo de erro:
0 significa sem erros;
qualquer outro valor significa um erro e impede lua_dump de
chamar a fun��o de escrita novamente.
lua_xmove[-?, +?, –]
void lua_xmove (lua_State *from, lua_State *to, int n);
Troca valores entre diferentes fluxos de execu��o do mesmo estado.
Esta fun��o retira n valores da pilha from,
e os coloca na pilha to.
lua_yield[-?, +?, –]
int lua_yield (lua_State *L, int nresults);
Esta fun��o � equivalente a lua_yieldk,
mas ela n�o possui uma continua��o (veja §4.7).
Assim, quando o fluxo de execu��o recome�a,
ela retorna para a fun��o que chamou
a fun��o chamando lua_yield.
lua_yieldk[-?, +?, –]
int lua_yieldk (lua_State *L, int nresults, int ctx, lua_CFunction k);
Cede uma co-rotina.
Esta fun��o somente deve ser chamada como a express�o de retorno de uma fun��o C, como a seguir:
return lua_yieldk (L, n, i, k);
Quando uma fun��o C chama lua_yieldk dessa maneira,
a co-rotina que est� executando suspende sua execu��o,
e a chamada a lua_resume que iniciou essa co-rotina retorna.
O par�metro nresults � o n�mero de valores da pilha
que s�o passados como resultados para lua_resume.
Quando a co-rotina � retomada novamente,
Lua chama a fun��o de continua��o fornecida k para continuar
a execu��o da fun��o C que cedeu (veja §4.7).
Essa fun��o de continua��o recebe a mesma pilha
da fun��o anterior,
com os resultados removidos e
substitu�dos pelos argumentos passados para lua_resume.
Al�m disso,
a fun��o de continua��o pode acessar o valor ctx
chamando lua_getctx.
Lua n�o possui facilidades de depura��o pr�-definidas. Ao inv�s disso, ela oferece uma interface especial por meio de fun��es e ganchos. Essa interface permite a constru��o de diferentes tipos de depuradores, analisadores din�micos de programas, e outras ferramentas que precisam de "informa��o interna" do interpretador.
lua_Debugtypedef 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) n�mero de upvalues */
unsigned char nparams; /* (u) n�mero de par�metros */
char isvararg; /* (u) */
char istailcall; /* (t) */
char short_src[LUA_IDSIZE]; /* (S) */
/* parte privada */
outros campos
} lua_Debug;
Uma estrutura usada para guardar peda�os diferentes de
informa��o sobre uma fun��o ou um registro de ativa��o.
lua_getstack preenche somente a parte privada
dessa estrutura, para uso posterior.
Para preencher os outros campos de lua_Debug com informa��o �til,
chame lua_getinfo.
Os campos de lua_Debug possuem o seguinte significado:
source:
a fonte do trecho que criou a fun��o.
Se source come�a com um '@',
significa que a fun��o foi definida em um arquivo onde
o nome do arquivo vem depois do '@'.
Se source come�a com um '=',
o resto de seu conte�do descreve a fonte de uma maneira que depende do usu�rio.
Caso contr�rio,
a fun��o foi definida em uma cadeia onde
source � essa cadeia.
short_src:
uma vers�o "imprim�vel" de source, para ser usada em mensagens de erro.
linedefined:
o n�mero da linha onde a defini��o da fun��o come�a.
lastlinedefined:
o n�mero da linha onde a defini��o da fun��o termina.
what:
a cadeia "Lua" se a fun��o � uma fun��o Lua,
"C" se ela � uma fun��o C,
"main" se ela � a parte principal de um trecho.
currentline:
a linha corrente onde a fun��o dada est� executando.
Quando nenhuma informa��o sobre a linha est� dispon�vel,
currentline recebe -1.
name:
um nome razo�vel para a fun��o dada.
Como fun��es em Lua s�o valores de primeira classe,
elas n�o possuem um nome fixo:
algumas fun��es podem ser o valor de m�ltiplas vari�veis globais,
enquanto outras podem estar armazenadas somente em um campo de uma tabela.
A fun��o lua_getinfo verifica como a fun��o foi
chamada para encontrar um nome adequado.
Se ela n�o consegue encontrar um nome,
ent�o 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 fun��o foi chamada.
(Lua usa a cadeia vazia quando nenhum outra op��o parece se aplicar.)
istailcall:
verdadeiro se esta invoca��o de fun��o foi chamada por uma chamada final.
Nesse caso, o chamador deste n�vel n�o est� na pilha.
nups:
o n�mero de upvalues da fun��o.
nparams:
o n�mero de par�metros fixo da fun��o
(sempre 0 para fun��es C).
isvararg:
verdadeiro se a fun��o � uma fun��o vararg.
(sempre verdadeiro para fun��es C).
lua_gethook[-0, +0, –]
lua_Hook lua_gethook (lua_State *L);
Retorna a fun��o 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 m�scara do gancho corrente.
lua_getinfo[-(0|1), +(0|1|2), e]
int lua_getinfo (lua_State *L, const char *what, lua_Debug *ar);
Obt�m informa��o sobre uma fun��o ou invoca��o de fun��o espec�fica.
Para obter informa��o sobre uma invoca��o de fun��o,
o par�metro ar deve ser um registro de ativa��o v�lido que foi
preenchido por uma chamada anterior a lua_getstack ou
fornecido como argumento para um gancho (veja lua_Hook).
Para obter informa��o sobre uma fun��o voc� a coloca na pilha
e inicia a cadeia what com o caractere '>'.
(Nesse caso,
lua_getinfo desempilha a fun��o do topo da pilha.)
Por exemplo, para saber em qual linha uma fun��o f foi definida,
voc� pode escrever o c�digo a seguir:
lua_Debug ar;
lua_getglobal(L, "f"); /* obt�m '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 fun��o que est�
executando no n�vel fornecido;
L':
coloca na pilha uma tabela cujos �ndices s�o os
n�meros das linhas que s�o v�lidas na fun��o.
(Uma linha v�lida � uma linha com algum c�digo associado,
isto �, uma linha onde voc� pode colocar um ponto de parada.
Linhas n�o v�lidas incluem linhas vazias e coment�rios.)
Esta fun��o retorna 0 em caso de erro
(por exemplo, um op��o inv�lida em what).
lua_getlocal[-0, +(0|1), –]
const char *lua_getlocal (lua_State *L, lua_Debug *ar, int n);
Obt�m informa��o sobre uma vari�vel local de um dado registro de ativa��o ou de uma dada fun��o.
No primeiro caso,
o par�metro ar dever ser um registro de ativa��o v�lido 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 vari�vel local inspecionar;
veja debug.getlocal para detalhes sobre �ndices e nomes
de vari�veis.
lua_getlocal coloca o valor da vari�vel na pilha
e retorna o nome dela.
No segundo caso, ar deve ser NULL e a fun��o
a ser inspecionada deve estar no topo da pilha.
Nesse caso, somente par�metros de fun��es Lua s�o vis�veis
(pois n�o h� informa��o sobre quais vari�veis est�o ativas)
e nenhum valor � colocado na pilha.
Retorna NULL (e n�o empilha nada)
quando o �ndice � maior do que
o n�mero de vari�veis locais ativas.
lua_getstack[-0, +0, –]
int lua_getstack (lua_State *L, int level, lua_Debug *ar);
Obt�m informa��o sobre a pilha de tempo de execu��o do interpretador.
Esta fun��o preenche partes de uma estrutura lua_Debug com
uma identifica��o do registro de ativa��o
da fun��o executando em um dado n�vel.
O n�vel 0 � a fun��o executando atualmente,
enquanto que o n�vel n+1 � a fun��o que chamou o n�vel n
(exceto para chamadas finais, que n�o contam com a pilha).
Quando n�o h� erros, lua_getstack retorna 1;
quando chamada com um n�vel 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);
Obt�m informa��o sobre um upvalue de um fecho.
(Para fun��es Lua,
upvalues s�o as vari�veis locais externas que a fun��o usa,
e que s�o consequentemente inclu�das em seu fecho.)
lua_getupvalue obt�m 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 n�o possuem uma ordem particular,
pois eles est�o ativos durante a fun��o inteira.
Assim, eles s�o numerados em uma ordem arbitr�ria.)
Retorna NULL (e n�o empilha nada)
quando o �ndice � maior do que o n�mero de upvalues.
Para fun��es C, esta fun��o usa a cadeia vazia ""
como um nome para todos os upvalues.
lua_Hooktypedef void (*lua_Hook) (lua_State *L, lua_Debug *ar);
O tipo para fun��es de gancho de depura��o.
Sempre que um gancho � chamado, o campo event de seu argumento
ar recebe o evento espec�fico que disparou o gancho.
Lua identifica esses eventos com as seguintes constantes:
LUA_HOOKCALL, LUA_HOOKRET,
LUA_HOOKTAILCALL, LUA_HOOKLINE,
e LUA_HOOKCOUNT.
Al�m disso, para eventos de linha, o campo currentline tamb�m � 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 recurs�o final;
neste caso, n�o 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 fun��o ou um gancho, essa execu��o ocorre sem quaisquer chamadas a ganchos.
Fun��es de gancho n�o podem ter continua��es,
isto �, elas n�o podem chamar lua_yieldk,
lua_pcallk, ou lua_callk com um k n�o nulo.
Fun��es de gancho podem ceder sob as seguintes condi��es:
Somente eventos de contagem e de linha podem ceder
e eles n�o podem produzir nenhum valor;
para ceder uma fun��o de gancho deve terminar sua execu��o
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 fun��o de gancho de depura��o.
O argumento f � a fun��o de gancho.
mask especifica sobre quais eventos o gancho ser� chamado:
ele � formado por uma conjun��o bit a bit das contantes
LUA_MASKCALL,
LUA_MASKRET,
LUA_MASKLINE,
e LUA_MASKCOUNT.
O argumento count somente possui significado quando a m�scara
inclui LUA_MASKCOUNT.
Para cada evento, o gancho � chamado como explicado abaixo:
count.
(Este evento somente acontece quando Lua est� executando uma fun��o 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 vari�vel local de um dado registro de ativa��o.
Os par�metros ar e n s�o como em lua_getlocal
(veja lua_getlocal).
lua_setlocal atribui o valor no topo da pilha
� vari�vel e retorna o nome dela.
Tamb�m desempilha o valor da pilha.
Retorna NULL (e n�o desempilha nada)
quando o �ndice � maior do que
o n�mero de vari�veis 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.
Tamb�m desempilha o valor da pilha.
Os par�metros funcindex e n s�o como em lua_getupvalue
(veja lua_getupvalue).
Retorna NULL (e n�o desempilha nada)
quando o �ndice � maior que o n�mero de upvalues.
lua_upvalueid[-0, +0, –]
void *lua_upvalueid (lua_State *L, int funcindex, int n);
Retorna um identificador �nico para o upvalue de n�mero n
do fecho no �ndice funcindex.
Os par�metros funcindex e n s�o como em lua_getupvalue
(veja lua_getupvalue)
(mas n n�o pode ser maior do que o n�mero 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 vari�vel local externa) retornar�o identificadores id�nticos 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.
A biblioteca auxiliar oferece v�rias fun��es convenientes para interfacear C com Lua. Enquanto a API b�sica oferece fun��es primitivas para todas as intera��es entre C e Lua, a biblioteca auxiliar oferece fun��es de mais alto n�vel para algumas tarefas comuns.
Todas as fun��es e tipos da biblioteca auxiliar
est�o definidos no arquivo de cabe�alho lauxlib.h e
possuem um prefixo luaL_.
Todas as fun��es na biblioteca auxiliar s�o constru�das em cima da API b�sica, e portanto elas n�o oferecem nada que n�o possa ser feito com essa API. Apesar disso, o uso da biblioteca auxiliar garante mais consist�ncia para seu c�digo.
V�rias fun��es na biblioteca auxiliar usam internamente alguns espa�os extras de pilha. Quando uma fun��o na biblioteca auxiliar usa menos do que cinco espa�os, ela n�o verifica o tamanho da pilha; ela simplesmente assume que h� espa�os suficientes.
V�rias fun��es na biblioteca auxiliar s�o usadas para
verificar argumentos de fun��es C.
Como a mensagem de erro � formatada para argumentos
(e.g., "argumento ruim #1"),
voc� n�o deve usar essas fun��es para outros valores da pilha.
Fun��es chamadas luaL_check*
sempre lan�am um erro se a verifica��o n�o � satisfeita.
Aqui listamos todas as fun��es e tipos da biblioteca auxiliar em ordem alfab�tica.
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 n�o 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 fun��o 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 n�o, lan�a um erro com uma mensagem padr�o.
luaL_argerror[-0, +0, v]
int luaL_argerror (lua_State *L, int arg, const char *extramsg);
Lan�a um erro com uma mensagem de erro padr�o
que inclui extramsg como um coment�rio.
Esta fun��o nunca retorna,
mas � idiom�tico us�-la em fun��es C
como return luaL_argerror(args).
luaL_Buffertypedef struct luaL_Buffer luaL_Buffer;
O tipo para um buffer de cadeia.
Um buffer de cadeia permite c�digo C construir cadeias Lua pouco a pouco. Seu padr�o de uso � como a seguir:
b do tipo luaL_Buffer.luaL_buffinit(L, &b).luaL_add*.
luaL_pushresult(&b).
Essa chamada deixa a cadeia final no topo da pilha.
Se voc� sabe de antem�o o tamanho total da cadeia resultante, voc� pode usar o buffer assim:
b do tipo luaL_Buffer.sz com uma chamada luaL_buffinitsize(L, &b, sz).luaL_pushresultsize(&b, sz),
onde sz � o tamanho total da cadeia resultante
copiada para esse espa�o.
Durante sua opera��o normal,
um buffer de cadeia usa um n�mero vari�vel de espa�os de pilha.
Assim, ao usar um buffer, voc� n�o pode assumir que voc� sabe onde
o topo da pilha est�.
Voc� pode usar a pilha entre chamadas sucessivas �s opera��es de buffer
desde que esse uso seja balanceado;
isto �,
quando voc� chama uma opera��o de buffer,
a chamada est� no mesmo n�vel
que ela estava imediatamente ap�s a opera��o de buffer anterior.
(A �nica exce��o a esta regra � luaL_addvalue.)
Ap�s chamar luaL_pushresult a pilha volta ao
n�vel 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 fun��o n�o alocar nenhum espa�o;
o buffer deve ser declarado como uma vari�vel
(veja luaL_Buffer).
luaL_buffinitsize[-?, +?, e]
char *luaL_buffinitsize (lua_State *L, luaL_Buffer *B, size_t sz);
Equivalente � sequ�ncia
luaL_buffinit, luaL_prepbuffsize.
luaL_callmeta[-0, +(0|1), e]
int luaL_callmeta (lua_State *L, int obj, const char *e);
Chama um metam�todo.
Se o objeto no �ndice obj tem uma metatabela e essa
metatabela tem um campo e,
esta fun��o chama esse campo passando o objeto como seu �nico argumento.
Nesse caso esta fun��o retorna verdadeiro e coloca na
pilha o valor retornado pela chamada.
Se n�o h� metatabela ou metam�todo,
esta fun��o retorna falso (sem colocar nenhum valor na pilha).
luaL_checkany[-0, +0, v]
void luaL_checkany (lua_State *L, int arg);
Verifica se a fun��o possui um argumento
de qualquer tipo (incluindo nil) na posi��o arg.
luaL_checkint[-0, +0, v]
int luaL_checkint (lua_State *L, int arg);
Verifica se o argumento arg da fun��o � um n�mero
e retorna esse n�mero convertido para um int.
luaL_checkinteger[-0, +0, v]
lua_Integer luaL_checkinteger (lua_State *L, int arg);
Verifica se o argumento arg da fun��o � um n�mero
e retorna esse n�mero convertido para um lua_Integer.
luaL_checklong[-0, +0, v]
long luaL_checklong (lua_State *L, int arg);
Verifica se o argumento arg da fun��o � um n�mero
e retorna esse n�mero 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 fun��o � uma cadeia
e retorna essa cadeia;
se l n�o � NULL preenche *l
com o comprimento da cadeia.
Esta fun��o usa lua_tolstring para obter seu resultado,
assim todas as convers�es e cuidados dessa fun��o se aplicam aqui.
luaL_checknumber[-0, +0, v]
lua_Number luaL_checknumber (lua_State *L, int arg);
Verifica se o argumento arg da fun��o � um n�mero
e retorna esse n�mero.
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 fun��o � 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.
Lan�a um erro se o argumento n�o � uma cadeia ou
se a cadeia n�o pode ser encontrada.
Se def n�o � NULL,
a fun��o usa def como um valor padr�o quando
n�o h� argumento arg ou quando esse argumento � nil.
Esta � uma fun��o �til para mapear cadeias para enumera��es de C. (A conven��o usual em bibliotecas Lua � usar cadeias ao inv�s de n�meros para selecionar op��es.)
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,
lan�ando um erro se a pilha n�o 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 fun��o � uma cadeia
e retorna essa cadeia.
Esta fun��o usa lua_tolstring para obter seu resultado,
assim todas as convers�es e cuidados relacionados a essa fun��o se aplicam aqui.
luaL_checktype[-0, +0, v]
void luaL_checktype (lua_State *L, int arg, int t);
Verifica se o argumento arg da fun��o tem tipo t.
Veja lua_type para a codifica��o 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 fun��o � um userdata
do tipo tname (veja luaL_newmetatable) e
retorna o endere�o 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 fun��o � um n�mero
e retorna esse n�mero convertido para um lua_Unsigned.
luaL_checkversion[-0, +0, –]
void luaL_checkversion (lua_State *L);
Verifica se o n�cleo executando a chamada, o n�cleo que criou o estado Lua, e o c�digo fazendo a chamada est�o todos usando a mesma vers�o de Lua. Tamb�m verifica se o n�cleo executando a chamada e o n�cleo que criou o estado Lua est�o usando o mesmo espa�o de endere�os.
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 n�o 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 n�o h� erros ou verdadeiro em caso de erros.
luaL_error[-0, +0, v]
int luaL_error (lua_State *L, const char *fmt, ...);
Lan�a um erro.
O formato da mensagem de erro � dado por fmt
mais quaisquer argumentos extras,
seguindo as mesmas regras de lua_pushfstring.
Tamb�m adiciona no come�o da mensagem de erro o nome do arquivo e
o n�mero da linha onde o erro ocorreu,
se essa informa��o est� dispon�vel.
Esta fun��o nunca retorna,
mas � idiom�tico us�-la em fun��es C
como return luaL_error(args).
luaL_execresult[-0, +3, e]
int luaL_execresult (lua_State *L, int stat);
Esta fun��o produz os valores retornados por
fun��es relacionadas a processos na biblioteca padr�o
(os.execute e io.close).
luaL_fileresult[-0, +(1|3), e]
int luaL_fileresult (lua_State *L, int stat, const char *fname);
Esta fun��o produz os valores retornados por
fun��es relacionadas a arquivos na biblioteca padr�o
(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 n�o tem uma metatabela,
ou se a metatabela n�o tem esse campo,
retorna falso e n�o 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 c�pia da cadeia s substituindo
qualquer ocorr�ncia 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 n�mero;
� equivalente ao operador '#' em Lua (veja §3.4.6).
Lan�a um erro se o resultado da opera��o n�o � um n�mero.
(Esse caso somente pode acontecer atrav�s de metam�todos.)
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 fun��o usa lua_load para carregar o trecho no
buffer apontado por buff com tamanho sz.
Esta fun��o retorna os mesmos resultados de lua_load.
name � o nome do trecho,
usado para informa��o de depura��o e mensagens de erro.
A cadeia mode funciona como na fun��o 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 fun��o usa lua_load para carregar o trecho no arquivo
chamado filename.
Se filename � NULL,
ent�o ela carrega a partir da entrada padr�o.
A primeira linha no arquivo � ignorada se ela come�a com um #.
A cadeia mode funciona como na fun��o lua_load.
Esta fun��o retorna os mesmos resultados de lua_load,
mas ela possui um c�digo de erro extra LUA_ERRFILE
se ela n�o pode abrir/ler o arquivo ou o arquivo tem um modo errado.
Como lua_load, esta fun��o somente carrega o trecho;
ela n�o o executa.
luaL_loadstring[-0, +1, –]
int luaL_loadstring (lua_State *L, const char *s);
Carrega uma cadeia como um trecho Lua.
Esta fun��o usa lua_load para carregar o trecho na
cadeia terminada por zero s.
Esta fun��o retorna os mesmos resultados de lua_load.
Tamb�m como lua_load, esta fun��o somente carrega o trecho;
ela n�o 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 fun��es 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 n�o as armazena de fato).
� planejada para ser usada em conjun��o com luaL_setfuncs
(veja luaL_newlib).
� implementada como uma macro.
O array l deve ser o array de fato,
n�o 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 contr�rio,
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 fun��o realloc de C padr�o
e ent�o estabelece uma fun��o de p�nico (veja §4.6) que imprime
uma mensagem de erro para a sa�da de erro padr�o em caso de erros
fatais.
Retorna o novo estado,
ou NULL se h� um erro de aloca��o de mem�ria.
luaL_openlibs[-0, +0, e]
void luaL_openlibs (lua_State *L);
Abre todas as bibliotecas Lua padr�o no estado fornecido.
luaL_optint[-0, +0, v]
int luaL_optint (lua_State *L, int arg, int d);
Se o argumento arg da fun��o � um n�mero,
retorna esse n�mero convertido para um int.
Se esse argumento est� ausente ou � nil,
retorna d.
Caso contr�rio, lan�a um erro.
luaL_optinteger[-0, +0, v]
lua_Integer luaL_optinteger (lua_State *L,
int arg,
lua_Integer d);
Se o argumento arg da fun��o � um n�mero,
retorna esse n�mero convertido para um lua_Integer.
Se esse argumento est� ausente ou � nil,
retorna d.
Caso contr�rio, lan�a um erro.
luaL_optlong[-0, +0, v]
long luaL_optlong (lua_State *L, int arg, long d);
Se o argumento arg da fun��o � um n�mero,
retorna esse n�mero convertido para um long.
Se esse argumento est� ausente ou � nil,
retorna d.
Caso contr�rio, lan�a 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 fun��o � uma cadeia,
retorna essa cadeia.
Se esse argumento est� ausente ou � nil,
retorna d.
Caso contr�rio, lan�a um erro.
Se l n�o � NULL,
preenche a posi��o *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 fun��o � um n�mero,
retorna esse n�mero.
Se esse argumento est� ausente ou � nil,
retorna d.
Caso contr�rio, lan�a um erro.
luaL_optstring[-0, +0, v]
const char *luaL_optstring (lua_State *L,
int arg,
const char *d);
Se o argumento arg da fun��o � uma cadeia,
retorna essa cadeia.
Se esse argumento est� ausente ou � nil,
retorna d.
Caso contr�rio, lan�a um erro.
luaL_optunsigned[-0, +0, v]
lua_Unsigned luaL_optunsigned (lua_State *L,
int arg,
lua_Unsigned u);
Se o argumento arg da fun��o � um n�mero,
retorna esse n�mero convertido para um lua_Unsigned.
Se esse argumento est� ausente ou � nil,
retorna u.
Caso contr�rio, lan�a 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 endere�o para um espa�o de tamanho sz
onde voc� pode copiar uma cadeia a ser adicionada ao buffer B
(veja luaL_Buffer).
Ap�s copiar a cadeia nesse espa�o 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 � sequ�ncia luaL_addsize, luaL_pushresult.
luaL_ref[-1, +0, e]
int luaL_ref (lua_State *L, int t);
Cria e retorna uma refer�ncia,
na tabela no �ndice t,
para o objeto no topo da pilha (e desempilha o objeto).
Uma refer�ncia � uma chave inteira �nica.
Contanto que voc� n�o adicione manualmente chaves inteiras na tabela t,
luaL_ref garante a unicidade da chave que ela retorna.
Voc� pode recuperar um objeto referenciado pela refer�ncia r
chamando lua_rawgeti(L, t, r).
A fun��o luaL_unref libera uma refer�ncia 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 refer�ncia retornada por luaL_ref.
luaL_Regtypedef struct luaL_Reg {
const char *name;
lua_CFunction func;
} luaL_Reg;
O tipo para arrays de fun��es a serem registradas por
luaL_setfuncs.
name � o nome da fun��o e func � um ponteiro para
a fun��o.
Qualquer array de luaL_Reg deve terminar com uma entrada sentinela
na qual tanto name como func s�o NULL.
luaL_requiref[-0, +1, e]
void luaL_requiref (lua_State *L, const char *modname,
lua_CFunction openf, int glb);
Chama a fun��o openf com a cadeia modname como um argumento
e atribui a package.loaded[modname] o resultado da chamada,
como se essa fun��o tivesse sido chamada atrav�s de require.
Se glb � verdadeiro,
tamb�m armazena o resultado na global modname.
Deixa uma c�pia desse resultado na pilha.
luaL_setfuncs[-nup, +0, e]
void luaL_setfuncs (lua_State *L, const luaL_Reg *l, int nup);
Registra todas as fun��es no array l
(veja luaL_Reg) na tabela no topo da pilha
(abaixo de upvalues opcionais, veja a seguir).
Quando nup n�o � zero,
todas as fun��es s�o criadas compartilhando nup upvalues,
os quais devem ser colocados previamente no topo
da pilha da tabela da biblioteca.
Esses valores s�o retirados da pilha ap�s 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 fun��o funciona como luaL_checkudata,
exceto pelo fato de que, quando o teste falha,
ela retorna NULL ao inv�s de lan�ar 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 razo�vel.
A cadeia resultante � colocada na pilha e tamb�m
retornada pela fun��o.
Se len n�o � NULL,
a fun��o tamb�m atribui a *len o comprimento da cadeia.
Se o valor possui uma metatabela com um campo "__tostring",
ent�o luaL_tolstring chama o metam�todo 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 tra�o na pilha L1.
Se msg n�o � NULL ela � acrescentada
ao in�cio do tra�o.
O par�metro level diz em qual n�vel
come�ar o tra�o.
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 refer�ncia ref da tabela no �ndice t
(veja luaL_ref).
A entrada � removida da tabela,
de modo que o objeto referenciado pode ser coletado.
A refer�ncia ref tamb�m � liberada para ser usada novamente.
Se ref � LUA_NOREF ou LUA_REFNIL,
luaL_unref n�o faz nada.
luaL_where[-0, +1, e]
void luaL_where (lua_State *L, int lvl);
Coloca na pilha uma cadeia identificando a posi��o corrente
do controle no n�vel lvl na pilha de chamadas.
Tipicamente essa cadeia possui o seguinte formato:
nometrecho:linhacorrente:
O N�vel 0 � a fun��o executando, o N�vel 1 � a fun��o que chamou a fun��o executando, etc.
Esta fun��o � usada para construir um prefixo para mensagens de erro.
As bibliotecas padr�o de Lua oferecem fun��es �teis
que s�o implementadas diretamente atrav�s da API C.
Algumas dessas fun��es oferecem servi�os essenciais para a linguagem
(e.g., type e getmetatable);
outras oferecem acesso a servi�os "externos" (e.g., I/O);
e outras poderiam ser implementadas em Lua mesmo,
mas s�o bastante �teis ou possuem exig�ncias de desempenho cr�ticas que
merecem uma implementa��o em C (e.g., table.sort).
Todas as bibliotecas s�o implementadas atrav�s da API C oficial e s�o oferecidas como m�dulos C separados. Atualmente, Lua possui as seguintes bibliotecas padr�o:
Exceto pelas bibliotecas b�sica e de pacotes, cada biblioteca oferece todas as suas fun��es como campos de uma tabela global ou como m�todos de seus objetos.
Para ter acesso a essas bibliotecas,
o programa hospedeiro C deve chamar a fun��o luaL_openlibs,
que abre todas as bibliotecas padr�o.
Alternativamente,
o programa hospedeiro pode abri-las individualmente usando
luaL_requiref para chamar
luaopen_base (para a biblioteca b�sica),
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 matem�tica),
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 depura��o).
Essas fun��es est�o declaradas em lualib.h.
A biblioteca b�sica oferece fun��es essenciais para Lua. Se voc� n�o incluir esta biblioteca em sua aplica��o, voc� deve verificar cuidadosamente se voc� precisa oferecer implementa��es para algumas de suas facilidades.
assert (v [, message])v � falso (i.e., nil ou false);
caso contr�rio, retorna todos os seus argumentos.
message � uma mensagem de erro;
quando ausente, a mensagem padr�o � "assertion failed!"
collectgarbage ([opt [, arg]])
Esta fun��o � interface gen�rica para o coletor de lixo.
Ela realiza fun��es diferentes de acordo com o seu primeiro argumento, opt:
collect":
realiza um ciclo de coleta de lixo completo.
Esta � a op��o padr�o.
stop":
para a execu��o autom�tica do coletor de lixo.
O coletor executar� somente quando explicitamente invocado,
at� uma chamada para reinici�-lo.
restart":
reinicia a execu��o autom�tica do coletor de lixo.
count":
retorna a mem�ria total em uso por Lua (em Kbytes) e
uma segundo valor com a mem�ria total em bytes m�dulo 1024.
O primeiro valor tem uma parte fracion�ria,
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 n�meros.)
step":
realiza um passo de coleta de lixo.
O passo "size" � controlado por arg
(valores maiores significam passos maiores) de maneira n�o 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., n�o parado).
generational":
muda o coletor para o modo generacional.
Esta � uma caracter�stica experimental (veja §2.5).
incremental":
muda o coletor para o modo incremental.
Este � o modo padr�o.
dofile ([filename])dofile executa o conte�do da entrada padr�o (stdin).
Retorna todos os valores retornados pelo trecho.
Em caso de erros, dofile propaga o erro
para seu chamador (isto �, dofile n�o executa em modo protegido).
error (message [, level])message como a mensagem de erro.
A fun��o error nunca retorna.
Geralmente, error adiciona alguma informa��o sobre a posi��o do erro
ao come�o da mensagem, se a mensagem � uma cadeia.
O argumento level especifica como obter a posi��o do erro.
Quando level � 1 (o padr�o), a posi��o do erro � onde a
fun��o error foi chamada.
O level 2 aponta o erro para onde a fun��o
que chamou error foi chamada; e assim por diante.
Passar um level 0 evita a adi��o de informa��o da posi��o do erro
� mensagem.
_G
getmetatable (object)
Se object n�o tem uma metatabela, retorna nil.
Caso contr�rio,
se a metatabela do objeto tem um campo "__metatable",
retorna o valor associado.
Caso contr�rio, retorna a metatabela do objeto fornecido.
ipairs (t)
Se t tem um metam�todo __ipairs,
chama-o com t como argumento e retorna os primeiros tr�s
resultados da chamada.
Caso contr�rio,
retorna tr�s valores: uma fun��o iteradora, a tabela t, e 0,
de modo que a constru��o
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 fun��o,
load a chama repetidamente para obter os peda�os 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 n�o h� erros sint�ticos, retorna o trecho compilado como uma fun��o; caso contr�rio, retorna nil mais a mensagem de erro.
Se a fun��o resultante tem upvalues,
o primeiro upvalue recebe o valor de env,
se esse par�metro � fornecido,
ou o valor do ambiente global.
(Quando voc� carrega um trecho principal,
a fun��o resultante sempre ter� exatamente um upvalue,
a vari�vel _ENV (veja §2.2).
Quando voc� carrega um trecho bin�rio criado a partir de uma fun��o (veja string.dump),
a fun��o resultante pode ter upvalues arbitr�rios.)
source � usada como a fonte do trecho para mensagens de erro
e informa��o de depura��o (veja §4.9).
Quando ausente,
o padr�o � ld, se ld � uma cadeia,
ou "=(load)" caso contr�rio.
A cadeia mode controla se o trecho pode ser texto ou bin�rio
(isto �, um trecho pr�-compilado).
Ela pode ser a cadeia "b" (somente trechos bin�rios),
"t" (somente trechos textuais),
ou "bt" (tanto bin�rio como texto).
O padr�o � "bt".
loadfile ([filename [, mode [, env]]])
Similar a load,
mas obt�m o trecho do arquivo filename
ou da entrada padr�o,
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 pr�ximo �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, ent�o ele � interpretado como nil.
Em particular,
voc� pode usar next(t) para verificar se uma tabela � vazia.
A ordem na qual os �ndices s�o enumerados n�o � especificada, mesmo para �ndices num�ricos. (Para percorrer uma tabela em ordem num�rica, use um for num�rico.)
O comportamento de next � indefinido se,
durante o percorrimento,
voc� atribuir qualquer valor a um campo n�o existente na tabela.
Voc� pode contudo modificar campos existentes.
Em particular, voc� pode limpar campos existentes.
pairs (t)
Se t tem um metam�todo __pairs,
chama-o com t como argumento e retorna os primeiros tr�s
resultados da chamada.
Caso contr�rio,
retorna tr�s valores: a fun��o next, a tabela t, e nil,
de modo que a constru��o
for k,v in pairs(t) do corpo end
ir� iterar sobre todos os pares chave–valor da tabela t.
Veja a fun��o next para os cuidados que se deve ter ao modificar
a tabela durante seu percorrimento.
pcall (f [, arg1, ···])
Chama a fun��o f com
os argumentos dados em modo protegido.
Isso significa que qualquer erro dentro de f n�o � propagado;
ao inv�s disso, pcall captura o erro
e retorna um c�digo de estado.
Seu primeiro resultado � o c�digo de estado (um booleano),
o qual � verdadeiro se a chamada aconteceu sem erros.
Em tal caso, pcall tamb�m retorna todos os resultados da chamada,
ap�s esse primeiro resultado.
Em caso de qualquer erro, pcall retorna false mais a mensagem de erro.
print (···)stdout,
usando a fun��o tostring para converter cada argumento para uma cadeia.
print n�o � projetada para sa�da formatada,
mas somente como uma maneira r�pida de mostrar um valor,
por exemplo para depura��o.
Para um controle completo sobre a sa�da,
use string.format e io.write.
rawequal (v1, v2)v1 � igual a v2,
sem invocar nenhum metam�todo.
Retorna um booleano.
rawget (table, index)table[index],
sem invocar nenhum metam�todo.
table deve ser um tabela;
index pode ser qualquer valor.
rawlen (v)v,
o qual deve ser uma tabela ou uma cadeia,
sem invocar qualquer metam�todo.
Retorna um n�mero inteiro.
rawset (table, index, value)value como o valor real de table[index],
sem invocar nenhum metam�todo.
table deve ser uma tabela,
index qualquer valor diferente de nil e NaN,
e value qualquer valor Lua.
Esta fun��o retorna table.
select (index, ···)
Se index � um n�mero,
retorna todos os argumentos ap�s o argumento n�mero index;
um n�mero negativo indexa a partir do fim (-1 � o �ltimo argumento).
Caso contr�rio, index deve ser a cadeia "#",
e select retorna o n�mero total de argumentos extras que ela recebeu.
setmetatable (table, metatable)
Estabelece a metatabela para a tabela fornecida.
(Voc� n�o 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",
lan�a um erro.
Esta fun��o retorna table.
tonumber (e [, base])
Quando chamada sem base,
tonumber tenta converter seu argumento para um n�mero.
Se o argumento j� � um n�mero ou
uma cadeia que pode ser convertida para um n�mero (veja §3.4.2),
ent�o tonumber retorna esse n�mero;
caso contr�rio, retorna nil.
Quando chamada com base,
ent�o e deve ser uma cadeia a ser interpretada como
um n�mero inteiro nessa base.
A base pode ser qualquer inteiro entre 2 e 36, inclusive.
Em bases acima de 10, a letra 'A' (mai�scula ou min�scula)
representa 10, 'B' representa 11, e assim por diante,
com 'Z' representando 35.
Se a cadeia e n�o � um n�mero v�lido na base fornecida,
a fun��o retorna nil.
tostring (v)string.format.)
Se a metatabela de v tem um campo "__tostring",
ent�o tostring chama o valor correspondente
com v como argumento,
e usa o resultado da chamada como seu resultado.
type (v)nil" (uma cadeia, n�o o valor nil),
"number",
"string",
"boolean",
"table",
"function",
"thread",
e "userdata".
_VERSIONLua 5.2".
xpcall (f, msgh [, arg1, ···])
Esta fun��o � similar a pcall,
exceto pelo fato de que ela estabelece um novo tratador de mensagens msgh.
As opera��es relacionadas a co-rotinas compreendem uma sub-biblioteca da
biblioteca b�sica e v�m dentro da tabela coroutine.
Veja §2.6 para uma descri��o geral de co-rotinas.
coroutine.create (f)
Cria uma nova co-rotina, com corpo f.
@{f} deve ser uma fun��o Lua.
Retorna essa nova co-rotina,
um objeto com tipo "thread".
coroutine.resume (co [, val1, ···])
Come�a ou continua a execu��o da co-rotina co.
Da primeira vez que voc� retoma uma co-rotina,
ela come�a executando o corpo dela.
Os valores val1, ... s�o passados
como os argumentos para a fun��o do corpo.
Se a co-rotina cedeu,
resume a recome�a;
os valores val1, ... s�o passados
como os resultados da cess�o.
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 fun��o 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 n�o come�ou a executar ainda;
"normal" se a co-rotina est� ativa mas n�o est� executando
(isto �, ela retomou outra co-rotina);
e "dead" se a co-rotina finalizou a fun��o 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 fun��o Lua.
Retorna uma fun��o que retoma a co-rotina cada vez que ela � chamada.
Quaisquer argumentos extras passados para a fun��o 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 execu��o da co-rotina chamadora.
Quaisquer argumentos para yield s�o passados como resultados extras para resume.
A biblioteca de pacotes oferece facilidades
b�sicas para carregar m�dulos em Lua.
Ela exporta uma fun��o diretamente no ambiente global:
require.
Todo o resto � exportado em um tabela package.
require (modname)
Carrega o m�dulo fornecido.
A fun��o come�a investigando a tabela package.loaded
para determinar se modname j� est� carregado.
Se est�, ent�o require retorna o valor armazenado
em package.loaded[modname].
Caso contr�rio, tenta encontrar um carregador para o m�dulo.
Para encontrar um carregador,
require � guiada pela sequ�ncia de package.searchers.
Modificando essa sequ�ncia,
podemos modificar como require procura por um m�dulo.
A explica��o a seguir � baseada na configura��o padr�o
de package.searchers.
Primeiro require consulta package.preload[modname].
Se ela tem um valor,
esse valor (que deve ser uma fun��o) � o carregador.
Caso contr�rio require procura por um carregador Lua usando o
caminho armazenado em package.path.
Se isso tamb�m falha, ela procura por um carregador C usando o
caminho armazenado em package.cpath.
Se isso tamb�m 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 n�o retorna um valor diferente de nil e
n�o atribuiu nenhum valor a package.loaded[modname],
ent�o 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 m�dulo,
ou se ela n�o encontrou nenhum carregador para o m�dulo,
ent�o require lan�a um erro.
package.configUma cadeia descrevendo algumas configura��es de tempo de compila��o para pacotes. Esta cadeia � uma sequ�ncia de linhas:
\' para Windows e '/' para todos os outros sistemas.;'.?'.!'.luaopen_.
O padr�o � '-'.
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 vari�vel de ambiente LUA_CPATH_5_2
ou a vari�vel de ambiente LUA_CPATH
ou um caminho padr�o definido em luaconf.h.
package.loaded
Uma tabela usada por require para controlar quais
m�dulos j� est�o carregados.
Quando voc� requisita um m�dulo modname e
package.loaded[modname] n�o � falso,
require simplesmente retorna o valor armazenado l�.
Essa vari�vel � somente uma refer�ncia para a tabela real;
atribui��es a essa vari�vel n�o modificam a
tabela usada por require.
package.loadlib (libname, funcname)
Dinamicamente liga o programa hospedeiro com a biblioteca C libname.
Se a fun��o funcname � "*",
ent�o somente liga com a biblioteca,
tornando os s�mbolos exportados pela biblioteca
dispon�veis para outras bibliotecas ligadas dinamicamente.
Caso contr�rio,
procura por uma fun��o funcname dentro da biblioteca
e retorna essa fun��o como uma fun��o C.
Assim, funcname deve seguir o prot�tipo lua_CFunction
(veja lua_CFunction).
Essa � uma fun��o de baixo n�vel.
Ela ignora completamente o sistema de pacotes e m�dulos.
Ao contr�rio de require,
ela n�o realiza nenhuma busca de caminho e
n�o adiciona extens�es automaticamente.
libname deve ser o nome completo do arquivo da biblioteca C,
incluindo se necess�rio um caminho e uma extens�o.
funcname deve ser o nome exato exportado pela biblioteca C
(o qual pode depender do compilador e do ligador C usados).
Esta fun��o n�o � suportada por C Padr�o.
Dessa forma, ela est� dispon�vel somente em algumas plataformas
(Windows, Linux, Mac OS X, Solaris, BSD,
al�m de outros sistemas Unix que suportam o padr�o dlfcn).
package.path
O caminho usado por require para procurar por um carregador Lua.
Ao iniciar, Lua inicializa esta vari�vel com
o valor da vari�vel de ambiente LUA_PATH_5_2 ou
da vari�vel de ambiente LUA_PATH ou
com um valor padr�o definido em luaconf.h,
se essas vari�veis de ambiente n�o est�o definidas.
Qualquer ";;" no valor da vari�vel de ambiente
� substitu�do pelo caminho padr�o.
package.preload
Uma tabela para guardar carregadores para m�dulos espec�ficos
(veja require).
Esta vari�vel � somente uma refer�ncia para a tabela real;
atribui��es a esta vari�vel n�o modificam a
tabela usada por require.
package.searchers
Uma tabela usada por require para controlar como carregar m�dulos.
Cada entrada nesta tabela � uma fun��o buscadora.
Ao procurar por um m�dulo,
require chama cada uma dessas buscadoras em ordem ascendente,
com o nome do m�dulo (o argumento fornecido para require) como seu
�nico argumento.
A fun��o pode retornar outra fun��o (o carregador do m�dulo)
mais um valor extra que ser� passado para esse carregador,
ou uma cadeia explicando por que ela n�o encontrou esse m�dulo
(ou nil se ela n�o tem nada a dizer).
Lua inicializa esta tabela com quatro fun��es 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 fun��o package.searchpath.
A terceira buscadora procura por um carregador como uma biblioteca C,
usando o caminho fornecido pela vari�vel package.cpath.
Novamente,
a busca � feita como descrito na fun��o package.searchpath.
Por exemplo,
se o caminho C � a cadeia
"./?.so;./?.dll;/usr/local/?/init.so"
a buscadora para o m�dulo 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 liga��o din�mica para ligar a
aplica��o com a biblioteca.
Em seguida ela tenta encontrar uma fun��o C dentro da biblioteca a
ser usada como carregador.
O nome dessa fun��o C � a cadeia "luaopen_"
concatenada com uma c�pia do nome do m�dulo onde cada ponto
� substitu�do por um sublinhado.
Al�m disso, se o nome do m�dulo tem um h�fen,
seu prefixo at� (e incluindo) o primeiro h�fen � removido.
Por exemplo, se o nome do m�dulo � a.v1-b.c,
o nome da fun��o 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 m�dulo fornecido.
Por exemplo, ao requisitar a.b.c,
ela procurar� por uma biblioteca C para a.
Se encontrar, busca dentro dela por uma fun��o de abertura para
o subm�dulo;
no nosso exemplo, essa seria luaopen_a_b_c.
Com essa facilidade, um pacote pode empacotar v�rios subm�dulos C
dentro de uma �nica biblioteca,
com cada subm�dulo mantendo sua fun��o de abertura original.
Todas as buscadoras exceto a primeira (preload) retorna como valor extra
o nome do arquivo onde o m�dulo foi encontrado,
como retornado por package.searchpath.
A primeira buscadora n�o retorna valor extra.
package.searchpath (name, path [, sep [, rep]])
Procura pelo name fornecido no path fornecido.
Um caminho � uma cadeia contendo uma sequ�ncia de
modelos separados por ponto-e-v�rgula.
Para cada modelo,
a fun��o substitui cada ponto de interroga��o (se houver)
no modelo por uma c�pia de name
onde todas as ocorr�ncias de sep
(um ponto, por padr�o)
foram substitu�das por rep
(o separador de diret�rios do sistema, por padr�o),
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 (ap�s 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.)
Esta biblioteca oferece fun��es gen�ricas para manipula��o de cadeias, tais como encontrar e extrair subcadeias, e casamento de padr�es. Ao indexar uma cadeia em Lua, o primeiro caractere est� na posi��o 1 (n�o na 0, como em C). �ndices podem ser negativos e s�o interpretados como uma indexa��o de tr�s pra frente, a partir do fim da cadeia. Dessa forma, o �ltimo caractere est� na posi��o -1, e assim por diante.
A biblioteca de cadeias oferece todas as suas fun��es dentro da tabela
string.
Ela tamb�m estabelece uma metatabela para cadeias
onde o campo __index aponta para a tabela string.
Logo, voc� pode usar as fun��es 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 codifica��es de caracteres de um byte.
string.byte (s [, i [, j]])s[i],
s[i+1], ..., s[j].
O valor padr�o para i � 1;
o valor padr�o para j � i.
Esses �ndices s�o corrigidos
seguindo as mesmas regras da fun��o string.sub.
C�digos num�ricos n�o s�o necessariamente port�veis entre plataformas.
string.char (···)C�digos num�ricos n�o s�o necessariamente port�veis entre plataformas.
string.dump (function)
Retorna uma cadeia contendo uma representa��o bin�ria da fun��o fornecida,
de modo que um load posterior sobre essa cadeia retorna
uma c�pia da fun��o (mas com novos upvalues).
string.find (s, pattern [, init [, plain]])
Procura pelo primeiro casamento de
pattern na cadeia s.
Se encontra um casamento, ent�o find retorna os �ndices de s
onde essa ocorr�ncia come�ou e terminou;
caso contr�rio, retorna nil.
Um terceiro argumento num�rico opcional init especifica
onde come�ar a busca;
o valor padr�o dele � 1 e pode ser negativo.
Um valor true para o quarto argumento opcional plain
desabilita as facilidades de casamento de padr�o,
de modo que a fun��o faz uma opera��o de "busca de subcadeia" simples,
sem que os caracteres de pattern sejam considerados m�gicos.
No que se plain � fornecido, ent�o init deve ser fornecido tamb�m.
Se o padr�o possui capturas, ent�o em um casamento bem sucedido os valores capturados tamb�m s�o retornados, ap�s os dois �ndices.
string.format (formatstring, ···)
Retorna uma vers�o formatada de seu n�mero vari�vel de argumentos
seguindo a descri��o dada em seu primeiro argumento (que deve ser uma cadeia).
A cadeia de formata��o segue as mesmas regras de ANSI C function sprintf.
As �nicas diferen�as s�o que as op��es/modificadores
*, h, L, l, n,
e p n�o s�o suportadas
e que h� uma op��o extra, q.
A op��o q formata uma cadeia entre aspas duplas,
usando sequ�ncias de escape quando necess�rio 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 op��es
A e a (quando dispon�veis),
E, e, f,
G, e g esperam todas um n�mero como argumento.
As op��es c, d,
i, o, u, X, e x
tamb�m esperam um n�mero,
mas o intervalo desse n�mero pode ser limitado pela
implementa��o C subjacente.
Para as op��es o, u, X, e x,
o n�mero n�o pode ser negativo.
A op��o q espera uma cadeia;
a op��o s espera uma cadeia sem zeros dentro dela.
Se o argumento para a op��o s n�o � uma cadeia,
ele � convertido para uma seguindo as mesmas regras de tostring.
string.gmatch (s, pattern)pattern na cadeia s.
Se pattern n�o especifica capturas,
ent�o o casamento inteiro � produzido a cada chamada.
Como um exemplo, o seguinte la�o
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 pr�ximo 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 fun��o, um circunflexo '^' no in�cio do padr�o n�o
funciona como uma �ncora, pois isso impediria a itera��o.
string.gsub (s, pattern, repl [, n])s
na qual todas (ou as primeiras n, se fornecido)
ocorr�ncias de pattern foram
substitu�das por uma cadeia de substitui��o especificada por repl,
que pode ser uma cadeia, uma tabela, ou uma fun��o.
gsub tamb�m retorna, como seu segundo valor,
o n�mero total de casamentos que ocorreram.
O nome gsub vem de Global SUBstitution.
Se repl � uma cadeia, ent�o seu valor � usado para a substitui��o.
O caractere % funciona como um caractere de escape:
qualquer sequ�ncia em repl da forma %d,
com d entre 1 e 9,
representa o valor da d-�sima subcadeia capturada.
A sequ�ncia %0 representa o casamento inteiro.
A sequ�ncia %% representa um % simples.
Se repl � uma tabela, ent�o a tabela � consultada a cada casamento,
usando a primeira captura como a chave.
Se repl � uma fun��o, ent�o essa fun��o � chamada toda vez que um
casamento ocorre, com todas as subcadeias capturadas passadas como argumentos,
em ordem.
Em todo caso, se o padr�o n�o especifica capturas, ent�o ela comporta-se como se o padr�o inteiro estivesse dentro de uma captura.
Se o valor retornado pela consulta � tabela ou pela chamada de fun��o � uma cadeia ou um n�mero, ent�o ele � usado como a cadeia de substitui��o; caso contr�rio, se ele � false ou nil, ent�o n�o h� substitui��o (isto �, o casamento original � mantido na cadeia).
Aqui est�o 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)"" possui comprimento 0.
Zeros dentro da cadeia s�o contados,
assim "a\000bc\000" possui comprimento 5.
string.lower (s)
string.match (s, pattern [, init])pattern na cadeia s.
Se encontra um, ent�o match retorna
as capturas do padr�o;
caso contr�rio retorna nil.
Se patten n�o especifica capturas,
ent�o o casamento inteiro � retornado.
Um terceiro argumento num�rico, opcional, init especifica
onde come�ar a busca;
seu valor padr�o � 1 e pode ser negativo.
string.rep (s, n [, sep])n c�pias da
cadeia s separadas pela cadeia sep.
O valor padr�o para sep � a cadeia vazia
(isto �, nenhum separador).
string.reverse (s)s invertida.
string.sub (s, i [, j])s que
come�a em i e continua at� j;
i e j podem ser negativos.
Se j est� ausente, ent�o 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, ap�s a tradu��o 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, ap�s essas corre��es,
i � maior do que j,
a fun��o retorna a cadeia vazia.
string.upper (s)Uma classe de caracteres � usada para representar um conjunto de caracteres. As seguintes combina��es s�o permitidas ao descrever uma classe de caracteres:
^$()%.[]*+-?)
representa o pr�prio caractere x.
.: (um ponto) representa todos os caracteres.%a: representa todas as letras.%c: representa todos os caracteres de controle.%d: representa todos os d�gitos.%g: representa todos os caracteres que podem ser impressos exceto o espa�o.%l: representa todas as letras min�sculas.%p: representa todos os caracteres de pontua��o.%s: representa todos os caracteres de espa�o.%u: representa todas as letras mai�sculas.%w: representa todos os caracteres alfanum�ricos.%x: representa todos os d�gitos hexadecimais.%x: (onde x � qualquer caractere n�o-alfanum�rico)
representa o caractere x.
Esta � a maneira padr�o de escapar caracteres m�gicos.
Qualquer caractere de pontua��o (mesmo os n�o m�gicos)
podem ser precedidos por um '%'
quando usado para representar a si mesmo em um padr�o.
[set]:
representa a classe que � a uni�o 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 tamb�m 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 alfanum�ricos mais o sublinhado,
[0-7] representa os d�gitos octais,
e [0-7%l%-] representa os d�gitos octais mais
as letras min�sculas mais o caractere '-'.
A intera��o entre intervalos e classes n�o � definida.
Assim, padr�es como [%a-z] ou [a-%%]
n�o 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 mai�scula correspondente representa o complemento da classe.
Por exemplo, %S representa todos os caracteres que n�o s�o de espa�o.
As defini��es de letra, espa�o, e outros grupos de caracteres
depende do idioma corrente.
Em particular, a classe [a-z] pode n�o ser equivalente a %l.
Um item de padr�o pode ser
*',
que casa 0 ou mais repeti��es de caracteres na classe.
Esses itens de repeti��o sempre casar�o a maior sequ�ncia poss�vel;
+',
que casa 1 ou mais repeti��es de caracteres na classe.
Esses itens de repeti��o sempre casar�o a maior sequ�ncia poss�vel;
-',
que tamb�m casa 0 ou mais repeti��es de caracteres na classe.
Ao contr�rio de '*',
esses itens de repeti��o sempre casar�o a menor sequ�ncia poss�vel;
?',
que casa 0 ou 1 ocorr�ncia 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 s�o dois caracteres distintos;
tal item casa cadeias que come�am com x, terminam com y,
e onde os x e y s�o 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 alcan�a 0.
Por exemplo, o item %b() casa express�es com
par�nteses balanceados.
%f[set], um padr�o de fronteira;
tal item casa uma cadeia vazia em qualquer posi��o desde que
o pr�ximo caractere perten�a a set
e o caractere anterior n�o perten�a a set.
O conjunto set � interpretado como descrito anteriormente.
O in�cio e o fim da cadeia principal s�o tratados como se
eles fossem o caractere '\0'.
Um padr�o � uma sequ�ncia de itens de padr�o.
Um circunflexo '^' no in�cio de um padr�o ancora o casamento no
in�cio do texto principal.
Um '$' no fim de um padr�o ancora o casamento no
fim do texto principal.
Em outras posi��es,
'^' e '$' n�o possuem significado especial e representam eles mesmos.
Um padr�o pode conter subpadr�es delimitados por par�nteses;
eles descrevem capturas.
Quando um casamento � bem sucedido, as subcadeias da cadeia principal
que casam capturas s�o armazenadas (capturadas) para uso futuro.
Capturas s�o numeradas de acordo com seu par�ntese esquerdo.
Por exemplo, no padr�o "(a*(.)%w(%s*))",
a parte da cadeia casando "a*(.)%w(%s*)" �
armazenada como a primeira captura (e por isso tem o n�mero 1);
o caractere casando "." � capturado com o n�mero 2,
e a parte casando "%s*" tem o n�mero 3.
Como um caso especial, a captura vazia () captura
a posi��o da cadeia corrente (um n�mero).
Por exemplo, se aplicarmos o padr�o "()aa()" sobre a
cadeia "flaaap", haver� duas capturas: 3 and 5.
Esta biblioteca oferece fun��es gen�ricas para manipula��o de tabelas.
Ela oferece todas as suas fun��es dentro da tabela table.
Lembre-se que, sempre que uma opera��o precisa do comprimento de uma tabela,
a tabela deve ser uma sequ�ncia de fato
ou ter um metam�todo __len (veja §3.4.6).
Todas as fun��es ignoram chaves n�o num�ricas
em tabelas fornecidas como argumentos.
Por raz�es de desempenho, todas os acessos (get/set) a tabelas realizados por estas fun��es s�o primitivos.
table.concat (list [, sep [, i [, j]]])
Dada uma lista onde todos os elementos s�o cadeias ou n�meros,
retorna a cadeia list[i]..sep..list[i+1] ··· sep..list[j].
O valor padr�o para sep � a cadeia vazia,
o padr�o para i � 1,
e o padr�o para j � #list.
Se i � maior do que j, retorna a cadeia vazia.
table.insert (list, [pos,] value)
Insere o elemento value na posi��o pos de list,
deslocando os elementos
list[pos], list[pos+1], ···, list[#list].
O valor padr�o 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 par�metros armazenados nas chaves 1, 2, etc.
e com um campo "n" com o n�mero total de par�metros.
Note que a tabela resultante pode n�o ser uma sequ�ncia.
table.remove (list [, pos])
Remove de list o elemento na posi��o pos,
retornando o valor do elemento removido.
Quando pos � um inteiro entre 1 e #list,
desloca os elementos
list[pos+1], list[pos+2], ···, list[#list]
e apaga o elemento list[#list];
O �ndice pos pode tamb�m ser 0 quando #list � 0,
ou #list + 1;
nesses casos, a fun��o apaga o elemento list[pos].
O valor padr�o 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,
ent�o ela deve ser uma fun��o 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 ap�s a ordena��o).
Se comp n�o � fornecido,
ent�o o operador Lua padr�o < � usado ao inv�s.
O algoritmo de ordena��o n�o � est�vel; isto �, elementos considerados iguais pela ordem fornecida podem ter suas posi��es relativas alteradas ap�s a ordena��o.
table.unpack (list [, i [, j]])Retorna os elementos da lista fornecida. Esta fun��o � equivalente a
return list[i], list[i+1], ···, list[j]
Por padr�o, i � 1 e j � #list.
Esta biblioteca � uma interface para a biblioteca matem�tica de C padr�o.
Ela oferece todas as suas fun��es 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 par�metros para encontrar
o quadrante do resultado.
(Tamb�m 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 hiperb�lico 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 divis�o de x por y
que arredonda o quociente em dire��o 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 num�rico.
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 padr�o para base � e
(de modo que a fun��o retorna o logaritmo natural de x).
math.max (x, ···)Retorna o valor m�ximo entre seus argumentos.
math.min (x, ···)Retorna o valor m�nimo entre seus argumentos.
math.modf (x)
Retorna dois n�meros,
a parte integral de x e a parte fracion�ria de x.
math.piO valor de π.
math.pow (x, y)
Retorna xy.
(Voc� tamb�m pode usar a express�o x^y para computar esse valor.)
math.rad (x)
Retorna o �ngulo x (dado em graus) em radianos.
math.random ([m [, n]])
Esta fun��o � um interface para a fun��o
geradora pseudo-rand�mica rand simples oferecida por C Padr�o.
(Nenhuma garantia pode ser dada para suas propriedades estat�sticas.)
Quando chamada sem argumentos,
retorna um n�mero real pseudo-rand�mico uniforme
no intervalo [0,1).
Quando chamada com um n�mero inteiro m,
math.random retorna
um inteiro pseudo-rand�mico uniforme no intervalo [1, m].
Quando chamada com dois n�meros inteiros m e n,
math.random retorna um inteiro pseudo-rand�mico
uniforme no intervalo [m, n].
math.randomseed (x)
Estabelece x como a "semente"
para o gerador pseudo-rand�mico:
sementes iguais produzem sequ�ncias iguais de n�meros.
math.sin (x)
Retorna o seno de x (que se assume estar em radianos).
math.sinh (x)
Retorna o seno hiperb�lico de x.
math.sqrt (x)
Retorna a raiz quadrada de x.
(Voc� tamb�m pode usar a express�o 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 hiperb�lica de x.
Esta biblioteca oferece opera��es bit a bit.
Ela oferece todas as suas fun��es dentro da tabela bit32.
A menos que dito de outra maneira,
todas as fun��es aceitam argumentos num�ricos no intervalo
(-251,+251);
cada argumento � normalizado para
o resto dessa divis�o por 232
e truncado para um inteiro (de algum modo n�o especificado),
de modo que seu valor final cabe no intervalo [0,232 - 1].
De maneira similar, todos os resultados est�o no intervalo [0,232 - 1].
Note que bit32.bnot(0) � 0xFFFFFFFF,
o que � diferente de -1.
bit32.arshift (x, disp)
Retorna o n�mero x deslocado disp bits para a direita.
O n�mero disp pode ser qualquer inteiro represent�vel.
Deslocamentos negativos deslocam para a esquerda.
Esta opera��o de deslocamento � o que � chamado de deslocamento aritm�tico.
Bits vagos � esquerda s�o preenchidos
com c�pias do bit mais significativo de x;
bits vagos � direita s�o preenchidos com zeros.
Em particular,
deslocamentos com valores absolutos maiores do que 31
resultam em zero ou 0xFFFFFFFF (todos os bits originais s�o deslocados para fora).
bit32.band (···)Retorna o and bit a bit de seus operandos.
bit32.bnot (x)
Retorna a nega��o 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 n�mero sem sinal formado pelos bits
field a field + width - 1 de n.
Bits s�o numerados de 0 (menos significativo) a 31 (mais significativo).
Todos os bits acessados deve estar no intervalo [0, 31].
O padr�o para width � 1.
bit32.replace (n, v, field [, width])
Retorna uma c�pia de n com
os bits de field a field + width - 1
substitu�dos pelo valor v.
Veja bit32.extract para detalhes sobre field e width.
bit32.lrotate (x, disp)
Retorna o n�mero x rotacionado disp bits para a esquerda.
O n�mero disp pode ser qualquer inteiro represent�vel.
Para qualquer deslocamento v�lido, 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 n�mero x deslocado disp bits para a esquerda.
O n�mero disp pode ser qualquer inteiro represent�vel.
Deslocamentos negativos deslocam para a direita.
Em qualquer dire��o, bits vagos s�o preenchidos com zeros.
Em particular,
deslocamentos com valores absolutos maiores do que 31
resultam em zero (todos os bits s�o 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 n�mero x rotacionado disp bits para a direita.
O n�mero disp pode ser qualquer inteiro represent�vel.
Para qualquer deslocamento v�lido, 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 n�mero x deslocado disp bits para a direita.
O n�mero disp pode ser qualquer inteiro represent�vel.
Deslocamentos negativos deslocam para a esquerda.
Em qualquer dire��o, bits vagos s�o preenchidos com zeros.
Em particular,
deslocamentos com valores absolutos maiores do que 31
resultam em zero (todos os bits s�o deslocados para fora).
Para deslocamentos positivos, a seguinte igualdade vale:
assert(bit32.rshift(b, disp) == math.floor(b % 2^32 / 2^disp))
Esta opera��o de deslocamento � o que � chamado de deslocamento l�gico.
A biblioteca de E/S oferece dois estilos diferentes para manipula��o de arquivos. O primeiro usa descritores de arquivos impl�citos; isto �, h� opera��es para estabelecer um arquivo de entrada padr�o e um arquivo de sa�da padr�o, e todas as opera��es de entrada/sa�da s�o sobre esses arquivos padr�o. O segundo estilo usa descritores de arquivos expl�citos.
Ao usar descritores de arquivos impl�citos,
todas as opera��es s�o fornecidas pela tabela io.
Ao usar descritores de arquivos expl�citos,
a opera��o io.open retorna um descritor de arquivo
e ent�o todas as opera��es s�o fornecidas como m�todos do descritor de arquivo.
A tabela io tamb�m oferece
tr�s 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 fun��es de E/S retornam nil em caso de falha
(mais uma mensagem de erro como um segundo resultado e
um c�digo de erro dependente do sistema como um terceiro resultado)
e algum valor diferente de nil em caso de sucesso.
Em sistemas n�o Posix,
a computa��o da mensagem de erro e do c�digo de erro
em caso de erros
pode n�o ser segura se h� m�ltiplos fluxos de execu��o,
pois ela depende da vari�vel C global errno.
io.close ([file])
Equivalente a file:close().
Sem um file, fecha o arquivo de sa�da padr�o.
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 sa�da padr�o. Quando chamada com um manipulador de arquivo, simplesmente estabelece esse manipulador de arquivo como o arquivo de entrada padr�o. Quando chamada sem par�metros, retorna o arquivo de entrada padr�o corrente.
Em caso de erros esta fun��o lan�a o erro, ao inv�s de retornar um c�digo de erro.
io.lines ([filename ···])
Abre o nome do arquivo fornecido em modo de leitura
e retorna uma fun��o iteradora que
funciona como file:lines(···) sobre o arquivo aberto.
Quando a fun��o iteradora detecta o fim do arquivo,
retorna nil (para finalizar o la�o) 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 padr�o.
Nesse caso ela n�o fecha o arquivo quando o la�o termina.
Em caso de erros esta fun��o lan�a o erro, ao inv�s de retornar um c�digo de erro.
io.open (filename [, mode])
Esta fun��o 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 padr�o);w": modo de escrita;a": modo de adi��o;r+": modo de atualiza��o, todos os dados anteriores s�o preservados;w+": modo de atualiza��o, todos os dados anteriores s�o apagados;a+": modo de atualiza��o de adi��o, todos os dados anteriores s�o preservados,
a escrita somente � permitida no fim do arquivo.
A cadeia mode tamb�m pode ter um 'b' no fim,
que � necess�rio em alguns sistemas para abrir o arquivo em modo bin�rio.
io.output ([file])
Similar a io.input, mas opera sobre o arquivo de sa�da padr�o.
io.popen (prog [, mode])Esta fun��o � dependente do sistema e n�o est� dispon�vel em todas as plataformas.
Come�a 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 padr�o)
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 tempor�rio. Esse arquivo � aberto em modo de atualiza��o e � automaticamente removido quando o programa termina.
io.type (obj)
Verifica se obj � um manipulador de arquivo v�lido.
Retorna a cadeia "file" se obj � um manipulador de arquivo aberto,
"closed file" se obj � um manipulador de arquivo fechado,
ou nil se obj n�o � um manipulador de arquivo.
io.write (···)
Equivalente a io.output():write(···).
file:close ()
Fecha file.
Note que arquivos s�o automaticamente fechados quando
seus manipuladores s�o coletados pelo coletor de lixo,
mas isso leva uma quantidade imprevis�vel 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 fun��o iteradora que, cada vez que � chamada, l� o arquivo de acordo com os formatos fornecidos. Quando nenhum formato � fornecido, usa "*l" como um padr�o. Como um exemplo, a constru��o
for c in file:lines(1) do corpo end
ir� iterar sobre todos os caracteres do arquivo,
come�ando na posi��o corrente.
Diferente de io.lines, esta fun��o n�o fecha o arquivo
quando o la�o termina.
Em caso de erros esta fun��o lan�a o erro, ao inv�s de retornar um c�digo de erro.
file:read (···)
L� o arquivo file,
de acordo com os formatos fornecidos, os quais especificam o que ler.
Para cada formato,
a fun��o retorna uma cadeia (ou um n�mero) com os caracteres lidos,
ou nil se ela n�o conseguiu ler dados com o formato especificado.
Quando chamada sem formatos,
usa o formato padr�o que l� a pr�xima linha
(veja abaixo).
Os formatos dispon�veis s�o
*n":
l� um n�mero;
este � o �nico formato que retorna um n�mero ao inv�s de uma cadeia.
*a":
l� o arquivo inteiro, come�ando na posi��o corrente.
no fim do arquivo, retorna a cadeia vazia.
*l":
l� a pr�xima linha pulando o fim de linha,
retornando nil no fim do arquivo.
Este � o formato padr�o.
*L":
l� a pr�xima linha mantendo o fim de linha (se presente),
retornando nil no fim do arquivo.
number � zero,
n�o l� nada e retorna uma cadeia vazia,
ou nil no fim do arquivo.
file:seek ([whence [, offset]])
Estabelece e obt�m a posi��o do arquivo,
medida a partir do in�cio do arquivo,
at� a posi��o dada por offset mais uma base
especificada pela cadeia whence, como segue:
set": base � a posi��o 0 (in�cio do arquivo);cur": base � a posi��o corrente;end": base � o fim do arquivo;
Em caso de sucesso, seek retorna a posi��o final do arquivo,
medida em bytes a partir do in�cio do arquivo.
Se seek falha, retorna nil,
mais uma cadeia descrevendo o erro.
O valor padr�o para whence � "cur",
e para offset � 0.
Por isso, a chamada file:seek() retorna a posi��o
corrente do arquivo, sem modific�-la;
a chamada file:seek("set") ajusta a posi��o para o
in�cio do arquivo (e retorna 0);
e a chamada file:seek("end") ajusta a posi��o para o
fim do arquivo, e retorna seu tamanho.
file:setvbuf (mode [, size])Estabelece o modo de bufferiza��o para um arquivo de sa�da. H� tr�s modos dispon�veis:
no":
sem bufferiza��o; o resultado de qualquer opera��o de sa�da aparece imediatamente.
full":
bufferiza��o completa; a opera��o � realizada somente
quando o buffer est� cheio ou quando
voc� explicitamente descarrega o arquivo (veja io.flush).
line":
bufferiza��o de linha; a sa�da � 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 padr�o � um tamanho apropriado.
file:write (···)
Escreve o valor de cada um de seus argumentos para file.
Os argumentos devem ser cadeias ou n�meros.
Em caso de sucesso, esta fun��o retorna file.
Caso contr�rio retorna nil mais uma cadeia descrevendo o erro.
Esta biblioteca � implementada atrav�s da tabela os.
os.clock ()Retorna uma aproxima��o 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 fun��o os.time para uma descri��o desse valor).
Caso contr�rio, date formata a hora corrente.
Se format come�a com '!',
ent�o a data est� formatada no Tempo Universal Coordenado.
Ap�s esse caractere opcional,
se format � a cadeia "*t",
ent�o date retorna uma tabela com os seguintes campos:
year (quatro d�gitos), month (1–12), day (1–31),
hour (0–23), min (0–59), sec (0–61),
wday (dia da semana, domingo � 1),
yday (dia do ano),
and isdst (flag do hor�rio de ver�o, um booleano).
Esse �ltimo campo pode estar ausente
se a informa��o n�o est� dispon�vel.
Se format n�o � "*t",
ent�o 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 representa��o razo�vel de data e hora que depende
do sistema hospedeiro e do idioma corrente
(isto �, os.date() � equivalente a os.date("%c")).
Em sistemas n�o Posix,
esta fun��o pode n�o ser segura se h� m�ltiplos fluxos de execu��o
por causa de sua depend�ncia de C function gmtime e C function localtime.
os.difftime (t2, t1)
Retorna o n�mero 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 fun��o � 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 contr�rio.
Ap�s esse primeiro resultado
a fun��o retorna uma cadeia e um n�mero,
como segue:
exit":
o comando terminou normalmente;
o n�mero seguinte � o estado de sa�da do comando.
signal":
o comando foi terminado por um sinal;
o n�mero 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� dispon�vel.
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 c�digo retornado � EXIT_FAILURE;
se code � um n�mero,
o estado retornado � esse n�mero.
O valor padr�o para code � true.
Se o segundo argumento opcional close � verdadeiro,
fecha o estado Lua antes de sair.
os.getenv (varname)
Retorna o valor da vari�vel de ambiente do processo varname,
ou nil se a vari�vel n�o est� definida.
os.remove (filename)Apaga o arquivo (ou diret�rio vazio, em sistemas POSIX) com o nome fornecido. Se esta fun��o falha, ela retorna nil, mais uma cadeia descrevendo o erro e o c�digo do erro.
os.rename (oldname, newname)
Renomeia o arquivo ou diret�rio chamado oldname para newname.
Se esta fun��o falha, ela retorna nil,
mais uma cadeia descrevendo o erro e o c�digo 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 padr�o � "all".
A fun��o retorna o nome do novo idioma,
ou nil se a requisi��o n�o pode ser honrada.
Se locale � a cadeia vazia,
o idioma corrente � definido como uma idioma nativo definido pela implementa��o.
Se locale � a cadeia "C",
o idioma corrente � definido como o idioma de C padr�o.
Quando chamada com nil como primeiro argumento, esta fun��o somente retorna o nome do idioma corrente para a categoria fornecida.
Esta fun��o pode n�o ser segura se h� m�ltiplos fluxos de execu��o
por causa de sua depend�ncia 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 padr�o � 12),
min (o padr�o � 0),
sec (o padr�o � 0),
e isdst (o padr�o � nil).
Para uma descri��o desses campos, veja a fun��o os.date.
O valor retornado � um n�mero, cujo significado depende de seu sistema.
Em POSIX, Windows, e alguns outros sistemas,
este n�mero conta o n�mero
de segundos desde algum dado tempo de in�cio (a "�poca").
Em outros sistemas, o significado n�o � especificado,
e o n�mero 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 tempor�rio. O arquivo deve ser explicitamente aberto antes de seu uso e explicitamente removido quando n�o mais necess�rio.
Em sistemas POSIX, esta fun��o tamb�m cria um arquivo com esse nome, para evitar riscos de seguran�a. (Alguma outra pessoa poderia criar o arquivo com permiss�es 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� n�o us�-lo).
Quando poss�vel,
voc� pode preferir usar io.tmpfile,
que automaticamente remove o arquivo quando o programa termina.
Esta biblioteca oferece a funcionalidade da interface de depura��o (§4.9) para programas Lua. Voc� deve ter cuidado ao usar esta biblioteca. V�rias de suas fun��es violam suposi��es b�sicas a respeito de c�digo Lua (e.g., que vari�veis locais a uma fun��o n�o podem ser acessadas de fora; que metatabelas de userdatas n�o podem ser modificadas por c�digo Lua; que programas Lua n�o quebram) e por isso podem comprometer c�digo que de outro modo seria seguro. Al�m disso, algumas fun��es desta biblioteca podem ser lentas.
Todas as fun��es desta biblioteca s�o oferecidas
dentro da tabela debug.
Todas as fun��es que operam sobre um fluxo de execu��o
possuem um primeiro argumento opcional que � o
fluxo sobre o qual operar.
O padr�o � sempre o fluxo corrente.
debug.debug ()
Entra em um modo interativo com o usu�rio,
executando cada cadeia que o usu�rio entra.
Usando comandos simples e outras facilidades de depura��o,
o usu�rio pode inspecionar vari�veis globais e locais,
modificar seus valores, avaliar express�es, e assim por diante.
Uma linha contendo somente a palavra cont finaliza esta fun��o,
de modo que a chamadora continua sua execu��o.
Note que comandos para debug.debug n�o est�o lexicamente aninhados
dentro de nenhuma fun��o e assim n�o possuem acesso direto a vari�veis locais.
debug.gethook ([thread])
Retorna as configura��es de gancho correntes do fluxo, como tr�s valores:
a fun��o de gancho corrente, a m�scara de gancho corrente,
e o contador de gancho corrente
(como definido pela fun��o debug.sethook).
debug.getinfo ([thread,] f [, what])
Retorna uma tabela com informa��o sobre uma fun��o.
Voc� pode fornecer a fun��o diretamente
ou voc� pode fornecer um n�mero como o valor de f,
o qual significa a fun��o executando no n�vel f da pilha de chamadas
do fluxo fornecido:
o n�vel 0 � a fun��o corrente (a pr�pria getinfo);
o n�vel 1 � a fun��o que chamou getinfo
(exceto para chamadas finais, que n�o contam na pilha);
e assim por diante.
Se f � um n�mero maior do que o n�mero de fun��es ativas,
ent�o getinfo retorna nil.
A tabela retornada pode conter todos os campos retornados por lua_getinfo,
com a cadeia what descrevendo quais campos preencher.
O padr�o para what � obter toda informa��o dispon�vel,
exceto a tabela de linhas v�lidas.
Se presente,
a op��o 'f'
adiciona um campo chamado func com a pr�pria fun��o.
Se presente,
a op��o 'L'
adiciona um campo chamado activelines com a tabela de
linhas v�lidas.
Por exemplo, a express�o debug.getinfo(1,"n").name retorna
uma tabela com um nome para a fun��o corrente,
se um nome razo�vel puder ser encontrado.
e a express�o debug.getinfo(print)
retorna uma tabela com toda informa��o dispon�vel
sobre a fun��o print.
debug.getlocal ([thread,] f, local)
Esta fun��o retorna o nome e o valor da vari�vel local
com �ndice local da fun��o no n�vel f da pilha.
Esta fun��o acessa n�o somente vari�veis locais expl�citas,
mas tamb�m par�metros, tempor�rios, etc.
O primeiro par�metro ou vari�vel local possui �ndice 1, e assim por diante,
at� a �ltima vari�vel ativa.
�ndices negativos se referem a par�metros vararg;
-1 � o primeiro par�metro vararg.
A fun��o retorna nil se n�o h� nenhuma vari�vel com o �ndice fornecido,
e lan�a um erro quando chamada com um n�vel fora do intervalo.
(Voc� pode chamar debug.getinfo para verificar se o n�vel � v�lido.)
Nomes de vari�veis come�ando com '(' (abre par�ntese)
representam vari�veis internas
(vari�veis de controle de la�o, tempor�rios, varargs, e locais de fun��es C).
O par�metro f tamb�m pode ser uma fun��o.
Nesse caso, getlocal retorna somente o nome dos par�metros da fun��o.
debug.getmetatable (value)
Retorna a metatabela do value fornecido
ou nil se ele n�o possui uma metatabela.
debug.getregistry ()Retorna a tabela de registro (veja §4.5).
debug.getupvalue (f, up)
Esta fun��o retorna o nome e o valor do upvalue
com �ndice up da fun��o f.
A fun��o retorna nil se n�o h� upvalue com o �ndice fornecido.
debug.getuservalue (u)
Retorna o valor Lua associado a u.
Se u n�o � um userdata,
retorna nil.
debug.sethook ([thread,] hook, mask [, count])
Estabelece a fun��o fornecida como um gancho.
A cadeia mask e o n�mero count descrevem
quando o gancho ser� chamado.
A cadeia mask pode ter qualquer combina��o dos seguintes caracteres,
com o significado dado:
c': o gancho � chamado toda vez que Lua chama uma fun��o;r': o gancho � chamado toda vez que retorna de uma fun��o;l': o gancho � chamado toda vez que Lua entra uma nova linha de c�digo.
Al�m disso,
com um count diferente de zero,
o gancho � chamado tamb�m ap�s cada count instru��es.
Quando chamada sem argumentos,
debug.sethook desabilita o gancho.
Quando o gancho � chamado, seu primeiro par�metro � uma cadeia
descrevendo o evento que disparou sua chamada:
"call" (ou "tail call"),
"return",
"line", e "count".
Para eventos de linha,
o gancho tamb�m recebe o novo n�mero de linha como seu segundo par�metro.
Dentro de um gancho,
voc� pode chamar getinfo com n�vel 2 para obter mais informa��o sobre
a fun��o executando.
(o n�vel 0 � a fun��o getinfo,
e o n�vel 1 � a fun��o de gancho).
debug.setlocal ([thread,] level, local, value)
Esta fun��o atribui o valor value � vari�vel local
com �ndice local da fun��o no n�vel level da pilha.
A fun��o retorna nil se n�o h� nenhuma vari�vel
local com o �ndice fornecido,
e lan�a um erro quando chamada com um level fora do intervalo.
(Voc� pode chamar getinfo para verificar se o n�vel � v�lido.)
Caso contr�rio, retorna o nome da vari�vel local.
Veja debug.getlocal para mais informa��es sobre
�ndices e nomes de vari�veis.
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 fun��o atribui o valor value ao upvalue
com �ndice up da fun��o f.
A fun��o retorna nil se n�o h� nenhum upvalue
com o �ndice fornecido.
Caso contr�rio, 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 n�o � uma cadeia nem nil,
esta fun��o retorna message sem processamento adicional.
Caso contr�rio,
retorna uma cadeia com um tra�o da pilha de chamadas.
Uma cadeia opcional message � adicionada
ao in�cio do tra�o.
Um n�mero opcional level diz em qual n�vel
come�ar o tra�o
(o padr�o � 1, a fun��o chamando traceback).
debug.upvalueid (f, n)
Retorna um identificador �nico (como um userdata leve)
para o upvalue com n�mero n
da fun��o fornecida.
Esses identificadores �nicos permitem um programa verificar se diferentes fechos compartilham upvalues. Fechos Lua que compartilham um upvalue (isto �, que acessam uma mesma vari�vel local externa) retornar�o identificadores id�nticos 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.
Embora Lua tenha sido projetada como uma linguagem de extens�o,
para ser embarcada em um programa C hospedeiro,
ela tamb�m � frequentemente usada como uma linguagem auto-suficiente.
Um interpretador para Lua como uma linguagem auto-suficiente,
chamado simplesmente de lua,
� fornecido com a distribui��o padr�o.
O interpretador de linha de comando inclui
todas as bibliotecas padr�o, incluindo a biblioteca de depura��o.
Seu uso �:
lua [options] [script [args]]
As op��es s�o:
-e comando: executa a cadeia comando;-l mod: "requisita" mod;-i: entra em modo interativo ap�s executar script;-v: imprime informa��es da vers�o;-E: ignora vari�veis de ambiente;--: para de tratar op��es;-: executa stdin como um arquivo e para de tratar op��es.
Ap�s tratar suas op��es, 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 padr�o (stdin) � um terminal,
e como lua - caso contr�rio.
Quando chamado sem a op��o -E,
o interpretador verifica se h� uma vari�vel de ambiente LUA_INIT_5_2
(ou LUA_INIT se ela n�o est� definida)
antes de executar ser argumento.
Se o conte�do da vari�vel possui o formato @nomearquivo,
ent�o lua executa o arquivo.
Caso contr�rio, lua executa a pr�pria cadeia.
Quando chamado com a op��o -E,
al�m de ignorar LUA_INIT,
Lua tamb�m ignora
os valores de LUA_PATH e LUA_CPATH,
estabelecendo os valores de
package.path e package.cpath
com os caminhos padr�o definidos em luaconf.h.
Todas as op��es s�o tratadas em ordem, exceto -i e -E.
Por exemplo, uma invoca��o 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 come�ar 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 ap�s 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 op��es)
v�o 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 tamb�m pode acessar esses argumentos com a express�o 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 n�o protegidos no script,
o interpretador reporta o erro para o fluxo de sa�da padr�o.
Se o objeto de erro � uma cadeia,
o interpretador adiciona um tra�o de pilha a ela.
Caso contr�rio, se o objeto de erro possui um metam�todo __tostring,
o interpretador chama esse metam�todo para produzir a mensagem final.
Finalmente, se o objeto de erro � nil,
o interpretador n�o 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 come�a com #.
Assim, scripts Lua podem virar programas execut�veis
usando chmod +x e a forma #!,
como em
#!/usr/local/bin/lua
(Obviamente,
a localiza��o do interpretador Lua pode ser diferente em sua m�quina.
Se lua est� no seu PATH,
ent�o
#!/usr/bin/env lua
� uma solu��o mais port�vel.)
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
op��es apropriadas (veja o arquivo luaconf.h).
Contudo,
todas essas op��es de compatibilidade ser�o removidas na pr�xima vers�o de Lua.
De modo similar,
todas as caracter�sticas marcadas como obsoletas em Lua 5.1
foram removidas em Lua 5.2.
_ENV ou a fun��o load.
Fun��es C n�o possuem mais ambientes.
Use um upvalue com uma tabela compartilhada se voc� precisa manter
estado compartilhado entre v�rias fun��es C.
(Voc� pode usar luaL_setfuncs para abrir uma biblioteca C
com todas as fun��es compartilhando um upvalue comum.)
Para manipular o "ambiente" de um userdata
(o qual � agora chamado de valor do usu�rio),
use as novas fun��es
lua_getuservalue and lua_setuservalue.
module est� obsoleta.
� f�cil montar um m�dulo com c�digo Lua normal.
N�o se espera que m�dulos sejam vari�veis globais.
setfenv e getfenv foram removidas,
por causa das mudan�as em ambientes.
math.log10 est� obsoleta.
Use math.log com 10 como seu segundo argumento, ao inv�s.
loadstring est� obsoleta.
Use load ao inv�s; ela agora aceita cadeias como argumentos
e � exatamente equivalente a loadstring.
table.maxn est� obsoleta.
Escreva-a em Lua se voc� realmente precisa dela.
os.execute agora retorna true quando o comando
termina com sucesso e nil mais informa��o de erro
caso contr�rio.
unpack foi movida para a biblioteca de tabelas
e desse modo deve ser chamada como table.unpack.
%z em padr�es est� obsoleta,
pois agora padr�es podem conter '\0' como um caractere normal.
package.loaders foi renomeada para package.searchers.
load e loadfile)
s�o potencialmente inseguras ao carregar dados bin�rios n�o confi�veis.
(Na verdade, essas fun��es j� eram inseguras por causa
de falhas no algoritmo de verifica��o.)
Quando em d�vida,
use o argumento mode dessas fun��es
para restringi-las a carregar trechos textuais.
LUA_GLOBALSINDEX foi removido.
Voc� deve obter o ambiente global do registro
(veja §4.5).
LUA_ENVIRONINDEX
e as fun��es lua_getfenv/lua_setfenv
foram removidas,
pois fun��es C n�o possuem mais ambientes.
luaL_register est� obsoleta.
Use luaL_setfuncs de modo que seu m�dulo n�o crie globais.
(N�o se espera mais que m�dulos estabele�am vari�veis globais.)
osize da fun��o de aloca��o
pode n�o 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.
__gc)
para userdatas s�o chamados na
ordem reversa em que eles foram marcados para finaliza��o,
n�o na que eles foram criados (veja §2.5.1).
(A maioria dos userdatas s�o marcados imediatamente ap�s eles serem criados.)
Al�m disso,
se a metatabela n�o possui um campo __gc quando definida,
o finalizador n�o ser� chamado,
mesmo se ele for definido depois.
luaL_typerror foi removida.
Escreva sua pr�pria vers�o se voc� precisar.
lua_cpcall est� obsoleta.
Voc� pode simplesmente empilhar a fun��o com lua_pushcfunction
e cham�-la com lua_pcall.
lua_equal e lua_lessthan est�o obsoletas.
Use a nova lua_compare com op��es apropriadas ao inv�s.
lua_objlen foi renomeada para lua_rawlen.
lua_load tem um par�metro extra, mode.
Passe NULL para simular o comportamento antigo.
lua_resume tem um par�metro extra, from.
Passe NULL ou o fluxo fazendo a chamada.
Aqui est� a sintaxe completa de Lua em BNF estendido. (Ela n�o descreve as preced�ncias dos operadores.)
trecho ::= bloco
bloco ::= {comando} [comandoret]
comando ::= ‘;’ |
listavars ‘=’ listaexps |
chamadafun��o |
r�tulo |
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 nomefun��o corpofun��o |
local fun��o Nome corpofun��o |
local listanomes [‘=’ listaexps]
comandoret ::= return [listaexps] [‘;’]
r�tulo ::= ‘::’ Nome ‘::’
nomefun��o ::= Nome {‘.’ Nome} [‘:’ Nome]
listavars ::= var {‘,’ var}
var ::= Nome | prefixexp ‘[’ exp ‘]’ | prefixexp ‘.’ Nome
listanomes ::= Nome {‘,’ Nome}
listaexps ::= exp {‘,’ exp}
exp ::= nil | false | true | N�mero | Cadeia | ‘...’ | deffun��o |
expprefixo | construtortabela | exp opbin exp | opun�ria exp
expprefixo ::= var | chamadafun��o | ‘(’ exp ‘)’
chamadafun��o ::= expprefixo args | expprefixo ‘:’ Nome args
args ::= ‘(’ [listaexps] ‘)’ | construtortabela | Cadeia
deffun��o ::= function corpofun��o
corpofun��o ::= ‘(’ [listapars] ‘)’ bloco end
listapars ::= listanomes [‘,’ ‘...’] | ‘...’
construtortabela ::= ‘{’ [listacampos] ‘}’
listacampos ::= campo {sepcampos campo} [sepcampos]
campo ::= ‘[’ exp ‘]’ ‘=’ exp | Nome ‘=’ exp | exp
sepcampos ::= ‘,’ | ‘;’
opbin ::= ‘+’ | ‘-’ | ‘*’ | ‘/’ | ‘^’ | ‘%’ | ‘..’ |
‘<’ | ‘<=’ | ‘>’ | ‘>=’ | ‘==’ | ‘~=’ |
and | or
opun�ria ::= ‘-’ | not | ‘#’