Manual de Referencia de Lua 5.1
Manual de Referencia de Lua 5.1
por Roberto Ierusalimschy, Luiz Henrique de Figueiredo, Waldemar Celes
(traducci�n de Julio Manuel Fern�ndez-D�az; v�anse las notas sobre la misma al final del documento.)
Copyright © 2007–2008 Lua.org, PUC-Rio. Libremente disponible bajo los t�rminos de la licencia de Lua.
Lua es un lenguage de programaci�n extensible dise�ado para una programaci�n procedimental general con utilidades para la descripci�n de datos. Tambi�n ofrece un buen soporte para la programaci�n orientada a objetos, programaci�n funcional y programaci�n orientada a datos. Se pretende que Lua sea usado como un lenguaje de script potente y ligero para cualquier programa que lo necesite. Lua est� implementado como una biblioteca escrita en C limpio (esto es, en el subconjunto com�n de ANSI C y C++).
Siendo un lenguaje de extensi�n, Lua no tiene noci�n de programa principal (main): s�lo funciona embebido en un cliente anfitri�n, denominado programa contenedor o simplemente anfitri�n (host). �ste puede invocar funciones para ejecutar un trozo de c�digo Lua, puede escribir y leer variables de Lua y puede registrar funciones C para que sean llamadas por el c�digo Lua. A trav�s del uso de funciones C, Lua puede ser aumentado para abarcar un amplio rango de diferentes dominios, creando entonces lenguajes de programaci�n personalizados que comparten el mismo marco sint�ctico. La distribuci�n de Lua incluye un programa anfitri�n de muestra denominado lua, que usa la biblioteca de Lua para ofrecer un int�rprete de Lua completo e independiente.
Lua es software libre, y se proporciona, como es usual, sin garant�as, como se establece en su licencia. La implementaci�n descrita en este manual est� disponible en el sitio web oficial de Lua, www.lua.org.
Como cualquier otro manual de referencia, este documento es parco en algunos lugares. Para una discusi�n de las decisiones detr�s del dise�o de Lua, v�anse los art�culos t�cnicos disponibles en el sitio web de Lua. Para una detallada introducci�n a la programaci�n en Lua, v�ase el libro de Roberto, Programming in Lua (Second Edition).
Esta secci�n describe el l�xico, la sintaxis y la sem�ntica de Lua. En otras palabras, esta secci�n describe qu� elementos (tokens) son v�lidos, c�mo deben combinarse y qu� significa su combinaci�n.
Las construcciones del lenguaje se explicar�n usando la notaci�n BNF extendida usual, en la que {a} significa 0 o m�s aes, y [a] significa una a opcional. Los s�mbolos no terminales se muestran en it�lica, las palabras clave (keywords) se muestran en negrita, y los otros s�mbolos terminales se muestran en un tipo de letra de paso fijo (typewriter), encerrada entre comillas simples. La sintaxis completa de Lua se encuentra al final de este manual.
Los nombres (tambi�n llamados identificadores) en Lua pueden ser cualquier tira de caracteres (string) s�lo con letras, d�gitos y caracteres de subrayado (underscore), no comenzando por un d�gito. Esto coincide con la definici�n de los nombres en la mayor�a de los lenguajes. (La definici�n de letra depende de la implementaci�n local actual a trav�s del sistema locale: cualquier car�cter considerado alfab�tico en el sistema local puede ser usado en un identificador.) Los identificadores se usan para nombrar variables y campos de tablas.
Las siguientes palabras clave (keywords) est�n reservadas y no pueden usarse como nombres:
and break do else elseif
end false for function if
in local nil not or
repeat return then true until while
En Lua las letras may�sculas y las min�sculas se consideran diferentes: and es una palabra reservada, pero And y AND son dos nombres diferentes v�lidos. Como convenci�n, los nombres que comienzan por un subrayado seguido por letras en may�sculas (como _VERSION) est�n reservados para uso como variables globales internas de Lua.
Los siguientes strings denotan otros elementos:
+ - * / % ^ #
== ~= <= >= < > =
( ) { } [ ]
; : , . .. ...
Los strings literales pueden ser delimitados por comillas simples (ap�strofes) o dobles, y pueden contener las siguientes secuencias de escape de C:
'\a' (pitido, bell)
'\b' (retroceso, backspace),
'\f' (salto de p�gina, form feed),
'\n' (nueva l�nea, newline),
'\r' (retorno de carro, carriage return),
'\t' (tabulador horizontal, horizontal tab),
'\v' (tabulador vertical, vertical tab),
'\\' (barra inversa, backslash),
'\"' (comilla doble, quotation mark o double quote) y
'\'' (ap�strofe, apostrophe o single quote).
Adem�s, una '\newline' (esto es, una barra inversa seguida por un salto de l�nea real) produce un salto de l�nea en el string. Un car�cter en un string puede tambi�n especificarse por su valor num�rico usando la secuencia de escape '\ddd', donde ddd es una secuencia de tres d�gitos decimales. (Tenga presente que si la secuencia num�rica de escape est� seguida de un d�gito debe ser expresada usando exactamente tres d�gitos.) Los strings en Lua pueden contener cualquier valor de 8 bits, incluyendo el car�cter cero, el cual puede ser especificado mediante '\0'.
Para poner una comilla (simple) doble, una barra inversa, un retorno de carro o un car�cter cero dentro de un string literal encerrado por comillas (simples) dobles se debe usar una secuencia de escape. Cualquier otro car�cter puede ser incluido en el literal. (Algunos caracteres de control pueden causar problemas con el sistema de ficheros, pero Lua no tiene problemas con ellos.)
Los strings literales pueden definirse usando un formato largo, encerrados en corchetes largos. Definimos un corchete largo de abrir de nivel n como un corchete de abrir seguido de n signos igual (=) seguidos de otro corchete de abrir. As�, un corchete largo de abrir de nivel 0 se escribe [[, un corchete largo de abrir de nivel 1 se escribe [=[, y as� sucesivamente. Los corchetes largos de cerrar se define de manera similar; por ejemplo, un corchete largo de cerrar de nivel 4 se expresa ]====]. Un string largo comienza en un corchete largo de abrir de cualquier nivel y termina en el primer corchete largo de cerrar del mismo nivel. Los strings literales delimitados de esta manera pueden extenderse por varias l�neas, las secuencias de escape no son interpretadas y se ignoran los corchetes largos de cualquier otro nivel. Por tanto, pueden contener cualquier cosa excepto un corchete de cerrar del mismo nivel o caracteres cero.
Por conveniencia, cuando un corchete largo de abrir es seguido inmediatamente de un car�cter de nueva l�nea, �ste no es incluido en el string. Por ejemplo, usando el c�digo de caracteres ASCII (en el cual 'a' se codifica como 97, el car�cter de nueva l�nea se codifica como 10, y '1' se codifica como 49), los cinco literales siguientes denotan el mismo string:
a = 'alo\n123"'
a = "alo\n123\""
a = '\97lo\10\04923"'
a = [[alo
123"]]
a = [==[
alo
123"]==]
Las constantes num�ricas pueden contener una parte decimal opcional y tambi�n un exponente opcional. Lua tambi�n acepta constantes enteras hexadecimales, escritas anteponiendo el prefijo 0x. Algunos ejemplos de constantes num�ricas v�lidas son
3 3.0 3.1416 314.16e-2 0.31416E1 0xff 0x56
Los comentarios comienzan con un doble gui�n (--) en cualquier lugar fuera de un string. Si el texto que sigue inmediatamente despu�s de -- no es un corchete largo de abrir el comentario es corto y llega hasta el final de l�nea. En otro caso tenemos un comentario largo, que alcanza hasta el correspondiente corchete largo de cerrar. Los comentarios largos se usan frecuentemente para deshabilitar temporalmente trozos de c�digo.
Lua es un lenguaje din�micamente tipado. Esto significa que las variables no tienen tipos; s�lo tienen tipo los valores. No existen definiciones de tipo en el lenguaje. Todos los valores almacenan su propio tipo.
Todos los valores en Lua son valores de primera clase. Esto significa que todos ellos pueden ser almacenados en variables, pueden ser pasados como argumentos de funciones, y tambi�n ser devueltos como resultados.
Existen ocho tipos b�sicos en Lua:
nil, boolean, number,
string, function, userdata,
thread y table.
Nil es el tipo del valor nil, cuya principal propiedad es ser
diferente de cualquier otro valor; normalmente representa la ausencia de un valor �til.
Boolean es el tipo de los valores false (falso) y true (verdadero).
Tanto nil como false hacen una condici�n falsa;
cualquier otro valor la hace verdadera.
Number representa n�meros reales (en coma flotante y doble precision).
(Es f�cil construir int�rpretes de Lua que usen otra representaci�n interna para
los n�meros, ya sea en coma flotante con precisi�n simple o enteros largos.
V�ase el fichero luaconf.h.)
String representa una tira de caracteres.
Lua trabaja con 8 bits: los strings pueden contener cualquier car�cter de 8 bits, incluyendo el car�cter cero ('\0') (v�ase §2.1).
Lua puede llamar (y manejar) funciones escritas en Lua y funciones escritas en C (v�ase §2.5.8).
El tipo userdata se incluye para permitir guardar en variables de Lua datos arbitrarios en C. Este tipo corresponde a bloques de memoria y no tienen asociadas operaciones predefinidas en Lua, excepto la asignaci�n y el test de identidad. Sin embargo, usando §metatablas, el programador puede definir operaciones asociadas a valores de tipo userdata (v�ase §2.8). Los valores de este tipo no pueden ser creados o modificados en Lua, sino s�lo a trav�s de la API de C. Esto garantiza la integridad de los datos propiedad del programa anfitri�n.
El tipo thread representa procesos de ejecuci�n y es usado para implementar co-rutinas (v�ase §2.11). No deben confundirse los procesos de Lua con los del sistema operativo. Lua soporta co-rutinas en todos los sistemas, incluso en aqu�llos que no soporten procesos.
El tipo table (tabla) implementa arrays asociativos, esto es, arrays que pueden ser indexados no s�lo con n�meros, sino tambi�n con cualquier valor (excepto nil). Las tablas pueden ser heterog�neas, ya que pueden contener valores de todos los tipos (excepto nil). Las tablas son el �nico mecanismo de estructuraci�n de datos en Lua; pueden ser usadas para representar arrays ordinarios, tablas de s�mbolos, conjuntos, registros, grafos, �rboles, etc. Para representar registros Lua usa el nombre del campo como �ndice. El lenguaje soporta esta representaci�n haciendo la notaci�n b.nombre equivalente a b["nombre"]. Existen varias maneras convenientes de crear tablas en Lua (v�ase §2.5.7).
Como �ndices, tambi�n los valores de los campos de una tabla pueden ser de cualquier tipo (excepto nil). En particular, debido a que las funciones son valores de primera clase, los campos de las tablas pueden contener funciones. Entonces las tablas pueden contener tambi�n m�todos (v�ase §2.5.9).
Los valores de las tablas, las funciones, los procesos y los userdata (completos) son objetos: las variables no contienen realmente esos valores, sino que s�lo los referencian. La asignaci�n, el paso de argumentos y el retorno de las funciones siempre manejan referencias a esos valores; esas operaciones no implican ning�n tipo de copia.
La funci�n de biblioteca type retorna un string que describe el tipo de un valor dado.
Lua puede convertir autom�ticamente entre valores string y valores num�ricos en tiempo de ejecuci�n. Cualquier operaci�n aritm�tica aplicada a un string intenta convertir el mismo en un n�mero, siguiendo las reglas normales de conversi�n. Y viceversa, cuando un n�mero se usa donde se espera un string el n�mero se convierte a string, con un formato razonable. Para un control completo en la conversi�n de n�meros en strings debe usarse la funci�n format de la biblioteca de manejo de strings (v�ase string.format).
Las variables son lugares donde se almacenan valores. Existen tres tipos de variables en Lua: globales, locales y campos de tabla.
Un �nico nombre puede denotar una variable local o una global (o un argumento formal de una funci�n, el cual es una forma particular de una variable local):
var ::= nombre
nombre denota identificadores, como se definen en §2.1.
Lua asume que las variables son globales, a no ser que sean declaradas expl�citamente como locales (v�ase §2.4.7). Las variables locales tienen un �mbito (scope) definido l�xicamente: pueden ser accedidas libremente desde dentro de las funciones definidas en su mismo �mbito (v�ase §2.6).
Antes de la primera asignaci�n el valor de una variable es nil.
Los corchetes se usan para indexar una tabla:
var ::= prefixexp '[' exp ']'La primera expresi�n (prefixexp) debe dar como resultado un valor tabla; la segunda expresi�n (exp) identifica una entrada espec�fica en esta tabla. La expresi�n que denota la tabla que es indexada tienen una sintaxis restringida; v�ase §2.5 para m�s detalles.
La sintaxis var.nombre es otra manera de expresar
var["nombre"] y se usa para denotar campos de tablas:
var ::= prefixexp '.' nombre
La manera en qu� se accede a las variables globales y a los campos de las tablas puede ser cambiada mediante metatablas. Un acceso a la variable indexada t[i] equivale a una llamada a gettable_event(t,i) (v�ase §2.8 para una completa descripci�n de la funci�n gettable_event. Esta funci�n no est� definida ni es invocable desde Lua. Se usa aqu� s�lo con prop�sitos ilustrativos).
Todas las variables globales se almacenan como campos de tablas ordinarias en Lua, denominadas tablas de entorno o simplemente entornos (v�ase §2.9). Cada funci�n tiene su propia referencia a un entorno, as� que todas las variables globales de esta funci�n se refieren a esa tabla de entorno. Cuando se crea una funci�n, �sta hereda el entorno de la funci�n que la cre�. Para obtener la tabla de entorno de una funci�n en c�digo Lua, se invoca a getfenv. Para reemplazarla se llama a setfenv. (Se pueden manejar los entornos de una funci�n C, pero s�lo a trav�s de la biblioteca de depuraci�n; v�ase §5.9.)
Un acceso a la variable global x equivale a _env.x, que a su vez equivale a
gettable_event(_env, "x")donde
_env es el entorno de la funci�n que se est� ejecutando en ese momento (v�ase §2.8 para una completa descripci�n de la funci�n gettable_event. Esta funci�n no est� definida ni es invocable desde Lua. Igualmente, la variable _env no est� definida en Lua. Se usan aqu� s�lo con prop�sitos ilustrativos.)
Lua soporta un conjunto casi convencional de sentencias, similar a los de Pascal o C. Este conjunto incluye la asignaci�n, estructuras de control de flujo, llamadas a funciones, constructores de tablas y declaraciones de variables.
La unidad de ejecuci�n en Lua se denomina chunk, el cual es simplemente un conjunto de sentencias que se ejecutan secuencialmente. Cada sentencia puede llevar opcionalmente al final un punto y coma:
chunk ::= {sentencia [';']}
No existen sentencias vac�as en Lua y por tanto ';;' no es legal.
Lua maneja cada chunk como el cuerpo de una funci�n an�nima con un n�mero variable de argumentos (v�ase §2.5.9). Los chunks pueden definir variables locales, recibir argumentos y retornar valores.
Un chunk puede ser almacenado en un fichero o en un string dentro de un programa anfitri�n. Cuando se ejecuta un chunk primero se precompila, cre�ndose instrucciones para una m�quina virtual, y es entonces cuando el c�digo compilado es ejecutado por un int�rprete de la m�quina virtual.
Los chunks pueden tambi�n estar precompilados en forma binaria; v�ase el programa luac para m�s detalles. Las formas fuente y compilada de los programas son intercambiables; Lua detecta autom�ticamente el tipo de fichero y act�a de manera acorde.
bloque ::= chunk
Un bloque puede ser delimitado expl�citamente para producir una sentencia simple:
sentencia ::= do bloque endLos bloques expl�citos son �tiles para controlar el �mbito de las declaraciones de variable. Tambi�n se utilizan a veces para a�adir sentencias return o break en medio de otro bloque (v�ase §2.4.4).
Lua permite asignaciones m�ltiples. Por tanto la sintaxis de una asignaci�n define una lista de variables a la izquierda y una lista de expresiones a la derecha. Los elementos de ambas listas est�n separados por comas:
sentencia ::= varlist '=' explist
varlist ::= var {',' var}
explist ::= exp {',' exp}
Las expresiones se analizan en §2.5.
Antes de una asignaci�n la lista de expresiones se ajusta a la longitud de la lista de variables. Si existen m�s valores de los necesarios el exceso se descarta. Si existen menos valores de los necesarios la lista se extiende con tantos valores nil como se necesiten. Si la lista de expresiones finaliza con una llamada a una funci�n entonces todos los valores devueltos en la llamada pueden entrar en la lista de valores antes del ajuste (excepto cuando se encierra entre par�ntesis; v�ase §2.5).
La sentencia de asignaci�n primero eval�a todas sus expresiones y s�lo despu�s se hace la asignaci�n. Entonces, el c�digo
i = 3
i, b[i] = i+1, 20
asigna 20 a b[3], sin afectar a b[4] debido a que i en b[i] se eval�a (a 3) antes de que se le asigne el valor 4. Similarmente, la l�nea
x, y = y, xintercambia los valores de
x e y.
El mecanismo de asignaci�n a las variables globales y a los campos de tablas puede ser modificado mediante metatablas. Una asignaci�n a una variable indexada t[i] = val equivale a settable_event(t,i,val). (V�ase §2.8 para una completa descripci�n de la funci�n settable_event. Esta funci�n no est� definida ni es invocable desde Lua. Se usa s�lo con prop�sitos ilustrativos.)
Una asignaci�n a la variable global x = val
equivale a la asignaci�n _env.x = val,
que a su vez equivalen a
settable_event(_env, "x", val)donde
_env es el entorno de la funci�n que est� ejecut�ndose en ese momento.
(La variable _env no est� definida en Lua.
Se utiliza aqu� s�lo con prop�sitos ilustrativos.)
sentencia ::= while exp do bloque end
sentencia ::= repeat bloque until exp
sentencia ::= if exp then bloque {elseif exp then bloque} [else bloque] end
Lua tiene tambi�n una sentencia for, en dos formatos (v�ase §2.4.5).
La condici�n de una expresi�n de una estructura de control puede retornar cualquier valor. Tanto false como nil se consideran falsos. Todos los valores diferentes de nil y false se consideran verdaderos (en particular, el n�mero 0 y el string vac�o son tambi�n verdaderos).
En el bucle repeat–until el bloque interno no acaba en la palabra clave until sino detr�s de la condici�n. De esta manera la condici�n puede referirse a variables locales declaradas dentro del bloque del bucle.
La orden return se usa para devolver valores desde una funci�n o un chunk (el cual es justamente una funci�n). Las funciones y los chunks pueden retornar m�s de un valor, por lo que la sintaxis para return es
sentencia ::= return [explist]
La orden break se usa para terminar la ejecuci�n de los bucles while, repeat y for, saltando a la sentencia que sigue despu�s del bucle:
sentencia ::= breakUn break finaliza el bucle m�s interno que est� activo.
Las �rdenes return y break pueden aparecer s�lo como �ltima sentencia dentro de un bloque. Si se necesita realmente un return o un break en medio de un bloque se debe usar un bloque m�s interno expl�citamente, como en 'do return end' y 'do break end', debido a que as� return y break son las �ltimas sentencias en su propio bloque.
La sentencia for tiene dos formas: una num�rica y otra gen�rica.
La forma num�rica del bucle for repite un bloque mientras una variable de control sigue una progresi�n aritm�tica. Tiene la sintaxis siguiente:
sentencia ::= for nombre '=' exp1 ',' exp2 [',' exp3] do bloque endEl bloque se repite para los valores de nombre comenzando en exp1 hasta que sobrepasa exp2 usando como paso exp3. M�s precisamente una sentencia for como
for v = e1, e2, e3 do bloque endequivale al 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
bloque
var = var + step
end
end
N�tese lo siguiente:
v es local dentro del bucle; no se puede utilizar su valor despu�s de que finalice el bucle for o despu�s de una salida del mismo con break. Si se necesita el valor de la variable var entonces debe asignarse a otra variable antes del break o de la salida del bucle.
La sentencia for gen�rica trabaja con funciones, denominadas iteradores. En cada iteraci�n se invoca a la funci�n iterador que produce un nuevo valor, par�ndose la iteraci�n cuando el nuevo valor es nil. El bucle for gen�rico tiene la siguiente sintaxis:
sentencia ::= for lista_de_nombres in explist do bloque end
lista_de_nombres ::= nombre {',' nombre}
Una sentencia for como
for var_1, ..., var_n in explist do bloque endequivale al 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
bloque
end
end
N�tese lo siguiente:
sentencia ::= llamada_a_funcEn ese caso todos los valores retornados se descartan. Las llamadas a funci�n est�n explicadas en §2.5.8.
sentencia ::= local lista_de_nombres ['=' explist]Si est� presente, una asignaci�n inicial tiene la misma sem�ntica que una asignaci�n m�ltiple (v�ase §2.4.3). En otro caso todas las variables son inicializadas con nil.
Un chunk es tambi�n un bloque (v�ase §2.4.1), as� que las variables locales pueden ser declaradas en un chunk fuera de cualquier bloque expl�cito. El �mbito de esas variables se extiende hasta el final del chunk.
Las reglas de visibilidad para las variables locales se exponen en §2.6.
Las expresiones b�sicas en Lua son las siguientes:
exp ::= prefixexp
exp ::= nil | false | true
exp ::= N�mero
exp ::= String
exp ::= func
exp ::= constructor_de_tabla
exp ::= '...'
exp ::= exp operador_binario exp
exp ::= operador_unario exp
prefixexp ::= var | llamada_a_func | '(' exp ')'
Los n�meros y los string literales se explican en §2.1; las variables se explican en §2.3; la definici�n de funciones se explica en §2.5.9; las llamadas a funci�n se explican en §2.5.8; los constructores de tablas se explican en §2.5.7. Las expresiones vararg (que indican un n�mero variable de argumentos en una funci�n), denotadas mediante tres puntos ('...'), pueden ser usadas directamente s�lo cuando est�n dentro de las funciones con vararg; se explican en §2.5.9.
Los operadores binarios comprenden los operadores aritm�ticos (v�ase §2.5.1), los operadores relacionales (v�ase §2.5.2) y los operadores l�gicos (v�ase §2.5.3). Los operadores unarios compenden el menos unario (v�ase §2.5.1), el not unario (v�ase §2.5.3) y el operador de longitud unario (v�ase §2.5.5).
Tanto las llamadas a funci�n como las expresiones vararg pueden resultar en valores m�ltiples. Si la expresi�n se usa como una sentencia (v�ase §2.4.6) (s�lo posible con llamadas a funci�n), entonces su lista de valores retornados se ajusta a cero elementos, descartando todos los valores retornados. Si la expresi�n se usa como el �ltimo (o �nico) elemento de una lista de expresiones entonces no se realiza ning�n ajuste (a no ser que la llamada se encierre entre par�ntesis). En todos los dem�s contextos Lua ajusta el resultado de la lista a un solo elemento, descartando todos los valores excepto el primero.
He aqu� varios ejemplos:
f() -- ajustado a 0 resultados
g(f(), x) -- f() es ajustado a 1 resultado
g(x, f()) -- g toma x y todos los valores devueltos por f()
a,b,c = f(), x -- f() se ajusta a 1 resultado (c toma el valor nil)
a,b = ... -- a toma el primer argumento vararg, b toma
-- el segundo (a y b pueden ser nil si no existen los
-- correspondientes argumentos vararg)
a,b,c = x, f() -- f() se ajusta a 2 resultados
a,b,c = f() -- f() se ajusta a 3 resultados
return f() -- retorna todos los valores devueltos por f()
return ... -- retorna todos los argumentos vararg recibidos
return x,y,f() -- retorna x, y, y todos los valores devueltos por f()
{f()} -- crea una lista con todos los valores retornados por f()
{...} -- crea una lista con todos los argumentos vararg
{f(), nil} -- f() se ajusta a 1 resultado
Una expresi�n encerrada en par�ntesis siempre resulta en un �nico valor. Entonces, (f(x,y,z)) siempre es un valor �nico, incluso si f retorna varios valores. (El valor de (f(x,y,z)) es el primer valor retornado por f o nil si f no retorna ning�n valor).
+ (adici�n), - (substracci�n), * (multiplicaci�n), / (divisi�n), % (m�dulo) y ^ (exponenciaci�n); y el unario - (negaci�n). Si los operandos son n�meros o strings que se convierten a n�meros (v�ase §2.2.1), entonces todas las operaciones tienen el significado corriente. La exponenciaci�n trabaja con cualquier exponente. Por ejemplo, x^(-0.5) calcula la inversa de la raiz cuadrada de x. El m�dulo se define como
a % b == a - math.floor(a/b)*bEsto es, es el resto de la divisi�n que redondea el cociente hacia menos infinito.
== ~= < > <= >=Devuelven siempre un resultado false o true.
La igualdad (==) primero compara el tipo de los operandos. Si son diferentes entonces el resultado es false. En otro caso se comparan los valores de los operandos. Los n�meros y los strings se comparan de la manera usual. Los objetos (tablas, userdata, procesos y funciones) se comparan por referencia: dos objetos se consideran iguales s�lo si son el mismo objeto. Cada vez que se crea un nuevo objeto (una tabla, userdata, proceso o funci�n) este nuevo objeto es diferente de todos los dem�s objetos preexistentes.
Se puede cambiar la manera en que Lua compara tablas y userdata usando el metam�todo "eq" (v�ase §2.8).
Las reglas de conversi�n de §2.2.1 no se aplican en las comparaciones de igualdad. De este modo "0"==0 es false, y t[0] y t["0"] denotan diferentes entradas en una tabla.
El operador ~= es exactamente la negaci�n de la igualdad (==).
El orden de los operadores funciona de la siguiente manera. Si ambos argumentos son n�meros entonces se comparan como tales. En otro caso, si ambos argumentos son strings sus valores se comparan de acuerdo al sistema local. En otro caso, Lua trata de usar los metam�todos "lt" o "le" (v�ase §2.8).
El operador negaci�n not siempre retorna false o true. El operador conjunci�n and retorna su primer operando si su valor es false o nil; en caso contrario and retorna su segundo operando. El operador disyunci�n or retorna su primer operando si su valor es diferente de nil y false; en caso contrario or retorna su segundo argumento. Tanto and como or usan evaluaci�n de cortocircuito; esto es, su segundo operando se eval�a s�lo si es necesario. He aqu� varios ejemplos:
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
(En este manual '-->' indica el resultado de la expresi�n precedente.)
..'). Si ambos operandos son strings o n�meros entonces se convierten a strings mediante las reglas mencionadas en §2.2.1. En otro caso se invoca al metam�todo "concat" (v�ase §2.8).
El operador longitud se denota mediante #. La longitud de un string es su n�mero de bytes (significado normal de la longitud de un string cuando cada car�cter ocupa un byte).
La longitud de una tabla t se define como un �ndice entero n tal que t[n] no es nil y t[n+1] es nil; adem�s, si t[1] es nil entonces n puede ser cero. Para un array regular, con valores no nil desde 1 hasta un n dado, la longitud es exactamente n, el �ndice es su �ltimo valor. Si el array tiene "agujeros" (esto es, valores nil entre otros valores que no lo son), entonces #t puede ser cualquiera de los �ndices que preceden a un valor nil (esto es, Lua puede considerar ese valor nil como el final del array).
or
and
< > <= >= ~= ==
..
+ -
* / %
not # - (unario)
^
Como es usual, se pueden usar par�ntesis para cambiar la precedencia en una expresi�n. Los operadores de concatenaci�n ('..') y de exponenciaci�n ('^') son asociativos por la derecha. Todos los dem�s operadores son asociativos por la izquierda.
constructor_de_tabla ::= '{' [lista_de_campos] '}'
lista_de_campos ::= campo {separador_de_campos campo} [separador_de_campos]
campo ::= '[' exp ']' '=' exp | nombre '=' exp | exp
separador_de_campos ::= ',' | ';'
Cada campo de la forma [exp1] = exp2 a�ade una entrada a la nueva tabla con la clave exp1 y con el valor exp2. Un campo de la forma nombre = exp equivale a ["nombre"] = exp. Finalmente, campos de la forma exp son equivalentes a [i] = exp, donde i son n�meros enteros consecutivos, comenzando con 1. Los campos en el otro formato no afectan este contador. Por ejemplo,
a = { [f(1)] = g; "x", "y"; x = 1, f(x), [30] = 23; 45 }
equivale a
do
local t = {}
t[f(1)] = g
t[1] = "x" -- 1� exp
t[2] = "y" -- 2� exp
t.x = 1 -- t["x"] = 1
t[3] = f(x) -- 3� exp
t[30] = 23
t[4] = 45 -- 4� exp
a = t
end
Si el �ltimo campo en la lista tiene la forma exp y la expresi�n es una llamada a funci�n o una expresi�n vararg, entonces todos los valores retornados por esta expresi�n entran en la lista consecutivamente (v�ase §2.5.8). Para evitar esto debe encerrarse la llamada a la funci�n (o la expresi�n vararg) entre par�ntesis (v�ase §2.5).
La lista de campos puede tener un separador opcional al final, una conveniencia para c�digo fuente generado de manera autom�tica.
llamada_a_func ::= prefixexp argumentosEn una llamada a funci�n, se eval�an primero prefixexp y los argumentos. Si el valor de prefixexp es del tipo function, entonces se invoca a esta funci�n con los argumentos dados. En caso contrario se invoca el metam�todo "call", pasando como primer argumento el valor de prefixexp seguido por los argumentos originales de la llamada (v�ase §2.8).
La forma
llamada_a_func ::= prefixexp ':' nombre argumentospuede ser usada para invocar "m�todos". Una llamada
v:nombre(...)
es otra manera de expresar v.nombre(v,...),
excepto que v se eval�a s�lo una vez.
Los argumentos tienen la siguiente sintaxis:
argumentos ::= '(' [explist] ')'
argumentos ::= constructor_de_tabla
argumentos ::= String
Todos los argumentos de la expresi�n se eval�an antes de la llamada. Un llamada de la forma f{...} es otra manera de expresar f({...}); esto es, la lista de argumentos es una nueva tabla simple. Una llamada de la forma f'...' (o f"..." o f[[...]]) es otra manera de expresar f('...'); esto es, la lista de argumentos es un string literal simple.
Como excepci�n a la sintaxis de formato libre de Lua, no se puede poner una rotura de l�nea antes de '(' en una llamada a funci�n. Esta restricci�n evita algunas ambig�edades en el lenguaje. Si se escribe
a = f
(g).x(a)
Lua podr�a ententerlo como una sentencia simple, a = f(g).x(a). Entonces, si se desean dos sentencias se debe a�adir un punto y coma entre ellas. Si realmente se desea llamar a f, se debe eliminar la rotura de l�nea antes de (g).
Una llamada de la forma return llamada_a_func se denomina una llamada de cola. Lua implementa llamadas de cola correctas (o recursi�n de cola correcta): en una llamada de cola la funci�n invocada reutiliza la entrada en la pila de la funci�n que la est� llamando. Por tanto no existe l�mite en el n�mero de llamadas de cola anidadas que un programa puede ejecutar. Sin embargo una llamada de cola borra cualquier informaci�n de depuraci�n relativa a la funci�n invocante. N�tese que una llamada de cola s�lo ocurre con una sintaxis particular donde el return tiene una llamada simple a funci�n como argumento; esta sint�sis hace que la funci�n invocante devuelva exactamente el retorno de la funci�n invocada. Seg�n esto ninguno de los siguientes ejemplos son llamadas de cola:
return (f(x)) -- resultados ajustados a 1
return 2 * f(x)
return x, f(x) -- resultados adicionales
f(x); return -- resultados descartados
return x or f(x) -- resultados ajustados a 1
La sintaxis para la definici�n de funciones es
func ::= function cuerpo_de_func
cuerpo_de_func ::= '(' [lista_de_argumentos] ')' bloque end
La siguiente forma simplifica la definici�n de funciones:
sentencia ::= function nombre_de_func cuerpo_de_func
sentencia ::= local function nombre cuerpo_de_func
nombre_de_func ::= nombre {'.' nombre} [':' nombre]
La sentencia
function f () cuerpo_de_funci�n endse traduce en
f = function () cuerpo_de_funci�n endLa sentencia
function t.a.b.c.f () cuerpo_de_funci�n endse traduce en
t.a.b.c.f = function () cuerpo_de_funci�n endLa sentencia
local function f () cuerpo_de_funci�n endse traduce en
local f; f = function () cuerpo_de_funci�n endno en:
local f = function () cuerpo_de_funci�n end(Esto s�lo entra�a diferencias cuando el cuerpo de la funci�n contiene referencias a
f.)
Una definici�n de funci�n es una expresi�n ejecutable, cuyo valor tiene el tipo function. Cuando Lua precompila un chunk todos sus cuerpos de funci�n son tambi�n precompilados. Entonces cuando Lua ejecuta la definici�n de funci�n, la misma es instanciada (o cerrada). Esta instancia de funci�n (o closure) es el valor final de la expresi�n. Diferentes instancias de la misma funci�n pueden referirse a diferentes variables locales externas y pueden tener diferentes tablas de entorno.
Los argumentos formales de una funci�n act�an como variables locales que son inicializadas con los valores actuales de los argumentos:
lista_de_argumentos ::= lista_de_nombres [',' '...'] | '...'Cuando se invoca una funci�n, la lista de argumentos actuales se ajusta a la longitud de la lista de argumentos formales, a no ser que la funci�n sea de tipo vararg, lo que se indica por tres puntos ('
...') al final de la lista de argumentos formales. Una funci�n vararg no ajusta su lista de argumentos; en su lugar recolecta todos los argumentos actuales extra y se los pasa a la funci�n a trav�s de una expresi�n vararg, lo que tambi�n se indica por medio de tres puntos. El valor de esta expresi�n es una lista de todos los argumentos actuales extra, similar a una funci�n con resultados m�ltiples. Si la expresi�n vararg se usa en el interior de otra expresi�n o en el medio de una lista de expresiones, entonces su retorno se ajusta a un s�lo elemento. Si la expresi�n es usada como el �ltimo elemento de una lista de expresiones entonces no se hace ning�n ajuste (a no ser que la llamada se realice entre par�ntesis).
Como ejemplo, consideremos las siguientes definiciones:
function f(a, b) end
function g(a, b, ...) end
function r() return 1,2,3 end
Entonces tenemos la siguiente correspondencia de los argumentos actuales a los formales y a la expresi�n vararg:
LLAMADA ARGUMENTOS
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
Los resultados se devuelven usando la sentencia return (v�ase §2.4.4). Si el flujo del programa alcanza el final de una funci�n sin encontrar una sentencia return entonces la funci�n retorna sin resultados.
La sintaxis con dos puntos (':') se usa para definir m�todos, esto es, funciones que tienen un argumento extra denominado self. Entonces la sentencia
function t.a.b.c:f (params) cuerpo_de_funci�n endes otra manera de expresar
t.a.b.c.f = function (self, params) cuerpo_de_funci�n end
Lua es un lenguaje con �mbito l�xico. El �mbito de las variables comienza en la primera sentencia despu�s de su declaraci�n y termina al final del bloque m�s interno que incluya la declaraci�n. Consideremos el siguiente ejemplo:
x = 10 -- variable global
do -- nuevo bloque
local x = x -- nueva 'x', con valor 10
print(x) --> 10
x = x+1
do -- otro bloque
local x = x+1 -- otra 'x'
print(x) --> 12
end
print(x) --> 11
end
print(x) --> 10 (el valor de la variable global)
Tengase presente que en una declaraci�n como local x = x, la nueva x que est� siendo declarada no tiene �mbito todav�a, y la segunda x se refiere a la variable externa.
Debido a las reglas de �mbito l�xico, las variables locales pueden ser accedidas por funciones definidas en el interior de su propio �mbito. Una variable local usada en una funci�n interna se denomina upvalue o variable local externa en el interior de la funci�n.
N�tese que cada ejecuci�n de una sentencia local define nuevas variables locales. Consid�rese el siguiente ejemplo:
a = {}
local x = 20
for i=1,10 do
local y = 0
a[i] = function () y=y+1; return x+y end
end
El bucle crea diez closures (esto es, diez instancias de una funci�n an�nima). Cada uno de estas instancias usa una variable y diferente, mientras que todas ellas comparten la misma x.
Debido a que Lua es un lenguaje de extensi�n embebido, todas las acciones de Lua comienzan con c�digo C en el programa anfitri�n llamando a una funci�n de la biblioteca de Lua (v�ase lua_pcall). Cada vez que ocurra un error durante la compilaci�n o ejecuci�n de Lua, el control retorna a C, que puede tomar las medidas apropiadas (tales como imprimir un mensaje de error).
Se puede generar (o activar) expl�citamente en Lua un error invocando la funci�n error. Si se necesita capturar errores en Lua se puede usar la funci�n pcall.
Cada valor en Lua puede tener una metatabla. �sta es una tabla ordinaria de Lua que define el comportamiento del valor original para ciertas operaciones especiales. Se pueden cambiar varios aspectos del comportamiento de las operaciones realizadas sobre un valor estableciendo campos espec�ficos en su metatabla. Por ejemplo, cuando un valor no num�rico es un operando de una adici�n Lua busca una funci�n en el campo "__add" de su metatabla. Si se encuentra una, entonces se invoca esa funci�n para realizar la adici�n.
Llamamos eventos a los campos de una metatabla y a los valores los denominamos metam�todos. En el ejemplo anterior el evento es "add" mientras que el metam�todo es la funci�n que realiza la adici�n.
Se puede solicitar la metatabla de cualquier valor a trav�s de la funci�n getmetatable.
Se puede reemplazar la metatabla de una tabla a trav�s de la funci�n setmetatable. No se puede cambiar la metatabla de otros tipos de datos desde Lua (excepto usando la biblioteca de depuraci�n); se debe usar la API de C para ello.
Las tablas y los userdata completos tienen metatablas individuales (aunque varias tablas y userdata pueden compartir sus metatablas); los valores de los otros tipos comparten una �nica metatabla por tipo. Por tanto, existe una �nica metatabla para todos los n�meros, otra para todos los strings, etc.
Una metatabla puede controlar c�mo se comporta un objeto en las operaciones aritm�ticas, en las comparaciones de orden, en la concatenaci�n, en la operaci�n longitud y en el indexado. Una metatabla puede tambi�n definir una funci�n que ser� invocada cuando se libera memoria ocupada (garbage collection) por userdata. A cada una de esas operaciones Lua le asocia una clave espec�fica denominada evento. Cuando Lua realiza una de esas operaciones con un valor, comprueba si �ste tiene una metatabla con el correspondiente evento. Si es as�, el valor asociado con esa clave (el metam�todo) controla c�mo realiza Lua la operaci�n.
Las metatablas controlan las operaciones listadas a continuaci�n. Cada operaci�n se identifica por su correspondiente nombre. La clave asociada a cada operaci�n es un string con su nombre prefijado con dos subrayados, '__'; por ejemplo, la clave para la operaci�n "add" es el string "__add". La sem�ntica de esas operaciones est� mejor expuesta a trav�s de una funci�n Lua que describe c�mo ejecuta el int�rprete la operaci�n.
El c�digo Lua mostrado aqu� es s�lo ilustrativo; el comportamiento real est� codificado internamente en el int�rprete y es mucho m�s eficiente que esta simulaci�n. Todas las funciones usadas en estas descripciones (rawget, tonumber, etc.) est�n descritas en §5.1. En particular, para recuperar el metam�todo de un objeto dado, usamos la expresi�n
metatable(objeto)[evento]Esto puede tambi�n ser expresado mediante
rawget(getmetatable(objeto) or {}, evento)
Por tanto, el acceso a un metam�todo no invoca otros metam�todos, y el acceso a los objetos sin metatablas no falla (simplemente devuelve nil).
+.
La funci�n getbinhandler que aparece m�s abajo define c�mo escoge Lua un manejador de la operaci�n binaria. Primero Lua prueba el primer operando. Si su tipo no define un manejador para la operaci�n entonces Lua lo intenta con el segundo operando.
function getbinhandler (op1, op2, evento) return metatable(op1)[evento] or metatable(op2)[evento] endUsando esta funci�n el comportamiento del c�digo
op1 + op2 es
function add_event (op1, op2)
local o1, o2 = tonumber(op1), tonumber(op2)
if o1 and o2 then -- �son num�ricos ambos operandos?
return o1 + o2 -- '+' aqu� es la primitiva 'add'
else -- al menos uno de los operandos es no num�rico
local h = getbinhandler(op1, op2, "__add")
if h then
-- invoca el manejador de ambos operandos
return (h(op1, op2))
else -- no existe un manejador disponible: comportamiento por defecto
error(···)
end
end
end
-.
El comportamiento es similar a la operaci�n "add".
*.
El comportamiento es similar a la operaci�n "add".
/.
El comportamiento es similar a la operaci�n "add".
%.
El comportamiento es similar a la operaci�n "add", usando o1 - floor(o1/o2)*o2 como operaci�n primitiva.
^ (exponenciaci�n).
El comportamiento es similar a la operaci�n "add", con la funci�n pow (de la biblioteca matem�tica de C) como operaci�n primitiva.
- unaria.
function unm_event (op)
local o = tonumber(op)
if o then -- �es num�rico el operando?
return -o -- '-' aqu� es la funci�n primitiva 'unm'
else -- el operando no es num�rico.
-- intentar obtener un manejador para el operando
local h = metatable(op).__unm
if h then
-- invocar el manejador con el operando
return (h(op))
else -- no hay manejador disponible: comportamiento por defecto
error(···)
end
end
end
.. (concatenaci�n).
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 -- concatenaci�n primitiva de strings
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) -- longitud primitiva de string
elseif type(op) == "table" then
return #op -- longitud primitiva de tabla
else
local h = metatable(op).__len
if h then
-- invocar el manejador con el operando
return (h(op))
else -- no hay manejador disponible: comportamiento por defecto
error(···)
end
end
end
V�ase §2.5.5 para una descripci�n de la longitud de una tabla.
==.
La funci�n getcomphandler define c�mo elige Lua un metam�todo para el operador de comparaci�n. Se selecciona un metam�todo cuando ambos objetos que son comparados tienen el mismo tipo y el mismo metam�todo para la operaci�n dada.
function getcomphandler (op1, op2, evento) if type(op1) ~= type(op2) then return nil end local mm1 = metatable(op1)[evento] local mm2 = metatable(op2)[evento] if mm1 == mm2 then return mm1 else return nil end endEl evento "eq" se define as�:
function eq_event (op1, op2)
if type(op1) ~= type(op2) then -- �diferentes tipos?
return false -- diferentes objetos
end
if op1 == op2 then -- �iguales primitivas?
return true -- los objetos son iguales
end
-- probar un metam�todo
local h = getcomphandler(op1, op2, "__eq")
if h then
return (h(op1, op2))
else
return false
end
end
a ~= b equivale a not (a == b).
<.
function lt_event (op1, op2)
if type(op1) == "number" and type(op2) == "number" then
return op1 < op2 -- comparaci�n num�rica
elseif type(op1) == "string" and type(op2) == "string" then
return op1 < op2 -- comparaci�n lexicogr�fica
else
local h = getcomphandler(op1, op2, "__lt")
if h then
return (h(op1, op2))
else
error(···);
end
end
end
a > b equivale a b < a.
<=.
function le_event (op1, op2)
if type(op1) == "number" and type(op2) == "number" then
return op1 <= op2 -- comparaci�n num�rica
elseif type(op1) == "string" and type(op2) == "string" then
return op1 <= op2 -- comparaci�n 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 equivale a b <= a. T�ngase presente que en ausencia de un metam�todo "le" Lua intenta usar el de "lt", asumiendo que a <= b equivale a not (b < a).
tabla[clave].
function gettable_event (tabla, clave)
local h
if type(tabla) == "table" then
local v = rawget(tabla, clave)
if v ~= nil then return v end
h = metatable(tabla).__index
if h == nil then return nil end
else
h = metatable(tabla).__index
if h == nil then
error(···);
end
end
if type(h) == "function" then
return (h(tabla, clave)) -- invocar el manejador
else return h[clave] -- o repetir la operaci�n con �l
end
end
tabla[clave] = valor.
function settable_event (tabla, clave, valor)
local h
if type(tabla) == "table" then
local v = rawget(tabla, clave)
if v ~= nil then rawset(tabla, clave, valor); return end
h = metatable(tabla).__newindex
if h == nil then rawset(tabla, clave, valor); return end
else
h = metatable(tabla).__newindex
if h == nil then
error(···);
end
end
if type(h) == "function" then
h(tabla, clave, valor) -- invoca el manejador
else h[clave] = valor -- o repite la operaci�n con �l
end
end
function function_event (func, ...)
if type(func) == "function" then
return func(...) -- llamada primitiva
else
local h = metatable(func).__call
if h then
return h(func, ...)
else
error(···)
end
end
end
Adem�s de metatablas, los objetos de tipo proceso, las funciones y los userdata tienen otra tabla asociada, denominada entorno. Como las metatablas los entornos son tablas normales y varios objetos pueden compartir el mismo entorno.
Los entornos asociados con userdata no tienen significado en Lua. Es s�lo una caracter�stica para los programadores asociar una tabla con userdata.
Los entornos asociados con procesos se denominan entornos globales. Son usados como entornos por defecto para los procesos y para las funciones no anidadas creadas por el proceso (a trav�s de loadfile, loadstring o load) y pueden ser accedidas directamente por el c�digo en C (v�ase §3.3).
Los entornos asociados con funciones C pueden ser accedidos directamente por el c�digo en C (v�ase §3.3). Son usadas como entornos por defecto por otras funciones C creadas por la funci�n dada.
Los entornos asociados con funciones en Lua son utilizados para resolver todos los accesos a las variables globales dentro de la funci�n (v�ase §2.3). Son usados tambi�n como entornos por defecto por otras funciones en Lua creadas por la funci�n.
Se puede cambiar el entorno de una funci�n Lua o de un proceso en ejecuci�n invocando setfenv. Se puede obtener el entorno de una funci�n Lua o del proceso en ejecuci�n invocando getfenv. Para manejar el entorno de otros objetos (userdata, funciones C, otros procesos) se debe usar la API de C.
Lua realiza autom�ticamente la gesti�n de la memoria. Esto significa que no debemos preocuparnos ni de asignar (o reservar) memoria para nuevos objetos ni de liberarla cuando los objetos dejan de ser necesarios. Lua gestiona la memoria autom�ticamente ejecutando un liberador de memoria (garbage collector) de cuando en cuando para eliminar todos los objetos muertos (esos objetos que ya no son accesibles desde Lua). Todos los objetos en Lua son susceptibles de gesti�n autom�tica: tablas, userdata, funciones, procesos y strings.
Lua implementa un liberador de memoria del tipo marcado-barrido incremental. Utiliza dos n�meros para controlar sus ciclos de liberaci�n de memoria: la pausa del liberador de memoria y el multiplicador del paso del liberador de memoria.
La pausa del liberador de memoria controla cu�nto tiempo debe esperar el liberador de memoria antes de comenzar un nuevo ciclo. Valores grandes hacen al liberador menos agresivo. Valores menores que 1 significan que el liberador no esperar� para comenzar un nuevo ciclo. Un valor de 2 significa que el liberador espera que la memoria total en uso se doble antes de comenzar un nuevo ciclo.
El multiplicador del paso controla la velocidad relativa del liberador en cuanto a asignaci�n de memoria. Los valores m�s largos hacen el liberador m�s agresivo pero tambi�n aumentan el tama�o de cada paso incremental. Valores menores que 1 hacen el liberador demasiado lento y puede resultar en que el liberador nunca acabe un ciclo. El n�mero por defecto, 2, significa que el liberador se ejecuta a una velocidad doble que la asignaci�n de memoria.
Se pueden cambiar esos n�meros invocando en C a lua_gc o en Lua a collectgarbage. Ambos tienen como argumentos un porcentaje (y entonces un argumento 100 significa un valor real de 1). Con esas funciones se puede tambi�n controlar el liberador directamente (por ejemplo, pararlo y reiniciarlo).
Usando la API de C se pueden establecer metam�todos liberadores de memoria para userdata (v�ase §2.8). Esos metam�todos se denominan tambi�n finalizadores. �stos permiten coordinar el sistema de liberaci�n de memoria de Lua con gestores externos de recursos (tales como cerrar ficheros, conexiones de red o de bases de datos, o liberar su propia memoria).
Los userdata que se van a liberar con un campo __gc en sus metatablas no son liberados inmediatamente por el liberador de memoria. En su lugar Lua los pone en una lista. Despu�s de eso Lua hace el equivalente a la siguiente funci�n para cada userdata en la lista:
function gc_event (udata)
local h = metatable(udata).__gc
if h then
h(udata)
end
end
Al final de cada ciclo de liberaci�n de memoria, los finalizadores de userdata que aparecen en la lista que va a ser liberada son invocados en orden inverso al de su creaci�n. Esto es, el primer finalizador en ser invocado es el que est� asociado con el userdata creado en �ltimo lugar por el programa. El propio userdata puede ser liberado s�lo en el pr�ximo ciclo de liberaci�n de memoria.
Una tabla d�bil es una tabla cuyos elementos son referencias d�biles. Una referencia d�bil es ignorada por el liberador de memoria. En otras palabras, si las �nicas referencias a un objeto son referencias d�biles entonces se libera la memoria asociada con este objeto.
Una tabla d�bil puede tener claves d�biles, valores d�biles o ambas cosas. Una tabla con claves d�biles permite la liberaci�n de sus claves, pero prohibe la liberaci�n de sus valores. Una tabla con claves d�biles y valores d�biles permite la liberaci�n tanto de claves como de valores. En cualquier caso, ya sea la clave o el valor el liberado, el par completo es eliminado de la tabla. La debilidad de una tabla est� controlada por el campo __mode de su metatabla. Si el campo __mode es un string que contiene el car�cter 'k', las claves en la tabla son d�biles. Si __mode contiene 'v', los valores en la tabla son d�biles.
Despu�s de usar una tabla como metatabla no se deber�a cambiar el valor de su campo __mode. En caso contrario el comportamiento d�bil de las tablas controladas por esa metatabla es indefinido.
Lua tiene co-rutinas, tambi�n denominadas multiprocesos colaborativos. En Lua una co-rutina representa un proceso de ejecuci�n independiente. A diferencia de los sistemas multiproceso, en Lua una co-rutina s�lo suspende su ejecuci�n invocando de manera expl�cita una funci�n yield (cesi�n).
Se pueden crear co-rutinas con una llamada a coroutine.create. El �nico argumento de esta funci�n es otra funci�n que es la funci�n principal de la co-rutina.
Cuando se llama por primera vez a coroutine.resume, pas�ndole como argumento el proceso retornado por coroutine.create, la co-rutina comienza a ejecutarse en la primera l�nea de su funci�n principal. Los argumentos extra pasados a coroutine.resume se pasan a su vez a la funci�n principal de la co-rutina. Despu�s de que la co-rutina empieza a ejecutarse lo hace hasta que termina o se produce una cesi�n del control de flujo del programa.
Una co-rutina puede terminar su ejecuci�n de dos maneras: normalmente, cuando su funci�n principal retorna (expl�cita o impl�citamente, despu�s de su �ltima instrucci�n); y anormalmente, si se produjo un error no protegido. En el primer caso, coroutine.resume devuelve true, m�s cualquier valor retornado por la funci�n principal de la co-rutina. En caso de error coroutine.resume devuelve false m�s un mensaje de error.
Una co-rutina cede el control invocando a coroutine.yield. Cuando una co-rutina cede el control la correspondiente coroutine.resume retorna inmediatamente, incluso si la cesi�n ocurre dentro de una llamada a una funci�n anidada (esto es, no en la funci�n principal, sino en una funci�n directa o indirectamente invocada desde la funci�n principal). En el caso de una cesi�n, coroutine.resume tambi�n devuelve true, m�s cualesquiera valores pasados a coroutine.yield. La pr�xima vez que se resuma la misma co-rutina, continuar� su ejecuci�n desde el punto en que fue realizada la cesi�n, con la llamada a coroutine.yield devolviendo cualquier argumento extra pasado a coroutine.resume.
La funci�n coroutine.wrap crea una co-rutina, justo igual que lo har�a coroutine.create, pero en lugar de retornar la co-rutina misma, devuelve una funci�n que, cuando es invocada resume la co-rutina. Cualesquiera argumentos pasados a esta funci�n pasan como argumentos a coroutine.resume. coroutine.wrap devuelve todos los valores retornados por coroutine.resume, excepto el primero (el c�digo booleano de error). A diferencia de coroutine.resume, coroutine.wrap no captura errores; cualquier error se propaga a la rutina invocante.
Como ejemplo, consid�rese el siguiente 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"))
Cuando se ejecuta se produce la siguiente salida:
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 secci�n describe la API de C para Lua, esto es, el conjunto de funciones C disponibles para que el programa anfitri�n se comunique con Lua. Todas las funciones de la API y sus tipos y constantes relacionados est�n declaradas en el fichero de cabecera lua.h.
Aunque se usa el t�rmino "function", algunas rutinas en la API pueden ser macros. Todas esas macros usan cada uno de sus argumentos exactamente una vez (excepto su primer argumento, que es siempre el estado de Lua), y por tanto no generan efectos laterales ocultos.
Como en la mayor�a de las bibliotecas de C, la funciones API de Lua no verifican la validez ni la consistencia de sus argumentos. Sin embargo se puede cambiar este comportamiento compilando Lua con las definiciones adecuadas para la macro luai_apicheck, en el fichero luaconf.h.
Lua usa una pila virtual para pasar valores a y desde C. Cada elemento en esta pila representa un valor de Lua (nil, n�mero, string, etc.).
Siempre que Lua llame al C, la funci�n llamada obtiene una nueva pila, que es independiente de las pilas anteriores y de las pilas de las funciones C que todav�a est�n activas. Esta pila contiene inicialmente cualquier argumento de la funci�n C y es donde �sta coloca los resultados que deben ser devueltos a la rutina invocadora (v�ase lua_CFunction).
Por conveniencia, la mayor�a de las operaciones de petici�n de la API no siguen una disciplina estricta de pila. En su lugar pueden referirse a cualquier elemento en la pila usando un �ndice: un valor positivo representa una posici�n absoluta en la pila (comenzando en 1); un valor negativo representa un desplazamiento relativo a la parte superior de la pila. M�s espec�ficamente, si la pila tiene n elementos, entonces el �ndice 1 representa el primer elemento (esto es, el elemento que fue colocado primero en la pila) y un �ndice n representa el �ltimo elemento; un �ndice -1 tambi�n representa el �ltimo elemento (esto es, el elemento en la parte superior) y un �ndice -n representa el primer elemento. Decimos que un �ndice es v�lido si tiene un valor comprendido entre 1 y la parte superior de la pila (esto es, si 1 ≤ abs(�ndice) ≤ top).
Cuando el programador interacciona con la API de Lua es responsable de asegurar la consistencia. En particular es responsable de controlar el crecimiento correcto de la pila. Se puede usar la funci�n lua_checkstack para hacer crecer el tama�o de la pila.
Siempre que Lua llama al C, se asegura de que al menos existen LUA_MINSTACK posiciones disponibles en la pila. LUA_MINSTACK est� definida como 20, as� que normalmente el programador no tiene que preocuparse del espacio en la pila, a no ser que su c�digo tenga bucles que coloquen elementos en la pila.
La mayor�a de las funciones de petici�n aceptan como �ndice cualquier valor dentro del espacio disponible en la pila, o sea �ndices hasta el m�ximo del tama�o de la pila establecido mediante lua_checkstack. Esos �ndices se denominan �ndices aceptables.
M�s formalmente, definimos un �ndice aceptable de la siguiente manera:
(�ndice < 0 && abs(�ndice) <= top) ||
(�ndice > 0 && �ndice <= stackspace)
N�tese que 0 no es nunca un �ndice aceptable.
Excepto en los casos en que se indique, cualquier funci�n que acepta �ndices v�lidos tambi�n puede ser invocada con pseudo�ndices, los cuales representan algunos valores en Lua que son accesibles desde el c�digo en C pero que no est�n en la pila. Los pseudo�ndices son usados para acceder al entorno del proceso, al entorno de la funci�n, al registro y a los upvalues de una funci�n C (v�ase §3.4).
El entorno del proceso (donde "viven" las variables globales) est� siempre en el pseudo�ndice LUA_GLOBALSINDEX. El entorno de una funci�n C que est� en ejecuci�n est� siempre en el pseudo�ndice LUA_ENVIRONINDEX.
Para acceder y cambiar el valor de una variable global se pueden usar operaciones normales de tabla en la tabla de entorno. Por ejemplo, para acceder al valor de una variable global se hace
lua_getfield(L, LUA_GLOBALSINDEX, nombre_de_variable_global);
Cuando se crea una funci�n C es posible asociarle algunos valores, creando una instancia en C; esos valores se denominan upvalues y son accesibles a la funci�n en cualquier momento en que sea invocada (v�ase lua_pushcclosure).
Siempre que se invoque a una funci�n C sus upvalues se localizan en pseudo�ndices espec�ficos. �stos se producen mediante la macro lua_upvalueindex. El primer valor asociado con una funci�n est� en la posici�n lua_upvalueindex(1), y as� sucesivamente. Cualquier acceso a lua_upvalueindex(n), donde n es mayor que el n�mero de upvalues de la funci�n actual produce un �ndice aceptable pero inv�lido.
Lua proporciona un registro, una tabla predefinida que puede ser usada por cualquier c�digo en C para almacenar cualquier valor que Lua necesite guardar. Esta tabla se localiza siempre en el pseudo�ndice LUA_REGISTRYINDEX. Cualquier biblioteca de C puede almacenar datos en esta tabla, pero deber�a tener cuidado de elegir claves diferentes de aqu�llas usadas por otras bibliotecas, para evitar conflictos. T�picamente se podr�a usar como clave un string conteniendo el nombre de la biblioteca o userdata "ligeros" con la direcci�n de un objeto de C en el c�digo.
Las claves de tipo entero en el registro son usadas como mecanismo para referenciar, implementado en la biblioteca auxiliar, y por tanto no deber�an ser usados para otros prop�sitos diferentes.
Internamente Lua usa la funci�n de C longjmp para facilitar el manejo de errores. (Se puede tambi�n elegir usar directamente excepciones si se trabaja en C++; v�ase el fichero luaconf.h.) Cuando Lua se encuentra con cualquier error (tal como un error de asignaci�n de memoria, un error de tipo, un error de sintaxis o un error de ejecuci�n) entonces activa un error, esto es, realiza un salto largo en la memoria. Un entorno protegido usa setjmp para establecer un punto de recuperaci�n; cualquier error provoca un salto al punto de recuperaci�n activo m�s reciente.
Muchas funciones de la API pueden activar un error, por ejemplo debido a un problema de asignaci�n de memoria. La documentaci�n de cada funci�n indica si puede activar un error.
Dentro de una funci�n C se puede activar un error invocando lua_error.
He aqu� la lista de todas las funciones y tipos de la API de C por orden alfab�tico. Cada funci�n tiene un indicador como �ste: [-o, +p, x]
El primer campo, o, indica cu�ntos elementos elimina la funci�n en la pila. El segundo campo, p, es cuantos elementos coloca la funci�n en la pila. (Toda funci�n siempre coloca sus resultados despu�s de eliminar sus argumentos.) Un campo de la forma x|y significa que la funci�n puede colocar (o eliminar) x � y elementos, dependiendo de la situaci�n; un signo de interrogaci�n '?' significa que no se puede conocer cu�ntos elementos coloca/elimina la funci�n observando s�lo sus argumentos (por ejemplo, puede depender de lo qu� est� en la pila). El tercer, campo x, indica si la funci�n puede activar errores: '-' significa que la funci�n nunca activa errores; 'm' indica que la funci�n puede activar un error s�lo debido a falta de memoria; 'e' indica que la funci�n puede activar otros tipos de errores; 'v' indica que la funci�n puede activar un error a prop�sito.
lua_Alloc
typedef void * (*lua_Alloc) (void *ud,
void *ptr,
size_t osize,
size_t nsize);
El tipo de la funci�n que maneja la memoria usada por los estados de Lua. La funci�n que maneja memoria debe proporcionar una funcionalidad similar a realloc, pero no exactamente la misma. Sus argumentos son: ud, un puntero opaco pasado a lua_newstate; ptr, un puntero al bloque que est� siendo reservado/reasignado/liberado; osize, el tama�o original del bloque; nsize, el nuevo tama�o del bloque. ptr es NULL si y s�lo si osize es cero. Cuando nsize es cero, el manejador debe retornar NULL; si osize no es cero debe ser liberado el bloque apuntado por ptr. Cuando nsize no es cero el manejador retorna NULL si y s�lo si no puede ejecutar la petici�n. Cuando nsize no es cero y osize es cero el manejador deber�a comportarse como malloc. Cuando nsize y osize no son cero, el manejador se comporta como realloc. Lua asume que el manejador nunca falla cuando osize >= nsize.
He aqu� una implementaci�n simple para la funci�n manejadora de memoria. Es usada en la biblioteca auxiliar por lua_newstate.
static void *l_alloc (void *ud, void *ptr, size_t osize, size_t nsize) {
(void) ud; (void) osize; /* no usadas */
if (nsize == 0) {
free(ptr);
return NULL;
}
else
return realloc(ptr, nsize);
}
Este c�digo asume que free(NULL) no tiene efecto y que realloc(NULL, size) es equivalente a malloc(size). ANSI C asegura ambos comportamientos.
lua_atpanic[-0, +0, -]
lua_CFunction lua_atpanic (lua_State *L, lua_CFunction panicf);
Establece una nueva funci�n de p�nico y devuelve la vieja.
Si ocurre un error fuera de cualquier entorno protegido Lua llama a la funci�n p�nico y luego invoca exit(EXIT_FAILURE), saliendo por tanto de la aplicaci�n anfitriona. Si usa otra funci�n de p�nico diferente, �sta puede evitar esta salida sin retorno (por ejemplo, haciendo un salto largo).
La funci�n de p�nico puede acceder al mensaje de error en la parte superior de la pila.
lua_call[-(nargs + 1), +nresults, e]
void lua_call (lua_State *L, int nargs, int nresults);
Llama a una funci�n.
Para llamar a una funci�n se debe usar el siguiente protocolo: primero, la funci�n a ser invocada se coloca en la parte superior de la pila; entonces, se colocan tambi�n en la pila los argumentos de la funci�n en orden directo; esto es, el primer argumento se coloca primero. Finalmente, se llama a lua_call; nargs es el n�mero de argumentos que se han colocado en la pila. Todos los argumentos y el valor de la funci�n se eliminan de la pila cuando la funci�n es invocada. Los resultados de la funci�n se colocan en la parte superior de la pila cuando retorna la funci�n. El n�mero de resultados se ajusta a nresults, a no ser que nresults sea LUA_MULTRET. En este caso se colocan todos los resultados de la funci�n. Lua tiene cuidado de que los valores retornados se ajusten en el espacio de pila. Los resultados de la funci�n son colocados en la pila en orden directo (el primero es colocado antes), por lo que despu�s de la llamada el �ltimo resultado aparece en la parte superior de la pila.
Cualquier error dentro de la funci�n llamada se propaga hacia atr�s (con un longjmp).
El siguiente ejemplo muestra c�mo puede el programa anfitri�n hacer algo equivalente a este c�digo en Lua:
a = f("how", t.x, 14)
Aqu� est� en C:
lua_getfield(L, LUA_GLOBALSINDEX, "f"); /* funci�n que es llamada */
lua_pushstring(L, "how"); /* primer argumento */
lua_getfield(L, LUA_GLOBALSINDEX, "t"); /* tabla que es indexada */
lua_getfield(L, -1, "x"); /* coloca en la pila t.x (2� argumento) */
lua_remove(L, -2); /* elimina 't' de la pila */
lua_pushinteger(L, 14); /* 3� argumento */
lua_call(L, 3, 1); /* llama a la funci�n con 3 argumentos y 1 resultado */
lua_setfield(L, LUA_GLOBALSINDEX, "a"); /* modifica la variable global 'a' */
T�ngase presente que el c�digo de arriba est� "equilibrado" al final, pues la pila ha vuelto a su configuraci�n inicial. Esto est� considerado como una buena pr�ctica de programaci�n.
lua_CFunctiontypedef int (*lua_CFunction) (lua_State *L);
Tipo para las funciones C.
Con objeto de comunicar adecuadamente con Lua, una funci�n C debe usar el siguiente protocolo, el cual define la manera en que son pasados los argumentos y los resultados: una funci�n C recibe sus argumentos desde Lua en su pila en orden directo (el primer argumento se coloca primero). Por tanto, cuando comienza una funci�n, lua_gettop(L) devuelve el n�mero de argumentos recibidos por la funci�n. Su primer argumento (si existe) est� en el �ndice 1 y su �ltimo argumento est� en el �ndice lua_gettop(L). Para retornar valores a Lua una funci�n C s�lo los coloca en la pila, en orden directo (el primer resultado va primero), y retorna el n�mero de resultados. Cualquier otro valor en la pila por debajo de los resultados debe ser adecuadamente descartado por Lua. Como una funci�n Lua, una funci�n C llamada desde Lua puede retornar varios resultados.
Como ejemplo, la siguiente funci�n recibe un n�mero variable de argumentos num�ricos y retorna su media y su suma:
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, "argumento incorrecto en la funci�n 'media'");
lua_error(L);
}
sum += lua_tonumber(L, i);
}
lua_pushnumber(L, sum/n); /* primer resultado */
lua_pushnumber(L, sum); /* segundo resultado */
return 2; /* n�mero de resultados */
}
lua_checkstack[-0, +0, m]
int lua_checkstack (lua_State *L, int extra);
Se asegura de que hay al menos extra posiciones libres en la pila. Devuelve false si no puede hacer crecer la pila hasta ese tama�o. Esta funci�n nunca disminuye la pila; si la pila es ya m�s grande que el nuevo tama�o la deja sin modificar.
lua_close[-0, +0, -]
void lua_close (lua_State *L);
Destruye todos los objetos en el estado dado de Lua (llamando al correspondiente metam�todo de liberaci�n de memoria, si existe) y libera toda la memoria din�mica usada por este estado. En algunas plataformas puede no ser necesario llamar a esta funci�n, debido a que todos los recursos se liberan de manera natural cuando finaliza el programa anfitri�n. Por otro lado, programas de ejecuci�n larga, como puede ser el demonio de un servidor web, pueden necesitar la liberaci�n de estados tan pronto como �stos no se necesiten para evitar un crecimiento desmesurado.
lua_concat[-n, +1, e]
void lua_concat (lua_State *L, int n);
Concatena los n valores de la parte superior de la pila, los elimina y deja el resultado en la parte superior de la pila. Si n es 1 el resultado es el valor simple en la pila (esto es, la funci�n no hace nada); si n es 0 el resultado es un string vac�o. La concatenaci�n se realiza siguiendo la sem�ntica normal de Lua (v�ase §2.5.4).
lua_cpcall[-0, +(0|1), -]
int lua_cpcall (lua_State *L, lua_CFunction func, void *ud);
Invoca la funci�n C func en modo protegido. func comienza con un solo elemento en su pila, un userdata ligero conteniendo ud. En caso de errores lua_cpcall devuelve el mismo c�digo de error que lua_pcall, adem�s del objeto error en la parte superior de la pila; en caso contrario retorna cero y no cambia la pila. Todos los valores retornados por func se descartan.
lua_createtable[-0, +1, m]
void lua_createtable (lua_State *L, int narr, int nrec);
Crea una nueva tabla vac�a y la coloca en la pila. La nueva tabla tiene espacio reservado para narr elementos array y nrec elementos no array. Esta reserva es �til cuando no se sabe cu�ntos elementos va a contener la tabla. En otro caso se puede usar la funci�n lua_newtable.
lua_dump[-0, +0, m]
int lua_dump (lua_State *L, lua_Writer writer, void *data);
Vuelca una funci�n en forma de chunk binario. Recibe una funci�n de Lua en la parte superior de la pila y produce un chunk binario que si se carga de nuevo resulta en una funci�n equivalente a la volcada previamente. Seg�n va produciendo partes del chunk, lua_dump invoca a la funci�n writer (v�ase lua_Writer) con los datos data para escribirlos.
El valor retornado es el c�digo de error devuelto por la �ltima llamada a Writer; 0 significa no error.
Esta funci�n no elimina de la pila la funci�n de Lua.
lua_equal[-0, +0, e]
int lua_equal (lua_State *L, int index1, int index2);
Retorna 1 si los dos valores en los �ndices aceptables index1 e index2 son iguales, siguiendo la sem�ntica del operador == de Lua (esto es, puede invocar metam�todos). En otro caso retorna 0. Tambi�n devuelve 0 si alguno de los �ndices no es v�lido.
lua_error[-1, +0, v]
int lua_error (lua_State *L);
Genera un error de Lua. El mensaje de error (que puede ser realmente un valor de Lua de cualquier tipo) debe de estar en la parte superior de la pila. Esta funci�n realiza un salto largo, y por tanto nunca retorna. (v�ase luaL_error).
lua_gc[-0, +0, e]
int lua_gc (lua_State *L, int what, int data);
Controla el liberador de memoria.
Esta funci�n realiza varias tareas, de acuerdo con el valor del argumento what:
LUA_GCSTOP --- detiene el liberador de memoria.
LUA_GCRESTART --- reinicia el liberador de memoria.
LUA_GCCOLLECT --- realiza un ciclo completo de liberaci�n de memoria.
LUA_GCCOUNT --- retorna la cantidad actual de
memoria (en Kbytes) en uso por Lua.
LUA_GCCOUNTB --- retorna el resto de dividir por 1024 la cantidad actual de memoria en bytes en uso por Lua.
LUA_GCSTEP --- realiza un paso incremental de liberaci�n de memoria. El "tama�o" del paso est� controlado por data (un valor mayor significa m�s pasos) de una manera no especificada. Si se desea controlar el tama�o del paso se debe afinar experimentalmente el valor de data. La funci�n retorna 1 si el paso acab� con un ciclo de liberaci�n de memoria.
LUA_GCSETPAUSE --- establece data/100 como el nuevo valor de la pausa del liberador de memoria (v�ase §2.10). La funci�n retorna el valor previo de la pausa.
LUA_GCSETSTEPMUL --- establece data/100 como el nuevo valor del multiplicador del paso del liberador de memoria (v�ase §2.10). La funci�n retorna el valor previo del multiplicador.
lua_getallocf[-0, +0, -]
lua_Alloc lua_getallocf (lua_State *L, void **ud);
Retorna la funci�n manejadora de memoria de un estado dado. Si ud no es NULL Lua guarda en *ud el puntero opaco pasado a lua_newstate.
lua_getfenv[-0, +1, -]
void lua_getfenv (lua_State *L, int index);
Coloca en la pila la tabla de entorno de un valor en el �ndice dado.
lua_getfield[-0, +1, e]
void lua_getfield (lua_State *L, int index, const char *k);
Coloca en la pila el valor t[k], donde t es el valor dado por el �ndice v�lido. Como en Lua esta funci�n puede activar un metam�todo para el evento "index" (v�ase §2.8).
lua_getglobal[-0, +1, e]
void lua_getglobal (lua_State *L, const char *name);
Coloca en la pila el valor del nombre global. Est� definida como 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 en la pila la metatabla del valor situado en el �ndice aceptable dado. Si el �ndice no es v�lido o si el valor no tiene metatabla, la funci�n retorna 0 y no coloca nada en la pila.
lua_gettable[-1, +1, e]
void lua_gettable (lua_State *L, int index);
Coloca en la pila el valor t[k], donde t es el valor en el �ndice v�lido y k es el valor situado en la parte superior de la pila.
Esta funci�n quita la clave de la parte superior de la pila (colocando a su vez el valor resultante en su lugar). Como en Lua esta funci�n puede activar un metam�todo para el evento "index" (v�ase §2.8).
lua_gettop[-0, +0, -]
int lua_gettop (lua_State *L);
Retorna el �ndice del elemento situado en la parte superior de la pila. Debido a que los �ndices comienzan en 1 este resultado es igual al n�mero de elementos en la pila (y as�, 0 significa una pila vac�a).
lua_insert[-1, +1, -]
void lua_insert (lua_State *L, int index);
Mueve el elemento situado en la parte superior de la pila hacia el �ndice v�lido dado, desplazando hacia arriba los elementos por encima de este �ndice para abrir hueco. No puede ser invocada con un pseudo�ndice debido a que �ste no es una posici�n real en la pila.
lua_Integertypedef ptrdiff_t lua_Integer;
El tipo usado por la API de Lua para representar valores enteros.
Por defecto es ptrdiff_t, que es normalmente el tipo entero con signo m�s grande que la m�quina maneja "confortablemente".
lua_isboolean[-0, +0, -]
int lua_isboolean (lua_State *L, int index);
Retorna 1 si el valor en la situaci�n del �ndice aceptable tiene tipo booleano y 0 en caso contrario.
lua_iscfunction[-0, +0, -]
int lua_iscfunction (lua_State *L, int index);
Retorna 1 si el valor en la situaci�n del �ndice aceptable es una funci�n C y 0 en caso contrario.
lua_isfunction[-0, +0, -]
int lua_isfunction (lua_State *L, int index);
Retorna 1 si el valor en la situaci�n del �ndice aceptable es una funci�n (en C o en Lua) y 0 en caso contrario.
lua_islightuserdata[-0, +0, -]
int lua_islightuserdata (lua_State *L, int index);
Retorna 1 si el valor en la situaci�n del �ndice aceptable es un userdata ligero y 0 en caso contrario.
lua_isnil[-0, +0, -]
int lua_isnil (lua_State *L, int index);
Retorna 1 si el valor en la situaci�n del �ndice aceptable es nil y 0 en caso contrario.
lua_isnone[-0, +0, -]
int lua_isnone (lua_State *L, int index);
Retorna 1 si el valor en la situaci�n del �ndice aceptable es no v�lido (esto es, si se refiere a un elemento fuera de la pila actual) y 0 en caso contrario.
lua_isnoneornil[-0, +0, -]
int lua_isnoneornil (lua_State *L, int index);
Retorna 1 si el valor en la situaci�n del �ndice aceptable es no v�lido (esto es, si se refiere a un elemento fuera de la pila actual) o si el valor en este �ndice es nil, y 0 en caso contrario.
lua_isnumber[-0, +0, -]
int lua_isnumber (lua_State *L, int index);
Retorna 1 si el valor en la situaci�n del �ndice aceptable es un n�mero o un string convertible a n�mero y 0 en caso contrario.
lua_isstring[-0, +0, -]
int lua_isstring (lua_State *L, int index);
Retorna 1 si el valor en la situaci�n del �ndice aceptable es un string o un n�mero (que es siempre convertible a un string) y 0 en caso contrario.
lua_istable[-0, +0, -]
int lua_istable (lua_State *L, int index);
Retorna 1 si el valor en la situaci�n del �ndice aceptable es una tabla y 0 en caso contrario.
lua_isthread[-0, +0, -]
int lua_isthread (lua_State *L, int index);
Retorna 1 si el valor en la situaci�n del �ndice aceptable es un proceso y 0 en caso contrario.
lua_isuserdata[-0, +0, -]
int lua_isuserdata (lua_State *L, int index);
Retorna 1 si el valor en la situaci�n del �ndice aceptable es un userdata (ligero o completo) y 0 en caso contrario.
lua_lessthan[-0, +0, e]
int lua_lessthan (lua_State *L, int index1, int index2);
Retorna 1 si el valor situado en la posici�n del �ndice aceptable index1 es menor que el situado en la posici�n del �ndice aceptable index2, siguiendo la sem�ntica del operador < de Lua (esto es, puede invocar metam�todos). En caso contrario retorna 0. Tambi�n retorna 0 si alguno de los �ndices es inv�lido.
lua_load[-0, +1, -]
int lua_load (lua_State *L,
lua_Reader reader,
void *data,
const char *chunkname);
Carga un chunk de Lua. Si no hay errores, lua_load coloca el chunk compilado en la parte superior de la pila. En caso contrario coloca ah� un mensaje de error. Los valores de retorno de lua_load son:
LUA_ERRSYNTAX ---
error de sintaxis durante la precompilaci�n.
LUA_ERRMEM ---
error de reserva de memoria.
lua_load detecta autom�ticametne si el chunk est� en binario o en forma de texto, y lo carga de acuerdo con esto (v�ase el programa luac).
lua_load usa una funci�n lectora suplida por el usuario para leer el chunk (v�ase lua_Reader). El argumento data es un valor opaco pasado a la funci�n lectora.
El argumento chunkname da un nombre al chunk. el cual es usado en los mensajes de error y en la informaci�n de depuraci�n (v�ase §3.8).
lua_newstate[-0, +0, -]
lua_State *lua_newstate (lua_Alloc f, void *ud);
Crea un nuevo estado independiente. Retorna NULL si no puede crear el estado (debido a falta de memoria). El argumento f es la funci�n de reserva de memoria; Lua hace toda la reserva de memoria para este estado a trav�s de esta funci�n. El segundo argumento, ud, es un puntero opaco que Lua simplemente pasa al reservador de memoria en cada llamada.
lua_newtable[-0, +1, m]
void lua_newtable (lua_State *L);
Crea una nueva tabla vac�a y la coloca en la pila. Equivale a lua_createtable(L, 0, 0).
lua_newthread[-0, +1, m]
lua_State *lua_newthread (lua_State *L);
Crea un nuevo proceso, lo coloca en la pila y retorna un puntero a un lua_State que representa este nuevo proceso. El nuevo estado retornado por esta funci�n comparte con el original todos los objetos globales (como las tablas), pero tiene una pila de ejecuci�n independiente.
No existe una funci�n expl�cita para cerrar o destruir un proceso. Los procesos est�n sujetos a liberaci�n de memoria, como cualquier otro objeto de Lua.
lua_newuserdata[-0, +1, m]
void *lua_newuserdata (lua_State *L, size_t size);
Esta funci�n reserva un nuevo bloque de memoria con el tama�o dado, coloca en la pila un nuevo userdata completo con la direcci�n del bloque de memoria y retorna esta direcci�n.
Los userdata representan valores de C en Lua. Un userdata completo representa un bloque de memoria. Es un objeto (como una tabla): se puede crear, puede tener su propia metatabla y se puede detectar cu�ndo est� siendo eliminado de memoria. Un userdata completo es s�lo igual a s� mismo (en un test de igualdad directa).
Cuando Lua libera un userdata completo con un metam�todo gc, llama al metam�todo y marca el userdata como finalizado. Cuando este userdata es liberado de nuevo entonces es cuando Lua libera definitivamente la memoria correspondiente.
lua_next[-1, +(2|0), e]
int lua_next (lua_State *L, int index);
Elimina una clave de la pila y coloca un par clave-valor de una tabla en el �ndice dado (la "siguiente" pareja despu�s de la clave dada). Si no hay m�s elementos en la tabla entonces lua_next retorna 0 (y no coloca nada en la pila).
Una t�pica iteraci�n de recorrido de tabla ser�a:
/* la tabla est� en la pila en el �ndice 't' */
lua_pushnil(L); /* primera clave */
while (lua_next(L, t) != 0) {
/* 'clave' est� en el �ndice -2 y 'valor' en el �ndice -1 */
printf("%s - %s\n",
lua_typename(L, lua_type(L, -2)),
lua_typename(L, lua_type(L, -1)));
/* elimina 'valor'; mantiene 'clave' para la siguiente iteraci�n */
lua_pop(L, 1);
}
Mientras se recorre una tabla no debe llamarse a lua_tolstring directamente en una clave a no ser que se conozca que la clave es realmente un string. Recuerde que lua_tolstring cambia el valor en el �ndice dado; esto confunde a la siguiente llamada a lua_next.
lua_Numbertypedef double lua_Number;
El tipo de los n�meros en Lua. Por defecto es un double, pero puede ser cambiado en luaconf.h.
A trav�s del fichero de configuraci�n se puede cambiar Lua para que opere con otro tipo de n�meros (por ejemplo, float o long).
lua_objlen[-0, +0, -]
size_t lua_objlen (lua_State *L, int index);
Retorna la "longitud" de un valor situado en el �ndice aceptable: para un string, es la longitud del mismo; para una tabla, es el resultado del operador longitud ('#'); para un userdata, es el tama�o del bloque de memoria reservado para el mismo; para otros valores es 0.
lua_pcall[-(nargs + 1), +(nresults|1), -]
int lua_pcall (lua_State *L, int nargs, int nresults, int errfunc);
Invoca una funci�n en modo protegido.
Tanto nargs como nresults tienen el mismo significado que en lua_call. Si no hay errores durante la llamada, lua_pcall se comporta exactamente igual que lua_call. Sin embargo en caso de error lua_pcall lo captura, colocando un �nico valor en la pila (el mensaje de error) y retorna un c�digo de error. Como lua_call, lua_pcall siempre elimina la funci�n y sus argumentos de la pila.
Si errfunc es 0 entonces el mensaje de error retornado en la pila es exactamente el mensaje original. En otro caso, errfunc es el �ndice en la pila de una funci�n manejadora de error. (En la implementaci�n actual, este �ndice no puede ser un pseudo�ndice.) En caso de errores de ejecuci�n esta funci�n ser� llamada con el mensaje de error y el valor devuelto ser� el mensaje retornado en la pila por lua_pcall.
T�picamente la funci�n manejadora de error se usa para a�adir m�s informaci�n de depuraci�n al mensaje de error, tal como un "trazado inverso" de la pila. Esa informaci�n no puede ser recolectada despu�s del retorno de lua_pcall, puesto que por entonces la pila ya no tiene esa informaci�n.
La funci�n lua_pcall retorna 0 en caso de �xito o uno de los siguientes c�digos de error (definidos en lua.h):
LUA_ERRRUN --- un error de ejecuci�n.
LUA_ERRMEM --- un error de reserva de memoria. Para este error Lua no llama a la funci�n manejadora de error.
LUA_ERRERR ---
error mientras se est� ejecutando la funci�n manejadora de error.
lua_pop[-n, +0, -]
void lua_pop (lua_State *L, int n);
Elimina n elementos de la pila.
lua_pushboolean[-0, +1, -]
void lua_pushboolean (lua_State *L, int b);
Coloca el valor booleano b en la pila.
lua_pushcclosure[-n, +1, m]
void lua_pushcclosure (lua_State *L, lua_CFunction fn, int n);
Coloca en la pila una nueva instancia en C.
Cuando se crea una funci�n C es posible asociarle algunos valores, creando entonces una instancia en C (v�ase §3.4); estos valores son entonces accesibles a la funci�n en cualquier momento en que sea invocada. Para asociar valores a una funci�n C, primero �stos deber�an colocarse en la pila (cuando hay varios, el primero se coloca antes). Entonces se invoca lua_pushcclosure para crear y colocar la funci�n C en la pila, con el argumento n indicando cuantos valores est�n asociados con la misma. lua_pushcclosure tambi�n elimina esos valores de la pila.
lua_pushcfunction[-0, +1, m]
void lua_pushcfunction (lua_State *L, lua_CFunction f);
Coloca una funci�n C en la pila. Esta funci�n recibe un puntero a una funci�n C y coloca en la pila un valor de Lua de tipo function que, cuando se llama, invoca la correspondiente funci�n C.
Cualquier funci�n que sea registrada en Lua debe seguir el protocolo correcto para recibir sus argumentos y devolver sus resultados (v�ase lua_CFunction).
lua_pushcfunction(L, f) est� definida como una macro:
#define lua_pushcfunction(L, f) lua_pushcclosure(L, f, 0)
lua_pushfstring[-0, +1, m]
const char *lua_pushfstring (lua_State *L, const char *fmt, ...);
Coloca en la pila un string formateado y retorna un puntero a este string. Es similar a la funci�n sprintf de C, pero tiene con ella algunas importantes diferencias:
%%' (inserta un '%' en el string), '%s' (inserta un string terminado en cero sin restricciones de tama�o), '%f' (inserta un lua_Number), '%p' (inserta un puntero como n�mero hexadecimal), '%d' (inserta un int), y '%c' (inserta un int como car�cter).
lua_pushinteger[-0, +1, -]
void lua_pushinteger (lua_State *L, lua_Integer n);
Coloca un n�mero entero de valor n en la pila.
lua_pushlightuserdata[-0, +1, -]
void lua_pushlightuserdata (lua_State *L, void *p);
Coloca un userdata ligero en la pila.
Los userdata representan valores de C en Lua. Un userdata ligero representa un puntero. Es un valor (como un n�mero): no se crea ni tiene metatablas y no sufre liberaci�n de memoria (puesto que nunca fue reservada). En una comparaci�n de igualdad, un userdata ligero es igual que cualquier otro userdata ligero con la misma direcci�n en C.
lua_pushliteral[-0, +1, m]
void lua_pushliteral (lua_State *L, const char *s);
Esta macro es equivalente a lua_pushlstring,
pero puede ser usada solamente cuando s es un string literal.
En esos casos, proporciona autom�ticamente la longitud del string.
lua_pushlstring[-0, +1, m]
void lua_pushlstring (lua_State *L, const char *s, size_t len);
Coloca el string apuntado por s con tama�o len en la pila. Lua realiza (o reutiliza) una copia interna del string dado, as� que la memoria en s puede ser liberada o reutilizada inmediamente despu�s de que la funci�n retorne. El string puede contener ceros.
lua_pushnil[-0, +1, -]
void lua_pushnil (lua_State *L);
Coloca un valor nil en la pila.
lua_pushnumber[-0, +1, -]
void lua_pushnumber (lua_State *L, lua_Number n);
Coloca un n�mero con valor n en la pila.
lua_pushstring[-0, +1, m]
void lua_pushstring (lua_State *L, const char *s);
Coloca el string terminado en cero al que apunta s en la pila. Lua realiza (o reutiliza) una copia interna del string dado, as� que la memoria en s puede ser liberada o reutilizada inmediamente despu�s de que la funci�n retorne. El string no puede contener caracteres cero; se asume que el final del mismo es el primer car�cter cero que aparezca.
lua_pushthread[-0, +1, -]
int lua_pushthread (lua_State *L);
Coloca un proceso representado por L en la pila. Retorna 1 si este proceso es el proceso principal de su estado.
lua_pushvalue[-0, +1, -]
void lua_pushvalue (lua_State *L, int index);
Coloca una copia del elemento situado en el �ndice v�lido dado en la pila.
lua_pushvfstring[-0, +1, m]
const char *lua_pushvfstring (lua_State *L,
const char *fmt,
va_list argp);
Equivalente a lua_pushfstring, excepto que recibe un argumento de tipo va_list en lugar de un n�mero variable de argumentos.
lua_rawequal[-0, +0, -]
int lua_rawequal (lua_State *L, int index1, int index2);
Retorna 1 si los dos valores situados en los �ndices aceptables index1 e index2 son iguales de manera primitiva (esto es, sin invocar metam�todos). En caso contrario retorna 0. Tambi�n retorna 0 si alguno de los �ndices no es v�lido.
lua_rawget[-1, +1, -]
void lua_rawget (lua_State *L, int index);
Similar a lua_gettable, pero realiza un acceso directo (sin metam�todos).
lua_rawgeti[-0, +1, -]
void lua_rawgeti (lua_State *L, int index, int n);
Coloca en la pila el valor t[n], donde t es el valor en el �ndice v�lido. El acceso es directo, esto es, sin invocar metam�todos.
lua_rawset[-2, +0, m]
void lua_rawset (lua_State *L, int index);
Similar a lua_settable, pero realizando una asignaci�n directa (sin invocar metam�todos).
lua_rawseti[-1, +0, m]
void lua_rawseti (lua_State *L, int index, int n);
Realiza el equivalente a t[n] = v, donde t es el valor en el �ndice v�lido y v es el valor en la parte superior de la pila.
Esta funci�n elimina el valor de la parte superior de la pila. La asignaci�n es directa, sin invocar metam�todos.
lua_Reader
typedef const char * (*lua_Reader) (lua_State *L,
void *data,
size_t *size);
La funci�n de lectura usada por lua_load. Cada vez que necesita otro fragmento de chunk, lua_load llama al "lector", pas�ndole su argumento data. El lector debe retornar un puntero a un bloque de memoria con un nuevo fragmento de chunk y establece size como el tama�o del bloque. El bloque debe existir hasta que la funci�n lectora se invoque de nuevo. Para se�alar el final del chunk el lector debe retornar NULL. La funci�n lectora puede retornar fragmentos de cualquier tama�o mayor que cero.
lua_register[-0, +0, e]
void lua_register (lua_State *L,
const char *name,
lua_CFunction f);
Establece la funci�n C f como el nuevo valor del nombre global. Est� definida en la macro:
#define lua_register(L,n,f) \
(lua_pushcfunction(L, f), lua_setglobal(L, n))
lua_remove[-1, +0, -]
void lua_remove (lua_State *L, int index);
Elimina el elemento en la posici�n del �ndice v�lido dado, desplazando hacia abajo los elementos que estaban por encima de este �ndice para llenar el hueco. No puede ser llamada con un pseudo�ndice, debido a que �ste no es una posici�n real en la pila.
lua_replace[-1, +0, -]
void lua_replace (lua_State *L, int index);
Mueve el elemento que est� en la parte superior de la pila a la posici�n dada (y lo elimina de la parte superior de la pila), sin desplazar ning�n elemento de la misma (por tanto reemplazando el valor en la posici�n dada).
lua_resume[-?, +?, -]
int lua_resume (lua_State *L, int narg);
Comienza y resume una co-rutina en un proceso dado.
Para comenzar una co-rutina se debe crear un nuevo proceso (v�ase lua_newthread); entonces se coloca en su propia pila la funci�n principal m�s cualquier posible argumento; posteriormente se invoca lua_resume, con narg siendo el n�mero de argumentos. Esta llamada retorna cuando la co-rutina suspende o finaliza su ejecuci�n. Cuando retorna, la pila contiene todos los valores pasados a lua_yield, o todos los valores retornados por el cuerpo de la funci�n. lua_resume retorna LUA_YIELD si la co-rutina cedi� el control, 0 si la co-rutina acab� su ejecuci�n sin errores, o un c�digo de error en caso de errores (v�ase lua_pcall). En caso de error, se deja informaci�n en la pila, as� que se puede usar la API de depuraci�n con ella. El mensaje de error est� en la parte superior de la pila. Para reiniciar una co-rutina se ponen en la pila s�lo los valores que son pasados como resultado de yield, y entonces se invoca lua_resume.
lua_setallocf[-0, +0, -]
void lua_setallocf (lua_State *L, lua_Alloc f, void *ud);
Utiliza f con el userdata ud como funci�n de reserva de memoria de un estado dado .
lua_setfenv[-1, +0, -]
int lua_setfenv (lua_State *L, int index);
Elimina una tabla de la parte superior de la pila y la toma como nuevo entorno para el valor situado en la posici�n del �ndice. Si el valor dado no es ni una funci�n ni un proceso ni un userdata entonces lua_setfenv retorna 0. En caso contrario retorna 1.
lua_setfield[-1, +0, e]
void lua_setfield (lua_State *L, int index, const char *k);
Realiza el equivalente a t[k] = v, donde t es el valor en la posici�n del �ndice v�lido y v es el valor en la parte superior de la pila.
Esta funci�n elimina el valor de la pila. Como en Lua, esta funci�n puede activar un metam�todo para el evento "newindex" (v�ase §2.8).
lua_setglobal[-1, +0, e]
void lua_setglobal (lua_State *L, const char *name);
Elimina un valor de la pila y lo toma como nuevo valor del
nombre global. Est� definida en una macro:
#define lua_setglobal(L,s) lua_setfield(L, LUA_GLOBALSINDEX, s)
lua_setmetatable[-1, +0, -]
int lua_setmetatable (lua_State *L, int index);
Elimina una tabla de la pila y la toma como nueva metatabla para el valor en la situaci�n del �ndice aceptable.
lua_settable[-2, +0, e]
void lua_settable (lua_State *L, int index);
Hace el equivalente a t[k] = v, donde t es el valor en la posici�n del �ndice v�lido, v es el valor en la parte superior de la pila y k es el valor justamente debajo.
Esta funci�n elimina de la pila tanto la clave como el valor. Como en Lua, esta funci�n puede activar un metam�todo para el evento "newindex" (v�ase §2.8).
lua_settop[-?, +?, -]
void lua_settop (lua_State *L, int index);
Acepta cualquier �ndice aceptable � 0 y establece la parte superior de la pila en este �ndice. Si ese valor es mayor que el antiguo entonces los nuevos elementos se rellenan con nil. Si index es 0 entonces todos los elementos de la pila se eliminan.
lua_Statetypedef struct lua_State lua_State;
Estructura opaca que almacena todo el estado de un int�rprete de Lua. La biblioteca de Lua es totalmente re-entrante: no tiene variables globales. Toda la informaci�n acerca de un estado se guarda en esta estructura.
Un puntero a este estado debe ser pasado como primer argumento a cualquier funci�n de la biblioteca, excepto a lua_newstate, la cual crea un nuevo estado de Lua desde cero.
lua_status[-0, +0, -]
int lua_status (lua_State *L);
Retorna el estatus del proceso L.
El estatus puede ser 0 para un proceso normal, un c�digo de error si el proceso finaliza su ejecuci�n con un error, o LUA_YIELD si el proceso est� suspendido.
lua_toboolean[-0, +0, -]
int lua_toboolean (lua_State *L, int index);
Convierte el valor de Lua situado en la posici�n del �ndice aceptable en un booleano de C (0 � 1). Como todos los test en Lua, lua_toboolean retorna 1 para cada valor de Lua diferente de false y nil; en caso contrario retorna 0. Tambi�n retorna 0 cuando se invoca sin un �ndice v�lido. (Si se desea aceptar s�lo los valores booleanos reales, �sese lua_isboolean para verificar el tipo del valor.)
lua_tocfunction[-0, +0, -]
lua_CFunction lua_tocfunction (lua_State *L, int index);
Convierte en una funci�n C el valor situado en el �ndice aceptable. Este valor debe ser una funci�n C; en caso contrario retorna NULL.
lua_tointeger[-0, +0, -]
lua_Integer lua_tointeger (lua_State *L, int index);
Convierte el valor de Lua situado en el �ndice aceptable en un entero sin signo del tipo lua_Integer. El valor de Lua debe ser un n�mero o un string convertible a un n�mero (v�ase §2.2.1); en otro caso lua_tointeger retorna 0.
Si el n�mero no es entero se trunca de una manera no especificada.
lua_tolstring[-0, +0, m]
const char *lua_tolstring (lua_State *L, int index, size_t *len);
Convierte el valor de Lua situado en la posici�n del �ndice aceptable en un string (const char*). Si len no es NULL, tambi�n establece *len como longitud del mismo. El valor Lua puede ser un string o un n�mero; en caso contrario la funci�n retorna NULL. Si el valor es un n�mero entonces lua_tolstring tambi�n cambia el valor actual en la pila a un string. (Este cambio confunde a lua_next cuando lua_tolstring se aplica a claves durante el recorrido de una tabla.)
lua_tolstring retorna un puntero totalmente alineado a un string dentro de un estado de Lua. Este string siempre tiene un cero ('\0') despu�s de su �ltimo car�cter (como en C), pero puede contener otros ceros en su cuerpo. Debido a que Lua tiene liberaci�n de memoria, no existen garant�as de que el puntero retornado por lua_tolstring siga siendo v�lido despu�s de que el valor correspondiente sea eliminado de la pila.
lua_tonumber[-0, +0, -]
lua_Number lua_tonumber (lua_State *L, int index);
Convierte el valor Lua dado en la posicion del �ndice aceptable en un n�mero (v�ase lua_Number). El valor Lua debe ser un n�mero o un string convertible a n�mero (v�ase §2.2.1); en caso contrario lua_tonumber retorna 0.
lua_topointer[-0, +0, -]
const void *lua_topointer (lua_State *L, int index);
Convierte el valor situado en el �ndice aceptable en un puntero gen�rico de C (void*). El valor puede ser un userdata, una tabla, un proceso o una funci�n; en caso contrario lua_topointer retorna NULL. Lua se asegura de que diferentes objetos retornen diferentes punteros. No hay una manera directa de convertir un puntero de nuevo a su valor original.
T�picamente esta funci�n s�lo es usada para informaci�n de depuraci�n.
lua_tostring[-0, +0, m]
const char *lua_tostring (lua_State *L, int index);
Equivalente a lua_tolstring
con len igual a NULL.
lua_tothread[-0, +0, -]
lua_State *lua_tothread (lua_State *L, int index);
Convierte el valor en la posici�n del �ndice aceptable en un proceso de Lua (representado como lua_State*). Este valor debe ser un proceso; en caso contrario la funci�n retorna NULL.
lua_touserdata[-0, +0, -]
void *lua_touserdata (lua_State *L, int index);
Si el valor en la posici�n del �ndice aceptable es un userdata completo retorna la direcci�n de su bloque de memoria. Si el valor es un userdata ligero retorna su puntero. En otro caso retorna NULL.
lua_type[-0, +0, -]
int lua_type (lua_State *L, int index);
Retorna el tipo del valor situado en el �ndice aceptable o LUA_TNONE si la direcci�n es inv�lida (esto es, un �ndice a una posici�n "vac�a" en la pila). Los tipos retornados por lua_type est�n codificados por las siguientes constantes, definidas en lua.h:
LUA_TNIL,
LUA_TNUMBER,
LUA_TBOOLEAN,
LUA_TSTRING,
LUA_TTABLE,
LUA_TFUNCTION,
LUA_TUSERDATA,
LUA_TTHREAD
y LUA_TLIGHTUSERDATA.
lua_typename[-0, +0, -]
const char *lua_typename (lua_State *L, int tp);
Retorna el nombre del tipo codificado por el valor tp, el cual debe ser uno de los valores retornados lua_type.
lua_Writer
typedef int (*lua_Writer) (lua_State *L,
const void* p,
size_t sz,
void* ud);
La funci�n escritora usada por lua_dump. Cada vez que produce otro fragmento de chunk, lua_dump llama al escritor, pas�ndole el buffer para ser escrito (p), su tama�o (sz) y el argumento data proporcionado a lua_dump.
El escritor retorna un c�digo de error: 0 significa no errores y cualquier otro valor significa un error y evita que lua_dump llame de nuevo al escritor.
lua_xmove[-?, +?, -]
void lua_xmove (lua_State *from, lua_State *to, int n);
Intercambia valores entre diferentes procesos del mismo estado global.
Esta funci�n elimina n valores de la pila indicada por from y los coloca en la pila indicada por to.
lua_yield[-?, +?, -]
int lua_yield (lua_State *L, int nresults);
Produce la cesi�n de una co-rutina.
Esta funci�n deber�a ser llamada solamente como expresi�n de retorno de una funci�n C, como sigue:
return lua_yield (L, nresults);Cuando una funci�n C llama a
lua_yield de esta manera, la co-rutina que est� ejecut�ndose suspende su ejecuci�n, y la llamada a lua_resume que comenz� esta co-rutina retorna. El argumento nresults es el n�mero de valores de la pila que son pasados como resultados a lua_resume.
Lua no tiene utilidades de depuraci�n internas. En su lugar ofrece una interface especial por medio de funciones y hooks. Esta interface permite la construcci�n de diferentes tipos de depuradores, analizadores de c�digo y otras herramientas que necesitan "informaci�n interna" del int�rprete.
lua_Debug
typedef struct lua_Debug {
int event;
const char *name; /* (n) */
const char *namewhat; /* (n) */
const char *what; /* (S) */
const char *source; /* (S) */
int currentline; /* (l) */
int nups; /* (u) number of upvalues */
int linedefined; /* (S) */
int lastlinedefined; /* (S) */
char short_src[LUA_IDSIZE]; /* (S) */
/* private part */
other fields
} lua_Debug;
Una estructura usada para contener diferentes fragmentos de informaci�n acerca de la funci�n activa. lua_getstack rellena s�lo la parte privada de esta estructura, para su uso posterior. Para rellenar otros campos de lua_debug con informaci�n �til, ll�mese a lua_getinfo.
Los campos de lua_debug tienen el siguiente significado:
source:
Si la funci�n fue definida en un string entonces source es ese string. Si la funci�n fue definida en un fichero entonces source comienza con un car�cter '@' seguido del nombre del fichero.
short_src:
una versi�n "imprimible" de source, que ser� usada en los mensajes de error.
linedefined:
el n�mero de l�nea donde comienza la definici�n de la funci�n.
lastlinedefined:
el n�mero de l�nea donde acaba la definici�n de funci�n.
what:
el string "Lua" si la funci�n es una funci�n Lua, "C" si la funci�n es una funci�n C, "main" si es la parte principal de un chunk, y "tail" si es una funci�n que realiza una llamada de cola. Es el �ltimo caso Lua no tiene m�s informaci�n acerca de la funci�n.
currentline:
la l�nea actual donde la funci�n dada se est� ejecutando. Cuando esta informaci�n no est� disponible, currentline toma el valor -1.
name:
un nombre razonable para la funci�n dada. Debido a que las funciones en Lua son valores de primera clase, no tienen un nombre fijo: algunas funciones pueden ser el valor de variables globales, mientras que otras pueden ser almacenadas s�lo en un campo de una tabla. La funci�n lua_getinfo analiza c�mo fue invocada la funci�n para encontrarle un nombre adecuado. Si no puede encontrarlo entonces nombre se hace NULL.
namewhat:
explica el campo nombre. El valor de namewhat puede ser "global", "local", "method", "field", "upvalue" o "" (un string vac�o), de acuerdo a c�mo fue invocada la funci�n. (Lua usa un string vac�o cuando otras opciones no son id�neas.)
nups:
el numero de upvalues de la funci�n.
lua_gethook[-0, +0, -]
lua_Hook lua_gethook (lua_State *L);
Retorna la funci�n hook actual.
lua_gethookcount[-0, +0, -]
int lua_gethookcount (lua_State *L);
Retorna el contador de hook actual.
lua_gethookmask[-0, +0, -]
int lua_gethookmask (lua_State *L);
Retorna la m�scara del hook actual.
lua_getinfo[-(0|1), +(0|1|2), m]
int lua_getinfo (lua_State *L, const char *what, lua_Debug *ar);
Devuelve informaci�n acerca de una funci�n espec�fica o de una invocaci�n de funci�n.
Para obtener informaci�n acerca de una invocaci�n de funci�n, el par�metro ar debe ser un registro de activaci�n v�lido, que haya sido llenado con una llamada previa a
lua_getstack o dada como argumento a un hook
(v�ase lua_Hook).
Para obtener informaci�n de una funci�n se coloca la misma en la parte superior de la pila
y se comienza el string what con el car�cter '>'. (En ese caso,
lua_getinfo elimina la funci�n de la parte superior de la pila.) Por ejemplo,
para conocer en qu� l�nea fue definida una funci�n f se puede utilizar el
siguiente c�digo:
lua_Debug ar;
lua_getfield(L, LUA_GLOBALSINDEX, "f"); /* obtiene la 'f' global */
lua_getinfo(L, ">S", &ar);
printf("%d\n", ar.linedefined);
Cada car�cter en el string what selecciona los campos de la estructura ar que ser�n rellenados o un valor que ser� colocado en la parte superior de la pila:
n': rellena los campos name y namewhat;
S': rellena los campos source, short_src, linedefined, lastlinedefined y what;
l': rellena el campo currentline;
u': rellena el campo nups;
f': coloca en la pila la funci�n que est� ejecut�ndose al nivel dado;
L': coloca en la pila una tabla cuyos �ndices son los n�meros de las
l�neas que son v�lidas en la funci�n. (Una l�nea v�lida es una l�nea con alg�n c�digo
asociado, esto es, una l�nea donde se puede poner un punto de rotura. Las l�neas no v�lidas
incluyen l�neas vac�as y comentarios.
Esta funci�n devuelve 0 en caso de error (por ejemplo, una opci�n inv�lida en
what).
lua_getlocal[-0, +(0|1), -]
const char *lua_getlocal (lua_State *L, lua_Debug *ar, int n);
Obtiene informaci�n acerca de una variable local de un registro de activaci�n dado. El argumento ar debe ser un registro de activaci�n v�lido que fue rellenado en una llamada previa a lua_getstack o dado como argumento a un hook (v�ase lua_Hook). El �ndice n selecciona qu� variable local inspeccionar (1 es el primer argumento o la primera variable local activa, y as� sucesivamente, hasta la �ltima variable local activa). lua_getlocal coloca el valor de la variable en la pila y retorna su nombre.
Los nombres de variable que comienzan con '(' (par�ntesis de abrir) representan variables internas (variables de control de bucle, variables temporales y variables locales de funciones C).
Retorna NULL (y no coloca nada en la pila) cuando el �ndice es mayor que el n�mero de variables locales activas.
lua_getstack[-0, +0, -]
int lua_getstack (lua_State *L, int level, lua_Debug *ar);
Obtiene informaci�n acerca de la pila en ejecuci�n del int�rprete.
Esta funci�n rellena partes de una estructura lua_debug con una identificaci�n del registro de activaci�n de la funci�n que se est� ejecutando al nivel dado. Nivel 0 es la funci�n actualmente en ejecuci�n, mientras que el nivel n+1 es la funci�n que ha invocado a la del nivel n. Cuando no hay errores, lua_getstack retorna 1; cuando se llama con un nivel mayor que el tama�o de la pila retorna 0.
lua_getupvalue[-0, +(0|1), -]
const char *lua_getupvalue (lua_State *L, int funcindex, int n);
Obtiene informaci�n acerca de un upavalue de una instancia. (Para las funciones Lua los upvalues son variables locales externas a la funci�n que las usa, y que, por consiguiente, est�n incluidas en su instancia.) lua_getupvalue obtiene el �ndice n de un upvalue, coloca su valor en la pila y retorna su nombre. funcindex apunta hacia la instancia en la pila. (Los upvalues no siguen un orden particular, puesto que est�n activos a lo largo de toda la funci�n. Por tanto, est�n numerados siguiendo un orden arbitrario.)
Retorna NULL (y no coloca nada en la pila) cuando el �ndice es mayor que el n�mero de upvalues. Para funciones C esta funci�n usa el string vac�o "" como nombre para todos los upvalues.
lua_Hooktypedef void (*lua_Hook) (lua_State *L, lua_Debug *ar);
Tipo para funciones hook de depuraci�n.
Cada vez que se invoca un hook su argumento ar tiene en su campo event el evento que ha activado el hook. Lua identifica estos eventos con las siguientes constantes: LUA_HOOKCALL, LUA_HOOKRET, LUA_HOOKTAILRET, LUA_HOOKLINE y LUA_HOOKCOUNT. Adem�s, para eventos de l�nea, tambi�n se establece el campo currentline. Para obtener el valor de alg�n otro campo en ar, el hook debe invocar a lua_getinfo. Para eventos de retorno, event puede ser LUA_HOOKRET, el valor normal, o LUA_HOOKTAILRET. En el �ltimo caso, Lua est� simulando un retorno de una funci�n que ha hecho una llamada de cola; en este caso, es in�til llamar a lua_getinfo.
Mientras Lua est� ejecutando un hook, deshabilita otras llamadas a hooks. Por tanto, si un hook llama de nuevo a Lua para ejecutar una funci�n o un chunk entonces esa ejecuci�n ocurre sin ninguna llamada a hooks.
lua_sethook[-0, +0, -]
int lua_sethook (lua_State *L, lua_Hook f, int mask, int count);
Establece la funci�n hook de depuraci�n.
func es la funci�n hook. mask especifica en qu� eventos debe ser llamado el hook: se forma mediante la operaci�n "or" aplicada a los bits de las constantes LUA_MASKCALL, LUA_MASKRET, LUA_MASKLINE, y LUA_MASKCOUNT. El argumento count s�lo tiene sentido cuando la m�scara incluye LUA_MASKCOUNT. Para cada evento, el hook es invocado como se explica a continuaci�n:
count. (Este evento s�lo ocurre cuando Lua est� ejecutando una funci�n Lua.)
Un hook se deshabilita estableciendo mask a cero.
lua_setlocal[-(0|1), +0, -]
const char *lua_setlocal (lua_State *L, lua_Debug *ar, int n);
Establece el valor de una variable local de un registro de activaci�n dado. Los argumentos ar y n son como los de lua_getlocal. lua_setlocal asigna el valor en la parte superior de la pila a la variable y retorna su nombre. Tambi�n elimina de la pila su valor.
Retorna NULL (y no hace nada con la pila) cuando el �ndice es mayor que el n�mero de variables locales activas.
lua_setupvalue[-(0|1), +0, -]
const char *lua_setupvalue (lua_State *L, int funcindex, int n);
Establece el valor de un upvalue de una instancia. Los argumentos funcindex y n son como los de lua_getupvalue. Asigna el valor que est� en la parte superior de la pila al upvalue y retorna su nombre. Tambi�n elimina de la pila el valor.
Retorna NULL (y no hace nada con la pila) cuando
el �ndice es mayor que el n�mero de upavalues.
La biblioteca auxiliar proporciona varias funciones convenientes para realizar la interface de C con Lua. Mientras que la API b�sica proporciona las funciones primitivas para todas las interaciones entre C y Lua, la biblioteca auxiliar proporciona funciones de alto nivel para algunas tareas comunes.
Todas las funciones de la biblioteca auxiliar est�n definidas en el fichero de cabecera lauxlib.h y llevan el prefijo luaL_.
Todas ellas est�n construidas encima de la API b�sica as� que realmente no proporcionan nada nuevo que no pueda ser realizado con la API.
Algunas funciones en la biblioteca auxiliar son usadas para verificar argumentos de funciones C. Sus nombres son siempre luaL_check* o luaL_opt*. Todas estas funciones activan un error si la verificaci�n no se satisface. Debido a que el mensaje de error se formatea para los argumentos (por ejemplo, "bad argument #1"), no se deber�an usar estas funciones para otros valores de la pila.
Aqu� tenemos la lista de todas las funciones y tipos de la biblioteca auxiliar por orden alfab�tico.
luaL_addchar[-0, +0, m]
void luaL_addchar (luaL_Buffer *B, char c);
A�ade el car�cter c al buffer B (v�ase luaL_Buffer).
luaL_addlstring[-0, +0, m]
void luaL_addlstring (luaL_Buffer *B, const char *s, size_t l);
A�ade el string al que apunta s con longitud l al buffer B (v�ase luaL_Buffer). El string puede contener ceros.
luaL_addsize[-0, +0, m]
void luaL_addsize (luaL_Buffer *B, size_t n);
A�ade un string de longitud n previamente copiado en el �rea del buffer (v�ase luaL_prepbuffer) al buffer B (v�ase luaL_Buffer).
luaL_addstring[-0, +0, m]
void luaL_addstring (luaL_Buffer *B, const char *s);
A�ade un string terminado en cero al que apunta s al buffer B (v�ase luaL_Buffer). El string no puede contener ceros.
luaL_addvalue[-1, +0, m]
void luaL_addvalue (luaL_Buffer *B);
A�ade el valor situado en la parte superior de la pila al buffer B (v�ase luaL_Buffer), elimin�ndolo de la pila.
�sta es la �nica funci�n asociada a los buffers de string que puede (y debe) ser invocada con un elemento extra en la pila, que es el valor que debe ser a�adido al buffer.
luaL_argcheck[-0, +0, v]
void luaL_argcheck (lua_State *L,
int cond,
int narg,
const char *extramsg);
Verifica si cond es verdadero. Si no es as� activa un error con el mensaje
"bad argument #<numarg> to <func> (<extramsg>)"donde
func es recuperado de la pila de llamada.
luaL_argerror[-0, +0, v]
int luaL_argerror (lua_State *L, int narg, const char *extramsg);
Activa un error con el mensaje
"bad argument #<numarg> to <func> (<extramsg>)"donde
func es recuperado de la pila de llamada.
Esta funci�n nunca retorna, pero es corriente usarla en funciones C
en la forma return luaL_argerror(args).
luaL_Buffertypedef struct luaL_Buffer luaL_Buffer;
Tipo para un buffer de string.
Un buffer de string permite al c�digo en C construir a trozos strings de Lua. Su metodolog�a de uso es como sigue:
b de tipo luaL_Buffer.
luaL_buffinit(L, &b).
luaL_add*.
luaL_pushresult(&b). Esta llamada deja el string final en la parte superior de la pila.
Durante su operaci�n normal, un buffer de strings usa un n�mero variable de posiciones en la pila. As�, mientras se est� usando el buffer, no se puede asumir que se conoce la posici�n de la parte superior de la pila. Se puede usar la pila entre llamadas sucesivas a las operaciones de buffer siempre que su uso est� equilibrado; esto es, cuando se invoca una operaci�n con el buffer, la pila est� al mismo nivel en el que estaba inmediatamente antes de la operaci�n previa con el buffer. (La �nica excepci�n a esta regla es luaL_addvalue.) Despu�s de llamar a luaL_pushresult la pila est� de nuevo en el mismo nivel que ten�a cuando el buffer fue inicializado, m�s el string final en su parte superior.
luaL_buffinit[-0, +0, e]
void luaL_buffinit (lua_State *L, luaL_Buffer *B);
Inicializa un buffer B. Esta funci�n no reserva ning�n espacio nuevo de memoria; el buffer debe ser declarado como variable (v�ase luaL_Buffer).
luaL_callmeta[-0, +(0|1), e]
int luaL_callmeta (lua_State *L, int obj, const char *e);
Invoca un metam�todo.
Si el objeto con �ndice obj tiene una metatabla y �sta tiene un campo e, esta funci�n llama a este campo y le pasa el objeto como �nico argumento. En este caso la funci�n retorna 1 y coloca en la pila el valor devuelto por la llamada. Si no hay metatabla o no hay metam�todo la funci�n retorna 0 (sin colocar ning�n valor en la pila).
luaL_checkany[-0, +0, v]
void luaL_checkany (lua_State *L, int narg);
Verifica si la funci�n tiene un argumento de alg�n tipo (incluyendo nil) en la posici�n narg.
luaL_checkint[-0, +0, v]
int luaL_checkint (lua_State *L, int narg);
Verifica si el argumento narg de la funci�n es un n�mero y retorna este n�mero como int (realizando un cast en C).
luaL_checkinteger[-0, +0, v]
lua_Integer luaL_checkinteger (lua_State *L, int narg);
Verifica si el argumento narg de la funci�n es un n�mero y lo retorna como tipo lua_Integer.
luaL_checklong[-0, +0, v]
long luaL_checklong (lua_State *L, int narg);
Verifica si el argumento narg de la funci�n es un n�mero y lo retorna como long (realizando un cast en C).
luaL_checklstring[-0, +0, v]
const char *luaL_checklstring (lua_State *L, int narg, size_t *l);
Verifica si el argumento narg de la funci�n es un string y retorna el mismo; si l no es NULL coloca la longitud del string en *l.
Esta funci�n usa lua_tolstring para
obtener su resultado, por lo que todas las conversiones y precauciones asociados
a esa funci�n se aplican aqu�.
luaL_checknumber[-0, +0, v]
lua_Number luaL_checknumber (lua_State *L, int narg);
Verifica si el argumento narg de la funci�n es un n�mero y retorna el mismo.
luaL_checkoption[-0, +0, v]
int luaL_checkoption (lua_State *L,
int narg,
const char *def,
const char *const lst[]);
Verifica si el argumento narg de la funci�n es un string y busca �ste en el array lst (que debe estar terminado con NULL). Retorna el �ndice en el array donde se encontr� el string. Activa un error si el argumento no es un string o si no pudo ser encontrado el string.
Si def no es NULL, se usa def como valor por defecto cuando la funci�n no tiene un argumento narg o si este argumento es nil.
�sta es una funci�n �til para hacer corresponder strings con enumeraciones de C. La convenci�n normal en las bibliotecas de Lua es usar strings en lugar de n�meros para seleccionar opciones.
luaL_checkstack[-0, +0, v]
void luaL_checkstack (lua_State *L, int sz, const char *msg);
Incrementa el tama�o de la pila a top + sz elementos, activando un error si la pila no puede crecer hasta ese tama�o. msg es un texto adicional que ir�a en el mensaje de error.
luaL_checkstring[-0, +0, v]
const char *luaL_checkstring (lua_State *L, int narg);
Verifica si el argumento narg de la funci�n es un string y retorna �ste.
Esta funci�n usa lua_tolstring para
obtener su resultado, por lo que todas las conversiones y precauciones asociados
a esa funci�n se aplican aqu�.
luaL_checktype[-0, +0, v]
void luaL_checktype (lua_State *L, int narg, int t);
Verifica si el argumento narg de la funci�n tiene tipo t.
luaL_checkudata[-0, +0, v]
void *luaL_checkudata (lua_State *L, int narg, const char *tname);
Verifica si el argumento narg de la funci�n es un userdata del tipo tname (v�ase luaL_newmetatable).
luaL_dofile[-0, +?, m]
int luaL_dofile (lua_State *L, const char *filename);
Carga y ejecuta el fichero dado. Est� definida en una macro:
(luaL_loadfile(L, filename) || lua_pcall(L, 0, LUA_MULTRET, 0))
Devuelve 0 si no hay errores � 1 en caso de error.
luaL_dostring[-0, +?, m]
int luaL_dostring (lua_State *L, const char *str);
Carga y ejecuta el string dado. Est� definida en una macro:
(luaL_loadstring(L, str) || lua_pcall(L, 0, LUA_MULTRET, 0))
Devuelve 0 si no hay errores � 1 en caso de error.
luaL_error[-0, +0, v]
int luaL_error (lua_State *L, const char *fmt, ...);
Activa un error. El formato del mensaje est� dado por fmt m�s cualesquiera argumentos extra, siguiendo las mismas reglas de lua_pushfstring. Tambi�n a�ade al principio del mensaje el nombre del fichero y el n�mero de l�nea donde ocurri� el error, si esta informaci�n est� disponible.
Esta funci�n nunca retorna, pero es corriente usarla en la forma return luaL_error(args) en funciones C.
luaL_getmetafield[-0, +(0|1), m]
int luaL_getmetafield (lua_State *L, int obj, const char *e);
Coloca en la parte superior de la pila el campo e de la metatabla del objeto situado en la posici�n del �ndice obj. Si el objeto no tiene metatabla o si el objeto no tiene este campo retorna 0 y deja la pila intacta.
luaL_getmetatable[-0, +1, -]
void luaL_getmetatable (lua_State *L, const char *tname);
Coloca en la parte superior de la pila la metatabla asociada con el nombre tname en el registro (v�ase luaL_newmetatable).
luaL_gsub[-0, +1, m]
const char *luaL_gsub (lua_State *L,
const char *s,
const char *p,
const char *r);
Crea una copia del string s reemplazando cualquier aparici�n del string p por el string r. Coloca el string resultante en la parte superior de la pila y devuelve su valor.
luaL_loadbuffer[-0, +1, m]
int luaL_loadbuffer (lua_State *L,
const char *buff,
size_t sz,
const char *name);
Carga un buffer como chunk de Lua. Esta funci�n usa lua_load para cargar el chunk en el buffer apuntado por buff con tama�o sz.
Esta funci�n retorna el mismo resultado que lua_load. name es el nombre del chunk, usado para informaci�n de depuraci�n y en los mensajes de error.
luaL_loadfile[-0, +1, m]
int luaL_loadfile (lua_State *L, const char *filename);
Carga un fichero como chunk de Lua. Esta funci�n usa lua_load para cargar el chunk que est� en el fichero filename. Si filename es NULL entonces se carga desde la entrada est�ndar. La primera l�nea en el fichero se ignora si comienza por #.
Esta funci�n retorna el mismo resultado que lua_load, pero tiene un c�digo extra de error LUA_ERRFILE si no puede leer o abrir el fichero.
Como lua_load esta funci�n s�lo carga el chunk y no lo ejecuta.
luaL_loadstring[-0, +1, m]
int luaL_loadstring (lua_State *L, const char *s);
Carga un string como chunk de Lua. Esta funci�n usa lua_load para cargar el chunk que est� en el string s terminado en un car�cter cero.
Esta funci�n retorna el mismo resultado que lua_load.
Como lua_load esta funci�n s�lo carga el chunk y no lo ejecuta.
luaL_newmetatable[-0, +1, m]
int luaL_newmetatable (lua_State *L, const char *tname);
Si el registro tiene ya una clave tname retorna 0. En caso contrario crea una nueva tabla que ser� usada como metatabla del userdata, a�adiendo la clave tname al registro, y retornando 1.
En ambos caso coloca en la parte superior de la pila el valor final asociado con tname en el registro.
luaL_newstate[-0, +0, -]
lua_State *luaL_newstate (void);
Crea un nuevo estado de Lua, invocando lua_newstate con una funci�n de reserva de memoria basada en la funci�n C est�ndar realloc y estableciendo una funci�n de "p�nico" (v�ase lua_atpanic) que imprime un mensaje en la salida est�ndar de error en caso de error fatal.
Retorna el nuevo estado o NULL si surgi� un error de reserva de memoria.
luaL_openlibs[-0, +0, m]
void luaL_openlibs (lua_State *L);
Abre todas las bibliotecas est�ndar de Lua en el estado dado.
luaL_optint[-0, +0, v]
int luaL_optint (lua_State *L, int narg, int d);
Si el argumento narg de la funci�n es un n�mero retorna �ste como un int. Si este argumento est� ausente o es nil retorna d. En otro caso activa un error.
luaL_optinteger[-0, +0, v]
lua_Integer luaL_optinteger (lua_State *L,
int narg,
lua_Integer d);
Si el argumento narg de la funci�n es un n�mero retorna el mismo como lua_Integer. Si este argumento est� ausente o es nil retorna d. En caso contrario activa un error.
luaL_optlong[-0, +0, v]
long luaL_optlong (lua_State *L, int narg, long d);
Si el argumento narg de la funci�n es un n�mero retorna el mismo como long. Si este argumento est� ausente o es nil retorna d. En caso contrario activa un error.
luaL_optlstring[-0, +0, v]
const char *luaL_optlstring (lua_State *L,
int narg,
const char *d,
size_t *l);
Si el argumento narg de la funci�n es un string retorna �ste. Si este argumento est� ausente o es nil retorna d. En caso contrario activa un error.
Si l no es NULL coloca la longitud del resultado en *l.
luaL_optnumber[-0, +0, v]
lua_Number luaL_optnumber (lua_State *L, int narg, lua_Number d);
Si el argumento narg de la funci�n es un n�mero retorna el mismo. Si este argumento est� ausente o es nil retorna d. En caso contrario activa un error.
luaL_optstring[-0, +0, v]
const char *luaL_optstring (lua_State *L,
int narg,
const char *d);
Si el argumento narg de la funci�n es un string retorna �ste. Si este argumento est� ausente o es nil retorna d. En caso contrario activa un error.
luaL_prepbuffer[-0, +0, -]
char *luaL_prepbuffer (luaL_Buffer *B);
Retorna una direcci�n que apunta a un espacio de tama�o LUAL_BUFFERSIZE donde se puede copiar un string para ser a�adido al buffer B (v�ase luaL_Buffer). Despu�s de copiar el string en este espacio se debe invocar luaL_addsize con el tama�o del string para a�adirlo realmente en el buffer.
luaL_pushresult[-?, +1, m]
void luaL_pushresult (luaL_Buffer *B);
Finaliza el uso del buffer B dejando el string en la parte superior de la pila.
luaL_ref[-1, +0, m]
int luaL_ref (lua_State *L, int t);
Crea y retorna una referencia en la tabla en la posici�n del �ndice t para el objeto en la parte superior de la pila (y elimina el mismo de la pila).
Una referencia es una clave entera �nica. Mientras que no se a�adan manualmente claves enteras a la tabla t, luaL_ref asegura la unicidad de la clave que retorna. Se puede recuperar un objeto apuntado por la referencia r invocando lua_rawgeti(L, t, r). La funci�n luaL_unref elimina una referencia y su objeto asociado.
Si el objeto en la parte superior de la pila es nil, luaL_ref retorna la constante LUA_REFNIL. Est� garantizado que la constante LUA_NOREF es diferente de cualquier referencia retornada por luaL_ref.
luaL_Reg
typedef struct luaL_Reg {
const char *name;
lua_CFunction func;
} luaL_Reg;
Tipo para arrays de funciones para ser registradas por
luaL_register.
name es el nombre de la funci�n y func es un puntero a la misma.
Cualquier array de luaL_Reg debe finalizar con
una entrada "centinela" en la que tanto name como func son NULL.
luaL_register[-(0|1), +1, m]
void luaL_register (lua_State *L,
const char *libname,
const luaL_Reg *l);
Abre una biblioteca.
Cuando se llama con libname igual a NULL simplemente registra todas las funciones de la lista l (v�ase luaL_Reg) en la tabla que est� en la parte superior de la pila.
Cuando se llama con un valor libname no nulo crea una nueva tabla t, establece la misma como valor de la variable global libname, establece la misma como valor de package.loaded[libname] y registra en ella todas las funciones de la lista l. Si existe una tabla en package.loaded[libname] o en la variable libname reutiliza esta tabla en lugar de crear una nueva.
En cualquier caso la funci�n deja la tabla en la parte superior de la pila.
luaL_typename[-0, +0, -]
const char *luaL_typename (lua_State *L, int index);
Retorna el nombre del tipo del valor situado en el �ndice dado.
luaL_typerror[-0, +0, v]
int luaL_typerror (lua_State *L, int narg, const char *tname);
Genera un error con un mensaje de la forma:
location: bad argument narg to function (tname expected, got rt)donde location est� producida por
luaL_where, function es el nombre de la funci�n actual y rt es el nombre del tipo del argumento actual.
luaL_unref[-0, +0, -]
void luaL_unref (lua_State *L, int t, int ref);
Libera la referencia ref de la tabla en el �ndice t (v�ase luaL_ref). La entrada es eliminada de la tabla, por lo que la memoria reservada para el objeto referido en la misma puede ser liberada. La referencia ref tambi�n es liberada para poder ser reutilizada.
Si ref es LUA_NOREF o LUA_REFNIL,
luaL_unref no hace nada.
luaL_where[-0, +1, m]
void luaL_where (lua_State *L, int lvl);
Coloca en la parte superior de la pila un string identificando la posici�n actual del control en el nivel lvl en la pila de llamada. T�picamente este string tiene el formato:
chunkname:currentline:
Nivel 0 es la funci�n actualmente ejecut�ndose, nivel 1 es la funci�n que llam� a la funci�n actual, etc.
Esta funci�n se usa para construir un prefijo para los mensajes de error.
Las bibliotecas est�ndar de Lua proporcionan funciones �tiles que est�n implementadas directamente a trav�s de la API de C. Algunas de estas funciones proveen servicios esenciales al lenguaje (por ejemplo, type y getmetatable); otras proporcionan acceso a servicios "externos" (por ejemplo, I/O); y otras podr�an ser implementadas en Lua mismo pero son muy �tiles o tienen requerimientos cr�ticos de tiempo de ejecuci�n y merecen una implementaci�n en C (por ejemplo, sort).
Todas las bibliotecas est�n implementadas a trav�s de la API oficial de C y se proporcionan como m�dulos separados en C. En estos momentos Lua tiene las siguientes bibliotecas est�ndar:
Para tener acceso a estas bibliotecas el programa anfitri�n en C debe invocar a luaL_openlibs, la cual abre todas las bibliotecas est�ndar. De manera alternativa se pueden abrir individualmente invocando a luaopen_base (la biblioteca b�sica), luaopen_package (la biblioteca de empaquetado), luaopen_string (la biblioteca de strings), luaopen_table (la biblioteca de tablas), luaopen_math (la biblioteca matem�tica), luaopen_io (la biblioteca de entrada/salida), luaopen_os (la biblioteca del Sistema Operativo) y luaopen_debug (la biblioteca de depuraci�n). Estas funciones est�n declaradas en lualib.h y no deber�an ser invocadas directamente: se deben llamar como a otra funci�n C cualquiera de Lua, por ejemplo, usando lua_call.
La biblioteca b�sica proporciona algunas funciones del n�cleo de Lua. Si no se desea incluir esta biblioteca en una aplicaci�n se debe analizar cuidadosamente si se necesitan proporcionar implementaciones de algunas de sus utilidades.
assert (v [, mensaje])Activa un error cuando el valor de su argumento v es falso (por ejemplo, nil o false); en otro caso retorna todos sus argumentos. mensaje es un mensaje de error; cuando est� ausente se utiliza por defecto "assertion failed!".
collectgarbage (opt [, arg])Esta funci�n es una interface gen�rica al liberador de memoria. Realiza diversas funciones de acuerdo a su primer argumento, opt:
arg (valores grandes significan m�s pasos) de una manera no especificada. Si se desea controlar el tama�o del paso se debe afinar experimentalmente el valor de arg. Devuelve true si el paso acaba un ciclo de liberaci�n.
arg/100 como el nuevo valor para la pausa del liberador (v�ase §2.10).
arg/100 como el nuevo valor para el multiplicador del paso del liberador (v�ase §2.10).
dofile (nombre_de_fichero)Abre el fichero con el nombre dado y ejecuta su contenido como un chunk de Lua. Cuando se invoca sin argumentos, dofile ejecuta el contenido de la entrada est�ndar (stdin). Devuelve todos los valores retornados por el chunk. En caso de error, dofile propaga el error a su invocador (esto es, dofile no se ejecuta en modo protegido).
error (mensaje [, nivel])mensaje como mensaje de error. La funci�n error nunca retorna.
Normalmente error a�ade, al comienzo del mensaje, cierta informaci�n acerca de la posici�n del error. El argumento nivel especifica c�mo obtener la posici�n del error. Con nivel 1 (por defecto) la posici�n del error es donde fue invocada la funci�n error. Nivel 2 apunta el error hacia el lugar en que fue invocada la funci�n que llam� a error; y as� sucesivamente. Pasar un valor 0 como nivel evita la adici�n de la informaci�n de la posici�n al mensaje.
_G_G._G = _G). Lua mismo no usa esta variable; cambiar su valor no afecta ning�n entorno, ni viceversa. (�sese setfenv para cambiar entornos.)
getfenv ([f])Retorna el entorno actualmente en uso por la funci�n. f puede ser una funci�n Lua o un n�mero que especifica la funci�n a ese nivel de la pila: nivel 1 es la funci�n que invoca a getfenv. Si la funci�n dada no es una funci�n Lua o si f es 0, getfenv retorna el entorno global. El valor por defecto de f es 1.
getmetatable (objeto)Si objeto no tiene una metatabla devuelve nil. En otro caso, si la metatabla del objeto tiene un campo "__metatable" retorna el valor asociado, o si no es as� retorna la metatabla del objeto dado.
ipairs (t)Retorna tres valores: una funci�n iteradora, la tabla t, y 0, de tal modo que la construcci�n
for i,v in ipairs(t) do bloque enditerar� sobre los pares (
1,t[1]), (2,t[2]), ···, hasta la primera clave entera con un valor nil en la tabla.
load (func [, nombre_de_chunk])Carga un chunk usando la funci�n func para obtener sus partes.
Cada llamada a func debe retornar un string que se concatena con los resultados previos. Un retorno de nil (o no valor) se�ala el final del chunk.
Si no hay errores retorna el chunk compilado como una funci�n; en otro caso retorna nil m�s un mensaje de error. El entorno de la funci�n retornada es el global.
nombre_de_chunk se utiliza para identificar el chunk en los mensajes de error y para informaci�n de depuraci�n.
loadfile ([nombre_de_fichero])Similar a load, pero obtiene el chunk del fichero nombre_de_fichero o de la entrada est�ndar si no se proporciona un nombre.
loadstring (string [, nombre_de_chunk])Similar a load, pero obtiene el chunk del string proporcionado.
Para cargar y ejecutar un string dado �sese
assert(loadstring(s))()
Cuando est� ausente, nombre_de_chunk toma por defecto el string dado.
next (tabla [, �ndice])Permite al programa recorrer todos los campos de una tabla. Su primer argumento es una tabla y su segundo argumento es un �ndice en esta tabla. next retorna el siguiente �ndice de la tabla y su valor asociado. Cuando se invoca con nil como segundo argumento next retorna un �ndice inicial y su valor asociado. Cuando se invoca con el �ltimo �ndice o con nil en una tabla vac�a next retorna nil. Si el segundo argumento est� ausente entonces se interpreta como nil. En particular se puede usar next(t) para comprobar si una tabla est� vac�a.
El orden en que se enumeran los �ndices no est� especificado, incluso para �ndices num�ricos. (Para recorrer una tabla en orden num�rico �sese el for num�rico o la funci�n ipairs.)
El comportamiento de next es indefinido si durante el recorrido se asigna un valor a un campo no existente previamente en la tabla. No obstante se pueden modificar campos existentes. En particular se pueden borrar campos existentes.
pairs (t)Retorna tres valores: la funci�n next, la tabla t, y nil, por lo que la construcci�n
for k,v in pairs(t) do bloque enditerar� sobre todas las parejas clave-valor de la tabla
t.
V�ase next para las precauciones a tomar cuando se modifica la tabla durante las iteraciones.
pcall (f, arg1, ···)Invoca la funci�n f con los argumentos dados en modo protegido. Esto significa que ning�n error dentro de f se propaga; en su lugar pcall captura el error y retorna un c�digo de estatus. Su primer resultado es el c�digo de estatus (booleano), el cual es verdadero si la llamada tiene �xito sin errores. En ese caso pcall tambi�n devuelve todos los resultados de la llamada despu�s del primer resultado. En caso de error pcall retorna false m�s un mensaje de error.
print (···)stdout), usando tostring como funci�n para convertir los argumentos a strings. print no est� dise�ada para salida formateada sino s�lo como una manera r�pida de mostrar valores, t�picamente para la depuraci�n del c�digo. Para salida formateada �sese string.format.
rawequal (v1, v2)Verifica si v1 es igual a v2,
sin invocar ning�n metam�todo. Devuelve un booleano.
rawget (tabla, �ndice)Obtiene el valor real de tabla[�ndice] sin invocar ning�n metam�todo. tabla debe ser una tabla e �ndice cualquier valor diferente de nil.
rawset (tabla, �ndice, valor)Asigna valor a tabla[�ndice] sin invocar ning�n metam�todo. tabla debe ser una tabla, �ndice cualquier valor diferente de nil y valor un valor cualquiera de Lua.
select (�ndice, ···)Si �ndice es un n�mero retorna todos los argumentos despu�s del n�mero �ndice. En otro caso �ndice debe ser el string "#", y select retorna el n�mero total de argumentos extra que recibe.
setfenv (f, tabla)Establece el entorno que va a ser usado por una funci�n. f puede ser una funci�n Lua o un n�mero que especifica la funci�n al nivel de pila: nivel 1 es la funci�n que invoca a setfenv. setfenv retorna la funci�n dada.
Como caso especial, cuando f es 0 setfenv cambia el entorno del proceso que est� en ejecuci�n. En este caso setfenv no retorna valores.
setmetatable (tabla, metatabla)Establece la metatabla de una tabla dada. (No se puede cambiar la metatabla de otros tipos desde Lua, sino s�lo desde C.) Si metatabla es nil entonces se elimina la metatabla de la tabla dada. Si la metatabla original tiene un campo "__metatable" se activa un error.
Esta funci�n retorna tabla.
tonumber (e [, base])Intenta convertir su argumento en un n�mero. Si el argumento es ya un n�mero o un string convertible a un n�mero entonces tonumber retorna este n�mero; en otro caso devuelve nil.
Un argumento opcional especifica la base para interpretar el n�mero. La base puede ser cualquier entero entre 2 y 36, ambos inclusive. En bases por encima de 10 la letra 'A' (en may�scula o min�scula) representa 10, 'B' representa 11, y as� sucesivamente, con 'Z' representando 35. En base 10 (por defecto), el n�mero puede tener parte decimal, as� como un exponente opcional (v�ase §2.1). En otras bases s�lo se aceptan enteros sin signo.
tostring (e)Recibe un argumento de cualquier tipo y lo convierte en un string con un formato razonable. Para un control completo de c�mo se convierten los n�meros, �sese string.format.
Si la metatabla de e tiene un campo "__tostring" entonces tostring invoca al correspondiente valor con e como argumento y usa el resultado de la llamada como su propio resultado.
type (v)Retorna el tipo de su �nico argumento, codificado como string. Los posibles resultados de esta funci�n son "nil" (un string, no el valor nil), "number", "string", "boolean, "table", "function", "thread" y "userdata".
unpack (lista [, i [, j]])Retorna los elementos de una tabla dada. Esta funci�n equivale a
return lista[i], lista[i+1], ···, lista[j]excepto que este c�digo puede ser escrito s�lo para un n�mero fijo de elementos. Por defecto
i es 1 y j es la longitud de la lista, como se define a trav�s del operador longitud (v�ase §2.5.5).
_VERSIONUna variable global (no una funci�n) que almacena un string que contiene la versi�n actual del int�rprete. En esta versi�n de Lua el contenido actual de esta variable es "Lua 5.1".
xpcall (f, err)Esta funci�n es similar a pcall, excepto que se puede establecer un manejador de error.
xpcall invoca a la funci�n f en modo protegido, usando err como manejador de error. Ning�n error dentro de f se propaga; en su lugar xpcall captura el error, llamando a la funci�n err con el objeto de error original, y retorna un c�digo de estatus. Su primer resultado es el c�digo de estatus (un booleano), que es verdadero si la llamada tiene �xito sin errores. En ese caso xpcall tambi�n devuelve todos los resultados de la llamada despu�s del primer resultado. En caso de error xpcall retorna false m�s el resultado de err.
Las operaciones relacionadas con co-rutinas comprenden una sub-biblioteca de la biblioteca b�sica y se sit�a en la tabla coroutine. V�ase §2.11 para una descripci�n general de las co-rutinas.
coroutine.create (f)Crea una nueva co-rutina con cuerpo f. f debe ser una funci�n Lua. Retorna una nueva co-rutina, un objeto de tipo "thread".
coroutine.resume (co [, val1, ���])Comienza o contin�a la ejecuci�n de la co-rutina co. La primera vez que se llama a esta funci�n la co-rutina comienza ejecutando su cuerpo. Los valores val1, ··· se pasan como argumentos al cuerpo de la funci�n. Si la co-rutina ha cedido el control del flujo, resume la reinicia; los valores val1, ··· son pasados como resultados de la cesi�n.
Si la co-rutina se ejecuta sin error resume retorna true m�s los valores pasados a yield (si la co-rutina realiza la cesi�n) o los valores retornados por el cuerpo de la funci�n (si la co-rutina acaba). Si existe cualquier error resume retorna false m�s un mensaje de error.
coroutine.running ()Retorna la co-rutina en ejecuci�n o nil cuando se invoca desde el proceso principal.
coroutine.status (co)Retorna el estatus de la co-rutina co como un string: "running", si la co-rutina est� en ejecuci�n (esto es, invoc� a status); "suspended", si la co-rutina est� suspendida en una llamada a yield, o si todav�a no ha comenzado a ejecutarse; "normal" si la co-rutina est� activa pero no ejecut�ndose (esto es, si ha resumido otra co-rutina); y "dead" si la co-rutina ha finalizado su funci�n o si se ha detenido con un error.
coroutine.wrap (f)Crea una nueva co-rutina con cuerpo f. f debe ser una funci�n Lua. Retorna una funci�n que resume la co-rutina cada vez que es invocada. Cualquier argumento pasado a la funci�n se comporta como un argumento extra para resume. Retorna los mismos valores devueltos por resume, excepto el primer booleano. En caso de error, �ste se propaga.
coroutine.yield (···)Suspende la ejecuci�n de la co-rutina invocante. La co-rutina no puede estar ejecutando una funci�n C, un metam�todo o un iterador. Cualquier argumento de yield es pasado como resultado extra a resume.
La biblioteca de empaquetado proporciona utilidades b�sicas para cargar y construir m�dulos en Lua. Exporta dos de sus funciones directamente al entorno global: module y require. Las dem�s se exportan en la tabla package.
module (nombre [, ···])Crea un m�dulo. Si existe una tabla en package.loaded[nombre] �sta es el m�dulo. En otro caso si existe una tabla global t con el nombre dado �sta es el m�dulo. Sino, finalmente, crea una nueva tabla t y le da el nombre global de nombre y el valor de package.loaded[nombre]. Esta funci�n tambi�n inicializa t._NAME con el nombre dado, t._M con el m�dulo (t mismo), y t._PACKAGE con el nombre del paquete (el m�dulo nombre completo menos su �ltimo componente; v�ase m�s abajo). Para acabar, module establece t como nuevo entorno de la funci�n actual y el nuevo valor de package.loaded[nombre], de tal manera que require retorna t.
Si nombre es un nombre compuesto (esto es, uno con componentes separados por puntos) module crea (o reutiliza, si ya existen) tablas para cada componente. Por ejemplo, si nombre es a.b.c, entonces module almacena la tabla m�dulo en el campo c del campo b de la tabla global a.
Esta funci�n puede recibir argumentos opcionales despu�s del nombre del m�dulo, donde cada opci�n es una funci�n que ser� aplicada sobre el m�dulo.
require (nombre)Carga el m�dulo dado. La funci�n comienza buscando en la tabla package.loaded para determinar si nombre est� ya cargado. Si es as� entonces require devuelve el valor almacenado en package.loaded[nombre]. En otro caso intenta encontrar un cargador para el m�dulo.
Para encontrar un cargador, primero require se gu�a por package.preload[nombre]. Cambiando este array, se cambia la manera que en require busca un m�dulo. La siguiente explicaci�n est� basada en la configuraci�n por defecto de package.loaders.
Primero require mira en package.prelodad[modname]. Si tiene un valor, �ste (que debe ser una funci�n) es el cargador. En otro caso require busca un cargador en Lua usando el camino de b�squeda guardado en package.path. Si tambi�n esto falla, busca un cargador en C usando el camino almacenado en package.cpath. Si tambi�n finalmente esto falla intenta un cargador todo en uno (v�ase package.loaders).
Una vez que se encontr� el cargador, require lo invoca con un �nico argumento, nombre. Si el cargador retorna un valor, require lo asigna a package.loaded[nombre]. Si el cargador no retorna un valor y no est� asignado un valor a package.loaded[nombre], entonces require asigna true a esta entrada. En cualquier caso, require retorna el valor final de package.loaded[nombre].
Si existen errores durante la carga o ejecuci�n del m�dulo en proceso o si no se pudo encontrar un cargador para el m�dulo, entonces require activa un error.
package.cpathEl camino de b�squeda usado por require para buscar un cargador en C.
Lua inicializa este camino package.cpath de la misma manera en que inicializa el camino de Lua package.path, usando la variable de entorno LUA_CPATH (adem�s de otro camino por defecto definido en luaconf.h).
package.loadedUna tabla usada por require para controlar qu� m�dulos est�n ya cargados. Cuando se solicita un m�dulo nombre y package.loaded[nombre] no es falso, require simplemente retorna el valor almacenado.
package.loadersUna tabla usada por require
que controla c�mo se cargan los m�dulos
Cada entrada en esta tabla es una funci�n buscadora. Cuando busca un m�dulo, require llama a cada uno de esas buscadoras en orden ascendente, con el nombre del m�dulo (el argumento pasado a require) com �nico argumento. La funci�n puede retornar otra funci�n (el m�dulo cargador o un string que explica que no encontr� ese m�dulo (o nil si no tuvo nada que decir). Lua inicializa esta tabla con cuatro funciones.
La primera buscadora simplemente busca un cargador en la tabla package.preload.
La segunda buscadora busca un cargador como biblioteca de Lua, usando el camino de b�squeda guardado en package.path. Un camino es una secuencia de plantillas separadas por puntos y comas (;). En cada plantilla, el buscador cambia cada signo de interrogaci�n que aparezca por nombre_de_fichero, que es el nombre del m�dulo con cada punto reemplazado por un "separador de directorios" (como "/" en Unix); entonces intentar� abrir el fichero con el nombre resultante. As�, por ejemplo, si el el camino de Lua es el string:
"./?.lua;./?.lc;/usr/local/?/init.lua"
la b�squeda de un fichero fuente de Lua para el m�dulo foo intentar� abrir los ficheros ./foo.lua., ./foo.lc y /usr/local/foo/init.lua, en ese orden
La tercera buscadora busca un cargador como biblioteca de C, usando el camino dado en la variable package.cpath. Por ejemplo, si el camino de C es el string:
"./?.so;./?.dll;/usr/local/?/init.so"
la buscadora, para el m�dulo foo intentar� abrir los ficheros ./foo.so., ./foo.dll y /usr/local/foo/init.so, en ese orden. Una vez que encuentre una biblioteca en C, el buscador usa la utilidad de enlace din�mico para enlazar la aplicaci�n con la biblioteca. Entones intenta encontrar la funci�n C dentro de la biblioteca para ser usada como cargador. El nombre de esta funci�n es el string "luaopen_" concatenado con una copia del nombre del m�dulo donde cada punto es reemplazado por un car�cter de subrayado (_). Adem�s, si el nombre del m�dulo tiene un gui�n, su prefijo hasta el primer gui�n incluido se elimina. Por ejemplo, si el nombre del m�dulo es a.v1-b.c el nombre de funci�n ser� luaopen_b_c.
La cuarta buscadora intenta un cargador todo-en-uno. Busca en el camino de C una biblioteca con el nombre raiz del m�dulo dado. Por ejemplo, cuando se pide a.b.c buscar� a en una bibliteca C. SI la encuentra busca dentro de ella una funci�n para abrir el subm�dulo; en nuestro ejemplo, ser�a luaopen_a_b_c. Con esta utilidad, un paquete puede guardar varios subm�dulos C en una �nica biblioteca, con cada subm�dulo manteniendo su funci�n original de apertura.
package.loadlib (nombre_de_biblioteca, nombre_de_func)Enlaza din�micamente el programa anfitri�n con la biblioteca en C nombre_de_biblio. Dentro de esta biblioteca busca una funci�n nombre_de_func y la retorna como una funci�n C. (Por tanto, nombre_de_func debe seguir el protocolo; v�ase lua_CFunction).
�sta es una funci�n de bajo nivel. Se salta completamente el sistema de paquetes y de m�dulos. A diferencia de require, no realiza ninguna b�squeda en el camino y no a�ade autom�ticamente extensiones. nombre_de_biblio debe ser un nombre completo de fichero de la biblioteca en C, incluyendo si es necesario el camino completo y la extensi�n. nombre_de_func debe ser el nombre exacto exportado por la biblioteca en C (el cual puede depender del compilador de C y del cargador del sistema operativo usados).
Esta funci�n no est� soportada por el C ANSI. Por tanto s�lo est� disponible en algunas plataformas (Windows, Linux, Mac OS X, Solaris, BSD, adem�s de otros sistemas Unix que soportan el est�ndar dlfcn).
package.pathEl camino de b�squeda usado por require para buscar un cargador de Lua.
Al comienzo Lua inicializa esta variable con el valor de la variable de entorno LUA_PATH o con un camino por defecto definido en luaconf.h, si la variable de entorno no est� definida. Si aparece ";;" en el valor de la variable de entorno se reemplaza por el camino por defecto.
package.preloadUna tabla que almacena cargadores para m�dulos espec�ficos (v�ase require).
package.seeall (m�dulo)Establece una metatabla para m�dulo con su campo __index refiri�ndose al entorno global, de tal manera que este m�dulo hereda los valores del entorno global. Se usa como una opci�n para la funci�n module.
Esta biblioteca proporciona funciones gen�ricas de manejo de strings, tales como encontrar y extraer substrings y detectar patrones. Cuando se indexa un string en Lua el primer car�cter est� en la posici�n 1 (no en 0 como en C). Se permite el uso de �ndices negativos que se interpretan como indexado hacia atr�s, desde el final del string. Por tanto el �ltimo car�cter del string est� en la posici�n -1, y as� sucesivamente.
La biblioteca de strings proporciona todas sus funciones en la tabla string. Tambi�n establece una metatabla para string donde el campo __index apunta a la misma metatabla. Por tanto, se pueden usar las funciones de manejo de string en un estilo orientado a objetos. Por ejemplo, string.byte(s, i) puede ponerse s:byte(i).
string.byte (s [, i [, j]])Devuelve los c�digos num�ricos internos de los caracteres s[i], s[i+1], ···, s[j]. El valor por defecto de i es 1; el valor por defecto de j es i.
T�ngase en cuenta que los c�digos num�ricos no son necesariamente portables de unas plataformas a otras.
string.char (···)Recibe cero o m�s enteros. Devuelve un string con igual longitud que el n�mero de argumentos, en el que cada car�cter tiene un c�digo num�rico interno igual a su correspondiente argumento.
T�ngase en cuenta que los c�digos num�ricos no son necesariamente portables de unas plataformas a otras.
string.dump (function)Devuelve un string que contiene la representaci�n binaria de la funci�n dada, de tal manera que una llamada posterior a loadstring con este string devuelve una copia de la funci�n. func debe ser una funci�n Lua sin upvalues.
string.find (s, patr�n [, inicio [, b�sica]])Busca la primera aparici�n de patr�n en el string s. Si la encuentra, find devuelve los �ndices de s donde comienza y acaba la aparaci�n; en caso contrario retorna nil. Un tercer argumento num�rico opcional inicio especifica d�nde comenzar la b�squeda; su valor por defecto es 1 y puede ser negativo. Un valor true como cuarto argumento opcional b�sica desactiva las utilidades de detecci�n de patrones, realizando entonces la funci�n una operaci�n de "b�squeda b�sica de substring", sin caracteres "m�gicos" en el patr�n. T�ngase en cuenta que si se proporciona el argumento b�sica tambi�n debe proporcionarse el argumento inicio.
Si el patr�n tiene capturas entonces en una detecci�n con �xito se devuelven los valores capturados, despu�s de los dos �ndices.
string.format (formato, ···)Devuelve una versi�n formateada de sus argumentos (en n�mero variable) siguiendo la descripci�n dada en su primer argumento (formato, que debe ser un string). El string de formato sigue las mismas reglas que la familia de funciones C est�ndar printf. Las �nicas diferencias son que las opciones/modificadores *, l, L, n, p, y h no est�n soportadas, y que existe una opci�n extra q. Esta �ltima opci�n da formato a un string en una forma adecuada para ser le�da de manera segura de nuevo por el int�rprete de Lua: el string es escrito entre dobles comillas, y todas las dobles comillas, nuevas l�neas, ceros y barras inversas del string se sustituyen por las secuencias de escape adecuadas en la escritura. Por ejemplo, la llamada
string.format('%q', 'un string con "comillas" y \n nueva l�nea')
producir� el string:
"un string con \"comillas\" y \ nueva l�nea"
Las opciones c, d, E, e, f, g, G, i, o, u, X y x esperan un n�mero como argumento, mientras que q y s esperan un string.
Esta funci�n no acepta valores de string que contengan caracteres cero, excepto como argumentos de la opci�n q.
string.gmatch (s, patr�n)Devuelve una funci�n iteradora que, cada vez que se invoca, retorna las siguientes capturas del patr�n en el string s.
Si el patr�n no produce capturas entonces la coincidencia completa se devuelve en cada llamada.
Como ejemplo, el siguiente bucle
s = "hola mundo desde Lua"
for w in string.gmatch(s, "%a+") do
print(w)
end
iterar� sobre todas las palabras del string s,
imprimiendo una por l�nea. El siguiente ejemplo devuelve en forma de tabla todos los pares clave=valor del string dado:
t = {}
s = "desde=mundo, a=Lua"
for k, v in string.gmatch(s, "(%w+)=(%w+)") do
t[k] = v
end
Para esta funci�n, un '^' al principio de un patr�n no funciona como un ancla, sino que previene la iteraci�n.
string.gsub (s, patr�n, reemplazamiento [, n])Devuelve una copia de s en la que todas (o las n primeras, si se especifica el argumento opcional) las apariciones del patr�n han sido reemplazadas por el reemplazamiento especificado, que puede ser un string, una tabla o una funci�n. gsub tambi�n devuelve, como segundo valor, el n�mero total de coincidencias detectadas.
Si reemplazamiento es un string entonces su valor se usa en la sustituci�n. El car�cter % funciona como un car�cter de escape: cualquier secuencia en reemplazamiento de la forma %n, con n entre 1 y 9, significa el valor de la captura n�mero n en el substring (v�ase m�s abajo). La secuencia %0 significa toda la coincidencia. La secuencia %% significa un car�cter porcentaje %.
Si reemplazamiento es una tabla entonces en cada captura se devuelve el elemento de la tabla que tiene por clave la primera captura; si el patr�n no proporciona ninguna captura entonce toda la coincidencia se utiliza como clave.
Si reemplazamiento es una funci�n entonces la misma es invocada cada vez que exista una captura con todos los substrings capturados pasados como argumentos en el mismo orden; si no existen capturas entonces toda la coincidencia se pasa como un �nico argumento.
Si el valor devuelto por la tabla o por la llamada a la funci�n es un string o un n�mero, entonces se usa como string de reemplazamiento; en caso contrario si es false o nil, entonces no se realiza ninguna sustituci�n (esto es, la coincidencia original se mantiene en el string).
He aqu� algunos ejemplos:
x = string.gsub("hola mundo", "(%w+)", "%1 %1")
--> x="hola hola mundo mundo"
x = string.gsub("hola mundo", "%w+", "%0 %0", 1)
--> x="hola hola mundo"
x = string.gsub("hola mundo desde Lua", "(%w+)%s*(%w+)", "%2 %1")
--> x="mundo hola Lua desde"
x = string.gsub("casa = $HOME, usuario = $USER", "%$(%w+)", os.getenv)
--> x="casa = /home/roberto, usuario = roberto"
x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s)
return loadstring(s)()
end)
--> x="4+5 = 9"
local t = {nombre="lua", versi�n="5.1"}
x = string.gsub("$nombre-$versi�n.tar.gz", "%$(%w+)", t)
--> x="lua-5.1.tar.gz"
string.len (s)Recibe un string y devuelve su longitud. El string vac�o "" tiene longitud 0. Los caracteres cero dentro del string tambi�n se cuentan, por lo que "a\000bc\000" tiene longitud 5.
string.lower (s)Recibe un string y devuelve una copia del mismo con todas las letras may�sculas cambiadas a min�sculas. El resto de los caracteres permanece sin cambios. La definici�n de letra may�scula depende del sistema local.
string.match (s, patr�n [, inicio])Busca la primera aparici�n del patr�n en el string s. Si encuentra una, entonces match retorna la captura del patr�n; en caso contrario devuelve nil. Si el patr�n no produce ninguna captura entonces se devuelve la coincidencia completa. Un tercer y opcional argumento num�rico inicio especifica d�nde comenzar la b�squeda; su valor por defecto es 1 y puede ser negativo.
string.rep (s, n)Devuelve un string que es la concatenaci�n de n copias del string s.
string.reverse (s)Devuelve un string que es el original s invertido.
string.sub (s, i [, j])Retorna el substring de s que comienza en i y contin�a hasta j; i y j pueden ser negativos. Si j est� ausente entonces se asume que vale -1 (equivalente a la longitud del string). En particular, la llamada string.sub(s,1,j) retorna un prefijo de s con longitud j, y string.sub(s, -i) retorna un sufijo de s con longitud i.
string.upper (s)Recibe un string y devuelve una copia del mismo con todas las letras min�sculas cambiadas a may�sculas. El resto de los caracteres permanece sin cambios. La definici�n de letra min�scula depende del sistema local.
Se usan clases de caracteres para representar conjuntos de caracteres. Est�n permitidas las siguientes combinaciones para describir una clase de caracteres:
^$()%.[]*+-?) representa el propio caracter x.
.: (un punto) representa cualquier car�cter.
%a: representa cualquier letra.
%c: representa cualquier car�cter de control.
%d: representa cualquier d�gito.
%l: representa cualquier letra min�scula.
%p: representa cualquier car�cter de puntuaci�n.
%s: representa cualquier car�cter de espacio.
%u: representa cualquier letra may�scula.
%w: representa cualquier car�cter alfanum�rico.
%x: representa cualquier d�gito hexadecimal.
%z: representa el car�cter con valor interno 0 (cero).
%x: (donde x es cualquier car�cter no alfanum�rico)
representa el car�cter x. �sta es la manera est�ndar de "escapar" los caracteres m�gicos. Cualquier caracter de puntuaci�n (incluso los no m�gicos) pueden ser precedidos por un signo de porcentaje '%' cuando se quieran representarse a s� mismos en el patr�n.
[conjunto]:
representa la clase que es la uni�n de todos los caracteres en el conjunto. Un rango de caracteres puede ser especificado separando el car�cter del principio y del final mediante un gui�n '-'. Todas las clases del tipo %x descritas m�s arriba pueden ser tambi�n utilizadas como componentes del conjunto. Todos los otros caracteres en el conjunto se representan a s� mismos. Por ejemplo, [%w_] (o [_%w]) representa cualquier car�cter alfanum�rico o el subrayado, [0-7] representa un d�gito octal, y [0-7%l%-] representa un d�gito octal, una letra min�scula o el car�cter '-'.
La interacci�n entre los rangos y las clases no est� definida. Por tanto, patrones como [%a-z] o [a-%%] carecen de significado.
[^conjunto]:
representa el complemento de conjunto, donde conjunto se interpreta como se ha indicado m�s arriba. %a, %c, etc.) las correspondientes letras may�sculas representan la clase complementaria. Por ejemplo, %S representa cualquier car�cter no espacio.
Las definiciones de letra, espacio y otros grupos de caracteres dependen del sistema local. En particular, la clase [a-z] puede no ser equivalente a %l.
Cada elemento de un patr�n puede ser
*', que equivale a 0 � m�s repeticiones de los caracteres de la clase. Estos elementos de repetici�n siempre equivaldr�n a la secuencia de caracteres m�s larga posible;
+', que equivale a 1 � m�s repeticiones de los caracteres de la clase. Estos elementos de repetici�n siempre equivaldr�n a la secuencia de caracteres m�s larga posible;
-', que tambi�n equivale a 0 � m�s repeticiones de los caracteres de la clase. Al contrario que '*', Estos elementos de repetici�n siempre equivaldr�n a la secuencia de caracteres m�s corta posible;
?', que equivale a 0 � 1 apariciones de un car�cter de la clase;
%n, para n entre 1 y 9; este elemento equivale a un substring igual a la captura n�mero n;
%bxy, donde x e y son dos caracteres diferentes; este elemento equivale a strings que comienzan con x, finalizan con y, estando equilibrados x e y. Esto significa que, iniciando un contador a 0, si se lee el string de izquierda a derecha, sumando +1 por cada x que aparezca y -1 por cada y, el y final es el primero donde el contador alcanza 0. Por ejemplo, el elemento %b() equivale a una expresi�n con par�ntesis emparejados.
Un patr�n es una secuencia de elementos de patr�n. Un '^' al comienzo de un patr�n ancla la b�squeda del patr�n al comienzo del string en el que se produce la b�squeda. Un '$' al final de un patr�n ancla la b�squeda del patr�n al final del string en el que se produce la b�squeda. En otras posiciones '^' y '$' no poseen un significado especial y se representan a s� mismos.
Un patr�n puede contener subpatrones encerrados entre par�ntesis que describen capturas. Cuando sucede una coincidencia entre un patr�n y un string dado, los substrings que concuerdan con lo indicado entre par�ntesis en el patr�n, son almacenados (capturados) para uso futuro. Las capturas son numeradas de acuerdo a sus par�ntesis izquierdos. Por ejemplo, en el patr�n "(a*(.)%w(%s*))", la parte del string que concuerda con "a*(.)%w(%s*)" se guarda en la primera captura (y por tanto tiene n�mero 1); el car�cter que concuerda con "." se captura con el n�mero 2, y la parte que concuerda con "%s*" tiene el n�mero 3.
Como caso especial, la captura vac�a () retorna la posici�n actual en el string (un n�mero). Por ejemplo, si se aplica el patr�n "()aa()" al string "flaaap", dar� dos capturas: 3 y 5.
Un patr�n no puede contener caracteres cero. �sese %z en su lugar.
table.
La mayor�a de las funciones en la biblioteca de tablas asume que las mismas representan arrays o listas (o sea, est�n indexadas num�ricamente). Para estas funciones, cuando hablamos de la "longitud" de una tabla queremos decir el resultado del operador longitud (#).
table.concat (tabla [, separador [, i [, j]]])tabla[i]..separador..tabla[i+1] ··· separador..tabla[j]. El valor por defecto de separador es el string vac�o, el valor por defecto de i es 1 y el valor por defecto de j es la longitud de la tabla. Si i es mayor que j, la funci�n devuelve un string vac�o.
table.insert (tabla, [posici�n,] valor)Inserta el elemento valor en la posici�n dada en la tabla, desplazando hacia adelante otros elementos para abrir hueco, si es necesario. El valor por defecto de posici�n es n+1, donde n = #tabla es la longitud de la tabla (v�ase §2.5.5), de tal manera que table.insert(t,x) inserta x al final de la tabla t.
table.maxn (tabla)Devuelve el mayor �ndice num�rico positivo de una tabla dada o cero si la tabla no tiene �ndices num�ricos positivos. (Para hacer su trabajo esta funci�n realiza un barrido lineal de la tabla completa.)
table.remove (tabla [, posici�n])Elimina de tabla el elemento situado en la posici�n dada, desplazando hacia atr�s otros elementos para cerrar espacio, si es necesario. Devuelve el valor del elemento eliminado. El valor por defecto de posici�n es n, donde n es la longitud de la tabla, por lo que la llamada table.remove(t) elimina el �ltimo elemento de la tabla t.
table.sort (tabla [, comparador])table[1] hasta table[n], donde n es la longitud de la tabla. Si se proporciona el argumento comparador �ste debe ser una funci�n que recibe dos elementos de la tabla y devuelve verdadero cuando el primero es menor que el segundo (por lo que not comparador(a[i+1],a[i]) ser� verdadero despu�s de la ordenaci�n). Si no se proporciona una funci�n comparador entonces se usa el operador est�ndar < de Lua.
El algoritmo de ordenaci�n no es estable; esto es, los elementos considerados iguales por la ordenaci�n dada pueden sufrir cambios de orden relativos despu�s de la ordenaci�n.
Esta biblioteca es una interface a la biblioteca matem�tica est�ndar de C. Proporciona todas sus funciones dentro de la tabla math.
math.abs (x)
Devuelve el valor absoluto de x.
math.acos (x)
Devuelve el arco coseno de x (en radianes).
math.asin (x)
Devuelve el arco seno de x (en radianes).
math.atan (x)
Devuelve el arco tangente de x (en radianes).
math.atan2 (y, x)
Devuelve el arco tangente de y/x (en radianes),
pero usa los signos de ambos argumentos para determinar el cuadrante del resultado.
(Tambi�n maneja correctamente el caso en que x es cero.)
math.ceil (x)
Devuelve el menor entero mayor o igual que x.
math.cos (x)
Devuelve el coseno de x (se asume que est� en radianes).
math.cosh (x)
Devuelve el coseno hiperb�lico de x.
math.deg (x)
Devuelve en grados sexagesimales el valor de x (dado en radianes).
math.exp (x)Devuelve el valor de ex.
math.floor (x)
Devuelve el mayor entero menor o igual que x.
math.fmod (x, y)
Devuelve el resto de la divisi�n de x por y.
math.frexp (x)
Devuelve m y e tales que x = m 2e,
e es un entero y el valor absoluto de m
est� en el intervalo [0.5, 1)
(o cero cuando x es cero).
math.huge
El valor HUGE_VAL, un valor m�s grande o igual que otro valor num�rico cualquiera.
math.ldexp (m, e)
Devuelve m 2e (e debe ser un entero).
math.log (x)
Devuelve el logaritmo natural de x.
math.log10 (x)
Devuelve el logaritmo decimal (base 10) de x.
math.max (x, ···)Devuelve el mayor valor de entre sus argumentos.
math.min (x, ···)Devuelve el menor valor de entre sus argumentos.
math.modf (x)
Devuelve dos n�meros, las partes entera y fraccional de x .
math.piEl valor de pi.
math.pow (x, y)
Devuelve xy.
(Se puede tambi�n usar la expresi�n x^y para calcular este valor.)
math.rad (x)
Devuelve en radianes el valor del �ngulo x (dado en grados sexagesimales).
math.random ([m [, n]])
Esta funci�n es un interface a rand, generador simple de n�meros pseudo-aleatorios
proporcionado por el ANSI C. (Sin garant�as de sus propiedades estad�sticas.)
Cuando se invoca sin argumentos devuelve un n�mero pseudoaleatorio real uniforme en el rango [0,1). Cuando se invoca con un n�mero entero m, math.random devuelve un n�mero pseudoaleatorio entero uniforme en el rango [1, m]. Cuando se invoca con dos argumentos m y n enteros, math.random devuelve un n�mero pseudoaleatorio entero uniforme en el rango [m, n].
math.randomseed (x)
Establece x como "semilla" para el generador de n�meros pseudoaleatorios: iguales semillas producen iguales secuencias de n�meros.
math.sin (x)Devuelve el seno de x (se asume que est� en radianes).
math.sinh (x)
Devuelve el seno hiperb�lico de x.
math.sqrt (x)
Devuelve la raiz cuadrada de x.
(Se puede usar tambi�n la expresi�n x^0.5 para calcular este valor.)
math.tan (x)
Devuelve la tangente de x (se asume que est� en radianes).
math.tanh (x)
Devuelve la tangente hiperb�lica de x.
La biblioteca de entrada/salida (I/O de sus siglas en ingl�s) proporciona dos estilos diferentes de manejo de ficheros. El primero de ellos usa descriptores de fichero impl�citos; esto es, existen dos ficheros por defecto, uno de entrada y otro de salida, y las operaciones se realizan sobre �stos. El segundo estilo usa descriptores de fichero expl�citos.
Cuando se usan descriptores impl�citos todas las operaciones soportadas est�n en la tabla io. Cuando se usan descriptores expl�citos, la operaci�n io.open devuelve un descriptor de fichero y todas las operaciones se proporcionan como m�todos asociados al descriptor.
La tabla io tambi�n proporciona tres descriptores de fichero predefinidos con sus significados usuales en C:
io.stdin, io.stdout e io.stderr.
La biblioteca de entrada/salida nunca cierra esos ficheros.
A no ser que se especifique, todas las funciones de entrada/salida devuelven nil en caso de fallo (m�s un mensaje de error como segundo resultado y un c�digo de error dependiente del sistema como un tercer resultado) y valores diferentes de nil si hay �xito.
io.close ([descriptor_de_fichero])Equivalente a descriptor_de_fichero:close(). Sin argumento cierra el fichero de salida por defecto.
io.flush ()Equivalente a descriptor_de_fichero:flush aplicado al fichero de salida por defecto.
io.input ([descriptor_de_fichero | nombre_de_fichero])Cuando se invoca con un nombre de fichero entonces lo abre (en modo texto), y establece su manejador de fichero como fichero de entrada por defecto. Cuando se llama con un descriptor de fichero simplemente lo establece como manejador para el fichero de entrada por defecto. Cuando se invoca sin argumento devuelve el fichero por defecto actual.
En caso de errores esta funci�n activa error en lugar de devolver un c�digo de error.
io.lines ([nombre_de_fichero])Abre el fichero de nombre dado en modo lectura y devuelve una funci�n iteradora que, cada vez que es invocada, devuelve una nueva l�nea del fichero. Por tanto, la construcci�n
for linea in io.lines(nombre_de_fichero) do bloque enditerar� sobre todas las l�neas del fichero. Cuando la funci�n iteradora detecta el final del fichero devuelve nil (para acabar el bucle) y cierra autom�ticamente el fichero.
La llamada a io.lines() (sin nombre de fichero) equivale a io.input():lines(); esto es, itera sobre todas las l�neas del fichero por defecto de entrada. En ese caso no cierra el fichero cuando acaba el bucle.
io.open (nombre_de_fichero [, modo])Esta funci�n abre un fichero, en el modo especificado en el string mode. Devuelve un descriptor de fichero o, en caso de error, nil adem�s de un mensaje de error.
El string que indica modo puede ser uno de los siguientes:
modo puede contener tambi�n 'b' al final, lo que es necesario en algunos sistemas para abrir el fichero en modo binario. Este string es exactamente el que se usa en la funci�n est�ndar de C fopen.
io.output ([descriptor_de_fichero | nombre_de_fichero])Similar a io.input, pero operando sobre el fichero por defecto de salida.
io.popen (prog [, modo])Comienza a ejecutar el programa prog en un proceso separado y retorna un descriptor de fichero que se puede usar para leer datos que escribe prog (si modo es "r", el valor por defecto) o para escribir datos que lee prog (si modo es "w").
Esta funci�n depende del sistema operativo y no est� disponible en todas las plataformas.
io.read (···)Equivalente a io.input():read.
io.tmpfile ()Devuelve un descriptor de fichero para un fichero temporal. �ste se abre en modo actualizaci�n y se elimina autom�ticamente cuando acaba el programa.
io.type (objeto)Verifica si objeto es un descriptor v�lido de fichero. Devuelve el string "file" si objeto es un descriptor de fichero abierto, "closed file" si objeto es un descriptor de fichero cerrado, o nil si objeto no es un descriptor de fichero.
io.write (···)Equivalente a io.output():write.
descriptor_de_fichero:close ()Cierra el descriptor de fichero descriptor_de_fichero. T�ngase en cuenta que los ficheros son cerrados autom�ticamente cuando sus descriptores se eliminan en un ciclo de liberaci�n de memoria, pero que esto toma un tiempo impredecible de ejecuci�n.
descriptor_de_fichero:flush ()Salva cualquier dato escrito en descriptor_de_fichero.
descriptor_de_fichero:lines ()Devuelve una funci�n iteradora que, cada vez que es invocada, devuelve una nueva l�nea le�da del fichero. Por tanto, la construcci�n
for linea in descriptor_de_fichero:lines() do bloque enditerar� sobre todas las l�neas del fichero. (A diferencia de
io.lines, esta funci�n no cierra el fichero cuando acaba el bucle.)
file:read (···)Lee en el fichero dado por el descriptor_de_fichero, de acuerdo el formato proporcionado, el cual especifica qu� leer. Para cada formato, la funci�n devuelve un string (o un n�mero) con los caracteres le�dos, o nil si no pudo leer los datos con el formato especificado. Cuando se invoca sin formato se usa uno por defecto que lee la pr�xima l�nea completa (v�ase m�s abajo).
Los formatos disponibles son
file:seek ([de_d�nde] [, desplazamiento])Establece (o solicita) la posici�n actual (del puntero de lectura/escritura) en el descriptor_de_fichero, medida desde el principio del fichero, en la posici�n dada por desplazamiento m�s la base especificada por el string d�nde, como se especifica a continuaci�n:
seek retorna la posici�n final (del puntero de lectura/escritura) en el fichero medida en bytes desde el principio del fichero. Si la llamada falla retorna nil, m�s un string describiendo el error.
El valor por defecto de d�nde es "cur", y para desplazamiento es 0. Por tanto, la llamada descriptor_de_fichero:seek() devuelve la posici�n actual, sin cambiarla; la llamada descriptor_de_fichero:seek("set") establece la posici�n al principio del fichero (y devuelve 0); y la llamada descriptor_de_fichero:seek("end") establece la posici�n al final del fichero y devuelve su tama�o.
file:setvbuf (modo [, tama�o])Establece un modo buffer para un fichero de salida. El argumento modo puede ser uno de estos tres:
flush en el descriptor del fichero.
Para los dos �ltimos casos, tama�o especifica el tama�o del buffer, en bytes. El valor por defecto es un tama�o adecuado.
file:write (···)Escribe el valor de sus argumentos en el fichero dado por su descriptor_de_fichero. Los argumentos pueden ser strings o n�meros. Para escribir otros valores �sese tostring o string.format antes que write.
Esta biblioteca est� implementada a trav�s de la tabla os.
os.clock ()Devuelve una aproximaci�n al total de segundos de CPU usados por el programa.
os.date ([formato [, tiempo]])Devuelve un string o una tabla conteniendo la fecha y hora, formateada
de acuerdo con el string dado en formato.
Si el argumento tiempo est� presente entonces ese tiempo concreto es el que se formatea (v�ase la funci�n os.time para una descripci�n de este valor). En caso contrario, date formatea el tiempo actual.
Si formato comienza con '!' entonces el tiempo se formatea de acuerdo al Tiempo Universal Coordinado. Despu�s de este car�cter opcional, si formato es *t entonces date devuelve una tabla con los siguientes campos: year (cuatro d�gitos), month (1--12), day (1--31), hour (0--23), min (0--59), sec (0--61), wday (d�a de la semana, el domingo es 1), yday (d�a dentro del a�o), e isdst (booleano, verdadero si es horario de verano).
Si formato no es *t entonces date devuelve el tiempo como un string, formateado de acuerdo con las mismas reglas que la funci�n strftime de C.
Cuando se invoca sin argumentos date devuelve una representaci�n razonable de la fecha y la hora que depende de la m�quina y del sistema local (esto es, os.date() equivale a os.date("%c")).
os.difftime (t2, t1)Devuelve el n�mero de segundos desde el instante t1 hasta el t2. En POSIX, Windows y algunos otros sistemas este valor es exactamente t2-t1.
os.execute ([comando])Esta funci�n equivale a la funci�n system de C. Pasa la orden comando para que sea ejecutada en el int�rprete de comandos del sistema operativo. Devuelve un c�digo de estatus, que es dependiente del sistema. Si el argumento comando est� ausente devuelve un valor no cero si est� disponible un int�rprete de comandos y cero si no est� disponible.
os.exit ([c�digo])Invoca la funci�n exit de C, con un c�digo entero opcional, para terminar el programa anfitri�n. El valor por defecto de c�digo es el valor correspondiente a �xito.
os.getenv (variable)Devuelve el valor asignado a la variable de entorno variable, o nil si la variable no est� definida.
os.remove (nombre_de_fichero)Elimina el fichero o directorio dado. Los directorios deben estar vac�os para poder ser eliminados. Si la funci�n falla retorna nil, m�s un string describiendo el error.
os.rename (nombre_viejo, nombre_nuevo)Renombra un fichero o directorio de nombre_viejo a nombre_nuevo. Si la funci�n falla retorna nil, m�s un string describiendo el error.
os.setlocale (local [, categor�a])Establece valores en el sistema local del programa. local es un string que especifica un valor local; categor�a es un string opcional que describe qu� categor�a cambiar: "all", "collate", "ctype", "monetary", "numeric", or "time"; la categor�a por defecto es "all". Esta funci�n retorna el nombre del nuevo local o nil si la petici�n no pudo ser aceptada.
Si local es el string vac�o, el local actual se establece como el local nativo (que depende de la implementaci�n). Si local es el string "C", el local actual se establece en el local est�ndar de C.
Cuando se invoca con nil como primer argumento, esta funci�n retorna s�lo el nombre del local actual en la categor�a dada.
os.time ([tabla])Devuelve el tiempo actual cuando se llama sin argumentos, o un tiempo representando la fecha y hora especificadas en la tabla dada. �sta debe tener los campos year, month y day, y puede tener los campos hour, min, sec e isdst (para una descripci�n de esos campos, v�ase la funci�n os.date).
El valor retornado es un n�mero, cuyo significado depende del sistema. En POSIX, Windows y algunos otros sistemas este n�mero cuenta el n�mero de segundos desde alguna fecha inicial dada (la "�poca"). En otros sistemas el significado no est� especificado, y el n�mero retornado por time puede ser usado s�lo como argumento de las funciones date y difftime.
os.tmpname ()Devuelve un string con un nombre de fichero que puede ser usado como fichero temporal. El fichero debe ser abierto expl�citamente antes de su uso y tambi�n eliminado expl�citamente cuando no se necesite m�s.
Esta biblioteca proporciona a los programas en Lua las funcionalidades de la interface de depuraci�n. Se debe usar con cuidado. Las funciones proporcionadas aqu� deben ser usadas exclusivamente para depuraci�n y labores similares, tales como el an�lisis de c�digo. Por favor, res�stase la tentaci�n de usar la biblioteca como una herramienta de programaci�n: puede llegar a ser muy lenta. Adem�s, alguna de sus funciones viola alguna de las asunciones acerca del c�digo en Lua (por ejemplo, que las variables locales de una funci�n no pueden ser accedidas desde fuera de la funci�n o que los userdata no pueden ser cambiados desde el c�digo Lua) y por tanto pueden comprometer c�digo de otra manera seguro.
Todas las funciones de esta biblioteca se proporcionan en la tabla debug.
debug.debug ()Entra en modo interactivo con el usuario, ejecutando cada string que introduce el usuario. Usando comandos simples y otras utilidades de depuraci�n el usuario puede inspeccionar variables globales y locales, cambiar sus valores, evaluar expresiones, etc. Una l�nea que contiene s�lo la palabra cont finaliza esta funci�n, por lo que el programa invocante contin�a su ejecuci�n.
T�ngase presente que los comandos para degub.debug no est�n l�xicamente anidados dentro de ninguna funci�n, y no tienen acceso directo a las variables locales.
debug.getfenv (o)Devuelve el entorno del objeto o.
debug.gethook ([proceso])Devuelve informaci�n sobre el hook actual del proceso, en forma de tres valores: la funci�n del hook actual, la m�scara del hook actual y el contador del hook actual (como fue establecida por la funci�n debug.sethook).
debug.getinfo ([proceso,] func [, qu�])Devuelve una tabla con informaci�n acerca de la funci�n func. Se puede dar la funci�n directamente, o se puede dar un n�mero en el lugar de func, lo que significa la funci�n al nivel de ejecuci�n de la llamada de pila: nivel 0 es el de la funci�n actual (getinfo misma); nivel 1 es la funci�n que llam� a getinfo; y as� sucesivamente. Si func es un n�mero mayor que el total de funciones activas entonces getinfo retorna nil.
La tabla devuelta contiene todos los campos retornados por lua_getinfo, con el string qu� describiendo los campos a rellenar. Por defecto, si no se proporciona qu�, se obtiene toda la informaci�n disponible. Si est� presente, la opci�n 'f' a�ade un campo denominado func con la funci�n misma. Si est� presente, la opci�n 'L' a�ade un campo denominado activelines con la tabla de l�neas v�lidas.
Por ejemplo, la expresi�n debug.getinfo(1,"n").nombre retorna una tabla con un nombre para la funci�n actual, si pudo encontrar un nombre razonable, y debug.getinfo(print) retorna una tabla con toda la informaci�n disponible sobre la funci�n print.
debug.getlocal ([proceso,] nivel, local)Esta funci�n devuelve el nombre y el valor de una variable local con �ndice local de la funci�n al nivel dado de la pila. (El primer argumento o variable local tiene �ndice 1, y as� sucesivamente, hasta la �ltima variable local activa.) La funci�n retorna nil si no existe una variable local con el �ndice dado, y activa un error cuando se invoca con nivel fuera de rango. (Se puede llamar a debug.getinfo para verificar si el nivel es v�lido.)
Los nombres de variable que comienzan con '(' (par�ntesis de abrir) representan variables internas (de control de bucles, temporales y locales de funciones C).
debug.getmetatable (objeto)Devuelve la metatabla del objeto dado o nil si �ste no tiene metatabla.
debug.getregistry ()Retorna la tabla de registro (v�ase §3.5).
debug.getupvalue (func, up)Esta funci�n retorna el nombre y el valor del upvalue con �ndice up de la funci�n func. La funci�n retorna nil si no hay un upvalue con el �ndice dado.
debug.setfenv (objeto, tabla)Establece la tabla de entorno de un objeto dado.
debug.sethook ([proceso,] func_hook, m�scara [, contador])Establece la funci�n func_hook como hook. El string dado en m�scara y el n�mero contador describen como se invoca al hook. La m�scara puede tener los siguientes caracteres, con el significado indicado:
"c": El hook se invoca cada vez que Lua llama a una funci�n;
"r": El hook se invoca cada vez que Lua retorna de una funci�n;
"l": El hook se invoca cada vez que Lua entra en una nueva l�nea de c�digo.
contador diferente de cero el hook se invoca cada ese n�mero de instrucciones.
Cuando se invoca sin argumentos debug.sethook desactiva el hook.
Cuando se invoca el hook su primer argumento es un string describiendo el evento que ha activado su invocaci�n: "call", "return" (o "tail return"), "line" y "count". Para los eventos de l�nea, el hook tambi�n devuelve el n�mero de l�nea como segundo valor. Dentro de un hook se puede invocar a getinfo con nivel 2 para obtener m�s informaci�n acerca de la funci�n en ejecuci�n (nivel 0 es la funci�n getinfo y nivel 1 es la funci�n hook), a no ser que el evento sea "tail return". En ese caso Lua s�lo simula el retorno, y una llamada a getinfo devolver� datos inv�lidos.
debug.setlocal ([proceso,] nivel, local, valor)Esta funci�n asigna el valor a la variable local con �ndice local de la funci�n al nivel dado en la pila, retornando el nombre de la variable local. La funci�n retorna nil si no existe una variable local con el �ndice dado, y activa un error cuando se llama con un nivel fuera de rango. (Se puede invocar getinfo para verificar si el nivel es v�lido.)
debug.setmetatable (objeto, tabla)Establece tabla (que puede ser nil) como la metatabla del objeto dado.
debug.setupvalue (func, up, valor)Esta funci�n asigna el valor al upvalue con �ndice up de la funci�n func, retornando el nombre del upvalue. La funci�n retorna nil si no existe el upvalue con el �ndice dado.
debug.traceback ([proceso,] [mensaje] [, nivel])Devuelve un string con el "trazado inverso" de la llamada en la pila. Un mensaje opcional se a�ade al principio del "trazado inverso".
Un n�mero de nivel opcional indica en qu� nivel se comienza el "trazado inverso"
(por defecto es 1, la funci�n que est� invocando a traceback).
Aunque Lua ha sido dise�ado como un lenguaje de extensi�n, para ser embebido en programas en C, tambi�n es frecuentemente usado como lenguaje independiente. Con la distribuci�n est�ndar se proporciona un int�rprete independiente denominado simplemente lua. �ste incluye todas las bibliotecas est�ndar, incluyendo la de depuraci�n. Se usa as�:
lua [opciones] [fichero_de_script [argumentos]]Las opciones son:
-e sentencia: ejecuta el string sentencia;
-l m�dulo: carga m�dulo con la funci�n require;
-i: entra en modo interactivo despu�s de ejecutar el fichero_de_script;
-v: imprime informaci�n de la versi�n;
--: deja de procesar opciones en el resto de la l�nea;
-: toma stdin como fichero para ejecutar y no procesa m�s opciones.
lua ejecuta el fichero_de_script dado, pas�ndole los argumentos dados como strings. Cuando se invoca sin argumentos lua se comporta como lua -v -i cuando la entrada est�ndar (stdin) es una terminal, y como lua - en otro caso.
Antes de ejecutar cualquier argumento el int�rprete comprueba si existe una variable de entorno LUA_INIT. Si su formato es @nombre_de_fichero entonces lua ejecuta este fichero. En otro caso lua ejecuta el propio string.
Todas las opciones se procesan en orden, excepto -i. Por ejemplo, una invocaci�n como
$ lua -e'b=1' -e 'print(b)' script.luaprimero establecer� el valor de
b a 1, luego imprimir� el valor de b (que es '1'), y finalmente ejectuar� el fichero script.lua sin argumentos. (Aqu� $ es el prompt del int�rprete de comandos del sistema operativo. El de cada sistema concreto puede ser diferente.)
Antes de comenzar a ejecutar fichero_de_script lua recolecta todos los argumentos de la l�nea de comandos en una tabla global denominada arg. El nombre del fichero_de_script se guarda en el �ndice 0, el primer argumento depu�s del nombre del programa se guarda en el �ndice 1, y as� sucesivamente. Cualesquiera argumentos antes del nombre del programa (esto es, el nombre del int�rprete m�s las opciones) van a los �ndices negativos. Por ejemplo, en la invocaci�n
$ lua -la b.lua t1 t2el int�rprete primero ejecuta el fichero
b.lua, luego crea la tabla
arg = { [-2] = "lua", [-1] = "-la",
[0] = "b.lua",
[1] = "t1", [2] = "t2" }
y finalmente ejecuta el fichero b.lua. �ste se invoca con arg[1], arg[2], ··· como argumentos; tambi�n se accede a estos argumentos con la expresi�n vararg '...'.
En modo interactivo si se escribe una sentencia incompleta el int�rprete espera para que sea completada, indic�ndolo con otro prompt diferente.
Si la variable global _PROMPT contiene un string entonces su valor se usa como prompt. De manera similar, si la variable global _PROMPT2 contiene un string su valor se usa como prompt secundario (el que se utiliza durante las sentencias incompletas). Por tanto, ambos prompts pueden ser cambiados directamente en la l�nea de comandos o en cualquier programa en Lua asignando un valor a _PROMPT. V�ase el siguiente ejemplo:
$ lua -e"_PROMPT='myprompt> '" -i(la pareja externa de comillas es para el int�rprete de comandos del sistema operativo; la interna para Lua). N�tese el uso de
-i para entrar en modo interactivo; en otro caso el programa acabar�a silenciosamente justo despu�s de la asignaci�n a _PROMPT.
Para permitir el uso de Lua como un int�rprete de scripts en los sistemas Unix, el int�rprete independiente de Lua se salta la primera l�nea de un chunk si �sta comienza con #. Por tanto, los programas de Lua pueden convertirse en ejecutables usando chmod +x y la forma #!, como en
#!/usr/local/bin/lua(Por supuesto, la localizaci�n del int�rprete de Lua puede ser diferente en cada m�quina. Si
lua est� en el camino de b�squeda de ejecutables, PATH, entonces
#!/usr/bin/env luaes una soluci�n m�s portable.)
Aqu� se listan las incompatibilidades que pueden aparecer cuando se porta un programa de Lua 5.0 a Lua 5.1. Se pueden evitar la mayor�a de ellas compilando Lua con las opciones apropiadas (v�ase el fichero luaconf.h). Sin embargo todas esas opciones de compatibilidad ser�n eliminadas en la siguiente versi�n de Lua.
arg con una tabla con argumentos extra a la expresi�n vararg. (V�ase la opci�n de compilaci�n LUA_COMPAT_VARARG en luaconf.h.)
[[...]] para string largo y para comentario largo no permite anidamientos. Se puede usar la nueva sintaxis [=[...]=] en esos casos. (V�ase la opci�n de compilaci�n LUA_COMPAT_LSTR en luaconf.h.)
string.gfind ha sido renombrada a string.gmatch. (V�ase la opci�n de compilaci�n LUA_COMPAT_GFIND en luaconf.h.)
string.gsub con una funci�n como su tercer argumento, siempre que esta funci�n devuelva nil o false el string de reemplazamiento es la coincidencia completa en lugar de un string vac�o.
table.setn. La funci�n table.getn corresponde al nuevo operador de longitud (#); �sese el operador en lugar de la funci�n. (V�ase la opci�n de compilaci�n LUA_COMPAT_GETN en luaconf.h.)
loadlib ha sido renombrada a package.loadlib. (V�ase la opci�n de compilaci�n LUA_COMPAT_LOADLIB en luaconf.h.)
math.mod ha sido renombrada a math.fmod. (V�ase la opci�n de compilaci�n LUA_COMPAT_MOD en luaconf.h.)
table.foreach y table.foreachi. En su lugar se puede usar un bucle con pairs o ipairs.
require debido al nuevo sistema de m�dulos. No obstante, el nuevo comportamiento es casi totalmente compatible con el viejo, aunque require obtiene el camino de b�squeda de package.path en lugar de LUA_PATH.
collectgarbage tiene otros argumentos. Se desaconseja el uso de la funci�n gcinfo; �sese collectgarbage("count") en su lugar.
luaopen_* (para abrir bibliotecas) no pueden ser invocadas directamente como funciones C regulares. Deben ser llamadas a trav�s de Lua, como otra funci�n Lua.
lua_open ha sido reemplazada por lua_newstate para permitir al usuario establecer una funci�n de asignaci�n de memoria. Se puede usar luaL_newstate de la biblioteca est�ndar para crear un estado con la funci�n est�ndar de asignaci�n de memoria (basada en realloc).
luaL_getn y luaL_setn (de la biblioteca auxiliar) no deben usarse. �sese lua_objlen en lugar de luaL_getn y nada en lugar de luaL_setn.
luaL_openlib ha sido reemplazada por luaL_register.
luaL_checkudata ahora provoca un error cuando el valor
dado no es un userdata del tipo esperado. (En Lua 5.0 retornaba NULL.)
Aqu� aparece la sintaxis completa de Lua en la notaci�n BNF extendida. No describe las prioridades de los operadores.
chunk ::= {sentencia [';']} [�ltima_sentencia[';']]
bloque ::= chunk
sentencia ::= varlist '=' explist |
llamada_a_func |
do bloque end |
while exp do bloque end |
repeat bloque until exp |
if exp then bloque {elseif exp then bloque} [else bloque] end |
for nombre '=' exp ',' exp [',' exp] do bloque end |
for lista_de_nombres in explist do bloque end |
function nombre_de_func cuerpo_de_func |
local function nombre cuerpo_de_func |
local lista_de_nombres ['=' explist]
�ltima_sentencia ::= return [explist] | break
nombre_de_func ::= nombre {'.' nombre} [':' nombre]
varlist ::= var {',' var}
var ::= nombre | prefixexp '[' exp ']' | prefixexp '.' nombre
lista_de_nombres ::= nombre {',' nombre}
explist ::= {exp ','} exp
exp ::= nil | false | true | n�mero | string | '...' |
func | prefixexp | constructor_de_tabla |
exp operador_binario exp | operador_unario exp
prefixexp ::= var | llamada_a_func | '(' exp ')'
llamada_a_func ::= prefixexp arg_actuales | prefixexp ':' nombre args_actuales
args_actuales ::= '(' [explist] ')' | constructor_de_tabla | string
func ::= function cuerpo_de_func
cuerpo_de_func ::= '(' [args_formal_list] ')' bloque end
args_formal_list ::= lista_de_nombres [',' '...'] | '...'
constructor_de_tabla ::= '{' [lista_de_campos] '}'
lista_de_campos ::= campo {separador_de_campo campo} [separador_de_campo]
campo ::= '[' exp ']' '=' exp | nombre '=' exp | exp
separador_de_campo ::= ',' | ';'
operador_binario ::= '+' | '-' | '*' | '/' | '^' | '%' |
'..' | '<' | '<=' | '>' | '>=' | '==' |
'~=' | and | or
operador_unario ::= '-' | not | '#'
He intentado ser lo m�s fiel posible al original; probablemente hay errores y erratas; en caso de duda cons�ltese el original en ingl�s.
Algunas palabras son de uso tan com�n en inform�tica que se utilizan en espa�ol sin traducir. Otras tienen por traducci�n una oraci�n completa y por tanto ser�a bastante poco coherente introducir esa frase en cada lugar. He preferido, por tanto, dejarlas en el texto (indicadas en it�lica como es costumbre en espa�ol con palabras de otros idiomas), exponiendo aqu� la traducci�n.
Algunas otras palabras han tenido la traducci�n siguiente: