manual lua

7/28/2019 Manual Lua

1/119

Manual de Referncia de Lua5.1por Roberto Ierusalimschy, Luiz Henrique de Figueiredo, Waldemar Celes

(Traduzido por Srgio Queiroz de Medeiros com apoio da Fbrica Digital eda FINEP)

Copyright 2007-2008 Lua.org, PUC-Rio. Disponvel livremente nos termos da licena de Lua.

contedo ndice english portugus espaol

1 - IntroduoLua uma linguagem de programao de extenso projetada para darsuporte programao procedimental em geral e que oferece facilidadespara a descrio de dados. A linguagem tambm oferece um bom suportepara programao orientada a objetos, programao funcional eprogramao orientada a dados. Lua foi planejada para ser utilizada porqualquer aplicao que necessite de uma linguagem de script leve epoderosa. Lua implementada como uma biblioteca, escrita em C limpo(isto , no subconjunto comum de ANSI C e C++).

Por ser uma linguagem de extenso, Lua no possui a noo de umprograma principal: ela somente funciona embarcada em um programacliente anfitrio, chamado de programa hospedeiro ou simplesmente dehospedeiro. Esse programa hospedeiro pode invocar funes para executarum pedao de cdigo Lua, pode escrever e ler variveis Lua e poderegistrar funes C para serem chamadas pelo cdigo Lua. Atravs do usode funes C, Lua pode ser estendida para lidar de maneira apropriadacom uma ampla variedade de domnios, permitindo assim a criao delinguagems de programao personalizadas que compartilham umarcabouo sinttico. A distribuio Lua inclui um exemplo de um programa

hospedeiro chamado lua, o qual usa a biblioteca de Lua para oferecer um

Manual de Referncia de Lua 5.1 http://www.lua.org/manual/5.1/pt/manual.html

1 of 119 07-08-2009 17:33


2/119

interpretador de linha de comando Lua completo.

Lua um software livre e, como de praxe, fornecido sem garantias,conforme dito na sua licena. A implementao descrita neste manualest disponvel no stio web oficial de Lua, www.lua.org.

Como qualquer outro manual de referncia, este documento rido emalgumas partes. Para uma discusso das decises por trs do projeto deLua, veja os artigos tcnicos disponveis no stio web oficial de Lua. Parauma introduo detalhada programao em Lua, veja o livro de RobertoIerusalimschy, Programming in Lua (Segunda Edio).

2 - A LinguagemEsta seo descreve os aspectos lxicos, sintticos e semnticos de Lua.Em outras palavras, esta seo descreve quais itens lxicos so vlidos,como eles so combinados, e qual o significado da sua combinao.

As construes da linguagem sero explicadas usando a notao BNFestendida usual, na qual {a} significa 0 ou mais a's e [a] significa um aopcional. No-terminais so mostrados como non-terminal, palavras-chaveso mostradas como kword e outros smbolos terminais so mostrados

como `=. A sintaxe completa de Lua pode ser encontrada em 8 no fimdeste manual.

2.1 - Convenes Lxicas

Em Lua, Nomes (tambm chamados de identificadores) podem ser qualquercadeia de letras, dgitos, e sublinhados que no comeam com um dgito.Esta definio est de acordo com a definio de nomes na maioria daslinguagens. (A definio de letras depende de qual o idioma (locale):

qualquer caractere considerado alfabtico pelo idioma corrente pode serusado como um identificador.) Identificadores so usados para nomearvariveis e campos de tabelas.

As seguintes palavras-chave so reservadas e no podem ser utilizadascomo nomes:

and break do else elseifend false for function ifin local nil not orrepeat return then true until while

Lua uma linguagem que diferencia minsculas de maisculas: and uma


2 of 119 07-08-2009 17:33


3/119

palavra reservada, mas And e AND so dois nomes vlidos diferentes. Comoconveno, nomes que comeam com um sublinhado seguido por letras

maisculas (tais como_VERSION

) so reservados para variveis globaisinternas usadas por Lua.

As seguintes cadeias denotam outros itens lxicos:

+ - * / % ^ #== ~= = < > =( ) { } [ ]; : , . .. ...

Cadeias de caracteres literais podem ser delimitadas atravs do uso deaspas simples ou aspas duplas, e podem conter as seguintes seqncias

de escape no estilo de C: '\a' (campainha), '\b' (backspace), '\f'(alimentao de formulrio), '\n' (quebra de linha), '\r' (retorno de carro),'\t' (tabulao horizontal), '\v' (tabulao vertical), '\\' (barra invertida), '\"'(citao [aspa dupla]) e '\'' (apstrofo [aspa simples]). Alm disso, umabarra invertida seguida por uma quebra de linha real resulta em umaquebra de linha na cadeia de caracteres. Um caractere em uma cadeia decaracteres tambm pode ser especificado pelo seu valor numrico usandoa seqncia de escape \ddd, onde ddd uma seqncia de at trs dgitosdecimais. (Note que se um caractere numrico representado como umseqncia de escape for seguido por um dgito, a seqncia de escapedeve possuir exatamente trs dgitos.) Cadeias de caracteres em Luapodem conter qualquer valor de 8 bits, incluindo zeros dentro delas, osquais podem ser especificados como '\0'.

Cadeias literais longas tambm podem ser definidas usando um formatolongo delimitado por colchetes longos. Definimos uma abertura de colchetelongo de nvel n como um abre colchete seguido por n sinais de igualseguido por outro abre colchete. Dessa forma, uma abertura de colchetelongo de nvel 0 escrita como [[, uma abertura de colchete longo denvel 1 escrita como [=[ e assim por diante. Um fechamento de colchete

longo definido de maneira similar; por exemplo, um fechamento decolchete longo de nvel 4 escrito como ]====]. Uma cadeia de caractereslonga comea com uma abertura de colchete longo de qualquer nvel etermina no primeiro fechamento de colchete longo do mesmo nvel. Literaisexpressos desta forma podem se estender por vrias linhas, nointerpretam nenhuma seqncia de escape e ignoram colchetes longos dequalquer outro nvel. Estes literais podem conter qualquer coisa, excetoum fechamento de colchete longo de nvel igual ao da abertura.

Por convenincia, quando uma abertura de colchete longo

imediatamente seguida por uma quebra de linha, a quebra de linha no


3 of 119 07-08-2009 17:33


4/119

includa na cadeia de caracteres. Como exemplo, em um sistema usandoASCII (no qual 'a' codificado como 97, quebra de linha codificado

como 10 e '1

' codificado como 49), as cinco cadeias literais abaixodenotam a mesma cadeia:

a = 'alo\n123"'a = "alo\n123\""a = '\97lo\10\04923"'a = [[alo123"]]a = [==[alo123"]==]

Uma constante numrica pode ser escrita com uma parte decimal opcionale com um expoente decimal opcional. Lua tambm aceita constanteshexadecimais inteiras, atravs do uso do prefixo 0x. Exemplos deconstantes numricas vlidas so:

3 3.0 3.1416 314.16e-2 0.31416E1 0xff 0x56

Um comentrio comea com um hfen duplo (--) em qualquer lugar, desdeque fora de uma cadeia de caracteres. Se o texto imediatamente depoisde -- no uma abertura de colchete longo, o comentrio um comentriocurto, o qual se estende at o fim da linha. Caso contrrio, ele um

comentrio longo, que se estende at o fechamento de colchete longocorrespondente. Comentrios longos so freqentemente usados paradesabilitar cdigo temporariamente.

2.2 - Valores e Tipos

Lua uma linguagem dinamicamente tipada. Isto significa que variveis nopossuem tipos; somente valores possuem tipos. No existe definio detipos na linguagem. Todos os valores carregam o seu prprio tipo.

Todos os valores em Lua so valores de primeira classe. Isto significa quetodos os valores podem ser armazenados em variveis, passados comoargumentos para outras funes e retornados como resultados.

Existem oito tipos bsicos em Lua: nil, boolean, number, string, function,userdata, thread e table. Nil o tipo do valor nil, cuja propriedade principal ser diferente de qualquer outro valor; ele geralmente representa aausncia de um valor til. Boolean o tipo dos valores false e true. Tantonil como false tornam uma condio falsa; qualquer outro valor torna acondio verdadeira. Number representa nmeros reais (ponto flutuantede preciso dupla). ( fcil construir interpretadores Lua que usem outra


4 of 119 07-08-2009 17:33


5/119

representao interna para nmeros, tais como preciso simples de pontoflutuante ou inteiros longos; veja o arquivo luaconf.h.) O tipo string

representa cadeias de caracteres. Em Lua, cadeias de caracteres podemconter qualquer caractere de 8 bits, incluindo zeros ('\0') dentro dela (ver2.1).

Lua pode chamar (e manipular) funes escritas em Lua e funes escritasem C (ver 2.5.8).

O tipo userdata permite que dados C arbitrrios possam ser armazenadosem variveis Lua. Este tipo corresponde a um bloco de memria e no temoperaes pr-definidas em Lua, exceto atribuio e teste de identidade.Contudo, atravs do uso de metatables, o programador pode definir

operaes para valores userdata (ver 2.8). Valores userdata no podemser criados ou modificados em Lua, somente atravs da API C. Isto garantea integridade dos dados que pertencem ao programa hospedeiro.

O tipo thread representa fluxos de execuo independentes e usadopara implementar co-rotinas (ver 2.11). No confunda o tipo thread deLua com processos leves do sistema operacional. Lua d suporte aco-rotinas em todos os sistemas, at mesmo naqueles que no dosuporte a processos leves.

O tipo table implementa arrays associativos, isto , arrays que podem serindexados no apenas por nmeros, mas por qualquer valor (exceto nil).

Tabelas podem ser heterogneas; isto , elas podem conter valores detodos os tipos (exceto nil). Tabelas so o nico mecanismo deestruturao de dados em Lua; elas podem ser usadas para representararrays comuns, tabelas de smbolos, conjuntos, registros, grafos, rvores,etc. Para representar registros, Lua usa o nome do campo como umndice. A linguagem d suporte a esta representao oferecendo a.namecomo um acar sinttico para a["name"]. Existem vrias maneirasconvenientes de se criar tabelas em Lua (ver 2.5.7).

Da mesma forma que os ndices, o valor de um campo da tabela podepossuir qualquer tipo (exceto nil). Em particular, dado que funes sovalores de primeira classe, campos de tabela podem conter funes.Portanto, tabelas podem tambm possuir metdos (ver 2.5.9).

Valores do tipo table, function, thread e userdata (completo) so objetos:variveis no contm realmente estes valores, somente referncias paraeles. Atribuio, passagem de parmetro, e retorno de funes semprelidam com referncias para tais valores; estas operaes no implicam em

qualquer espcie de cpia.


5 of 119 07-08-2009 17:33


6/119

A funo type retorna uma cadeia de caracteres descrevendo o tipo de umdado valor.

2.2.1 - Coero

Lua prov converso automtica entre valores do tipo string e do tiponumber em tempo de execuo. Qualquer operao aritmtica aplicada auma cadeia de caracteres tenta converter esta cadeia para um nmero,seguindo as regras de converso usuais. De forma anloga, sempre queum nmero usado onde uma cadeia de caracteres esperada, onmero convertido para uma cadeia, em um formato razovel. Para umcontrole completo sobre como nmeros so convertidos para cadeias, use

a funo format da biblioteca string (ver string.format).

2.3 - Variveis

Variveis so lugares usados para armazenar valores.

Existem trs tipos de variveis em Lua: variveis globais, variveis locais ecampos de tabelas.

Um nome simples pode denotar uma varivel global ou uma varivei local

(ou um parmetro formal de uma funo, que um caso particular devarivel local):

var ::= Nome

Nome denota identificadores, como definido em 2.1.

Assume-se que toda varivel uma varivel global a menos que ela sejaexplicitamente declarada como uma varivel local (ver 2.4.7). Variveislocais possuem escopo lxico: variveis locais podem ser livrementeacessadas por funes definidas dentro do seu escopo (ver 2.6).

Antes da varivel receber a sua primeira atribuio, o seu valor nil.

Colchetes so usados para indexar uma tabela:

var ::= expprefixo `[ exp `]

A semntica de acessos a variveis globais e a campos de tabelas podeser mudada atravs do uso de meta-tabelas. Um acesso a uma varivelindexada t[i] equivalente a uma chamada gettable_event(t,i). (Veja 2.8para uma descrio completa da funo gettable_event. Esta funo no

definida nem pode ser chamada em Lua. Ela usada aqui somente para


6 of 119 07-08-2009 17:33


7/119

fins didticos.)

A sintaxe var.Nome apenas um acar sinttico para var["Nome"]:

var ::= expprefixo `. Nome

Todas as variveis globais so mantidas como campos em tabelas Luacomuns, chamadas de tabelas de ambiente ou simplesmente de ambientes(ver 2.9). Cada funo tem sua prpria referncia para um ambiente, deforma que todas as variveis globais dentro de uma funo iro se referirpara esta tabela de ambiente. Quando uma funo criada, ela herda oambiente da funo que a criou. Para obter a tabela de ambiente de umafuno Lua, voc deve chamar getfenv. Para trocar a tabela de ambiente,

voc deve chamar setfenv. (A nica maneira de tratar o ambiente defunes C atravs da a biblioteca de depurao; (ver 5.9).)

Um acesso a uma varivel global x equivalente a _env.x, que por sua vez equivalente a

gettable_event(_env, "x")

onde _env o ambiente da funo corrente. (Veja 2.8 para uma descriocompleta da funo gettable_event. Esta funo no definida nem pode serchamada em Lua. De modo anlogo, a varivel _env no definida em Lua.

Elas foram usadas aqui somente para fins didticos.)

2.4 - Comandos

Lua oferece um conjunto quase convencional de comandos, similar aoconjunto de comandos disponveis em Pascal ou C. Este conjunto incluiatribuies, estruturas de controle, chamadas de funes e declaraesde variveis.

2.4.1 - TrechosA unidade de execuo de Lua denominada de trecho. Um trecho simplesmente uma seqncia de comandos, os quais so executadossequencialmente. Cada comando pode opcionalmente ser seguido por umponto-e-vrgula:

trecho ::= {comando [`;]}

No existem comandos vazios e portanto a construo ';;' no vlida.

Lua trata um trecho como o corpo de uma funo annima com um


7 of 119 07-08-2009 17:33


8/119

nmero varivel de argumentos (ver 2.5.9). Desta forma, trechos podemdefinir variveis locais, receber argumentos e retornar valores.

Um trecho pode ser armazenado em um arquivo ou em uma cadeia decaracteres dentro do programa hospedeiro. Para executar um trecho, Luaprimeiro pr-compila o trecho em instrues para uma mquina virtual edepois executa o cdigo compilado com um interpretador para a mquinavirtual.

Trechos tambm podem ser pr-compilados em uma forma binria; veja oprograma luac para mais detalhes. Programas na forma de cdigo fonte ena forma de um arquivo fonte j compilado so intercambiveis; Luaautomaticamente determina qual o tipo do arquivo e age em

conformidade com ele.

2.4.2 - Blocos

Um bloco uma lista de comandos; sintaticamente, um bloco a mesmacoisa que um trecho:

bloco ::= trecho

Um bloco pode ser explicitamente delimitado para produzir um nico

comando:comando ::= do bloco end

Blocos explcitos so teis para controlar o escopo de declaraes devariveis. Blocos explcitos so tambm usados s vezes para adicionar umcomando return ou breakno meio de outro bloco (ver 2.4.4).

2.4.3 - Atribuio

Lua permite atribuies mltiplas. Em virtude disto, a sintaxe paraatribuio define uma lista de variveis no lado esquerdo e uma lista deexpresses no lado direito. Os elementos em ambos os lados soseparados por vrgulas:

comando ::= listavar `= listaexplistavar ::= var {`, var}listaexp ::= exp {`, exp}

Expresses so discutidas em 2.5.

Antes da atribuio ser realizada, a lista de valores ajustada para o

comprimento da lista de variveis. Se h mais valores do que o necessrio,


8 of 119 07-08-2009 17:33


9/119

os valores em excesso so descartados. Se h menos valores do que onecessrio, a lista estendida com tantos nil's quantos sejam

necessrios. Se a lista de expresses termina com uma chamada defuno, ento todos os valores retornados por esta chamada entram nalista de valores, antes do ajuste ser realizado (exceto quando a chamada delimitada por parnteses; veja 2.5).

Um comando de atribuio primeiro avalia todas as suas expresses esomente depois que a atribuio realizada. Desta forma, o cdigo

i = 3i, 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 e

x, y, z = y, z, x

permuta de maneira cclica os valores de x, y e z.

A semntica de atribuies para variveis globais e campos de tabelaspode ser mudada atravs do uso de meta-tabelas. Uma atribuio parauma varivel indexada t[i] = val equivalente a settable_event(t,i,val). (Veja2.8 para uma descrio completa da funo settable_event. Esta funo no definida nem pode ser chamada em Lua. Ela foi usada aqui somentepara fins didticos.)

Uma atribuio a uma varivel global x = val equivalente atribuio _env.x= val, que por sua vez equivalente a

settable_event(_env, "x", val)

onde _env o ambiente da funo sendo executada. (A varivel _env no definida em Lua. Ela foi usada aqui somente para fins didticos.)

2.4.4 - Estruturas de Controle

As estruturas de controle if, while e repeat possuem o significado usuale a sintaxe familiar:

comando ::= while exp do bloco endcomando ::= repeat bloco until exp

comando ::= if exp then bloco {elseif exp then bloco} [else bloco] end


9 of 119 07-08-2009 17:33


10/119

Lua tambm possui um comando for, o qual possui duas variaes (ver2.4.5).

A expresso da condio de uma estrutura de controle pode retornarqualquer valor. Tanto false como nil so considerados um valor falso.

Todos os valores diferentes de nil e false so considerados comoverdadeiros (em particular, o nmero 0 e a cadeia de caracteres vaziatambm so considerados valores verdadeiros).

No lao repeatuntil, o bloco mais interno no termina na palavra-chaveuntil, mas somente depois da condio. Desta forma, a condio podereferenciar variveis locais declaradas dentro do bloco do lao.

O comando return usado para retornar valores de uma funo ou de umtrecho (que nada mais do que uma funo). Funes e trechos podemretornar mais de um valor, de modo que a sintaxe para o comando return

comando ::= return [listaexp]

O comando break usado para terminar a execuo de um lao while,repeat ou for, pulando para o prximo comando depois do lao:

comando ::= break

Um breaktermina a execuo do lao mais interno.

Os comandos return e breaksomente podem ser escritos como o ltimocomando de um bloco. Se realmente necessrio ter um return oubreakno meio de um bloco, ento um bloco interno explcito pode serusado, como nas expresses idiomticas do return end e do break end, poisagora tanto o return como o breakso os ltimos comandos em seusrespectivos blocos (internos).

2.4.5 - Comando forO comando for possui duas variaes: uma numrica e outra genrica.

O lao for numrico repete um bloco de cdigo enquanto uma varivel decontrole varia de acordo com uma progresso aritmtica. Ele possui aseguinte sintaxe:

comando ::= for nome `= exp `, exp [`, exp] do bloco end

O bloco repetido para nome comeando com o valor da primeira exp, at

que ele passe o valor da segunda exp atravs de seguidos passos, sendo


10 of 119 07-08-2009 17:33


11/119

que a cada passo o valor da terceira exp somado a nome. De forma maisprecisa, um comando for como

for v = e1, e2, e3 do bloco end

equivalente ao cdigo:

dolocal var, limite, passo = tonumber(e1), tonumber(e2), tonumber(e3)if not (var and limite and passo) then error() endwhile (passo > 0 and var


12/119

local var_1, , var_n = f(s, var) var = var_1

if var == nil then break end

blockendend

Note o seguinte:

explist avaliada somente uma vez. Os seus resultados so umafuno iteradora, um estado e um valor inicial para a primeira variveliteradora.f, s e var so variveis invisveis. Os nomes foram utilizados aquisomente para fins didticos.

possvel usar breakpara sair de um lao for.As variveis de lao var_i so locais ao lao; no possvel usar osvalores delas aps o trmino do for. Se voc precisa destes valores,voc deve atribu-los a outras variveis antes de interromper o lao ousair do mesmo.

2.4.6 - Chamadas de Funo como Comandos

Para permitir possveis efeitos colaterais, funes podem ser executadascomo comandos:

comando ::= chamadadefuncao

Neste caso, todos os valores retornados pela funo so descartados.Chamadas de funo so explicadas em 2.5.8.

2.4.7 - Declaraes Locais

Variveis locais podem ser declaradas em qualquer lugar dentro de umbloco. A declarao pode incluir uma atribuio inicial:

comando ::= local listadenomes [`= listaexp]

Caso ocorra uma atribuio inicial, a sua semntica a mesma de umaatribuio mltipla (ver 2.4.3). Caso contrrio, todas as variveis soinicializadas com nil.

Um trecho tambm um bloco (ver 2.4.1) e portanto variveis locaispodem ser declaradas em um trecho fora de qualquer bloco explcito. Oescopo de uma varivel declarada desta forma se estende at o fim dotrecho.

As regras de visibilidade para variveis locais so explicadas em 2.6.


12 of 119 07-08-2009 17:33


13/119

2.5 - Expresses

As expresses bsicas em Lua so as seguintes:exp ::= expprefixoexp ::= nil | false | trueexp ::= Numeroexp ::= Cadeiaexp ::= funcaoexp ::= construtortabelaexp ::= `...exp ::= exp opbin expexp ::= opunaria expexpprefixo ::= var | chamadadefuncao | `( exp `)

Nmeros e cadeias literais so explicados em 2.1; variveis soexplicadas em 2.3; definies de funes so explicadas em 2.5.9;chamadas de funes so explicadas em 2.5.8; construtores de tabelasso explicados em 2.5.7. Expresses vararg, denotadas por trs pontos('...'), somente podem ser usadas quando esto imediatamente dentro deuma funo que possui um nmero varivel de argumentos; elas soexplicadas em 2.5.9.

Operadores binrios compreendem operadores aritmticos (ver 2.5.1),

operadores relacionais (ver 2.5.2), operadores lgicos (ver 2.5.3) e ooperador de concatenao (ver 2.5.4). Operadores unrios compreendemo menos unrio (ver 2.5.1), o not unrio (ver 2.5.3) e o operador detamanho unrio (ver 2.5.5).

Tanto chamadas de funes como expresses vararg podem resultar emmltiplos valores. Se uma expresso usada como um comando (o quesomente possvel para chamadas de funes (ver 2.4.6)), ento a sualista de retorno ajustada para zero elementos, descartando portantotodos os valores retornados. Se uma expresso usada como o ltimo (ouo nico) elemento de uma lista de expresses, ento nenhum ajuste feito (a menos que a chamada seja delimitada por parnteses). Em todosos demais contextos, Lua ajusta a lista de resultados para um elemento,descartando todos os valores exceto o primeiro.

Aqui esto alguns exemplos:

f() -- ajusta para 0 resultadosg(f(), x) -- f() ajustado para 1 resultadog(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 parmetro da lista vararg,

-- b recebe o segundo (tanto a como b podem receber nil caso no-- exista um parmetro correspondente na lista)


13 of 119 07-08-2009 17:33


14/119

a,b,c = x, f() -- f() ajustado para 2 resultadosa,b,c = f() -- f() ajustado para 3 resultados

return f() -- retorna todos os resultados de f()return ... -- retorna todos os resultados recebidos da lista varargreturn x,y,f() -- retorna x, y e todos os resultados de f(){f()} -- cria uma lista com todos os resultados de f(){...} -- cria uma lista com todos os parmetros da lista vararg{f(), nil} -- f() ajustado para 1 resultado

Qualquer expresso delimitada por parnteses sempre resulta em umnico valor. Dessa forma, (f(x,y,z)) sempre um nico valor, mesmo que fretorne mltiplos valores. (O valor de (f(x,y,z)) o primeiro valor retornadopor f, ou nil se f no retorna nenhum valor.)

2.5.1 - Operadores Aritmticos

Lua prov os operadores aritmticos usuais: os operadores binrios +(adio), - (subtrao), * (multiplicao), / (diviso), % (mdulo) e ^(exponenciao); e o operador unrio - (negao). Se os operandos sonmeros ou cadeias de caracteres que podem ser convertidas paranmeros (ver 2.2.1), ento todas as operaes possuem o seusignificado usual. A exponenciao funciona para qualquer expoente. Porexemplo, x^(-0.5) calcula o inverso da raiz quadrada de x. Mdulo definido

comoa % b == a - math.floor(a/b)*b

Ou seja, o resto de uma diviso arredondada em direo a menosinfinito.

2.5.2 - Operadores Relacionais

Os operadores relacionais em Lua so

== ~= < > =

Estes operadores sempre possuem como resultado false ou true.

A igualdade (==) primeiro compara o tipo de seus operandos. Se os tiposso diferentes, ento o resultado false. Caso contrrio, os valores dosoperandos so comparados. Nmeros e cadeias de caracteres socomparados de maneira usual. Objetos (valores do tipo table, userdata,thread e function) so comparados por referncia: dois objetos soconsiderados iguais somente se eles so o mesmo objeto. Toda vez que

um novo objeto criado (um valor com tipo table, userdata, thread oufunction) este novo objeto diferente de qualquer outro objeto que existia


14 of 119 07-08-2009 17:33


15/119

anteriormente.

possvel mudar a maneira como Lua compara os tipos table e userdataatravs do uso do meta-mtodo "eq" (ver 2.8).

As regras de converso em 2.2.1 no se aplicam a comparaes deigualdade. Portanto, "0"==0 avaliado como false e t[0] e t["0"] denotamposies diferentes em uma tabela.

O operador ~= exatamente a negao da igualdade (==).

Os operadores de ordem trabalham da seguinte forma. Se ambos osargumentos so nmeros, ento eles so comparados como tais. Caso

contrrio, se ambos os argumentos so cadeias de caracteres, entoseus valores so comparados de acordo com a escolha de idioma atual.Caso contrrio, Lua tenta chamar o meta-mtodo "lt" ou o meta-mtodo"le" (ver 2.8). Uma comparao a > b traduzida para b < a, ao passo que a>= b traduzida para b 1010 or error() --> 10nil or "a" --> "a"nil and 10 --> nilfalse and error() --> falsefalse and nil --> falsefalse or nil --> nil10 and 20 --> 20

(Neste manual, --> indica o resultado da expresso precedente.)


15 of 119 07-08-2009 17:33


16/119

2.5.4 - Concatenao

O operador de concatenao de cadeias de caracteres em Lua denotado por dois pontos ('..'). Se ambos os operandos so cadeias decaracteres ou nmeros, ento eles so convertidos para cadeias decaracteres de acordo com as regras mencionadas em 2.2.1. Casocontrrio, o meta-mtodo "concat" chamado (ver 2.8).

2.5.5 - O Operador de Tamanho

O operador de tamanho denotado pelo operador unrio #. O tamanho deuma cadeia de caracteres o seu nmero 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 talque t[n] no nil e t[n+1] nil; alm disso, se t[1] nil, n pode ser zero.Para um array comum, com todos os valores diferentes de nil indo de 1at um dado n, o seu tamanho exatamente aquele n, o ndice do seultimo valor. Se o array possui "buracos" (isto , valores nil entre doisoutros valores diferentes de nil), ento #t pode ser qualquer um dosndices que imediatamente precedem um valor nil (isto , ele podeconsiderar qualquer valor nil como o fim do array).

2.5.6 - Precedncia

A precedncia de operadores em Lua segue a tabela abaixo, da menorprioridade para a maior:

orand< > = ~= ==..+ -* / %not # - (unary)^

Como de costume, voc pode usar parnteses para mudar asprecedncias de uma expresso. Os operadores de concatenao ('...') ede exponenciao (' ') so associativos a direita. Todos os demaisoperadores binrios so associativos a esquerda.

2.5.7 - Construtores de Tabelas

Construtores de tabelas so expresses que criam tabelas. Toda vez que


16 of 119 07-08-2009 17:33


17/119

um construtor avaliado, uma nova tabela criada. Um construtor podeser usado para criar uma tabelas vazia 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 | expseparadordecampos ::= , | ;

Cada campo da forma [exp1] = exp2 adiciona nova tabela uma entrada cujachave exp1 e cujo valor exp2. Um campo da forma Nome = exp equivalente a["Nome"] = exp. Finalmente, campos da forma exp so equivalentes a [i] = exp,onde i representa nmeros inteiros consecutivos, iniciando com 1.Campos nos outros formatos no afetam esta contagem. Por exemplo,

a = { [f(1)] = g; "x", "y"; x = 1, f(x), [30] = 23; 45 }

equivalente a

dolocal t = {}t[f(1)] = gt[1] = "x" -- primeira expt[2] = "y" -- segunda expt.x = 1 -- t["x"] = 1t[3] = f(x) -- terceira exp

t[30] = 23t[4] = 45 -- quarta expa = t

end

Se o ltimo campo na lista possui a forma exp e a expresso umachamada de funo ou uma expresso com um nmero varivel deargumentos, ento todos os valores retornados pela expresso entram nalista consecutivamente (ver 2.5.8). Para evitar isto, coloque parntesesao redor da chamada de funo ou da expresso com nmero varivel deargumentos (ver 2.5).

A lista de campos pode ter um separador a mais no fim, como umaconvenincia para cdigo gerado automaticamente.

2.5.8 - Chamadas de Funo

Uma chamada de funo em Lua tem a seguinte sintaxe:

chamadadefuncao ::= expprefixo args

Em uma chamada de funo, primeiro expprefixo e args so avaliados. Seo valor de expprefixo possui tipo function, ento esta funo chamada


17 of 119 07-08-2009 17:33


18/119

com os argumentos fornecidos. Caso contrrio, o meta-mtodo "call" deexpprefixo chamado, tendo como primeiro parmetro o valor de

expprefixo, seguido pelos argumentos originais da chamada (ver 2.8).A forma

chamadadefuncao ::= expprefixo : Nome args

pode ser usada para chamar "mtodos". Uma chamada v:nome(args) umacar sinttico para v.nome(v,args), com a diferena de que v avaliadosomente uma vez.

Argumentos possuem a seguinte sintaxe:

args ::= `( [listaexp] `)args ::= construtordetabelaargs ::= Cadeia

Todas as expresses fornecidas como argumento so avaliadas antes dachamada. Uma chamada da forma f{campos} uma acar sinttico paraf({campos}); ou seja, a lista de argumentos consiste somente em uma tabelanova. Uma chamada da forma f'cadeia' (ou f"cadeia" ou f[[cadeia]]) umacar sinttico para f('cadeia'); ou seja, a lista de argumentos consistesomente em uma cadeia de caracteres literal.

Uma exceo em relao sintaxe de formato livre de Lua que no possvel colocar uma quebra de linha antes do '(' em uma chamada defuno. Esta restrio evita algumas ambigidades na linguagem. Se vocescrevesse

a = f(g).x(a)

Lua poderia ver isto como um comando nico, a = f(g).x(a). Portanto, sevoc deseja dois comandos, voc deve obrigatoriamente colocar um

ponto-e-vrgula entre eles. Se voc realmente quer chamar f, voc deveremover a quebra de linha antes de (g).

Uma chamada da forma returnchamadadefuncao denominada de chamadafinal. Lua implementa chamadas finais prprias (ou recurses finais prprias):em uma chamada final, a funo chamada reusa a entrada na pilha dafuno que a chamou. Portanto, no h limite no nmero de chamadasfinais aninhadas que um programa pode executar. Contudo, uma chamadafinal apaga qualquer informao de depurao sobre a funo chamadora.Note que uma chamada final somente acontece com uma sintaxe

particular, onde o return possui uma nica chamada de funo comoargumento; esta sintaxe faz com que a chamada de funo retorne


18 of 119 07-08-2009 17:33


19/119

exatamente os valores de retorno da funo chamada. Dessa forma,nenhum dos exemplos a seguir so chamadas finais:

return (f(x)) -- o nmero de resultados ajustado para 1return 2 * f(x)return x, f(x) -- resultados adicionaisf(x); return -- resultados descartadosreturn x or f(x) -- o nmero de resultados ajustado para 1

2.5.9 - Definies de Funes

A sintaxe para a definio de uma funo

funcao ::= function corpodafuncao

funcao ::= `( [listapar] `) bloco end

O seguinte acar sinttico simplifica definies de funes:

comando ::= function nomedafuncao corpodafuncaocomando ::= localfunction Nome corpodafuncaonomedafuncao ::= 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

e no para

local f = function () corpo end

(Isto somente faz diferena quando o corpo da funo contm uma


19 of 119 07-08-2009 17:33


20/119

referncia para f.)

Uma definio de funo uma expresso executvel, cujo valor tem tipofunction. Quando Lua pr-compila um trecho, todos os corpos das funesdo trecho so pr-compilados tambm. Ento, sempre que Lua executa adefinio de uma funo, a funo instanciada (ou fechada). Estainstncia da funo (ou fecho) o valor final da expresso. Instnciasdiferentes da mesma funo podem se referir a diferentes variveis locaisexternas e podem ter diferentes tabelas de ambiente.

Parmetros comportam-se como variveis locais que so inicializadas comos valores dos argumentos:

listapar ::= listadenomes [`, ...] | `...

Quando uma funo chamada, a lista de argumentos ajustada para otamanho da lista de parmetros, a no ser que a funo seja de aridadevarivel ou vararg, o que indicado por trs pontos ('...') no final da sualista de parmetros. Uma funo vararg no ajusta sua lista deargumentos; ao invs disso, ela coleta todos os argumentos extras e osfornece para a funo atravs de uma expresso vararg, a qual tambm representada como trs pontos. O valor desta expresso uma lista detodos os argumentos extras correntes, similar a uma funo com mltiplos

valores de retorno. Se uma expresso vararg usada dentro de outraexpresso ou no meio de uma lista de expresses, ento a sua lista devalores de retorno ajustada para um elemento. Se a expresso usadacomo o ltimo elemento de uma lista de expresses, ento nenhum ajuste feito (a menos que a ltima expresso seja delimitada por parnteses).

Como um exemplo, considere as seguintes definies:

function f(a, b) endfunction g(a, b, ...) endfunction r() return 1,2,3 end

Neste caso, ns temos o seguinte mapeamento de argumentos paraparmetros e para as expresses vararg:

CHAMADA PARMETROS

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

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


20 of 119 07-08-2009 17:33


21/119

g(3, 4, 5, 8) a=3, b=4, ... --> 5 8g(5, r()) a=5, b=1, ... --> 2 3

Resultados so retornados usando o comando return (ver 2.4.4). Se ocontrole alcana o fim de uma funo sem encontrar um comando return,ento a funo retorna sem nenhum resultado.

A sintaxe de dois pontos usada para definir mtodos, isto , funes quepossuem um parmetro extra implcito self. Desta forma, o comando

function t.a.b.c:f (params) corpo end

uma acar sinttico para

t.a.b.c.f = function (self, params) corpo end

2.6 - Regras de Visibilidade

Lua uma linguagem com escopo lxico. O escopo das variveis comeano primeiro comando depois da sua declarao e vai at o fim do blocomais interno que inclui a declarao. Considere o seguinte exemplo:

x = 10 -- varivel globaldo -- bloco novo

local x = x -- novo 'x', com valor 10print(x) --> 10x = x+1do -- outro blocolocal x = x+1 -- outro 'x'print(x) --> 12

endprint(x) --> 11

endprint(x) --> 10 (o x global)

Note que, em uma declarao como local x = x, o novo x sendo declarado

no est no escopo ainda e portanto o segundo x se refere a uma varivelexterna.

Por causa das regras de escopo lxico, variveis locais podem serlivremente acessadas por funes definidas dentro do seu escopo. Umavarivel local usada por uma funo mais interna chamada de upvalue ouvarivel local externa, dentro da funo mais interna.

Note que cada execuo de um comando local define novas variveislocais. Considere o exemplo a seguir:

a = {}local x = 20


21 of 119 07-08-2009 17:33


22/119

for i=1,10 dolocal y = 0a[i] = function () y=y+1; return x+y end

end

O lao cria dez fechos (isto , dez instncias da funo annima). Cada umdestes fechos usa uma varivel y diferente, enquanto todos elescompartilham a mesma varivel x.

2.7 - Tratamento de Erros

Dado que Lua uma linguagem embarcada de extenso, todas as aesde Lua comeam a partir de cdigo C no programa hospedeiro que chama

uma funo da biblioteca de Lua (ver lua_pcall). Sempre que um erro ocorredurante a compilao ou execuo, o controle retorna para C, que podetomar as medidas apropriadas (tais como imprimir uma mensagem deerro).

O cdigo Lua pode explicitamente gerar um erro atravs de uma chamada funo error. Se voc precisa capturar erros em Lua, voc pode usar afuno pcall.

2.8 - Meta-tabelas

Todo valor em Lua pode ter uma meta-tabela. Esta meta-tabela umatabela Lua comum que define o comportamento do valor original comrelao a certas operaes especiais. possvel mudar vrios aspectos docomportamento de operaes sobre um valor especificando camposespecficos na meta-tabela do valor. Por exemplo, quando um valor nonumrico o operando de uma adio, Lua verifica se existe uma funoassociada com o campo "__add" na meta-tabela do valor. Se a funo existe,Lua chama esta funo para realizar a adio.

Chamamos as chaves em uma meta-tabela de eventos e os valores demeta-mtodos. No exemplo anterior, o evento "add" e o meta-mtodo afuno que realiza a adio.

possvel obter a meta-tabela de qualquer valor usando a funogetmetatable.

Voc pode mudar a meta-tabela de tabelas atravs da funo setmetatable.Voc no pode mudar a meta-tabela de outros tipos de Lua (a menos quevoc use a biblioteca de depurao); voc deve obrigatoriamente usar a

API C para fazer isto.


22 of 119 07-08-2009 17:33


23/119

Tabelas e objetos do tipo userdata completos possuem meta-tabelasindividuais (embora mltiplas tabelas e objetos userdata possam

compartilhar suas meta-tabelas). Valores de todos os outros tiposcompartilham um nica meta-tabela por tipo; ou seja, h somente umameta-tabela para todos os nmeros, uma para todas as cadeias decaracteres, etc.

Uma meta-tabela controla como um objeto se comporta em operaesaritmticas, comparaes com relao ordem, concatenao, operaode tamanho e indexao. Uma meta-tabela tambm pode definir umafuno a ser chamada quando um objeto userdata coletado pelo coletorde lixo. Para cada uma destas operaes Lua associa uma chaveespecfica chamada um evento. Quando Lua realiza uma destas operaessobre um valor, Lua verifica se este valor possui uma meta-tabela com oevento correspondente. Se este o caso, o valor associado quela chave(o meta-mtodo) controla como Lua ir realizar a operao.

Meta-tabelas controlam as operaes listadas a seguir. Cada operao identificada por seu nome correspondente. A chave para cada operao uma cadeia de caracteres comeando com o nome da operao sendoprecedido por dois sublinhados, '__'; por exemplo, a chave para a operao"add" a cadeia "__add". A semntica destas operaes melhor explicadapor meio de uma funo Lua que descreve como o interpretador executa aoperao.

O cdigo mostrado aqui meramente ilustrativo; o comportamento realest codificado no interpretador e muito mais eficiente do que estasimulao. Todas as funes usadas nestes descries (rawget, tonumber,etc.) so descritas em 5.1. Em particular, para recuperar o meta-mtodode um dado objeto, usamos a expresso

metatable(obj)[event]

Isto deve ser lido comorawget(getmetatable(obj) or {}, event)

Isto , o acesso a um meta-mtodo no invoca outros meta-mtodos e oacesso a objetos que no possuem meta-tabelas no falha (elesimplesmente resulta em nil).

"add": a operao +.

A funo getbinhandler abaixo define como Lua escolhe um tratador para

uma operao binria. Primeiro, Lua tenta o primeiro operando. Se oseu tipo no definie um tratador para a operao, ento Lua tenta o


23 of 119 07-08-2009 17:33


24/119

segundo operando.

function getbinhandler (op1, op2, event)

return metatable(op1)[event] or metatable(op2)[event]end

Usando esta funo, o comportamento da expresso op1 + op2

function add_event (op1, op2)local o1, o2 = tonumber(op1), tonumber(op2)if o1 and o2 then -- os dois operandos so numricos?return o1 + o2 -- '+' aqui a 'add' primitiva

else -- pelo menos um dos operandos nao numricolocal h = getbinhandler(op1, op2, "__add")if h then

-- chama o tratador com ambos os operandosreturn (h(op1, op2))else -- nenhum tratador disponvel: comportamento padroerror()

endend

end

"sub": a operao -. Comportamento similar ao da operao "add"."mul": a operao *. Comportamento s imilar ao da operao "add"."div": a operao /. Comportamento s imilar ao da operao "add"."mod":

a operao%

. Comportamento similar ao da operao "add",tendo a operao o1 - floor(o1/o2)*o2 como operao primitiva."pow": a operao ^ (exponenciao). Comportamento similar ao daoperao "add", com a funo pow (da biblioteca matemtica de C)como operao primitiva."unm": a operao - unria.

function unm_event (op)local o = tonumber(op)if o then -- operando numrico?return -o -- '-' aqui a 'unm' primitiva

else -- o operando no numrico.

-- Tenta obter um tratador do operandolocal h = metatable(op).__unmif h then-- chama o tratador com o operandoreturn (h(op))

else -- nenhum tratador disponvel: comportamento padroerror()

endend

end

"concat": a operao .. (concatenao).

function concat_event (op1, op2)


24 of 119 07-08-2009 17:33


25/119

if (type(op1) == "string" or type(op1) == "number") and(type(op2) == "string" or type(op2) == "number") thenreturn op1 .. op2 -- concatenao de cadeias primitiva

elselocal h = getbinhandler(op1, op2, "__concat")if h thenreturn (h(op1, op2))

elseerror()

endend

end

"len": a operao #.

function len_event (op)if type(op) == "string" thenreturn strlen(op) -- tamanho de string primitiva

elseif type(op) == "table" thenreturn #op -- tamanho de tabela primitiva

elselocal h = metatable(op).__lenif h then-- chama o tratador com o operandoreturn (h(op))

else -- nenhum tratador disponvel: comportamento padroerror()

end

endend

Veja 2.5.5 para uma descrio do tamanho de um tabela.

"eq": a operao ==. A funo getcomphandler define como Lua escolheum meta-mtodo para operadores de comparao. Um meta-mtodosomente selecionado quando os dois objetos que esto sendocomparados possuem o mesmo tipo e o mesmo meta-mtodo para aoperao selecionada.

function getcomphandler (op1, op2, event)if type(op1) ~= type(op2) then return nil endlocal 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

endif op1 == op2 then -- igual primitivo?


25 of 119 07-08-2009 17:33


26/119

return true -- objetos so iguaisend-- tenta meta-mtodo

local h = getcomphandler(op1, op2, "__eq")if h thenreturn (h(op1, op2))

elsereturn false

endend

a ~= b equivalente a not (a == b).

"lt": a operao b equivalente a b < a.

"le": a operao


27/119

a >= b equivalente a b


28/119

return h(func, ...)elseerror()

endendend

2.9 - Ambientes

Alm de meta-tabelas, objetos do tipo thread, function e userdatapossuem outra tabela associada com eles, chamada de seu ambiente.Assim como meta-tabelas, ambientes so tabelas normais e vrios objetospodem compartilhar o mesmo ambiente.

Objetos do tipo thread so criados compartilhando o ambiente da threadque os criou. Objetos do tipo userdata e funes C so criadoscompartilhando o ambiente da funo C que os criou. Funes Lua noaninhadas (criadas por loadfile, loadstring ou load) so criadascompartilhando o ambiente da thread que as criou. Funes Luaaninhadas so criadas compartilhando o ambiente da funo Lua que ascriou.

Ambientes associados com objetos do tipo userdata no possuem

significado para Lua. apenas uma convenincia para programadoresassociarem uma tabela a um objeto userdata.

Ambientes associados com fluxos de execuo (threads) so chamados deambientes globais. Eles so usados como o ambiente padro pelos fluxosde execuo e funes no aninhadas criadas pelo fluxo de execuo epodem ser diretamente acessados pelo cdigo C (ver 3.3).

O ambiente associado com uma funo C pode ser diretamente acessadopelo cdigo C (ver 3.3). Ele usado como o ambiente padro para outrasfunes C e objetos userdata criados pela funo.

Ambientes associados com funes Lua so usados para resolver todos osacessos a variveis globais dentro da funo (ver 2.3). Eles so usadoscomo o ambiente padro para outras funes Lua criadas pela funo.

possvel mudar o ambiente de uma funo Lua ou do fluxo de execuoque est sendo executado atualmente chamando setfenv. possvel obter oambiente de uma funo Lua ou do fluxo de execuo sendo executadoatualmente chamando getfenv. Para tratar o ambiente de outros objetos(userdata, funes C, outros fluxos de execuo) voc deve

obrigatoriamente usar a API C.


28 of 119 07-08-2009 17:33


29/119

2.10 - Coleta de Lixo

Lua realiza gerenciamento automtico da memria. Isto significa que vocno precisa se preocupar com a alocao de memria para novos objetosnem com a liberao de memria quando os objetos no so maisnecessrios. Lua gerencia a memria automaticamente executando umcoletor de lixo de tempos em tempos para coletar todos os objetos mortos(ou seja, objetos que no so mais acessveis a partir de Lua). Todamemria usada por Lua est sujeita ao gerenciamento automtico dememria: tabelas, userdata, funes, fluxos de execuo, cadeias decaracteres, etc.

Lua implementa um coletor de lixo marca-e-limpa (mark-and-sweep)incremental. O coletor usa dois nmeros para controlar o seu ciclo decoleta de lixo: apausa do coletor de lixo e o multiplicador de passo do coletorde lixo. O valor de ambos expresso de forma percentual (ou seja, umvalor de 100 representa um valor interno de 1).

A pausa do coletor de lixo controla quanto tempo o coletor espera antesde iniciar um novo ciclo. Valores maiores fazem o coletor ser menosagressivo. Valores menores do que 100 significam que o coletor no iresperar para iniciar um novo ciclo. Um valor de 200 significa que o coletor

ir esperar at que a memria total em uso dobre antes de iniciar um novociclo.

O multiplicador de passo controla a velocidade relativa do coletor emrelao alocao de memria. Valores maiores fazem o coletor ser maisagressivo mas tambm aumentam o tamanho de cada passo incremental.Valores menores do que 100 fazem com que o coletor seja muito lento epode ocorrer que o coletor nunca termine um ciclo. O valor padro, 200,significa que o coletor executado a uma velocidade que "duas vezes" avelocidade de alocao de memria.

possvel mudar estes nmeros atravs de chamadas s funes lua_gc emC ou collectgarbage em Lua. Com estas funes voc tambm pode controlaro coletor diretamente (e.g., par-lo e reinici-lo).

2.10.1 - Meta-mtodos de Coleta de Lixo

Usando a API C, voc pode configurar os meta-mtodos do coletor de lixopara objetos userdata (ver 2.8). Estes meta-mtodos tambm sochamados de finalizadores. Finalizadores permitem que voc coordene a

coleta de lixo de Lua com o gerenciamento de recursos externos (taiscomo o fechamento de arquivos, conexes de rede ou de bancos de


29 of 119 07-08-2009 17:33


30/119

dados ou a liberao de sua prpria memria).

Objetos userdata com um campo __gc em suas meta-tabelas no sorecolhidos imediatamente pelo coletor de lixo. Ao invs disso, Lua oscoloca naquela lista. Depois que a coleta realizada, Lua faz o equivalenteda seguinte funo para cada objeto userdata em uma lista:

function gc_event (userdata)local h = metatable(userdata).__gcif h thenh(userdata)

endend

Ao final do ciclo de coleta de lixo, os finalizadores para os objetos userdataso chamados na ordem reversa ao de sua criao, entre aquelescoletados naquele ciclo. Isto , o primeiro finalizador a ser chamado aquele associado com o objeto userdata que foi criado por ltimo noprograma. O userdata s efetivamente liberado no prximo ciclo decoleta de lixo.

2.10.2 - Tabelas Fracas

Uma tabela fraca uma tabela cujos elementos so referncias fracas. Uma

referncia fraca ignorada pelo coletor de lixo. Em outras palavras, se asnicas referncias para um objeto so referncias fracas, ento o coletorde lixo ir coletar este objeto.

Uma tabela fraca pode ter chaves fracas, valores fracos ou ambos. Umatabela com chaves fracas permite a coleta de suas chaves mas impede acoleta de seus valores. Uma tabela com chaves fracas e valores fracospermite a coleta tanto das chaves como dos valores. Em qualquer caso, sea chave coletada ou o valor coletado, o par inteiro removido databela. A fragilidade de uma tabela controlada pelo campo __mode de sua

meta-tabela. Se o campo __mode uma cadeia de caracteres contendo ocaractere 'k', as chaves da tabela so fracas. Se __mode contm 'v', osvalores na tabela so fracos.

Depois de usar uma tabela como uma meta-tabela, no se deve mudar ovalor de seu campo __mode. Caso contrrio, o comportamento fraco dastabelas controladas por esta meta-tabela indefinido.

2.11 - Co-rotinas

Lua oferece suporte a co-rotinas, tambm conhecidas como fluxos de


30 of 119 07-08-2009 17:33


31/119

execuo (threads) colaborativos. Uma co-rotina em Lua representa um fluxode execuo independente. Ao contrrio de processos leves em sistemas

que do suporte a mltiplos fluxos de execuo, uma co-rotina somentesuspende sua execuo atravs de uma chamada explcita a uma funode cesso.

possvel criar uma co-rotina com uma chamada coroutine.create. O seunico argumento uma funo que a funo principal da co-rotina. Afuno create somente cria uma nova co-rotina e retorna uma refernciapara ela (um objeto do tipo thread); ela no inicia a execuo da co-rotina.

Quando a funo coroutine.resume chamada pela primeira vez, recebendocomo seu primeiro argumento um objeto do tipo thread retornado porcoroutine.create, a co-rotina inicia a sua execuo, na primeira linha de suafuno principal. Depois que a co-rotina comea a ser executada, elacontinua executando at terminar ou ceder.

Uma funo pode terminar sua execuo de duas maneiras: normalmente,quando sua funo principal retorna (explicitamente ou implicitamente,depois da ltima instruo); e de maneira anormal, se ocorre um erro noprotegido. No primeiro caso, coroutine.resume retorna true mais quaisquervalores retornados pela funo principal da co-rotina. No caso deacontecerem erros, coroutine.resume retorna false mais uma mensagem de

erro.

Uma co-rotina cede a execuo atravs de uma chamada funocoroutine.yield. Quando uma co-rotina cede, a coroutine.resume correspondenteretorna imediatamente, mesmo se a cesso aconteceu dentro de umachamada de funo aninhada (isto , no ocorreu dentro da funoprincipal, mas em uma funo chamada direta ou indiretamente pelafuno principal). No caso de uma cesso, coroutine.resume tambm retornatrue, mais quaisquer valores passados para coroutine.yield. Na prxima vezque voc recomea a execuo da mesma co-rotina, ela continua sua

execuo do ponto onde ela cedeu, com a chamada para coroutine.yieldretornando quaisquer argumentos extras passados para coroutine.resume.

Como coroutine.create, a funo coroutine.wrap tambm cria uma co-rotina, masao invs de retornar a prpria co-rotina, ela retorna uma funo que,quando chamada, retoma a execuo da co-rotina. Quaisquer argumentospassados para esta funo vo como argumentos extras paracoroutine.resume. coroutine.wrap retorna todos os valores retornados porcoroutine.resume, exceto o primeiro (o cdigo booleano de erro).Diferentemente de coroutine.resume, coroutine.wrap no captura erros; qualquer

erro propagado para o chamador.


31 of 119 07-08-2009 17:33


32/119

Como um exemplo, considere o seguinde cdigo:

function foo (a)

print("foo", a)return coroutine.yield(2*a)

end

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

end)

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

Quando voc execut-lo, ele produzir a seguinte sada:

co-body 1 10foo 2

main true 4co-body rmain true 11 -9co-body x ymain true 10 endmain false cannot resume dead coroutine

3 - A Interface de Programao daAplicao (API)

Esta seo descreve a API C para Lua, ou seja, o conjunto de funes Cdisponveis para o programa hospedeiro se comunicar com Lua. Todas asfunes da API, bem como os tipos e constantes relacionados, estodeclarados no arquivo de cabealho lua.h.

Mesmo quando usamos o termo "funo", qualquer operao na API pode,de forma alternativa, ser provida como uma macro. Tais macros usam cadaum dos seus argumentos exatamente uma vez (com exceo do primeiroargumento, que sempre um estado Lua) e portanto no geram qualquerefeito colateral oculto.

Como na maioria das bibliotecas C, as funes da API Lua no verificam a


32 of 119 07-08-2009 17:33


33/119

validade ou a consistncia dos seus argumentos. Contudo, possvelmudar este comportamento compilando Lua com uma definio apropriada

para a macroluai_apicheck

, no arquivoluaconf.h

.

3.1 - A Pilha

Lua usa uma pilha virtual para passar e receber valores de C. Cadaelemento nesta pilha representa um valor Lua (nil, um nmero, umacadeia de caracteres, etc.).

Sempre que Lua chama C, a funo chamada recebe uma nova pilha, que independente de pilhas anteriores e de pilhas de funes C que ainda

estejam ativas. Esta pilha contm inicialmente quaisquer argumentos paraa funo C e onde a funo C empilha os seus resultados para seremretornados ao chamador (ver lua_CFunction).

Por convenincia, a maioria das operaes de consulta na API no segueuma disciplina estrita de pilha. Ao invs disso, elas podem se referir aqualquer elemento na pilha usando um ndice: Um ndice positivorepresenta uma posio absoluta na pilha (comeando em 1); um ndicenegativo representa uma posio relativa ao topo da pilha. De maneiramais especfica, se a pilha possui n elementos, ento o ndice 1

representa o primeiro elemento (isto , o elemento que foi empilhado napilha primeiro) e o ndice n representa o ltimo elemento; o ndice -1tambm representa o ltimo elemento (isto , o elemento no topo) e ondice -n representa o primeiro elemento. Dizemos que um ndice vlidose ele est entre 1 e o topo da pilha (isto , se 1 abs(ndice) topo).

3.2 - Tamanho da Pilha

Quando voc interage com a API de Lua, voc responsvel por assegurarconsistncia. Em particular, voc responsvel por controlar estouro da pilha.Voc pode usar a funo lua_checkstack para aumentar o tamanho da pilha.

Sempre que Lua chama C, ela assegura que pelo menos LUA_MINSTACKposies na pilha esto disponveis. LUA_MINSTACK definida como 20, entogeralmente voc no precisa se preocupar com o espao da pilha amenos que o seu cdigo possua laos empilhando elementos na pilha.

A maioria das funes de consulta aceita como ndices qualquer valordentro do espao da pilha disponvel, isto , ndices at o tamanhomximo da pilha que voc configurou atravs da funo lua_checkstack. Tais

ndices so chamados ndices aceitveis. Mais formalmente, definimos um


33 of 119 07-08-2009 17:33


34/119

ndice aceitvel como a seguir:

(ndice < 0 && abs(ndice) 0 && ndice


35/119

[-o, +p,x]

precise armazenar. Esta tabela est sempre localizada no pseudo-ndiceLUA_REGISTRYINDEX. Qualquer biblioteca de C pode armazenar dados nesta

tabela, mas ela deve tomar cuidado para escolher chaves diferentesdaquelas usadas por outras bibliotecas, para evitar colises. Tipicamente,voc deve usar como chave uma cadeia de caracteres contendo o nomeda sua biblioteca ou um objeto do tipo userdata leve com o endereo deum objeto C em seu cdigo.

As chaves inteiras no registro so usadas pelo mecanismo de referncia,implementado pela biblioteca auxiliar, e portanto no devem ser usadaspara outros propsitos.

3.6 - Tratamento de Erros em CInternamente, Lua usa o mecanismo de longjmp de C para tratar erros. (Vocpode tambm utilizar excees se voc usar C++; veja o arquivo luaconf.h.)Quando Lua se depara com qualquer erro (tais como erros de alocao dememria, erros de tipo, erros de sintaxe e erros de tempo de execuo)ela dispara um erro; isto , ela faz um desvio longo. Um ambiente protegidousa setjmp para estabelecer um ponto de recuperao; qualquer errodesvia o fluxo de execuo para o ponto de recuperao ativado maisrecentemente.

A maioria das funes na API pode disparar um erro, por exemplo devido aum erro de alocao de memria. A documentao para cada funoindica se ela pode disparar erros.

Dentro de uma funo C voc pode disparar um erro chamando lua_error.

3.7 - Funes e Tipos

Listamos aqui todas as funes e tipos da API C em ordem alfabtica. Cada

funo tem um indicador como este:

O primeiro campo, o, representa quantos elementos a funo desempilhada pilha. O segundo campo, p, indica quantos elementos a funo empilhana pilha. (Qualquer funo sempre empilha seus resultados depois dedesempilhar seus argumentos.) Um campo na forma x|y significa que afuno pode empilhar (ou desempilhar) x ou y elementos, dependendo dasituao; uma marca de interrogao '?' significa que no podemos saberquantos elementos a funo desempilha/empilha olhando somente osseus argumentos (e.g., o nmero de elementos pode depender do que

est na pilha). O terceiro campo, x, diz se a funao pode disparar erros: '-'


35 of 119 07-08-2009 17:33


36/119

significa que a funo nunca dispara qualquer erro; 'm' s ignifica que afuno pode disparar um erro somente devido falta de memria; 'e'

significa que a funo pode disparar outros tipos de erro; 'v

' significa que afuno pode disparar um erro de maneira proposital.

lua_Alloc

typedef void * (*lua_Alloc) (void *ud,void *ptr,size_t osize,size_t nsize);

O tipo da funo de alocao de memria usada pelos estados Lua. Afuno de alocao deve prover uma funcionalidade similar de realloc,mas no exatamente a mesma. Seus argumentos so ud, um ponteiroopaco passado para lua_newstate; ptr, um ponteiro para o bloco sendoalocado/realocado/liberado; osize, o tamanho original do bloco; e nsize, onovo tamanho do bloco. ptr NULL se e somente se osize zero. Quando nsize zero, a funo de alocao deve retornar NULL; se osize diferente dezero, o bloco de memria apontado por ptr deve ser liberado. Quando nsizeno zero, a funo de alocao retorna NULL se e somente se ela nopode alocar o tamanho do bloco requisitado. Quando nsize no zero e

osize zero, a funo de alocao deve comportar-se como malloc. Quandonsize e osize no so zero, a funo de alocao comporta-se como realloc.Lua assume que a funo de alocao nunca falha quando osize >= nsize.

Temos a seguir uma implementao simples para a funo de alocao.Ela usada na biblioteca auxiliar por luaL_newstate.

static void *l_alloc (void *ud, void *ptr, size_t osize,size_t nsize) {

(void)ud; (void)osize; /* no utilizados */if (nsize == 0) {free(ptr);

return NULL;}elsereturn realloc(ptr, nsize);

}

Este cdigo assume que free(NULL) no possui nenhum efeito e querealloc(NULL, size) equivalente a malloc(size). ANSI C garante esses doiscomportamentos.

lua_atpanic


36 of 119 07-08-2009 17:33


37/119

[-(nargs + 1), +nresults, e]

lua_CFunction lua_atpanic (lua_State *L, lua_CFunction panicf);

Estabelece uma nova funo de pnico e retorna a funo de pnico

antiga.

Se um erro ocorre fora de qualquer ambiente protegido, Lua chama umafuno de pnico e ento chama exit(EXIT_FAILURE), terminando ento aaplicao hospedeira. A sua funo de pnico pode evitar esta sada casoela nunca retorne (e.g., fazendo uma desvio longo).

A funo de pnico pode acessar a mensagem de erro no topo da pilha.

lua_callvoid lua_call (lua_State *L, int nargs, int nresults);

Chama uma funo.

Para chamar uma funo voc deve usar o seguinte protocolo: primeiro, afuno a ser chamada empilhada na pilha; em seguida, os argumentosda funo so empilhados em ordem direta; isto , o primeiro argumento empilhado primeiro. Por ltimo voc chama lua_call; nargs o nmero deargumentos que voc empilhou na pilha. Todos os argumentos e o valor

da funo so desempilhados da pilha quando a funo chamada. Osresultados da funo so empilhados na pilha quando a funo retorna. Onmero de resultados ajustado para nresults, a menos que nresults sejaLUA_MULTRET. Neste caso, todos os resultados da funo so empilhados. Luacuida para que os valores retornados caibam dentro do espao da pilha.Os resultados da funo so empilhados na pilha em ordem direta (oprimeiro resultado empilhado primeiro), de modo que depois dachamada o ltimo resultado est no topo da pilha.

Qualquer erro dentro da funo chamada propagado para cima (com umlongjmp).

O seguinte exemplo mostra como o programa hospedeiro pode fazer oequivalente a este cdigo Lua:

a = f("how", t.x, 14)

Aqui est o mesmo cdigo em C:

lua_getfield(L, LUA_GLOBALSINDEX, "f"); /* funo 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) */


37 of 119 07-08-2009 17:33


38/119

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 cdigo acima "balanceado": ao seu final, a pilha est de volta sua configurao original. Isto considerado uma boa prtica deprogramao.

lua_CFunction

typedef int (*lua_CFunction) (lua_State *L);

O tipo para funes C.

A fim de se comunicar apropriadamente com Lua, uma funo C deve usaro seguinte protocolo, o qual define o modo como parmetros e resultadosso passados: uma funo C recebe seus argumentos de Lua na sua pilhaem ordem direta (o primeiro argumento empilhado primeiro). Portanto,quando a funo inicia, lua_gettop(L) retorna o nmero de argumentosrecebidos pela funo. O primeiro argumento (se houver) est no ndice 1e seu ltimo argumento est no ndice lua_gettop(L). Para retornar valorespara Lua, uma funo C apenas os empilha na pilha, em ordem direta (o

primeiro resultado empilhado primeiro) e retorna o nmero deresultados. Qualquer outro valor na pilha abaixo dos resultados serdevidamente descartado por Lua. Como uma funo Lua, uma funo Cchamada por Lua tambm pode retornar muitos resultados.

Como um exemplo, a seguinte funo recebe um nmero varivel deargumentos numricos e retorna a mdia e a soma deles:

static int foo (lua_State *L) {int n = lua_gettop(L); /* nmero de argumentos */lua_Number sum = 0;

int i;for (i = 1; i


39/119

[-0, +0, m]

[-0, +0, -]

[-n, +1, e]

[-0, +(0|1), -]

lua_checkstack

int lua_checkstack (lua_State *L, int extra);

Garante que existem pelo menos extra posies disponveis na pilha. Afuno retorna falso se ela no puder aumentar o tamanho da pilha parao tamanho desejado. Esta funo nunca comprime a pilha; se a pilha j maior do que o novo tamanho, ela no ter o seu tamanho modificado.

lua_close

void lua_close (lua_State *L);

Destri todos os objetos no estado Lua fornecido (chamando osmeta-mtodos de coleta de lixo correspondentes, se houver) e libera todaa memria dinmica usada por aquele estado. Em vrias plataformas,pode no ser necessrio chamar esta funo, porque todos os recursosso naturalmente liberados quando o programa hospedeiro morre. Poroutro lado, programas que ficam rodando por muito tempo, como umdaemon ou um servidor web, podem precisar liberar estados to logo elesno sejam mais necessrios, para evitar um crescimento demasiado douso da memria.

lua_concat

void lua_concat (lua_State *L, int n);

Concatena os n valores no topo da pilha, desempilha-os e deixa oresultado no topo da pilha. Se n 1, o resultado o nico valor na pilha(isto , a funo no faz nada); se n 0, o resultado a cadeia decaracteres vazia. A concatenao realizada de acordo com a semntica

usual de Lua (ver 2.5.4).

lua_cpcall

int lua_cpcall (lua_State *L, lua_CFunction func, void *ud);

Chama a funo C func em modo protegido. func inicia somente com umnico elemento na sua pilha, o objeto userdata leve contendo ud. Em casode erros, lua_cpcall retorna o mesmo cdigo de erro de lua_pcall, mais oobjeto de erro no topo da pilha; caso contrrio, ela retorna zero e no

muda a pilha. Todos os valores retornados por func so descartados.


39 of 119 07-08-2009 17:33


40/119

[-0, +1, m]

[-0, +0, m]

[-0, +0, e]

[-1, +0, v]

lua_createtable

void lua_createtable (lua_State *L, int narr, int nrec);

Cria uma nova tabela vazia e a empilha no topo da pilha. A nova tabelapossui espao pr-alocado para narr elementos array e nrec elementosno-array. Esta pr-alocao til quando voc sabe exatamente quantoselementos a tabela ir ter. Caso contrrio voc pode usar a funolua_newtable.

lua_dump

int lua_dump (lua_State *L, lua_Writer writer, void *data);

Descarrega uma funo como um trecho de cdigo binrio. Recebe umfuno Lua no topo da pilha e produz um trecho de cdigo binrio que, secarregado novamente, resulta em uma funo equivalente quela que foidescarregada. Para produzir partes do trecho de cdigo, lua_dump chama afuno writer (ver lua_Writer) com o argumento data fornecido paraescrev-los.

O valor retornado o cdigo de erro retornado pela ltima chamada funo writer; 0 significa que no ocorreram erros.

Esta funo no desempilha a funo Lua da pilha.

lua_equal

int lua_equal (lua_State *L, int index1, int index2);

Retorna 1 se os dois valores nos ndices aceitveis index1 e index2 so iguais,

seguindo a semntica do operador == de Lua (ou seja, pode chamarmeta-mtodos). Caso contrrio retorna 0. Tambm retorna 0 se qualquerum dos ndices no vlido.

lua_error

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 funo faz um desviolongo e portanto nunca retorna. (ver luaL_error).


40 of 119 07-08-2009 17:33


41/119

[-0, +0, e]

[-0, +0, -]

[-0, +1, -]

lua_gc

int lua_gc (lua_State *L, int what, int data);

Controla o coletor de lixo.

Esta funo realiza vrias tarefas, de acordo com o valor do parmetrowhat:

LUA_GCSTOP: pra 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 memria (em Kbytes) que estsendo usada correntemente por Lua.LUA_GCCOUNTB: retorna o resto da diviso da quantidade de bytes dememria 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 maispassos) de maneira no especificada. Se voc quer controlar otamanho do passo voc deve ajustar de maneira experimental o valorde data. A funo retorna 1 se o passo finalizou um ciclo de coleta delixoLUA_GCSETPAUSE: estabelece data como o novo valor para apausa do coletor(ver 2.10). A funo retorna o valor anterior da pausa.LUA_GCSETSTEPMUL: estabelece data como o novo valor para o multiplicadorde passo do coletor (ver 2.10). A funo retorna o valor anterior domultiplicador de passo.

lua_getallocf

lua_Alloc lua_getallocf (lua_State *L, void **ud);

Retorna a funo de alocao de memria de um dado estado. Se ud no NULL, Lua armazena em *ud o ponteiro opaco passado para lua_newstate.

lua_getfenv

void lua_getfenv (lua_State *L, int index);

Coloca na pilha a tabela de ambiente do valor no ndice fornecido.


41 of 119 07-08-2009 17:33


42/119

[-0, +1, e]

[-0, +1, e]

[-0, +(0|1), -]

[-1, +1, e]

[-0, +0, -]

lua_getfield

void lua_getfield (lua_State *L, int index, const char *k);

Coloca na pilha o valor t[k], onde t o valor no ndice vlido fornecido.Como em Lua, esta funo pode disparar um meta-mtodo para o evento"index" (ver 2.8).

lua_getglobal

void lua_getglobal (lua_State *L, const char *name);

Coloca na pilha o valor da global name. Esta funo definida como umamacro:

#define lua_getglobal(L,s) lua_getfield(L, LUA_GLOBALSINDEX, s)

lua_getmetatable

int lua_getmetatable (lua_State *L, int index);

Coloca na pilha a meta-tabela do valor no ndice aceitvel fornecido. Se o

ndice no vlido ou se o valor no possui uma meta-tabela, a funoretorna 0 e no coloca nada na pilha.

lua_gettable

void lua_gettable (lua_State *L, int index);

Coloca na pilha o valor t[k], onde t o valor no ndice vlido fornecido e k o valor no topo da pilha.

Esta funo desempilha a chave 'k' (colocando o resultado no seu lugar).Como em Lua, esta funo pode disparar um meta-mtodo para o evento"index" (ver 2.8).

lua_gettop

int lua_gettop (lua_State *L);

Retorna o ndice do elemento no topo da pilha. Visto que os ndices

comeam em 1, este resultado igual ao nmero de elementos na pilha (eportanto 0 significa uma pilha vazia).


42 of 119 07-08-2009 17:33


43/119

[-1, +1, -]

[-0, +0, -]

[-0, +0, -]

[-0, +0, -]

lua_insert

void lua_insert (lua_State *L, int index);

Move o elemento no topo para o ndice vlido fornecido, deslocando oselementos acima deste ndice para abrir espao. Esta funo no podeser chamada com um pseudo-ndice, porque um pseudo-ndice no umaposio real da pilha.

lua_Integer

typedef ptrdiff_t lua_Integer;

O tipo usado pela API Lua para representar valores inteiros.

O tipo padro um ptrdiff_t, que usualmente o maior tipo inteiro comsinal que a mquina manipula "confortavelmente".

lua_isboolean

int lua_isboolean (lua_State *L, int index);

Retorna 1 se o valor no ndice aceitvel fornecido possui tipo booleano e0 caso contrrio.

lua_iscfunction

int lua_iscfunction (lua_State *L, int index);

Retorna 1 se o valor no ndice aceitvel fornecido uma funo C e 0 caso

contrrio.

lua_isfunction

int lua_isfunction (lua_State *L, int index);

Retorna 1 se o valor no ndice aceitvel fornecido uma funo (C ou Lua)e 0 caso contrrio.

lua_islightuserdata


43 of 119 07-08-2009 17:33


44/119

[-0, +0, -]

[-0, +0, -]

[-0, +0, -]

[-0, +0, -]

[-0, +0, -]

int lua_islightuserdata (lua_State *L, int index);

Retorna 1 se o valor no ndice aceitvel fornecido um objeto userdata

leve e 0 caso contrrio.

lua_isnil

int lua_isnil (lua_State *L, int index);

Retorna 1 se o valor no ndice aceitvel fornecido nil e 0 caso contrrio.

lua_isnoneint lua_isnone (lua_State *L, int index);

Retorna 1 se o ndice aceitvel fornecido no vlido (isto , se ele serefere a um elemento fora do espao da pilha corrente) e 0 casocontrrio.

lua_isnoneornil

int lua_isnoneornil (lua_State *L, int index);

Retorna 1 se o ndice aceitvel fornecido no vlido (isto , se ele serefere a um elemento fora do espao da pilha corrente) ou se o valorneste ndice nil e 0 caso contrrio.

lua_isnumber

int lua_isnumber (lua_State *L, int index);

Retorna 1 se o valor no ndice aceitvel fornecido um nmero ou umacadeia de caracteres que pode ser convertida para um nmero e 0 casocontrrio.

lua_isstring

int lua_isstring (lua_State *L, int index);

Retorna 1 se o valor no ndice aceitvel fornecido uma cadeia de

caracteres ou um nmero (o qual sempre pode ser convertido para uma


44 of 119 07-08-2009 17:33


45/119

[-0, +0, -]

[-0, +0, -]

[-0, +0, -]

[-0, +0, e]

[-0, +1, -]

cadeia) e 0 caso contrrio.

lua_istable

int lua_istable (lua_State *L, int index);

Retorna 1 se o valor no ndice aceitvel fornecido uma tabela e 0 casocontrrio.

lua_isthread

int lua_isthread (lua_State *L, int index);

Retorna 1 se o valor no ndice aceitvel fornecido do tipo thread e0 caso contrrio.

lua_isuserdata

int lua_isuserdata (lua_State *L, int index);

Retorna 1 se o valor no ndice aceitvel fornecido um objeto userdata(completo ou leve) e 0 caso contrrio.

lua_lessthan

int lua_lessthan (lua_State *L, int index1, int index2);

Retorna 1 se o valor no ndice aceitvel index1 menor do que o valor nondice aceitvel index2, seguindo a semntica do operador < de Lua (ou seja,pode chamar meta-mtodos). Caso contrrio retorna 0. Tambm retorna 0

se qualquer um dos ndices no for vlido.

lua_load

int lua_load (lua_State *L,lua_Reader reader,void *data,const char *chunkname);

Carrega um trecho de cdigo Lua. Se no ocorrer nenhum erro, lua_load

empilha o trecho compilado como uma funo Lua no topo da pilha. Casocontrrio, empilha uma mensagem de erro. Os valores de retorno de


45 of 119 07-08-2009 17:33


46/119

[-0, +0, -]

[-0, +1, m]

[-0, +1, m]

lua_load so:

0: sem erros;LUA_ERRSYNTAX: erro de sintaxe durante a pr-compilao;LUA_ERRMEM: erro de alocao de memria.

Esta funo somente carrega um trecho; ela no o executa.

lua_load automaticamente detecta se o trecho est na forma de texto ou naforma binria e o carrega de maneira correta (veja o programa luac).

A funo lua_load usa uma funo reader fornecida pelo usurio para ler otrecho de cdigo (ver lua_Reader). O argumento data um valor opaco

passado para a funo de leitura.

O argumento chunkname d um nome ao trecho, o qual usado paramensagens de erro e em informaes de depurao (ver 3.8).

lua_newstate

lua_State *lua_newstate (lua_Alloc f, void *ud);

Cria um estado novo independente. Retorna NULL se no puder criar o

estado (devido falta de memria). O argumento f a funo dealocao; Lua faz toda a alocao de memria para este estado atravsdesta funo. O segundo argumento, ud, um ponteiro opaco que Luasimplesmente passa para a funo de alocao a cada chamada.

lua_newtable

void lua_newtable (lua_State *L);

Cria uma nova tabela vazia e a coloca na pilha. equivalente alua_createtable(L, 0, 0).

lua_newthread

lua_State *lua_newthread (lua_State *L);

Cria um novo objeto do tipo thread, coloca-o na pilha e retorna umponteiro para um lua_State que representa este novo fluxo de execuo. Onovo fluxo de execuo retornado por esta funo compartilha todos osobjetos globais (tais como tabelas) com o estado original, mas possui uma


46 of 119 07-08-2009 17:33


47/119

[-0, +1, m]

[-1, +(2|0), e]

pilha de execuo independente.

No h uma funo explcita para terminar ou destruir um fluxo deexecuo. Objetos do tipo thread esto sujeitos coleta de lixo, assimcomo qualquer outro objeto de Lua.

lua_newuserdata

void *lua_newuserdata (lua_State *L, size_t size);

Esta funo aloca um novo bloco de memria com o tamanho fornecido,coloca na pilha um novo objeto userdata completo com o endereo do

bloco e retorna este endereo.

Objetos userdata representam valores C em Lua. Um userdata completorepresenta um bloco de memria. Ele um objeto (assim como umatabela): voc deve cri-lo, ele pode ter sua prpria meta-tabela e vocpode detectar quando ele est sendo coletado. Um objeto userdatacompleto somente igual a ele mesmo (usando a igualdade primitiva, semo uso de meta-mtodos).

Quando Lua coleta um userdata completo com um meta-mtodo gc, Lua

chama o meta-mtodo e marca o userdata como finalizado. Quando esteuserdata coletado novamente ento Lua libera sua memriacorrespondente.

lua_next

int lua_next (lua_State *L, int index);

Desempilha uma chave da pilha e empilha um par chave-valor da tabela nondice fornecido (o "prximo" par depois da chave fornecida). Se no h

mais elementos na tabela, ento lua_next retorna 0 (e no empilha nada).

Um percorrimento tpico parece com este:

/* tabela est na pilha no ndice 't'' */lua_pushnil(L); /* primeira chave */while (lua_next(L, t) != 0) {/* usa 'key' (no ndice -2) e 'value' (no ndice -1) */printf("%s - %s\n",

lua_typename(L, lua_type(L, -2)),lua_typename(L, lua_type(L, -1)));

/* remove 'value'; guarda 'key' para a prxima iterao */

lua_pop(L, 1);}


47 of 119 07-08-2009 17:33


48/119

[-0, +0, -]

[-(nargs + 1), +(nresults|1), -]

Durante o percorrimento de uma tabela, no chame lua_tolstringdiretamente sobre uma chave, a menos que voc saiba que a chave

realmente uma cadeia de carecteres. Lembre-se quelua_tolstring

altera ovalor no ndice fornecido; isto confunde a prxima chamada para lua_next.

lua_Number

typedef double lua_Number;

O tipo de nmeros em Lua. Por padro, ele double, mas pode sermudado em luaconf.h.

Atravs do arquivo de configurao possvel mudar Lua para operar comoutro tipo para nmeros (e.g., float ou long).

lua_objlen

size_t lua_objlen (lua_State *L, int index);

Retorna o "tamanho" do valor no ndice aceitvel fornecido: para cadeiasde 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 memria alocado para o userdata; paraoutros valores, o tamanho 0.

lua_pcall

int lua_pcall (lua_State *L, int nargs, int nresults, int errfunc);

Chama uma funo em modo protegido.

Tanto nargs quanto nresults possuem o mesmo significado que possuam emlua_call. Se no h erros durante a chamada, lua_pcall comporta-seexatamente 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 cdigode erro. Como lua_call, lua_pcall sempre remove a funo e seus argumentosda pilha.

Se errfunc 0, ento a mensagem de erro retornada na pilha exatamentea mensagem de erro original. Caso contrrio, errfunc o ndice na pilha deum funo de tratamento de erros. (Na implementao atual, este ndice

no pode ser um pseudo-ndice.) No caso de erros de tempo de execuo,esta funo ser chamada com a mensagem de erro e seu valor de


48 of 119 07-08-2009 17:33


49/119

[-n, +0, -]

[-0, +1, -]

[-n, +1, m]

retorno ser a mensagem retornada na pilha por lua_pcall.

Tipicamente, a funo de tratamento de erros usada para adicionar maisinformao de depurao mensagem de erro, como um trao da pilha.

Tal informao no pode ser obtida aps o retorno de lua_pcall, pois nesteponto a pilha j foi desfeita.

A funo lua_pcall retorna 0 em caso de sucesso ou um dos seguintescdigos de erro (definidos em lua.h):

LUA_ERRRUN: um erro de tempo de execuo.LUA_ERRMEM: erro de alocao de memria. Para tais erros, Lua nochama a funo de tratamento de erros.

LUA_ERRERR: erro quando estava executando a funo de tratamento deerros.

lua_pop

void lua_pop (lua_State *L, int n);

Desempilha n elementos da pilha.

lua_pushboolean

void lua_pushboolean (lua_State *L, int b);

Empilha um valor booleano com valor b na pilha.

lua_pushcclosure

void lua_pushcclosure (lua_State *L, lua_CFunction fn, int n);

Empilha um novo fecho C na pilha.

Quando uma funo C criada, possvel associar alguns valores a ela,criando ento um fecho C (ver 3.4); estes valores so ento acessveispara a funo sempre que ela chamada. Para associar valores com umafuno C, primeiro estes valores devem ser colocados na pilha (quando hmltiplos valores, o primeiro valor empilhado primeiro). Entolua_pushcclosure chamada para criar e colocar a funo C na pilha, com oargumento n informando quantos valores devem ser associados com a

funo. lua_pushcclosure tambm desempilha estes valores da pilha.


49 of 119 07-08-2009 17:33


50/119

[-0, +1, m]

[-0, +1, m]

[-0, +1, -]

O valor mximo para n 255.

lua_pushcfunction

void lua_pushcfunction (lua_State *L, lua_CFunction f);

Empilha uma funo C na pilha. Esta funo recebe um ponteiro para umafuno C e coloca na pilha um valor Lua do tipo function que, quandochamado, invoca a funo C correspondente.

Qualquer funo para ser registrada em Lua deve seguir o protocolocorreto para receber seus parmetros e retornar seus resultados (ver

lua_CFunction).

lua_pushcfunction definida como uma macro:

#define lua_pushcfunction(L,f) lua_pushcclosure(L,f,0)

lua_pushfstring

const char *lua_pushfstring (lua_State *L, const char *fmt, ...);

Coloca na pilha uma cadeia de caracteres formatada e retorna umponteiro para esta cadeia. Ela similar funo C sprintf, mas possuialgumas diferenas importantes:

Voc no precisa alocar espao para o resultado: o resultado umacadeia de caracteres e Lua cuida da alocao de memria (e dadesalocao, atravs da coleta de lixo).Os especificadores de converso so bastante restritos. No h flags,tamanhos ou precises. Os especificadores de converso podem sersomente '%%' (insere um '%' na cadeia), '%s' (insere uma cadeia

terminada por zero, sem restries de tamanho), '%f' (insere umlua_Number), '%p' (insere um ponteiro como um nmero hexadecimal), '%d'(insere um int) e '%c' (insere um int como um caractere).

lua_pushinteger

void lua_pushinteger (lua_State *L, lua_Integer n);

Coloca um nmero com valor n na pilha.


50 of 119 07-08-2009 17:33


51/119

[-0, +1, m]

[-0, +1, -]

[-0, +1, m]

[-0, +1, -]

[-0, +1, -]

lua_pushliteral

void lua_pushliteral (lua_State *L, const char *s);

Esta macro equivalente a lua_pushlstring, mas somente pode ser usadaquando s uma cadeia literal. Nestes casos, a macro automaticamenteprov o tamanho da cadeia.

lua_pushlightuserdata

manual lua

Documents