Manual de Referência de Lua 5.1
Manual de Referência de Lua 5.1
(Traduzido por Sérgio Queiroz de Medeiros com apoio da Fábrica Digital e da FINEP)
Copyright © 2007 Lua.org, PUC-Rio. Disponível livremente nos termos da licença de Lua.
conteúdo · índice · english · português · español
Lua é uma linguagem de programação de extensão projetada para dar suporte à programação procedimental em geral e que oferece facilidades para a descrição de dados. A linguagem também oferece um bom suporte para programação orientada a objetos, programação funcional e programação orientada a dados. Lua foi planejada para ser utilizada por qualquer aplicação que necessite de uma linguagem de script leve e poderosa. Lua é implementada como uma biblioteca, escrita em C limpo (isto é, no subconjunto comum de ANSI C 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
programa cliente anfitrião, chamado de programa hospedeiro ou simplesmente
de hospedeiro.
Esse 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 pelo código Lua.
Através do uso de funções C, Lua pode ser estendida para lidar
de maneira apropriada com uma ampla variedade de domínios,
permitindo assim a criação de linguagems 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 de Lua para oferecer um interpretador
de linha de comando Lua completo.
Lua é um software livre e, como de praxe, é fornecido sem garantias,
conforme dito na sua lincença.
A implementação descrita neste manual está disponível
no sítio web oficial de Lua, www.lua.org.
Como qualquer outro manual de referência, este documento é árido 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 sítio web oficial de Lua. Para uma introdução detalhada à programação em Lua, veja o livro de Roberto Ierusalimschy, Programming in Lua (Segunda Edição).
Esta seção descreve os aspectos léxicos, sintáticos e semânticos de Lua. Em outras palavras, esta seção descreve quais itens léxicos são válidos, como eles são combinados, e qual o significado da sua combinação.
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 non-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 no fim deste manual.
Em Lua, Nomes (também chamados de identificadores) podem ser qualquer cadeia de letras, dígitos, e sublinhados que não começam com um dígito. Esta definição está de acordo com a definição de nomes na maioria das linguagens. (A definição de letras depende de qual é o idioma (locale): qualquer caractere considerado alfabético pelo idioma corrente pode ser usado como um identificador.) Identificadores são usados para nomear variáveis e campos de tabelas.
As seguintes palavras-chave são reservadas e não podem ser utilizadas como nomes:
and break do else elseif
end false for function 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 convenção, nomes que começam com um sublinhado seguido por
letras maiúsculas (tais como _VERSION)
são reservados para variáveis globais internas usadas por Lua.
As seguintes cadeias denotam outros itens léxicos:
+ - * / % ^ #
== ~= <= >= < > =
( ) { } [ ]
; : , . .. ...
Cadeias de caracteres literais
podem ser delimitadas através do uso de aspas simples ou aspas duplas,
e podem conter as seguintes seqüências de escape no estilo de C:
'\a' (campainha),
'\b' (backspace),
'\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]).
Além disso, uma barra invertida seguida por uma quebra de linha real
resulta em uma quebra de linha na cadeia de caracteres.
Um caractere em uma cadeia de caracteres também pode ser especificado pelo seu valor numérico
usando a seqüência de escape \ddd,
onde ddd é uma seqüência de até três dígitos decimais.
(Note que se um caractere numérico representado como um seqüência de escape for
seguido por um dígito, a seqüência de escape deve possuir exatamente três dígitos.)
Cadeias de caracteres em Lua podem conter qualquer valor de 8 bits, incluindo zeros dentro delas,
os quais podem ser especificados como '\0'.
Para colocar uma aspa dupla (simples), uma quebra de linha, uma barra invertida ou inserir um zero dentro de uma cadeia de caracteres literal delimitada por aspas duplas (simples) você deve usar uma seqüência de escape. Qualquer outro caractere pode ser inserido diretamente dentro da cadeia literal. (Alguns caracteres de controle podem causar problemas para o sistema de arquivos, mas Lua não tem nenhum problema em relação a eles.)
Cadeias literais longas também podem ser definidas usando um formato longo
delimitado por colchetes longos.
Definimos uma abertura de colchete longo de nível n como um
abre colchete seguido por n sinais de igual seguido por outro
abre colchete.
Dessa forma, uma abertura de colchete longo de nível 0 é escrita como [[,
uma abertura de colchete longo de nível 1 é escrita como [=[
e assim por diante.
Um fechamento de colchete longo é definido de maneira similar;
por exemplo, um fechamento de colchete longo de nível 4 é escrito como ]====].
Uma cadeia de caracteres longa começa com uma abertura de colchete longo de qualquer nível e
termina no primeiro fechamento de colchete longo do mesmo nível.
Literais expressos desta forma podem se estender por várias linhas,
não interpretam nenhuma seqüência de escape
e ignoram colchetes longos de qualquer outro nível.
Estes literais podem conter qualquer coisa, exceto um fechamento de colchete longo de
nível igual ao da abertura.
Por conveniência,
quando uma abertura de colchete longo é imediatamente seguida por uma quebra de linha,
a quebra de linha não é incluída na cadeia de caracteres.
Como exemplo, em um sistema usando ASCII
(no qual 'a' é codificado como 97,
quebra de linha é codificado como 10 e '1' é codificado como 49),
os cinco literais abaixo 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 uma parte decimal opcional
e com um expoente decimal opcional.
Lua também aceita constantes hexadecimais inteiras, através do uso do
prefixo 0x.
Exemplos de constantes numéricas válidas são:
3 3.0 3.1416 314.16e-2 0.31416E1 0xff 0x56
Um comentário começa com um hífen duplo (--)
em qualquer lugar, desde que fora de uma cadeia de caracteres.
Se o texto imediatamente depois de -- não é uma abertura de colchete longo,
o comentário é um comentário curto,
o qual se estende até o fim da linha.
Caso contrário, ele é um comentário longo,
que se estende até o fechamento de colchete longo correspondente.
Comentários longos são freqüentemente usados para desabilitar código temporariamente.
Lua é uma linguagem dinamicamente tipada. Isto significa que variáveis não possuem tipos; somente valores possuem tipos. Não existe definição de tipos na linguagem. Todos os valores carregam o seu próprio tipo.
Todos os valores em Lua são valores de primeira classe. Isto significa que todos os valores podem ser armazenados em variáveis, passados como argumentos para outras funções e retornados como resultados.
Existem 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 torna a condição verdadeira.
Number representa números reais (ponto flutuante de precisão dupla).
(É fácil construir interpretadores Lua que usem outra
representação interna para números,
tais como precisão simples de ponto flutuante ou inteiros longos;
veja o arquivo luaconf.h.)
O tipo string representa cadeias de caracteres.
Em Lua,
cadeias de caracteres podem conter qualquer caractere de 8 bits,
incluindo zeros ('\0') dentro dela (ver §2.1).
Lua pode chamar (e manipular) funções escritas em Lua e funções escritas em C (ver §2.5.8).
O tipo userdata permite que dados C arbitrários possam ser armazenados em variáveis Lua. Este tipo corresponde a um bloco de memória e não tem operações pré-definidas em Lua, exceto atribuição e teste de identidade. Contudo, através do uso de metatables, o programador pode definir operações para valores userdata (ver §2.8). Valores userdata não podem ser criados ou modificados em Lua, somente através da API C. Isto garante a integridade dos dados que pertencem ao programa hospedeiro.
O tipo thread representa fluxos de execução independentes e é usado para implementar co-rotinas (ver §2.11). Não confunda o tipo thread de 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 por números,
mas por qualquer valor (exceto nil).
Tabelas podem ser heterogêneas;
isto é, elas podem conter valores de todos os tipos (exceto nil).
Tabelas são o único mecanismo de estruturação de dados em Lua;
elas podem ser usadas para representar arrays comuns,
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 esta representação oferecendo a.name como
um açúcar sintático para a["name"].
Existem várias maneiras convenientes de se criar tabelas em Lua
(ver §2.5.7).
Da mesma forma que os índices, o valor de um campo da tabela pode possuir qualquer tipo (exceto nil). Em particular, dado que funções são valores de primeira classe, campos de tabela podem conter funções. Portanto, tabelas podem também possuir metódos (ver §2.5.9).
Valores do tipo table, function, thread e userdata (completo) são objetos: variáveis não contêm realmente estes valores, somente referências para eles. Atribuição, passagem de parâmetro, e retorno de funções sempre lidam com referências para tais valores; estas operações não implicam em qualquer espécie de cópia.
A função type retorna uma cadeia de caracteres descrevendo o tipo
de um dado valor.
Lua provê conversão automática entre
valores do tipo string e do tipo number em tempo de execução.
Qualquer operação aritmética aplicada a uma cadeia de caracteres tenta converter
esta cadeia para um número, seguindo as regras de conversão usuais.
De forma análoga, sempre que um número é usado onde uma cadeia de caracteres é esperada,
o número é convertido para uma cadeia, em um formato razoável.
Para um controle completo sobre como números são convertidos para cadeias,
use a função format da biblioteca string (ver string.format).
Variáveis são lugares usados para armazenar valores.
Existem três tipos de variáveis em Lua: variáveis globais, variáveis locais e campos de tabelas.
Um nome simples pode denotar uma variável global ou uma variávei local (ou um parâmetro formal de uma função, que é um caso particular de variável local):
var ::= Nome
Nome denota identificadores, como definido em §2.1.
Assume-se que toda variável é uma variável global a menos que ela seja explicitamente declarada como uma variável local (ver §2.4.7). Variáveis locais possuem escopo léxico: variáveis locais podem ser livremente acessadas por funções definidas dentro do seu escopo (ver §2.6).
Antes da variável receber a sua primeira atribuição, o seu valor é nil.
Colchetes são usados para indexar uma tabela:
var ::= expprefixo `[´ exp `]´
A semântica de acessos a variáveis globais
e a campos de tabelas pode ser mudada através do uso de meta-tabelas.
Um acesso a uma variável indexada t[i] é equivalente a
uma chamada gettable_event(t,i).
(Veja §2.8 para uma descrição completa da
função gettable_event.
Esta função não é definida nem pode ser chamada em Lua.
Ela é usada aqui somente para fins didáticos.)
A sintaxe var.Nome é apenas um açúcar sintático para
var["Nome"]:
var ::= expprefixo `.´ Nome
Todas as variáveis globais são mantidas como campos em tabelas Lua comuns,
chamadas de tabelas de ambiente ou simplesmente
de ambientes (ver §2.9).
Cada função tem sua própria referência para um ambiente,
de forma que todas as variáveis globais dentro de uma função
irão se referir para esta tabela de ambiente.
Quando uma função é criada,
ela herda o ambiente da função que a criou.
Para obter a tabela de ambiente de uma função Lua,
você deve chamar getfenv.
Para trocar a tabela de ambiente,
você deve chamar setfenv.
(A única maneira de tratar o ambiente de funções C
é através da a biblioteca de depuração; (ver §5.9).)
Um acesso a uma variável global x
é equivalente a _env.x,
que por sua vez é equivalente a
gettable_event(_env, "x")
onde _env é o ambiente da função corrente.
(Veja §2.8 para uma descrição completa da
função gettable_event.
Esta função não é definida nem pode ser chamada em Lua.
De modo análogo, a variável _env não é definida em Lua.
Elas foram usadas aqui somente para fins didáticos.)
Lua oferece um conjunto quase convencional de comandos, similar ao conjunto de comandos disponíveis em Pascal ou C. Este conjunto inclui atribuição, estruturas de controle, chamadas de funções e declarações de variáveis.
A unidade de execução de Lua é denominada de trecho. Um trecho é simplesmente uma seqüência de comandos, os quais são executados sequencialmente. Cada comando pode opcionalmente ser seguido por um ponto-e-vírgula:
trecho ::= {comando [`;´]}
Não existem comandos vazios e portanto a construção ';;' não é válida.
Lua trata um trecho como o corpo de uma função anônima com um número variável de argumentos (ver §2.5.9). Desta forma, trechos podem definir variáveis locais, receber argumentos e retornar valores.
Um trecho pode ser armazenado em um arquivo ou em uma cadeia de caracteres dentro do programa hospedeiro. Quando um trecho é executado, ele é primeiro pré-compilado em instruções para uma máquina virtual e depois o código compilado é executado por um interpretador para a máquina virtual.
Trechos também podem ser pré-compilados em uma forma binária;
veja o programa luac para mais detalhes.
Programas na forma de código fonte e na forma de um arquivo fonte já compilado são intercambiáveis;
Lua automaticamente determina qual é o tipo do arquivo e age em conformidade com ele.
Um bloco é uma lista de comandos; sintaticamente, um bloco é a mesma coisa que um trecho:
bloco ::= trecho
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 usados às vezes para adicionar um comando return ou break no meio de outro bloco (ver §2.4.4).
Lua permite atribuição múltipla. Em virtude disto, 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 ambos os lados são separados por vírgulas:
comando ::= listavar `=´ listaexp
listavar ::= var {`,´ var}
listaexp ::= exp {`,´ exp}
Expressões são discutidas em §2.5.
Antes da atribuição ser realizada, 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 esta chamada entram na lista de valores, antes do ajuste ser realizado (exceto quando a chamada é delimitada por parênteses; veja §2.5).
Um comando de atribuição primeiro avalia todas as suas expressões e somente depois é que a atribuição é realizada. Desta forma, 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 (para 3)
antes de receber o valor 4.
De modo similar, a linha
x, y = y, x
troca os valores de x e y.
A semântica de atribuições para variáveis globais
e campos de tabelas pode ser mudada através do uso de meta-tabelas.
Uma atribuição para uma variável indexada t[i] = val é equivalente a
settable_event(t,i,val).
(Veja §2.8 para uma descrição completa da
função settable_event.
Esta função não é definida nem pode ser chamada em Lua.
Ela foi usada aqui somente para fins didáticos.)
Uma atribuição a uma variável global x = val
é equivalente à atribuição
_env.x = val,
que por sua vez é equivalente a
settable_event(_env, "x", val)
onde _env é o ambiente da função sendo executada.
(A variável _env não é definida em Lua.
Ela foi usada aqui somente para fins didáticos.)
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, o qual possui duas variações (ver §2.4.5).
A expressão da condição de uma estrutura de controle pode retornar qualquer valor. Tanto false como nil são considerados um valor falso. Todos os valores diferentes de nil e false são considerados como verdadeiros (em particular, o número 0 e a cadeia de caracteres vazia também são considerados valores verdadeiros).
No laço repeat–until, o bloco mais interno não termina na palavra-chave until, mas somente depois da condição. Desta forma, a condição pode referenciar variáveis locais declaradas dentro do bloco do laço.
O comando return é usado para retornar valores de uma função ou de um trecho (que nada mais é do que uma função). Funções e trechos podem retornar mais de um valor, de modo que a sintaxe para o comando return é
comando ::= return [listaexp]
O comando break é usado para terminar a execução de um laço while, repeat ou for, pulando para o próximo comando depois do laço:
comando ::= break
Um break termina a execução do laço mais interno.
Os comandos return e break
somente podem ser escritos como o último comando de um bloco.
Se é realmente necessário ter um return ou break no
meio de um bloco,
então um bloco interno explícito pode ser usado,
como nas expressões idiomáticas
do return end e do break end,
pois agora tanto o return como o break são os últimos comandos
em seus respectivos blocos (internos).
O comando for possui duas variações: uma 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 possui 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 o valor da segunda exp através de seguidos passos, sendo que a cada passo o valor da terceira exp é somado a nome. De forma mais precisa, um comando for como
for v = e1, e2, e3 do block end
é equivalente ao código:
do
local var, limit, step = tonumber(e1), tonumber(e2), tonumber(e3)
if not (var and limit and step) then error() end
while (step > 0 and var <= limit) or (step <= 0 and var >= limit) do
local v = var
block
var = var + step
end
end
Note o seguinte:
var, limit e step são variáveis invisíveis.
Os nomes foram utilizados aqui somente para fins didáticos.
v é local ao laço;
não é possível usar o valor desta variável após o fim do for ou depois
do for ter sido interrompido pelo uso de um break.
Se você precisa do valor desta variável,
atribua-o a outra variável antes de interromper ou sair do laço.
O comando for genérico funciona utilizando funções, chamadas de iteradoras. A cada iteração, a função iteradora é chamada para produzir um novo valor, parando quando este novo valor é nil. O laço for genérico possui a seguinte sintaxe:
comando ::= for listadenomes in listaexp do bloco end
listadenomes ::= Nome {`,´ Nome}
Um comando for como
for var_1, ···, var_n in explist do block end
é equivalente ao código:
do
local f, s, var = explist
while true do
local var_1, ···, var_n = f(s, var)
var = var_1
if var == nil then break end
block
end
end
Note o seguinte:
explist é avaliada somente uma vez.
Os 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 foram utilizados aqui somente para fins didáticos.
var_i são locais ao laço;
não é possível usar os valores delas após o término do for.
Se você precisa destes valores,
você deve atribuí-los a outras variáveis antes de interromper o laço ou sair do mesmo.
Para permitir possíveis efeitos colaterais, funções podem ser executadas como comandos:
comando ::= chamadadefuncao
Neste caso, todos os valores retornados pela função são descartados. Chamadas de função são explicadas em §2.5.8.
Variáveis locais podem ser declaradas em qualquer lugar dentro de um bloco. A declaração pode incluir uma atribuição inicial:
comando ::= local listadenomes [`=´ listaexp]
Caso ocorra uma atribuição inicial, a sua semântica é a mesma de uma atribuição múltipla (ver §2.4.3). Caso contrário, todas as variáveis são inicializadas com nil.
Um trecho também é um bloco (ver §2.4.1) e portanto variáveis locais podem ser declaradas em um trecho fora de qualquer bloco explícito. O escopo de uma variável declarada desta forma se estende até o fim do trecho.
As regras de visibilidade para variáveis locais são explicadas em §2.6.
As expressões básicas em Lua são as seguintes:
exp ::= expprefixo exp ::= nil | false | true exp ::= Numero exp ::= Cadeia exp ::= funcao exp ::= construtortabela exp ::= `...´ exp ::= exp opbin exp exp ::= opunaria exp expprefixo ::= var | chamadadefuncao | `(´ exp `)´
Números e cadeias literais são explicados em §2.1;
variáveis são explicadas em §2.3;
definições de funções são explicadas em §2.5.9;
chamadas de funções são explicadas em §2.5.8;
construtores de tabelas são explicados em §2.5.7.
Expressões vararg,
denotadas por três pontos ('...'), somente podem ser usadas quando
estão imediatamente dentro de uma função que possui um número variável de argumentos;
elas são explicadas em §2.5.9.
Operadores binários compreendem operadores aritméticos (ver §2.5.1), operadores relacionais (ver §2.5.2), operadores lógicos (ver §2.5.3) e o operador de concatenação (ver §2.5.4). Operadores unários compreendem o menos unário (ver §2.5.1), o not unário (ver §2.5.3) e o operador de tamanho unário (ver §2.5.5).
Tanto chamadas de funções como expressões vararg podem resultar em múltiplos valores. Se a expressão é usada como um comando (ver §2.4.6) (o que somente é possível para chamadas de funções), então a sua lista de retorno é ajustada para zero elementos, descartando portanto todos os valores retornados. Se a 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 chamada seja delimitada por parênteses). Em todos os demais contextos, Lua ajusta a lista de resultados para um elemento, descartando todos os valores exceto o primeiro.
Aqui estão alguns exemplos:
f() -- ajusta para 0 resultados
g(f(), x) -- f() é ajustado para 1 resultado
g(x, f()) -- g recebe x mais todos os resultados de f()
a,b,c = f(), x -- f() é ajustado para 1 resultado (c recebe nil)
a,b = ... -- a recebe o primeiro parâmetro da lista vararg,
-- b recebe o segundo (tanto a como b podem receber nil caso não
-- exista um parâmetro correspondente na lista)
a,b,c = x, f() -- f() é ajustado para 2 resultados
a,b,c = f() -- f() é ajustado para 3 resultados
return f() -- retorna todos os resultados de f()
return ... -- retorna todos os resultados recebidos da lista vararg
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 da lista vararg
{f(), nil} -- f() é ajustado para 1 resultado
Uma expressão delimitada por parênteses sempre resulta em um único valor.
Dessa forma,
(f(x,y,z)) é sempre um único valor,
mesmo que f retorne múltiplos valores.
(O valor de (f(x,y,z)) é o primeiro valor retornado por f,
ou nil se f não retorna nenhum valor.)
Lua provê os operadores aritméticos usuais:
os operadores binários + (adição),
- (subtração), * (multiplicação),
/ (divisão), % (módulo) e ^ (exponenciação);
e o operador unário - (negação).
Se os operandos são números ou cadeias de caracteres que podem ser convertidas para
números (ver §2.2.1),
então todas as operações possuem o seu significado usual.
A exponenciação funciona para qualquer expoente.
Por exemplo, x^(-0.5) calcula 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 arredondada em direção a menos infinito.
Os operadores relacionais em Lua são
== ~= < > <= >=
Estes operadores sempre possuem como resultado 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 de caracteres são comparados de maneira usual.
Objetos (valores do tipo table, userdata, thread e function)
são comparados por referência:
dois objetos são considerados iguais somente se eles são o mesmo objeto.
Toda vez que um novo objeto é criado
(um valor com tipo table, userdata, thread ou function)
este novo objeto é diferente de qualquer outro objeto que existia anteriormente.
É possível mudar a maneira como Lua compara os tipos table e userdata através do uso do meta-método "eq" (ver §2.8).
As regras de conversão em §2.2.1
não se aplicam a comparações de igualdade.
Portanto, "0"==0 é avaliado como false
e t[0] e t["0"] denotam posições
diferentes em uma tabela.
O operador ~= é exatamente a negação da igualdade (==).
Os operadores de ordem trabalham da seguinte forma. 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 de caracteres, então seus valores são comparados de acordo com a escolha de idioma atual. Caso contrário, Lua tenta chamar o meta-método "lt" ou o meta-método "le" (ver §2.8).
Os operadores lógicos em Lua são and, or e not. Assim como as estruturas de controle (ver §2.4.4), todos os operadores lógicos consideram false e nil como falso e qualquer coisa diferente como verdadeiro.
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 o valor deste é diferente de nil e de false; caso contrário, or retorna o seu segundo argumento. Tanto and como or usam avaliação de curto-circuito; isto é, o segundo operando é avaliado somente quando é 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 de caracteres em Lua é
denotado por dois pontos ('..').
Se ambos os operandos são cadeias de caracteres ou números, então eles são convertidos para
cadeias de caracteres de acordo com as regras mencionadas em §2.2.1.
Caso contrário, o meta-método "concat" é chamado (ver §2.8).
O operador de tamanho é denotado pelo operador unário #.
O tamanho de uma cadeia de caracteres é o seu número de bytes
(isto é, o significado usual de tamanho de uma cadeia quando
cada caractere ocupa um byte).
O tamanho de uma tabela t é definido como qualquer
índice inteiro n
tal que t[n] não é nil e t[n+1] é nil;
além disso, se t[1] é nil, n pode ser zero.
Para um array comum, com todos os valores diferentes de nil indo de 1 até um dado n,
o seu tamanho é exatamente aquele n,
o índice do seu último valor.
Se o array possui "buracos"
(isto é, valores nil entre dois outros valores diferentes de nil),
então #t pode ser qualquer um dos índices que
imediatamente precedem um valor nil
(isto é, ele pode considerar qualquer valor nil como o fim do
array).
A precedência de operadores em Lua segue a tabela abaixo, da menor prioridade para a maior:
or
and
< > <= >= ~= ==
..
+ -
* / %
not # - (unary)
^
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 demais operadores binários são associativos à esquerda.
Construtores de tabelas são expressões que criam tabelas. Toda vez que um construtor é avaliado, uma nova tabela é criada. Construtores podem ser usados para criar tabelas vazias ou para criar uma tabela e inicializar alguns dos seus campos. A sintaxe geral de construtores é
construtortabela ::= `{´ [listadecampos] `}´
listadecampos ::= campo {separadordecampos campo} [separadordecampos]
campo ::= `[´ exp `]´ `=´ exp | Nome `=´ exp | exp
separadordecampos ::= `,´ | `;´
Cada campo da forma [exp1] = exp2 adiciona à nova tabela uma entrada
cuja chave é exp1 e cujo 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 representa números inteiros consecutivos,
iniciando com 1.
Campos nos outros formatos não afetam esta 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 possui a forma exp
e a expressão é uma chamada de função ou uma expressão com um número variável de argumentos,
então todos os valores retornados pela expressão entram na lista consecutivamente
(ver §2.5.8).
Para evitar isto,
coloque parênteses ao redor da chamada de função (ou da expressão com
número variável de argumentos) (ver §2.5).
A lista de campos pode ter um separador a mais no fim, como uma conveniência para código gerado automaticamente.
Uma chamada de função em Lua tem a seguinte sintaxe:
chamadadefuncao ::= expprefixo args
Em uma chamada de função, primeiro expprefixo e args são avaliados. Se o valor de expprefixo possui tipo function, então esta função é chamada com os argumentos fornecidos. Caso contrário, o meta-método "call" de expprefixo é chamado, tendo como primeiro parâmetro o valor de expprefixo, seguido pelos argumentos originais da chamada (ver §2.8).
A forma
chamadadefuncao ::= expprefixo `:´ Nome args
pode ser usada para chamar "métodos".
Uma chamada v:nome(args)
é um açúcar sintático para v.nome(v,args),
com a diferença de que v é avaliado somente uma vez.
Argumentos possuem a seguinte sintaxe:
args ::= `(´ [listaexp] `)´ args ::= construtordetabela args ::= Cadeia
Todas as expressões fornecidas como argumento são avaliadas antes da chamada.
Uma chamada da forma f{campos} é
uma açúcar sintático para f({campos});
ou seja, a lista de argumentos consiste somente em uma tabela nova.
Uma chamada da forma f'cadeia'
(ou f"cadeia" ou f[[cadeia]])
é um açúcar sintático para f('cadeia');
ou seja, a lista de argumentos consiste somente em uma cadeia de caracteres literal.
Uma exceção em relação à sintaxe de formato livre de Lua
é que não é possível colocar uma quebra de linha antes do '(' em uma chamada de função.
Esta restrição evita algumas ambigüidades na linguagem.
Se você escrevesse
a = f
(g).x(a)
Lua poderia ver isto como um comando único, a = f(g).x(a).
Portanto, se você deseja dois comandos, você deve obrigatoriamente colocar um ponto-e-vírgula entre eles.
Se você realmente quer chamar f,
você deve remover a quebra de linha antes de (g).
Uma chamada da forma return chamadadefuncao é 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 que a chamou.
Portanto, 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 sobre a
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;
esta sintaxe faz com que a chamada de função retorne exatamente
os valores de retorno da função chamada.
Dessa forma, nenhum dos exemplos a seguir são chamadas finais:
return (f(x)) -- o número de resultados é ajustado para 1
return 2 * f(x)
return x, f(x) -- resultados adicionais
f(x); return -- resultados descartados
return x or f(x) -- o número de resultados é ajustado para 1
A sintaxe para a definição de uma função é
funcao ::= function corpodafuncao funcao ::= `(´ [listapar] `)´ bloco end
O seguinte açúcar sintático simplifica definições de funções:
comando ::= function nomedafuncao corpodafuncao
comando ::= local function Nome corpodafuncao
nomedafuncao ::= Nome {`.´ Nome} [`:´ Nome]
O comando
function f () body end
é traduzido para
f = function () body end
O comando
function t.a.b.c.f () body end
é traduzido para
t.a.b.c.f = function () body end
O comando
local function f () body end
é traduzido para
local f; f = function () body end
e não para
local f = function () body end
(Isto somente faz diferença quando o corpo da função
contém uma referência para f.)
Uma definição de função é uma expressão executável, cujo valor tem tipo function. Quando Lua pré-compila um trecho, todas os corpos das 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). Esta instância da função (ou fecho) é o valor final da expressão. Instâncias diferentes da mesma função podem se referir a diferentes variáveis locais externas e podem ter diferentes tabelas de ambiente.
Parâmetros comportam-se como variáveis locais que são inicializadas com os valores dos argumentos:
listapar ::= listadenomes [`,´ `...´] | `...´
Quando uma função é chamada,
a lista de argumentos é ajustada para
o tamanho da lista de parâmetros,
a não ser que a função seja de aridade variável ou vararg,
o que é
indicado por três pontos ('...') no final da 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
para a função através de uma expressão vararg,
a qual também é representada como três pontos.
O valor desta expressão é uma lista de todos os argumentos extras correntes,
similar a uma função com múltiplos valores de retorno.
Se uma expressão vararg é usada dentro de outra expressão
ou no meio de uma lista de expressões,
então a sua lista de valores 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 chamada seja delimitada por 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
Neste caso, nós temos o seguinte mapeamento de argumentos para parâmetros e para as 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 (ver §2.4.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.
A sintaxe de dois pontos
é usada para definir métodos,
isto é, funções que possuem um parâmetro extra implícito self.
Desta forma, o comando
function t.a.b.c:f (params) body end
é uma açúcar sintático para
t.a.b.c.f = function (self, params) body end
Lua é uma linguagem com escopo léxico. O escopo das variáveis começa no primeiro comando depois da sua declaração e vai até o fim do bloco mais interno que inclui a declaração. Considere o seguinte exemplo:
x = 10 -- variável global
do -- bloco novo
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 causa das regras de escopo léxico, variáveis locais podem ser livremente acessadas por funções definidas dentro do seu escopo. Uma variável local usada por uma função mais interna é chamada de upvalue ou 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 exemplo a seguir:
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 destes fechos usa uma variável y diferente,
enquanto todos eles compartilham a mesma variável x.
Dado que Lua é uma linguagem embarcada de extensão,
todas as ações de Lua começam a partir de código C no programa hospedeiro
que chama uma função da biblioteca de Lua (ver lua_pcall).
Sempre que um erro ocorre durante a compilação ou execução,
o controle retorna para C,
que pode tomar as medidas apropriadas
(tais como imprimir uma mensagem de erro).
O código Lua pode explicitamente gerar um erro através de uma chamada à
função error.
Se você precisa capturar erros em Lua,
você pode usar a função pcall.
Todo valor em Lua pode ter uma meta-tabela.
Esta meta-tabela é uma tabela Lua comum
que define o comportamento do valor original
com relação a certas operações especiais.
É possível mudar vários aspectos do comportamento
de operações sobre um valor especificando campos específicos na meta-tabela do valor.
Por exemplo, quando um valor não numérico é o operando de uma adição,
Lua verifica se existe uma função associada com o campo "__add" na meta-tabela do valor.
Se a função existe,
Lua chama esta função para realizar a adição.
Chamamos as chaves em uma meta-tabela de eventos
e os valores de meta-métodos.
No exemplo anterior, o evento é "add"
e o meta-método é a função que realiza a adição.
É possível obter a meta-tabela de qualquer valor
usando a função getmetatable.
Você pode mudar a meta-tabela de tabelas
através da função setmetatable.
Você não pode mudar a meta-tabela de outros tipos de Lua
(a menos que você use a biblioteca de depuração);
você deve obrigatoriamente usar a API C para fazer isto.
Tabelas e objetos do tipo userdata completos possuem meta-tabelas individuais (embora múltiplas tabelas e objetos userdata possam compartilhar suas meta-tabelas); valores de todos os outros tipos compartilham um única meta-tabela por tipo. Sendo assim, há somente uma meta-tabela para todos os números, uma para todas as cadeias de caracteres, etc.
Uma meta-tabela pode controlar como um objeto se comporta em operações aritméticas, comparações com relação à ordem, concatenação, operação de tamanho e indexação. Uma meta-tabela também pode definir uma função a ser chamada quando um objeto userdata é coletado pelo coletor de lixo. Para cada uma destas operações Lua associa uma chave específica chamada um evento. Quando Lua realiza uma destas operações sobre um valor, Lua verifica se este valor possui uma meta-tabela com o evento correspondente. Se este é o caso, o valor associado àquela chave (o meta-método) controla como Lua irá realizar a operação.
Meta-tabelas controlam as operações listadas a seguir.
Cada operação é identificada por seu nome correspondente.
A chave para cada operação é uma cadeia de caracteres começando com o nome
da operação sendo precedido por dois sublinhados, '__';
por exemplo, a chave para a operação "add" é a
cadeia "__add".
A semântica destas operações é melhor explicada por meio de uma função Lua
que descreve como o interpretador executa a operação.
O código mostrado aqui é meramente ilustrativo;
o comportamento real está codificado no interpretador
e é muito mais eficiente do que esta simulação.
Todas as funções usadas nestes descrições
(rawget, tonumber, etc.)
são descritas em §5.1.
Em particular, para recuperar o meta-método de um dado objeto,
usamos a expressão
metatable(obj)[event]
Isto deve ser lido como
rawget(getmetatable(obj) or {}, event)
Isto é, o acesso a um meta-método não invoca outros meta-métodos e o acesso a objetos que não possuem meta-tabelas não falha (ele simplesmente resulta em nil).
+.
A função getbinhandler abaixo define como Lua escolhe um tratador
para uma operação binária.
Primeiro, Lua tenta o primeiro operando.
Se o seu tipo não definie um tratador para a operação,
então Lua tenta o segundo operando.
function getbinhandler (op1, op2, event)
return metatable(op1)[event] or metatable(op2)[event]
end
Usando esta função,
o comportamento da expressão 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 nao é 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",
tendo a operação
o1 - floor(o1/o2)*o2 como 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 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 de cadeias primitiva
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) -- tamanho de string primitiva
elseif type(op) == "table" then
return #op -- tamanho de tabela primitiva
else
local h = metatable(op).__len
if h then
-- chama o tratador com o operando
return h(op)
else -- nenhum tratador disponível: comportamento padrão
error(···)
end
end
end
Veja §2.5.5 para uma descrição do tamanho de um tabela.
==.
A função getcomphandler define como Lua escolhe um meta-método
para operadores de comparação.
Um meta-método somente é selecionado quando os dois objetos
que estão sendo comparados possuem o mesmo tipo
e o mesmo meta-método para a operação selecionada.
function getcomphandler (op1, op2, event)
if type(op1) ~= type(op2) then return nil end
local mm1 = metatable(op1)[event]
local mm2 = metatable(op2)[event]
if mm1 == mm2 then return mm1 else return nil end
end
O evento "eq" é definido da seguinte forma:
function eq_event (op1, op2)
if type(op1) ~= type(op2) then -- tipos diferentes?
return false -- objetos diferentes
end
if op1 == op2 then -- igual primitivo?
return true -- objetos são iguais
end
-- tenta meta-método
local h = getcomphandler(op1, op2, "__eq")
if h then
return h(op1, op2)
else
return false
end
end
a ~= b é equivalente a not (a == b).
<.
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 = getcomphandler(op1, op2, "__lt")
if h then
return h(op1, op2)
else
error(···);
end
end
end
a > b é equivalente a b < a.
<=.
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 = getcomphandler(op1, op2, "__le")
if h then
return h(op1, op2)
else
h = getcomphandler(op1, op2, "__lt")
if h then
return not h(op2, op1)
else
error(···);
end
end
end
end
a >= b é equivalente a b <= a.
Note que, na ausência de um meta-método "le",
Lua tenta o "lt", assumindo que a <= b é
equivalente a not (b < a).
table[key].
function gettable_event (table, key)
local h
if type(table) == "table" then
local v = rawget(table, key)
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.
function settable_event (table, key, value)
local h
if type(table) == "table" then
local v = rawget(table, key)
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
return h(table, key, value) -- chama o tratador
else h[key] = value -- ou repete a operação sobre
end
end
function function_event (func, ...)
if type(func) == "function" then
return func(...) -- call primitiva
else
local h = metatable(func).__call
if h then
return h(func, ...)
else
error(···)
end
end
end
Além de meta-tabelas, objetos do tipo thread, function e userdata possuem outra tabela associada com eles, chamada de seu ambiente. Assim como meta-tabelas, ambientes são tabelas normais e vários objetos podem compartilhar o mesmo ambiente.
Ambientes associados com objetos do tipo userdata não possuem significado para Lua. É apenas uma conveniência para programadores associarem uma tabela a um objeto userdata.
Ambientes associados com fluxos de execução (threads) são chamados de
ambientes globais.
Eles são usados como o ambiente padrão pelos seus fluxos de execução e
funções não aninhadas criadas pelo fluxo de execução
(através de loadfile, loadstring ou load)
e podem ser diretamente acessados pelo código C (ver §3.3).
Ambientes associados com funções C podem ser diretamente acessados pelo código C (ver §3.3). Eles são usados como o ambiente padrão para outras funções C criadas pela função.
Ambientes associados com funções Lua são usados para resolver todos os acessos a variáveis globais dentro da função (ver §2.3). Eles são usados como o ambiente padrão para outras funções Lua criadas pela função.
É possível mudar o ambiente de uma função Lua ou do
fluxo de execução que está sendo executado atualmente chamando setfenv.
É possível obter o ambiente de uma função Lua ou do fluxo de execução sendo
executado atualmente chamando getfenv.
Para tratar o ambiente de outros objetos
(userdata, funções C, outros fluxos de execução) você deve obrigatoriamente
usar a API C.
Lua realiza gerenciamento automático da memória. Isto significa que você não precisa se preocupar com a alocação de memória para novos objetos nem com a liberação de memória quando os objetos não são mais necessários. Lua gerencia a memória automaticamente executando um coletor de lixo de tempos em tempos para coletar todos os objetos mortos (ou seja, aqueles objetos que não são mais acessíveis a partir de Lua). Todos os objetos em Lua estão sujeitos ao gerenciamento automático de memória: tabelas, userdata, funções, fluxos de execução e cadeias de caracteres.
Lua implementa um coletor de lixo marca-e-limpa (mark-and-sweep) incremental. O coletor usa dois números para controlar o seu ciclo de coleta de lixo: a pausa do coletor de lixo e o multiplicador de passo do coletor de lixo.
A pausa do coletor de lixo controla quanto tempo o coletor espera antes de iniciar um novo ciclo. Valores maiores fazem o coletor ser menos agressivo. Valores menores do que 1 significam que o coletor não irá esperar para iniciar um novo ciclo. Um valor de 2 significa que o coletor irá esperar até que a memória total em uso dobre antes de iniciar um novo ciclo.
O multiplicador de passo 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 1 fazem com que o coletor seja muito lento e pode ocorrer que o coletor nunca termine um ciclo. O valor padrão, 2, significa que o coletor é executado a uma velocidade que é "duas vezes" a velocidade de alocação de memória.
É possível mudar estes números através de chamadas às funções lua_gc em C
ou collectgarbage em Lua.
Ambas recebem valores em pontos percentuais como argumentos
(de modo que um argumento cujo valor é 100 significa um valor real de 1).
Com estas funções você também pode controlar
o coletor diretamente (e.g., pará-lo e reiniciá-lo).
Usando a API C, você pode configurar os meta-métodos do coletor de lixo para objetos userdata (ver §2.8). Estes meta-métodos também são chamados de finalizadores. Finalizadores permitem que você coordene a coleta de lixo de Lua com o gerenciamento de recursos externos (tais como o fechamento de arquivos, conexões de rede ou de bancos de dados ou a liberação de sua própria memória).
Objetos userdata com um campo __gc em suas meta-tabelas não são
recolhidos imediatamente pelo coletor de lixo.
Ao invés disso, Lua os coloca naquela lista.
Depois que a coleta é realizada,
Lua faz o equivalente da seguinte função
para cada objeto userdata em uma lista:
function gc_event (userdata)
local h = metatable(userdata).__gc
if h then
h(userdata)
end
end
Ao final do ciclo de coleta de lixo, os finalizadores para os objetos userdata são chamados na ordem reversa ao de sua criação, entre aqueles coletados naquele ciclo. Isto é, o primeiro finalizador a ser chamado é aquele associado com o objeto userdata que foi criado por último no programa. O userdata só é efetivamente liberado no próximo ciclo de coleta de lixo.
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 irá coletar este 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 qualquer caso, se a chave é coletada ou o valor é coletado,
o par inteiro é removido da tabela.
A fragilidade de uma tabela é controlada pelo
campo __mode de sua meta-tabela.
Se o campo __mode é uma cadeia de caracteres contendo o caractere 'k',
as chaves da tabela são fracas.
Se __mode contém 'v',
os valores na tabela são fracos.
Depois de usar uma tabela como uma meta-tabela,
não se deve mudar o valor de seu campo __mode.
Caso contrário, o comportamento fraco das tabelas controladas por esta
meta-tabela é indefinido.
Lua oferece suporte a co-rotinas, também conhecidas como fluxos de execução (threads) 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, uma co-rotina somente suspende sua execução através de uma chamada explícita a uma função de cessão.
É possível criar uma co-rotina com uma chamada à coroutine.create.
O 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 execução da co-rotina.
Quando a função coroutine.resume é chamada pela primeira vez,
recebendo como seu primeiro argumento
o objeto do tipo thread retornado por coroutine.create,
a co-rotina inicia a sua execução,
na primeira linha de sua função principal.
Depois que a co-rotina começa a ser executada,
ela continua executando até terminar ou ceder.
Uma função pode terminar sua execução de duas maneiras:
normalmente, quando sua função principal retorna
(explicitamente ou implicitamente, depois da última instrução);
e de maneira anormal, se ocorre um erro não protegido
No primeiro caso, coroutine.resume retorna true
mais quaisquer valores retornados pela função principal da co-rotina.
No caso de acontecerem erros, coroutine.resume retorna false
mais uma mensagem de erro.
Uma co-rotina cede a execução através de uma chamada à função coroutine.yield.
Quando uma co-rotina cede,
a coroutine.resume correspondente retorna imediatamente,
mesmo se a cessão aconteceu dentro de uma chamada de função aninhada
(isto é, não ocorreu dentro da função principal,
mas em uma função chamada direta ou indiretamente pela função principal).
No caso de uma cessão, coroutine.resume também retorna true,
mais quaisquer valores passados para coroutine.yield.
Na próxima vez que você recomeça a execução da mesma co-rotina,
ela continua sua execução do ponto onde ela cedeu,
com a chamada para 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, retoma a execução da co-rotina.
Quaisquer argumentos passados para esta 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).
Diferentemente de coroutine.resume,
coroutine.wrap não captura erros;
qualquer erro é propagado para o chamador.
Como um exemplo, considere o seguinde 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ê executá-lo, ele produzirá 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
Esta seção descreve a API C para Lua, ou seja,
o conjunto de funções C disponíveis para o programa hospedeiro se comunicar
com Lua.
Todas as funções da API, bem como os tipos e constantes relacionados,
estão declarados no arquivo de cabeçalho lua.h.
Mesmo quando usamos o termo "função", qualquer operação na API pode, de forma alternativa, ser provida como uma macro. Tais macros usam cada um dos seus argumentos exatamente uma vez (com exceção do primeiro argumento, que é sempre um estado Lua) e portanto 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 dos seus argumentos.
Contudo, é possível mudar este comportamento compilando Lua
com uma definição apropriada para a macro luai_apicheck,
no arquivo luaconf.h.
Lua usa uma pilha virtual para passar e receber valores de C. Cada elemento nesta pilha representa um valor Lua (nil, um número, uma cadeia de caracteres, 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 estejam ativas.
Esta pilha contém inicialmente quaisquer argumentos para a função C
e é onde a função C empilha os seus resultados
para serem retornados ao chamador (ver lua_CFunction).
Por conveniência,
a maioria das operações de consulta na API não segue uma disciplina estrita de pilha.
Ao invés disso, elas podem se referir a qualquer elemento na pilha
usando um índice:
Um índice positivo representa uma posição absoluta na pilha
(começando em 1);
um índice negativo representa uma posição relativa ao topo da pilha.
De maneira mais específica, se a pilha possui n elementos,
então o índice 1 representa o primeiro elemento
(isto é, o elemento que foi empilhado na pilha 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.
Dizemos que um índice é válido
se ele está entre 1 e o topo da pilha
(isto é, se 1 ≤ abs(índice) ≤ topo).
Quando você interage com a API de Lua,
você é responsável por assegurar consistência.
Em particular,
você é responsável por controlar estouro da pilha.
Você pode usar a função lua_checkstack
para aumentar o tamanho da pilha.
Sempre que Lua chama C,
ela assegura que pelo menos LUA_MINSTACK posições na pilha estão disponíveis.
LUA_MINSTACK é definida como 20,
então geralmente você não precisa se preocupar com o espaço da pilha
a menos que o seu código possua laços empilhando elementos na pilha.
A maioria das funções de consulta aceita como índices qualquer valor dentro do
espaço da pilha disponível, isto é, índices até o tamanho máximo da pilha
que você configurou através da função lua_checkstack.
Tais índices são chamados índices aceitáveis.
Mais formalmente, definimos um índice aceitável
como a seguir:
(índice < 0 && abs(índice) <= topo) ||
(índice > 0 && índice <= espaçodapilha)
Note que 0 nunca é um índice aceitável.
A menos que seja dito o contrário, qualquer função que aceita índices válidos pode também ser chamada com pseudo-índices, que representam alguns valores Lua que são acessíveis para o código C mas que não estão na pilha. Pseudo-índices são usados para acessar o ambiente do fluxo de execução, o ambiente da função, o registro e os upvalues da função C (ver §3.4).
O ambiente do fluxo de execução (onde as variáveis globais existem) está
sempre no pseudo-índice LUA_GLOBALSINDEX.
O ambiente da função C rodando está sempre
no pseudo-índice LUA_ENVIRONINDEX.
Para acessar e mudar o valor de variáveis globais, você pode usar operações de tabelas usuais sobre uma tabela de ambiente. Por exemplo, para acessar o valor de uma variável global, faça
lua_getfield(L, LUA_GLOBALSINDEX, varname);
Quando uma função C é criada,
é possível associar alguns valores a ela,
criando então um fecho C;
estes valores são chamados de upvalues e são
acessíveis para a função sempre que ela é chamada
(ver lua_pushcclosure).
Sempre que uma função C é chamada,
seus upvalues são posicionados em pseudo-índices específicos.
Estes pseudo-índices são gerados 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 atual,
produz um índice aceitável (embora inválido).
Lua provê um registro,
uma tabela pré-definida que pode ser usada por qualquer código C para
armazenar qualquer valor Lua que o código C precise armazenar.
Esta tabela está sempre localizada no pseudo-índice
LUA_REGISTRYINDEX.
Qualquer biblioteca de C pode armazenar dados nesta tabela,
mas ela deve tomar cuidado para escolher chaves diferentes daquelas usadas
por outras bibliotecas, para evitar colisões.
Tipicamente, você deve usar como chave uma cadeia de caracteres contendo o nome da sua biblioteca
ou um objeto do tipo userdata leve com o endereço de um objeto C em seu código.
As chaves inteiras no registro são usadas pelo mecanismo de referência, implementado pela biblioteca auxiliar, e portanto não devem ser usadas para outros propósitos.
Internamente, Lua usa o mecanismo de longjmp de C para tratar erros.
(Você pode também utilizar exceções se você usar C++;
veja o arquivo luaconf.h.)
Quando Lua se depara com qualquer erro
(tais como erros de alocação de memória, erros de tipo, erros de sintaxe
e erros de tempo de execução)
ela dispara um erro;
isto é, ela faz um desvio longo.
Um ambiente protegido usa setjmp
para estabelecer um ponto de recuperação;
qualquer erro desvia o fluxo de execução para o ponto de recuperação ativado mais recentemente.
A maioria das funções na API pode disparar 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 disparar erros.
Dentro de uma função C você pode disparar um erro chamando lua_error.
Listamos aqui todas as funções e tipos da API C em ordem alfabética. Cada função tem um indicador como este: [-o, +p, x]
O primeiro campo, o,
representa quantos elementos a função desempilha da pilha.
O segundo campo, p,
indica quantos elementos a função empilha na pilha.
(Qualquer função sempre empilha seus resultados depois de desempilhar seus argumentos.)
Um campo na forma x|y significa que a função pode empilhar (ou desempilhar)
x ou y elementos,
dependendo da situação;
uma marca de interrogação '?' significa
que não podemos saber quantos elementos a função desempilha/empilha
olhando somente os seus argumentos
(e.g., o número de elementos pode depender do que está na pilha).
O terceiro campo, x,
diz se a funçao pode disparar erros:
'-' significa que a função nunca dispara qualquer erro;
'm' significa que a função pode disparar um erro
somente devido à falta de memória;
'e' significa que a função pode disparar outros tipos de erro;
'v' significa que a função pode disparar um erro de maneira proposital.
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 pelos estados Lua.
A função de alocação deve prover uma
funcionalidade similar à de 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;
e nsize, o novo tamanho do bloco.
ptr é NULL se e somente se osize é zero.
Quando nsize é zero, a função de alocação deve retornar NULL;
se osize é diferente de zero,
o bloco de memória apontado por ptr deve ser liberado.
Quando nsize não é zero, a função de alocação retorna NULL
se e somente se ela não pode alocar o tamanho do bloco requisitado.
Quando nsize não é zero e osize é zero,
a função de alocação deve comportar-se como malloc.
Quando nsize e osize não são zero,
a função de alocação comporta-se como realloc.
Lua assume que a função de alocação nunca falha quando
osize >= nsize.
Temos a seguir uma implementação simples para a função de alocação.
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);
}
Este código assume
que free(NULL) não possui nenhum efeito e que
realloc(NULL, size) é equivalente a malloc(size).
ANSI C garante esses dois comportamentos.
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 função de pânico antiga.
Se um erro ocorre fora de qualquer ambiente protegido,
Lua chama uma função de pânico
e então chama exit(EXIT_FAILURE),
terminando então a aplicação hospedeira.
A sua função de pânico pode evitar esta saída caso
ela nunca retorne (e.g., fazendo uma desvio longo).
A função de pânico pode acessar a mensagem de erro no topo da pilha.
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 da função são empilhados
em ordem direta;
isto é, o primeiro argumento é empilhado primeiro.
Por último 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 desempilhados da pilha
quando a função é chamada.
Os resultados da função são empilhados na pilha quando a função retorna.
O número de resultados é ajustado para nresults,
a menos que nresults seja LUA_MULTRET.
Neste caso, todos os resultados da função são empilhados.
Lua cuida para que os valores retornados caibam dentro do espaço da pilha.
Os resultados da função são empilhados na pilha em ordem direta
(o primeiro resultado é empilhado primeiro),
de modo que depois da 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á o mesmo código em C:
lua_getfield(L, LUA_GLOBALSINDEX, "f"); /* função a ser chamada */
lua_pushstring(L, "how"); /* primeiro argumento */
lua_getfield(L, LUA_GLOBALSINDEX, "t"); /* tabela a ser indexada */
lua_getfield(L, -1, "x"); /* empilha o resultado de t.x (2º arg) */
lua_remove(L, -2); /* remove 't' da pilha */
lua_pushinteger(L, 14); /* 3º argumento */
lua_call(L, 3, 1); /* chama 'f' com 3 argumentos e 1 resultado */
lua_setfield(L, LUA_GLOBALSINDEX, "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_CFunctiontypedef int (*lua_CFunction) (lua_State *L);
O tipo para funções C.
A fim de se comunicar apropriadamente com Lua,
uma função C deve usar o seguinte protocolo,
o qual 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).
Portanto, quando a função inicia,
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á devidamente
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 seguinte função 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);
Garante que existem pelo menos extra posições disponíveis na pilha.
A função retorna falso se ela não puder aumentar o tamanho da pilha para o tamanho desejado.
Esta função nunca comprime a pilha;
se a pilha já é maior do que o novo tamanho,
ela não terá o seu tamanho modificado.
lua_close[-0, +0, -]
void lua_close (lua_State *L);
Destrói todos os objetos no estado Lua fornecido (chamando os meta-métodos de coleta de lixo correspondentes, se houver) e libera toda a memória dinâmica usada por aquele estado. Em várias plataformas, pode não ser necessário chamar esta função, porque todos os recursos são naturalmente liberados quando o programa hospedeiro morre. Por outro lado, programas que ficam rodando por muito tempo, como um daemon ou um servidor web, podem precisar liberar estados tão logo eles não sejam mais necessários, para evitar um crescimento demasiado do uso da memória.
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 da pilha.
Se n é 1, o resultado é o único valor na pilha
(isto é, a função não faz nada);
se n é 0, o resultado é a cadeia de caracteres vazia.
A concatenação é realizada de acordo com a semântica usual de Lua
(ver §2.5.4).
lua_cpcall[-0, +(0|1), -]
int lua_cpcall (lua_State *L, lua_CFunction func, void *ud);
Chama a função C func em modo protegido.
func inicia somente com um único elemento na sua pilha,
o objeto userdata leve contendo ud.
Em caso de erros,
lua_cpcall retorna o mesmo código de erro de lua_pcall,
mais o objeto de erro no topo da pilha;
caso contrário, ela retorna zero e não muda a pilha.
Todos os valores retornados por func são descartados.
lua_createtable[-0, +1, m]
void lua_createtable (lua_State *L, int narr, int nrec);
Cria uma nova tabela vazia e a empilha no topo da pilha.
A nova tabela possui espaço pré-alocado
para narr elementos array e nrec elementos não-array.
Esta pré-alocação é útil quando você sabe exatamente quantos elementos
a tabela irá ter.
Caso contrário você pode usar a função lua_newtable.
lua_dump[-0, +0, m]
int lua_dump (lua_State *L, lua_Writer writer, void *data);
Descarrega uma função como um trecho de código binário.
Recebe um função Lua no topo da pilha
e produz um trecho de código binário que,
se carregado novamente,
resulta em uma função equivalente àquela que foi descarregada.
Para produzir partes do trecho de código,
lua_dump chama a função writer (ver lua_Writer)
com o argumento data fornecido
para escrevê-los.
O valor retornado é o código de erro retornado pela última
chamada à função writer;
0 significa que não ocorreram erros.
Esta função não desempilha a função Lua da pilha.
lua_equal[-0, +0, e]
int lua_equal (lua_State *L, int index1, int index2);
Retorna 1 se os dois valores nos índices aceitáveis index1 e
index2 são iguais,
seguindo a semântica do operador == de Lua
(ou seja, pode chamar meta-métodos).
Caso contrário retorna 0.
Também retorna 0 se qualquer um dos índices não é válido.
lua_error[-1, +0, v]
int lua_error (lua_State *L);
Gera um erro Lua.
A mensagem de erro (que pode ser de fato um valor Lua de qualquer tipo)
deve estar no topo da pilha.
Esta função faz um desvio longo
e portanto nunca retorna.
(ver 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:
pára o coletor de lixo.
LUA_GCRESTART:
reinicia o coletor de lixo.
LUA_GCCOLLECT:
realiza um ciclo completo de coleta de lixo.
LUA_GCCOUNT:
retorna a quantidade de memória (em Kbytes) que está sendo usada correntemente por Lua.
LUA_GCCOUNTB:
retorna o resto da divisão da quantidade de bytes de memória usada correntemente
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 maneira não especificada.
Se você quer controlar o tamanho do passo
você deve ajustar de maneira experimental o valor de data.
A função retorna 1 se o passo finalizou um
ciclo de coleta de lixo
LUA_GCSETPAUSE:
estabelece data/100 como o novo valor
para a pausa do coletor (ver §2.10).
A função retorna o valor anterior da pausa.
LUA_GCSETSTEPMUL:
estabelece data/100 como o novo valor para o multiplicador de passo
do coletor (ver §2.10).
A função retorna o valor anterior do multiplicador de passo.
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_getfenv[-0, +1, -]
void lua_getfenv (lua_State *L, int index);
Coloca na pilha a tabela de ambiente do valor no índice fornecido.
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 válido fornecido.
Como em Lua, esta função pode disparar um meta-método
para o evento "index" (ver §2.8).
lua_getglobal[-0, +1, e]
void lua_getglobal (lua_State *L, const char *name);
Coloca na pilha o valor da global name.
Esta função é definida como uma macro:
#define lua_getglobal(L,s) lua_getfield(L, LUA_GLOBALSINDEX, s)
lua_getmetatable[-0, +(0|1), -]
int lua_getmetatable (lua_State *L, int index);
Coloca na pilha a meta-tabela do valor no índice aceitável fornecido. Se o índice não é válido ou se o valor não possui uma meta-tabela, 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 válido fornecido
e k é o valor no topo da pilha.
Esta função desempilha a chave 'k'
(colocando o resultado no seu lugar).
Como em Lua, esta função pode disparar um meta-método
para o evento "index" (ver §2.8).
lua_gettop[-0, +0, -]
int lua_gettop (lua_State *L);
Retorna o índice do elemento no topo da pilha. Visto que os índices começam em 1, este resultado é igual ao número de elementos na pilha (e portanto 0 significa uma pilha vazia).
lua_insert[-1, +1, -]
void lua_insert (lua_State *L, int index);
Move o elemento no topo para o índice válido fornecido, deslocando os elementos acima deste índice para abrir espaço. Esta função não pode ser chamada com um pseudo-índice, porque um pseudo-índice não é uma posição real da pilha.
lua_Integertypedef ptrdiff_t lua_Integer;
O tipo usado pela API Lua para representar valores inteiros.
O tipo padrão é 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 aceitável fornecido possui tipo 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 aceitável 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 aceitável 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 aceitável fornecido é um objeto 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 aceitável fornecido é nil e 0 caso contrário.
lua_isnone[-0, +0, -]
int lua_isnone (lua_State *L, int index);
Retorna 1 se o índice aceitável fornecido não é válido (isto é, se ele se refere a um elemento fora do espaço da pilha corrente) e 0 caso contrário.
lua_isnoneornil[-0, +0, -]
int lua_isnoneornil (lua_State *L, int index);
Retorna 1 se o índice aceitável fornecido não é válido (isto é, se ele se refere a um elemento fora do espaço da pilha corrente) ou se o valor neste í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 aceitável fornecido é um número ou uma cadeia de caracteres que pode ser convertida para um número e 0 caso contrário.
lua_isstring[-0, +0, m]
int lua_isstring (lua_State *L, int index);
Retorna 1 se o valor no índice aceitável fornecido é uma cadeia de caracteres 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 aceitável 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 aceitável fornecido é do tipo thread e 0 caso contrário.
lua_isuserdata[-0, +0, -]
int lua_isuserdata (lua_State *L, int index);
Retorna 1 se o valor no índice aceitável fornecido é um objeto userdata (completo ou leve) e 0 caso contrário.
lua_lessthan[-0, +0, e]
int lua_lessthan (lua_State *L, int index1, int index2);
Retorna 1 se o valor no índice aceitável index1 é menor
do que o valor no índice aceitável index2,
seguindo a semântica do operador < de Lua
(ou seja, pode chamar meta-métodos).
Caso contrário retorna 0.
Também retorna 0 se qualquer um dos índices não for válido.
lua_load[-0, +1, -]
int lua_load (lua_State *L,
lua_Reader reader,
void *data,
const char *chunkname);
Carrega um trecho de código Lua.
Se não ocorrer nenhum erro,
lua_load empilha o trecho compilado como uma
função Lua no topo da pilha.
Caso contrário, empilha uma mensagem de erro.
Os valores de retorno de lua_load são:
LUA_ERRSYNTAX:
erro de sintaxe durante a pré-compilação;LUA_ERRMEM:
erro de alocação de memória.Esta função somente carrega um trecho; ela não o executa.
lua_load automaticamente detecta se o trecho está na forma de texto ou na forma binária
e o carrega de maneira correta (veja o programa luac).
A função lua_load usa uma função reader fornecida pelo usuário
para ler o trecho de código (ver lua_Reader).
O argumento data é um valor opaco passado para a função de leitura.
O argumento chunkname dá um nome ao trecho,
o qual é usado para mensagens de erro e em informações de depuração (ver §3.8).
lua_newstate[-0, +0, -]
lua_State *lua_newstate (lua_Alloc f, void *ud);
Cria um estado novo independente.
Retorna NULL se não puder criar o estado
(devido à falta de memória).
O argumento f é a função de alocação;
Lua faz toda a alocação de memória para este estado através desta função.
O segundo argumento, ud, é um ponteiro opaco que Lua
simplesmente passa para a função de alocação a cada chamada.
lua_newtable[-0, +1, m]
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, m]
lua_State *lua_newthread (lua_State *L);
Cria um novo objeto do tipo thread, coloca-o na pilha
e retorna um ponteiro para um lua_State que representa este novo fluxo de execução.
O novo fluxo de execução retornado por esta função compartilha todos os objetos globais
(tais como tabelas) com o estado original,
mas possui uma pilha de execução independente.
Não há uma função explícita para terminar ou destruir um fluxo de execução. Objetos do tipo thread estão sujeitos à coleta de lixo, assim como qualquer outro objeto de Lua.
lua_newuserdata[-0, +1, m]
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 objeto userdata completo com o endereço do bloco e retorna este endereço.
Objetos userdata representam valores C em Lua. Um userdata completo representa um bloco de memória. Ele é um objeto (assim como uma tabela): você deve criá-lo, ele pode ter sua própria meta-tabela e você pode detectar quando ele está sendo coletado. Um objeto userdata completo somente é igual a ele mesmo (usando a igualdade primitiva, sem o uso de meta-métodos).
Quando Lua coleta um userdata completo com um meta-método gc,
Lua chama o meta-método e marca o userdata como finalizado.
Quando este userdata é coletado novamente então
Lua libera sua memória correspondente.
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 depois da chave fornecida).
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'; guarda 'key' para a próxima iteração */
lua_pop(L, 1);
}
Durante o percorrimento de uma tabela,
não chame lua_tolstring diretamente sobre uma chave,
a menos que você saiba que a chave é realmente uma cadeia de carecteres.
Lembre-se que lua_tolstring altera
o valor no índice fornecido;
isto confunde a próxima chamada para lua_next.
lua_Numbertypedef double lua_Number;
O tipo de números em Lua.
Por padrão, ele é double, mas pode ser mudado em luaconf.h.
Através do arquivo de configuração é possível mudar Lua para operar com outro tipo para números (e.g., float ou long).
lua_objlen[-0, +0, -]
size_t lua_objlen (lua_State *L, int index);
Retorna o "tamanho" do valor no índice aceitável fornecido:
para cadeias de caracteres, isto é o tamanho da cadeia;
para tabelas, isto é o resultado do operador de tamanho ('#');
para objetos do tipo userdata, isto é o tamanho do bloco de memória alocado
para o userdata;
para outros valores, o tamanho é 0.
lua_pcall[-(nargs + 1), +(nresults|1), -]
int lua_pcall (lua_State *L, int nargs, int nresults, int errfunc);
Chama uma função em modo protegido.
Tanto nargs quanto nresults possuem o mesmo significado
que possuíam 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 errfunc é 0,
então a mensagem de erro retornada na pilha
é exatamente a mensagem de erro original.
Caso contrário, errfunc é o índice na pilha de um
função de tratamento de erros.
(Na implementação atual, este índice não pode ser um pseudo-índice.)
No caso de erros de tempo de execução,
esta função será chamada com a mensagem de erro
e seu valor de retorno será a mensagem retornada na pilha por lua_pcall.
Tipicamente, a função de tratamento de erros é usada para adicionar mais informação
de depuração à mensagem de erro, como um traço da pilha.
Tal informação não pode ser obtida após o retorno de lua_pcall,
pois neste ponto a pilha já foi desfeita.
A função lua_pcall retorna 0 em caso de sucesso
ou um dos seguintes códigos de erro
(definidos em lua.h):
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 a função de tratamento de erros.
LUA_ERRERR:
erro quando estava executando a função de tratamento de erros.
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, m]
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 então um fecho C (ver §3.4);
estes valores são então acessíveis para a função sempre que ela é chamada.
Para associar valores com uma função C,
primeiro estes valores devem ser colocados na pilha
(quando há múltiplos valores, o primeiro valor é empilhado primeiro).
Então lua_pushcclosure
é chamada para criar e colocar a função C na pilha,
com o argumento n informando quantos valores devem ser
associados com a função.
lua_pushcclosure também desempilha estes valores da pilha.
lua_pushcfunction[-0, +1, m]
void lua_pushcfunction (lua_State *L, lua_CFunction f);
Empilha 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 para ser registrada em Lua deve
seguir o protocolo correto para receber seus parâmetros
e retornar seus resultados (ver lua_CFunction).
lua_pushcfunction é definida como uma macro:
#define lua_pushcfunction(L,f) lua_p