| % $Id: manual.tex,v 1.35 2000/04/14 17:47:55 roberto Exp roberto $ |
| |
| \documentclass[11pt]{article} |
| \usepackage{fullpage,bnf} |
| |
| \catcode`\_=12 |
| |
| \newcommand{\See}[1]{Section~\ref{#1}} |
| \newcommand{\see}[1]{(see \See{#1})} |
| \newcommand{\M}[1]{\emph{#1}} |
| \newcommand{\T}[1]{{\tt #1}} |
| \newcommand{\Math}[1]{$#1$} |
| \newcommand{\nil}{{\bf nil}} |
| \newcommand{\Line}{\rule{\linewidth}{.5mm}} |
| \def\tecgraf{{\sf TeC\kern-.21em\lower.7ex\hbox{Graf}}} |
| |
| \newcommand{\Index}[1]{#1\index{#1}} |
| \newcommand{\IndexVerb}[1]{\T{#1}\index{#1}} |
| \newcommand{\Def}[1]{\emph{#1}\index{#1}} |
| \newcommand{\Deffunc}[1]{\index{#1}} |
| |
| \newcommand{\ff}{$\bullet$\ } |
| |
| \newcommand{\Version}{4.0} |
| |
| \makeindex |
| |
| \begin{document} |
| |
| \title{Reference Manual of the Programming Language Lua \Version} |
| |
| \author{% |
| Roberto Ierusalimschy\quad |
| Luiz Henrique de Figueiredo\quad |
| Waldemar Celes |
| \vspace{1.0ex}\\ |
| \smallskip |
| \small\tt lua@tecgraf.puc-rio.br |
| \vspace{2.0ex}\\ |
| %MCC 08/95 --- |
| \tecgraf\ --- Computer Science Department --- PUC-Rio |
| } |
| |
| \date{{\small \tt\$Date: 2000/04/14 17:47:55 $ $}} |
| |
| \maketitle |
| |
| \thispagestyle{empty} |
| \pagestyle{empty} |
| |
| \begin{abstract} |
| \noindent |
| Lua is a programming language originally designed for extending applications, |
| but also frequently used as a general-purpose, stand-alone language. |
| Lua combines simple procedural syntax (similar to Pascal) |
| with powerful data description constructs based on associative |
| arrays and extensible semantics. |
| Lua is dynamically typed, interpreted from opcodes, |
| and has automatic memory management with garbage collection, |
| making it ideal for configuration, scripting, and rapid prototyping. |
| |
| This document describes version \Version\ of the Lua programming language |
| and the API that allows interaction between Lua programs and their |
| host C programs. |
| \end{abstract} |
| \vspace{4ex} |
| \begin{quotation} |
| \small |
| \begin{center}{\bf Sum\'ario}\end{center} |
| \vspace{1ex} |
| \noindent |
| Lua \'e uma linguagem de programa\c{c}\~ao originalmente projetada para |
| extens\~ao de aplica\c{c}\~oes, |
| e que \'e tamb\'em frequentemente usada como uma linguagem de |
| prop\'osito geral. |
| Lua combina uma sintaxe procedural simples (similar a Pascal) |
| com poderosas facilidades para descri\c{c}\~ao de dados baseadas |
| em tabelas associativas e uma sem\^antica estens\'{\i}vel. |
| Lua tem tipagem din\^amica, \'e interpretada via opcodes, |
| e tem gerenciamento autom\'atico de mem\'oria com coleta de lixo, |
| tornando-se ideal para configura\c{c}\~ao, scripting, |
| e prototipagem r\'apida. |
| |
| Este documento descreve a vers\~ao \Version\ da linguagem de |
| programa\c{c}\~ao Lua e a Interface de Programa\c{c}\~ao (API) que permite |
| a intera\c{c}\~ao entre programas Lua e programas C hospedeiros. |
| \end{quotation} |
| |
| |
| \newpage |
| \begin{quotation} |
| \parskip=10pt |
| \noindent |
| \footnotesize |
| Copyright \copyright\ 1994--2000 TeCGraf, PUC-Rio. All rights reserved. |
| |
| \noindent |
| Permission is hereby granted, without written agreement and without license |
| or royalty fees, to use, copy, modify, and distribute this software and its |
| documentation for any purpose, including commercial applications, subject to |
| the following conditions: |
| \begin{itemize} |
| \item The above copyright notice and this permission notice shall appear in all |
| copies or substantial portions of this software. |
| |
| \item The origin of this software must not be misrepresented; you must not |
| claim that you wrote the original software. If you use this software in a |
| product, an acknowledgment in the product documentation would be greatly |
| appreciated (but it is not required). |
| |
| \item Altered source versions must be plainly marked as such, and must not be |
| misrepresented as being the original software. |
| \end{itemize} |
| The authors specifically disclaim any warranties, including, but not limited |
| to, the implied warranties of merchantability and fitness for a particular |
| purpose. The software provided hereunder is on an ``as is'' basis, and the |
| authors have no obligation to provide maintenance, support, updates, |
| enhancements, or modifications. In no event shall TeCGraf, PUC-Rio, or the |
| authors be held liable to any party for direct, indirect, special, |
| incidental, or consequential damages arising out of the use of this software |
| and its documentation. |
| |
| \noindent |
| The Lua language and this implementation have been entirely designed and |
| written by Waldemar Celes, Roberto Ierusalimschy and Luiz Henrique de |
| Figueiredo at TeCGraf, PUC-Rio. |
| |
| \noindent |
| This implementation contains no third-party code. |
| \end{quotation} |
| |
| \newpage |
| |
| \tableofcontents |
| |
| \newpage |
| \setcounter{page}{1} |
| \pagestyle{plain} |
| |
| |
| \section{Introduction} |
| |
| Lua is an extension programming language designed to support |
| general procedural programming with data description |
| facilities. |
| Lua is intended to be used as a light-weight, but powerful, |
| configuration language for any program that needs one. |
| |
| Lua is implemented as a library, written in C. |
| Being an extension language, Lua has no notion of a ``main'' program: |
| it only works \emph{embedded} in a host client, |
| called the \emph{embedding} program. |
| This host program can invoke functions to execute a piece of |
| code in Lua, can write and read Lua variables, |
| and can register C functions to be called by Lua code. |
| Through the use of C functions, Lua can be augmented to cope with |
| a wide range of different domains, |
| thus creating customized programming languages sharing a syntactical framework. |
| |
| Lua is free-distribution software, |
| and provided as usual with no guarantees, |
| as stated in the copyright notice. |
| The implementation described in this manual is available |
| at the following URL's: |
| \begin{verbatim} |
| http://www.tecgraf.puc-rio.br/lua/ |
| ftp://ftp.tecgraf.puc-rio.br/pub/lua/lua.tar.gz |
| \end{verbatim} |
| |
| |
| \section{Environment and Chunks} |
| |
| All statements in Lua are executed in a \Def{global environment}. |
| This environment, which keeps all global variables, |
| is initialized with a call from the embedding program to |
| \verb|lua_newstate| and |
| persists until a call to \verb|lua_close|, |
| or the end of the embedding program. |
| Optionally, a user can create multiple independent global |
| environments \see{mangstate}. |
| |
| The global environment can be manipulated by Lua code or |
| by the embedding program, |
| which can read and write global variables |
| using API functions from the library that implements Lua. |
| |
| \Index{Global variables} do not need declaration. |
| Any variable is assumed to be global unless explicitly declared local |
| \see{localvar}. |
| Before the first assignment, the value of a global variable is \nil; |
| this default can be changed \see{tag-method}. |
| |
| The unit of execution of Lua is called a \Def{chunk}. |
| A chunk is simply a sequence of statements: |
| \begin{Produc} |
| \produc{chunk}{\rep{stat} \opt{ret}} |
| \end{Produc}% |
| Statements are described in \See{stats}. |
| (As usual, \rep{\emph{a}} means 0 or more \emph{a}'s, |
| \opt{\emph{a}} means an optional \emph{a} and \oneormore{\emph{a}} means |
| one or more \emph{a}'s.) |
| |
| A chunk may be in a file or in a string inside the host program. |
| A chunk may optionally end with a \verb|return| statement \see{return}. |
| When a chunk is executed, first all its code is pre-compiled, |
| then the statements are executed in sequential order. |
| All modifications a chunk effects on the global environment persist |
| after the chunk end. |
| |
| Chunks may also be pre-compiled into binary form; |
| see program \IndexVerb{luac} for details. |
| Text files with chunks and their binary pre-compiled forms |
| are interchangeable. |
| Lua automatically detects the file type and acts accordingly. |
| \index{pre-compilation} |
| |
| \section{\Index{Types and Tags}} \label{TypesSec} |
| |
| Lua is a dynamically typed language. |
| Variables do not have types; only values do. |
| Therefore, there are no type definitions in the language. |
| All values carry their own type. |
| Besides a type, all values also have a \Index{tag}. |
| |
| There are six \Index{basic types} in Lua: \Def{nil}, \Def{number}, |
| \Def{string}, \Def{function}, \Def{userdata}, and \Def{table}. |
| \emph{Nil} is the type of the value \nil, |
| whose main property is to be different from any other value. |
| \emph{Number} represents real (double-precision floating-point) numbers, |
| while \emph{string} has the usual meaning. |
| Lua is \Index{eight-bit clean}, |
| and so strings may contain any 8-bit character, |
| \emph{including} embedded zeros (\verb|'\0'|). |
| The \verb|type| function returns a string describing the type |
| of a given value \see{pdf-type}. |
| |
| Functions are considered first-class values in Lua. |
| This means that functions can be stored in variables, |
| passed as arguments to other functions, and returned as results. |
| Lua can call (and manipulate) functions written in Lua and |
| functions written in C. |
| They can be distinguished by their tags: |
| all Lua functions have the same tag, |
| and all C functions have the same tag, |
| which is different from the tag of Lua functions. |
| The \verb|tag| function returns the tag |
| of a given value \see{pdf-tag}. |
| |
| The type \emph{userdata} is provided to allow |
| arbitrary \Index{C pointers} to be stored in Lua variables. |
| It corresponds to a \verb|void*| and has no pre-defined operations in Lua, |
| besides assignment and equality test. |
| However, by using \emph{tag methods}, |
| the programmer can define operations for \emph{userdata} values |
| \see{tag-method}. |
| |
| The type \emph{table} implements \Index{associative arrays}, |
| that is, \Index{arrays} that can be indexed not only with numbers, |
| but with any value (except \nil). |
| Therefore, this type may be used not only to represent ordinary arrays, |
| but also symbol tables, sets, records, etc. |
| Tables are the main data structuring mechanism in Lua. |
| To represent \Index{records}, Lua uses the field name as an index. |
| The language supports this representation by |
| providing \verb|a.name| as syntactic sugar for \verb|a["name"]|. |
| Tables may also carry methods: |
| Because functions are first class values, |
| table fields may contain functions. |
| The form \verb|t:f(x)| is syntactic sugar for \verb|t.f(t,x)|, |
| which calls the method \verb|f| from the table \verb|t| passing |
| itself as the first parameter \see{func-def}. |
| |
| Note that tables are \emph{objects}, and not values. |
| Variables cannot contain tables, only \emph{references} to them. |
| Assignment, parameter passing, and returns always manipulate references |
| to tables, and do not imply any kind of copy. |
| Moreover, tables must be explicitly created before used |
| \see{tableconstructor}. |
| |
| Tags are mainly used to select \emph{tag methods} when |
| some events occur. |
| Tag methods are the main mechanism for extending the |
| semantics of Lua \see{tag-method}. |
| Each of the types \M{nil}, \M{number} and \M{string} has a different tag. |
| All values of each of these types have this same pre-defined tag. |
| Values of type \M{function} can have two different tags, |
| depending on whether they are Lua functions or C functions. |
| Finally, |
| values of type \M{userdata} and \M{table} have |
| variable tags, assigned by the program \see{tag-method}. |
| Tags are created with the function \verb|newtag|, |
| and the function \verb|tag| returns the tag of a given value. |
| To change the tag of a given table, |
| there is the function \verb|settag| \see{pdf-newtag}. |
| |
| |
| \section{The Language} |
| |
| This section describes the lexis, the syntax and the semantics of Lua. |
| |
| |
| \subsection{Lexical Conventions} \label{lexical} |
| |
| \Index{Identifiers} in Lua can be any string of letters, |
| digits, and underscores, |
| not beginning with a digit. |
| The definition of letter depends on the current locale: |
| Any character considered alphabetic by the current locale |
| can be used in an identifier. |
| The following words are reserved, and cannot be used as identifiers: |
| \index{reserved words} |
| \begin{verbatim} |
| and break do else |
| elseif end for function |
| if local nil not |
| or repeat return then |
| until while |
| \end{verbatim} |
| Lua is a case-sensitive language: |
| \T{and} is a reserved word, but \T{And} and \T{\'and} |
| (if the locale permits) are two other different identifiers. |
| As a convention, identifiers starting with underscore followed by |
| uppercase letters (such as \verb|_INPUT|) |
| are reserved for internal variables. |
| |
| The following strings denote other \Index{tokens}: |
| \begin{verbatim} |
| ~= <= >= < > == = + - * / % |
| ( ) { } [ ] ; , . .. ... |
| \end{verbatim} |
| |
| \Index{Literal strings} can be delimited by matching single or double quotes, |
| and can contain the C-like escape sequences |
| \verb|'\a'| (bell), |
| \verb|'\b'| (backspace), |
| \verb|'\f'| (form feed), |
| \verb|'\n'| (newline), |
| \verb|'\r'| (carriage return), |
| \verb|'\t'| (horizontal tab), |
| \verb|'\v'| (vertical tab), |
| \verb|'\\'|, (backslash), |
| \verb|'\"'|, (double quote), |
| \verb|'\''| (single quote), |
| and \verb|'\\n'| (that is, a backslash followed by a real newline, |
| which results in a newline in the string). |
| A character in a string may also be specified by its numerical value, |
| through the escape sequence \verb|'\ddd'|, |
| where \verb|ddd| is a sequence of up to three \emph{decimal} digits. |
| Strings in Lua may contain any 8-bit value, including embedded zeros. |
| |
| Literal strings can also be delimited by matching \verb|[[ ... ]]|. |
| Literals in this bracketed form may run for several lines, |
| may contain nested \verb|[[ ... ]]| pairs, |
| and do not interpret escape sequences. |
| This form is specially convenient for |
| writing strings that contain program pieces or |
| other quoted strings. |
| As an example, in a system using ASCII, |
| the following three literals are equivalent: |
| \begin{verbatim} |
| 1) "alo\n123\"" |
| 2) '\97lo\10\04923"' |
| 3) [[alo |
| 123"]] |
| \end{verbatim} |
| |
| |
| \Index{Comments} start anywhere outside a string with a |
| double hyphen (\verb|--|) and run until the end of the line. |
| Moreover, |
| the first line of a chunk is skipped if it starts with \verb|#|. |
| This facility allows the use of Lua as a script interpreter |
| in Unix systems \see{lua-sa}. |
| |
| \Index{Numerical constants} may be written with an optional decimal part, |
| and an optional decimal exponent. |
| Examples of valid numerical constants are |
| \begin{verbatim} |
| 3 3.0 3.1416 314.16e-2 0.31416E1 |
| \end{verbatim} |
| |
| \subsection{The \Index{Pre-processor}} \label{pre-processor} |
| |
| All lines that start with a \verb|$| sign are handled by a pre-processor. |
| The \verb|$| sign must be immediately |
| followed by one of the following directives: |
| \begin{description} |
| \item[\T{debug}] --- turn on debugging facilities \see{pragma}. |
| \item[\T{nodebug}] --- turn off debugging facilities \see{pragma}. |
| \item[\T{if \M{cond}}] --- starts a conditional part. |
| If \M{cond} is false, then this part is skipped by the lexical analyzer. |
| \item[\T{ifnot \M{cond}}] --- starts a conditional part. |
| If \M{cond} is true, then this part is skipped by the lexical analyzer. |
| \item[\T{end}] --- ends a conditional part. |
| \item[\T{else}] --- starts an ``else'' conditional part, |
| flipping the ``skip'' status. |
| \item[\T{endinput}] --- ends the lexical parse of the file. |
| \end{description} |
| |
| Directives may be freely nested. |
| Particularly, a \verb|$endinput| may occur inside a \verb|$if|; |
| in that case, even the matching \verb|$end| is not parsed. |
| |
| A \M{cond} part may be |
| \begin{description} |
| \item[\T{nil}] --- always false. |
| \item[\T{1}] --- always true. |
| \item[\T{\M{name}}] --- true if the value of the |
| global variable \M{name} is different from \nil. |
| Note that \M{name} is evaluated \emph{before} the chunk starts its execution. |
| Therefore, actions in a chunk do not affect its own conditional directives. |
| \end{description} |
| |
| \subsection{\Index{Coercion}} \label{coercion} |
| |
| Lua provides some automatic conversions between values at run time. |
| Any arithmetic operation applied to a string tries to convert |
| that string to a number, following the usual rules. |
| Conversely, whenever a number is used when a string is expected, |
| that number is converted to a string, in a reasonable format. |
| For complete control on how numbers are converted to strings, |
| use the \verb|format| function \see{format}. |
| |
| |
| \subsection{\Index{Adjustment}} \label{adjust} |
| |
| Functions in Lua can return many values. |
| Because there are no type declarations, |
| when a function is called |
| the system does not know how many values a function will return, |
| or how many parameters it needs. |
| Therefore, sometimes, a list of values must be \emph{adjusted}, at run time, |
| to a given length. |
| If there are more values than are needed, |
| then the excess values are thrown away. |
| If there are more needs than values, |
| then the list is extended with as many \nil's as needed. |
| Adjustment occurs in multiple assignment \see{assignment} |
| and function calls \see{functioncall}. |
| |
| |
| \subsection{Statements}\label{stats} |
| |
| Lua supports an almost conventional set of \Index{statements}, |
| similar to those in Pascal or C. |
| The conventional commands include |
| assignment, control structures and procedure calls. |
| Non-conventional commands include table constructors |
| \see{tableconstructor}, |
| and local variable declarations \see{localvar}. |
| |
| \subsubsection{Blocks} |
| A \Index{block} is a list of statements, which are executed sequentially. |
| A statement may be have an optional label, |
| and can be optionally followed by a semicolon: |
| \begin{Produc} |
| \produc{block}{\opt{label} \rep{stat sc}} |
| \produc{sc}{\opt{\ter{;}}} |
| \produc{label}{\ter{$\vert$} name \ter{$\vert$}} |
| \end{Produc}% |
| For syntactic reasons, \rwd{return} and |
| \rwd{break} statements can only be written |
| as the last statement of a block. |
| |
| A block may be explicitly delimited: |
| \begin{Produc} |
| \produc{stat}{\rwd{do} block \rwd{end}} |
| \end{Produc}% |
| This is useful to control the scope of local variables \see{localvar}, |
| and to add a \rwd{return} or a \rwd{break} statement in the middle |
| of another block: |
| \begin{verbatim} |
| do return end -- return is the last statement in this block |
| \end{verbatim} |
| |
| \subsubsection{\Index{Assignment}} \label{assignment} |
| The language allows \Index{multiple assignment}. |
| Therefore, the syntax for assignment |
| defines a list of variables on the left side, |
| and a list of expressions on the right side. |
| Both lists have their elements separated by commas: |
| \begin{Produc} |
| \produc{stat}{varlist1 \ter{=} explist1} |
| \produc{varlist1}{var \rep{\ter{,} var}} |
| \end{Produc}% |
| This statement first evaluates all values on the right side |
| and eventual indices on the left side, |
| and then makes the assignments. |
| Therefore, it can be used to exchange two values, as in |
| \begin{verbatim} |
| x, y = y, x |
| \end{verbatim} |
| The two lists may have different lengths. |
| Before the assignment, the list of values is \emph{adjusted} to |
| the length of the list of variables \see{adjust}. |
| |
| A single name can denote a global variable, a local variable, |
| or a formal parameter: |
| \begin{Produc} |
| \produc{var}{name} |
| \end{Produc}% |
| Square brackets are used to index a table: |
| \begin{Produc} |
| \produc{var}{simpleexp \ter{[} exp1 \ter{]}} |
| \end{Produc}% |
| The \M{simpleexp} should result in a table value, |
| from where the field indexed by the expression |
| value gets the assigned value. |
| |
| The syntax \verb|var.NAME| is just syntactic sugar for |
| \verb|var["NAME"]|: |
| \begin{Produc} |
| \produc{var}{simpleexp \ter{.} name} |
| \end{Produc}% |
| |
| The meaning of assignments and evaluations of global variables and |
| indexed variables can be changed by tag methods \see{tag-method}. |
| Actually, |
| an assignment \verb|x = val|, where \verb|x| is a global variable, |
| is equivalent to a call \verb|setglobal('x', val)|; |
| an assignment \verb|t[i] = val| is equivalent to |
| \verb|settable_event(t, i, val)|. |
| See \See{tag-method} for a complete description of these functions. |
| (Function \verb|setglobal| is pre-defined in Lua. |
| Function \T{settable\_event} is used only for explanatory purposes.) |
| |
| \subsubsection{Control Structures} |
| The \Index{condition expression} of a control structure may return any value. |
| All values different from \nil\ are considered true; |
| only \nil\ is considered false. |
| \T{if}'s, \T{while}'s and \T{repeat}'s have the usual meaning. |
| |
| \index{while-do}\index{repeat-until}\index{if-then-else} |
| \begin{Produc} |
| \produc{stat}{\rwd{while} exp1 \rwd{do} block \rwd{end} \OrNL |
| \rwd{repeat} block \rwd{until} exp1 \OrNL |
| \rwd{if} exp1 \rwd{then} block |
| \rep{\rwd{elseif} exp1 \rwd{then} block} |
| \opt{\rwd{else} block} \rwd{end}} |
| \end{Produc} |
| |
| \index{return} |
| A \rwd{return} is used to return values from a function or from a chunk. |
| \label{return} |
| Because they may return more than one value, |
| the syntax for a \Index{return statement} is |
| \begin{Produc} |
| \produc{stat}{\rwd{return} \opt{explist1}} |
| \end{Produc} |
| |
| \index{break} |
| A \rwd{break} statement can be used to terminate the execution of a block, |
| skipping to the next instruction after the block. |
| \begin{Produc} |
| \produc{stat}{\rwd{break} \opt{name}} |
| \end{Produc} |
| A \rwd{break} without a label ends the inner enclosing loop |
| (while, repeat, or for). |
| A \rwd{break} with a label breaks the inner enclosing |
| statement with that label. |
| |
| For syntactic reasons, \rwd{return} and \rwd{break} |
| statements can only be written as the last statement of a block. |
| |
| \subsubsection{For Statement} \label{for}\index{for} |
| |
| The \rwd{for} statement has the following syntax: |
| \begin{Produc} |
| \produc{stat}{\rwd{for} name \ter{=} exp1 \ter{,} exp1 \opt{\ter{,} exp1} |
| \rwd{do} block \rwd{end}} |
| \end{Produc} |
| A \rwd{for} statement like |
| \begin{verbatim} |
| for var=e1,e2,e3 do block end |
| \end{verbatim} |
| is equivalent to the following code: |
| \begin{verbatim} |
| 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 |
| block |
| var = var+_step |
| end |
| end |
| \end{verbatim} |
| Notice the following: |
| \begin{itemize} |
| \item \verb|_limit| and \verb|_step| are invisible variables. |
| \item The behavior is undefined if you assign to \verb|var| inside |
| the block. |
| \item If the third expression (the step) is absent, it defaults to 1. |
| \item Both the limit and the step are evaluated only once, |
| before the loop starts. |
| \item The variable \verb|var| is local to the statement; |
| you cannot use its value after the \rwd{for}. |
| \item You can use \rwd{break} to exit a \rwd{for}. |
| If you need the value of the index, |
| assign it to another variable before breaking. |
| \end{itemize} |
| |
| \subsubsection{Function Calls as Statements} \label{funcstat} |
| Because of possible side-effects, |
| function calls can be executed as statements: |
| \begin{Produc} |
| \produc{stat}{functioncall} |
| \end{Produc}% |
| In this case, all returned values are thrown away. |
| Function calls are explained in \See{functioncall}. |
| |
| \subsubsection{Local Declarations} \label{localvar} |
| \Index{Local variables} may be declared anywhere inside a block. |
| Their scope begins after the declaration and lasts until the |
| end of the block. |
| The declaration may include an initial assignment: |
| \begin{Produc} |
| \produc{stat}{\rwd{local} declist \opt{init}} |
| \produc{declist}{name \rep{\ter{,} name}} |
| \produc{init}{\ter{=} explist1} |
| \end{Produc}% |
| If present, an initial assignment has the same semantics |
| of a multiple assignment. |
| Otherwise, all variables are initialized with \nil. |
| |
| |
| \subsection{\Index{Expressions}} |
| |
| \subsubsection{\Index{Basic Expressions}} |
| The basic expressions in Lua are |
| \begin{Produc} |
| \produc{exp}{\ter{(} exp \ter{)}} |
| \produc{exp}{\rwd{nil}} |
| \produc{exp}{\ter{number}} |
| \produc{exp}{\ter{literal}} |
| \produc{exp}{function} |
| \produc{exp}{simpleexp} |
| \end{Produc}% |
| \begin{Produc} |
| \produc{simpleexp}{var} |
| \produc{simpleexp}{upvalue} |
| \produc{simpleexp}{functioncall} |
| \end{Produc}% |
| |
| Numbers (numerical constants) and |
| string literals are explained in \See{lexical}; |
| variables are explained in \See{assignment}; |
| upvalues are explained in \See{upvalue}; |
| function definitions (\M{function}) are explained in \See{func-def}; |
| function calls are explained in \See{functioncall}. |
| |
| An access to a global variable \verb|x| is equivalent to a |
| call \verb|getglobal('x')|; |
| an access to an indexed variable \verb|t[i]| is equivalent to |
| a call \verb|gettable_event(t, i)|. |
| See \See{tag-method} for a description of these functions. |
| (Function \verb|getglobal| is pre-defined in Lua. |
| Function \T{gettable\_event} is used only for explanatory purposes.) |
| |
| The non-terminal \M{exp1} is used to indicate that the values |
| returned by an expression must be adjusted to one single value: |
| \begin{Produc} |
| \produc{exp1}{exp} |
| \end{Produc} |
| |
| \subsubsection{Arithmetic Operators} |
| Lua supports the usual \Index{arithmetic operators}: |
| the binary \verb|+| (addition), |
| \verb|-| (subtraction), \verb|*| (multiplication), |
| \verb|/| (division) and \verb|^| (exponentiation), |
| and unary \verb|-| (negation). |
| If the operands are numbers, or strings that can be converted to |
| numbers (according to the rules given in \See{coercion}), |
| then all operations except exponentiation have the usual meaning. |
| Otherwise, an appropriate tag method is called \see{tag-method}. |
| An exponentiation always calls a tag method. |
| The standard mathematical library redefines this method for numbers, |
| giving the expected meaning to \Index{exponentiation} |
| \see{mathlib}. |
| |
| \subsubsection{Relational Operators} |
| Lua provides the following \Index{relational operators}: |
| \begin{verbatim} |
| == ~= < > <= >= |
| \end{verbatim} |
| All these return \nil\ as false and a value different from \nil\ as true. |
| |
| Equality first compares the tags of its operands. |
| If they are different, then the result is \nil. |
| Otherwise, their values are compared. |
| Numbers and strings are compared in the usual way. |
| Tables, userdata, and functions are compared by reference, |
| that is, two tables are considered equal only if they are the same table. |
| The operator \verb|~=| is exactly the negation of equality (\verb|==|). |
| |
| The conversion rules of \See{coercion} |
| \emph{do not} apply to equality comparisons. |
| Thus, \verb|"0"==0| evaluates to false, |
| and \verb|t[0]| and \verb|t["0"]| denote different |
| entries in a table. |
| |
| The order operators work as follows. |
| If both arguments are numbers, then they are compared as such. |
| Otherwise, if both arguments are strings, |
| then their values are compared using lexicographical order. |
| Otherwise, the \verb|"lt"| tag method is called \see{tag-method}. |
| |
| \subsubsection{Logical Operators} |
| The \Index{logical operators} are |
| \index{and}\index{or}\index{not} |
| \begin{verbatim} |
| and or not |
| \end{verbatim} |
| Like control structures, all logical operators |
| consider \nil\ as false and anything else as true. |
| The operator \verb|and| returns \nil\ if its first argument is \nil; |
| otherwise, it returns its second argument. |
| The operator \verb|or| returns its first argument |
| if it is different from \nil; |
| otherwise, it returns its second argument. |
| Both \verb|and| and \verb|or| use \Index{short-cut evaluation}, |
| that is, |
| the second operand is evaluated only when necessary. |
| |
| There are two useful Lua idioms with logical operators. |
| The first is \verb|x = x or v|, |
| which is equivalent to |
| \begin{verbatim} |
| if x == nil then x = v end |
| \end{verbatim} |
| i.e., it sets \verb|x| to a default value \verb|v| when |
| \verb|x| is not set. |
| The other is \verb|x = a and b or c|, |
| which is equivalent to |
| \begin{verbatim} |
| if a then x = b else x = c end |
| \end{verbatim} |
| provided that \verb|b| is not \nil. |
| |
| \subsubsection{Concatenation} |
| The string \Index{concatenation} operator in Lua is |
| denoted by ``\IndexVerb{..}''. |
| If both operands are strings or numbers, they are converted to |
| strings according to the rules in \See{coercion}. |
| Otherwise, the ``concat'' tag method is called \see{tag-method}. |
| |
| \subsubsection{Precedence} |
| \Index{Operator precedence} follows the table below, |
| from the lower to the higher priority: |
| \begin{verbatim} |
| and or |
| < > <= >= ~= == |
| .. |
| + - |
| * / |
| not - (unary) |
| ^ |
| \end{verbatim} |
| All binary operators are left associative, |
| except for \verb|^| (exponentiation), |
| which is right associative. |
| The pre-compiler may rearrange the order of evaluation of |
| associative operators (such as \verb|..| or \verb|+|), |
| as long as these optimizations do not change normal results. |
| However, they may change some results if you define non-associative |
| tag methods for these operators. |
| |
| \subsubsection{Table Constructors} \label{tableconstructor} |
| Table \Index{constructors} are expressions that create tables; |
| every time a constructor is evaluated, a new table is created. |
| Constructors can be used to create empty tables, |
| or to create a table and initialize some fields. |
| |
| The general syntax for constructors is |
| \begin{Produc} |
| \produc{tableconstructor}{\ter{\{} fieldlist \ter{\}}} |
| \produc{fieldlist}{lfieldlist \Or ffieldlist \Or lfieldlist \ter{;} ffieldlist |
| \Or ffieldlist \ter{;} lfieldlist} |
| \produc{lfieldlist}{\opt{lfieldlist1}} |
| \produc{ffieldlist}{\opt{ffieldlist1}} |
| \end{Produc} |
| |
| The form \emph{lfieldlist1} is used to initialize lists: |
| \begin{Produc} |
| \produc{lfieldlist1}{exp \rep{\ter{,} exp} \opt{\ter{,}}} |
| \end{Produc}% |
| The expressions in the list are assigned to consecutive numerical indices, |
| starting with 1. |
| For example, |
| \begin{verbatim} |
| a = {"v1", "v2", 34} |
| \end{verbatim} |
| is equivalent to |
| \begin{verbatim} |
| do |
| local temp = {} |
| temp[1] = "v1" |
| temp[2] = "v2" |
| temp[3] = 34 |
| a = temp |
| end |
| \end{verbatim} |
| |
| The form \emph{ffieldlist1} initializes other fields in a table: |
| \begin{Produc} |
| \produc{ffieldlist1}{ffield \rep{\ter{,} ffield} \opt{\ter{,}}} |
| \produc{ffield}{\ter{[} exp \ter{]} \ter{=} exp \Or name \ter{=} exp} |
| \end{Produc}% |
| For example, |
| \begin{verbatim} |
| a = {[f(k)] = g(y), x = 1, y = 3, [0] = b+c} |
| \end{verbatim} |
| is equivalent to |
| \begin{verbatim} |
| do |
| local temp = {} |
| temp[f(k)] = g(y) |
| temp.x = 1 -- or temp["x"] = 1 |
| temp.y = 3 -- or temp["y"] = 3 |
| temp[0] = b+c |
| a = temp |
| end |
| \end{verbatim} |
| An expression like \verb|{x = 1, y = 4}| is |
| in fact syntactic sugar for \verb|{["x"] = 1, ["y"] = 4}|. |
| |
| Both forms may have an optional trailing comma, |
| and can be used in the same constructor separated by |
| a semi-collon. |
| For example, all forms below are correct: |
| \begin{verbatim} |
| x = {;} |
| x = {'a', 'b',} |
| x = {type='list'; 'a', 'b'} |
| x = {f(0), f(1), f(2),; n=3,} |
| \end{verbatim} |
| |
| \subsubsection{Function Calls} \label{functioncall} |
| A \Index{function call} has the following syntax: |
| \begin{Produc} |
| \produc{functioncall}{simpleexp args} |
| \end{Produc}% |
| First, \M{simpleexp} is evaluated. |
| If its value has type \emph{function}, |
| then this function is called, |
| with the given arguments. |
| Otherwise, the ``function'' tag method is called, |
| having as first parameter the value of \M{simpleexp}, |
| and then the original call arguments. |
| |
| The form |
| \begin{Produc} |
| \produc{functioncall}{simpleexp \ter{:} name args} |
| \end{Produc}% |
| can be used to call ``methods''. |
| A call \verb|simpleexp:name(...)| |
| is syntactic sugar for |
| \begin{verbatim} |
| simpleexp.name(simpleexp, ...) |
| \end{verbatim} |
| except that \verb|simpleexp| is evaluated only once. |
| |
| Arguments have the following syntax: |
| \begin{Produc} |
| \produc{args}{\ter{(} \opt{explist1} \ter{)}} |
| \produc{args}{tableconstructor} |
| \produc{args}{\ter{literal}} |
| \produc{explist1}{\rep{exp1 \ter{,}} exp} |
| \end{Produc}% |
| All argument expressions are evaluated before the call. |
| A call of the form \verb|f{...}| is syntactic sugar for |
| \verb|f({...})|, that is, |
| the parameter list is a single new table. |
| A call of the form \verb|f'...'| |
| (or \verb|f"..."| or \verb|f[[...]]|) is syntactic sugar for |
| \verb|f('...')|, that is, |
| the parameter list is a single literal string. |
| |
| Because a function can return any number of results |
| \see{return}, |
| the number of results must be adjusted before used. |
| If the function is called as a statement \see{funcstat}, |
| then its return list is adjusted to~0, |
| thus discarding all returned values. |
| If the function is called in a place that needs a single value |
| (syntactically denoted by the non-terminal \M{exp1}), |
| then its return list is adjusted to~1, |
| thus discarding all returned values but the first one. |
| If the function is called in a place that can hold many values |
| (syntactically denoted by the non-terminal \M{exp}), |
| then no adjustment is made. |
| The only places that can hold many values |
| is the last (or the only) expression in an assignment, |
| in an argument list, or in a return statement; |
| see examples below. |
| \begin{verbatim} |
| f(); -- adjusted to 0 |
| g(f(), x); -- f() is adjusted to 1 result |
| g(x, f()); -- g gets x plus all values returned by f() |
| a,b,c = f(), x; -- f() is adjusted to 1 result (and c gets nil) |
| a,b,c = x, f(); -- f() is adjusted to 2 |
| a,b,c = f(); -- f() is adjusted to 3 |
| return f(); -- returns all values returned by f() |
| \end{verbatim} |
| |
| \subsubsection{\Index{Function Definitions}} \label{func-def} |
| |
| The syntax for function definition is |
| \begin{Produc} |
| \produc{function}{\rwd{function} \ter{(} \opt{parlist1} \ter{)} |
| block \rwd{end}} |
| \produc{stat}{\rwd{function} funcname \ter{(} \opt{parlist1} \ter{)} |
| block \rwd{end}} |
| \produc{funcname}{name \Or name \ter{.} name} |
| \end{Produc} |
| The statement |
| \begin{verbatim} |
| function f (...) |
| ... |
| end |
| \end{verbatim} |
| is just syntactic sugar for |
| \begin{verbatim} |
| f = function (...) |
| ... |
| end |
| \end{verbatim} |
| and |
| \begin{verbatim} |
| function o.f (...) |
| ... |
| end |
| \end{verbatim} |
| is syntactic sugar for |
| \begin{verbatim} |
| o.f = function (...) |
| ... |
| end |
| \end{verbatim} |
| |
| A function definition is an executable expression, |
| whose value has type \emph{function}. |
| When Lua pre-compiles a chunk, |
| all its function bodies are pre-compiled, too. |
| Then, whenever Lua executes the function definition, |
| its upvalues are fixed \see{upvalue}, |
| and the function is \emph{instantiated} (or \emph{closed}). |
| This function instance (or \emph{closure}) |
| is the final value of the expression. |
| Different instances of the same function |
| may have different upvalues. |
| |
| Parameters act as local variables, |
| initialized with the argument values: |
| \begin{Produc} |
| \produc{parlist1}{\ter{\ldots}} |
| \produc{parlist1}{name \rep{\ter{,} name} \opt{\ter{,} \ter{\ldots}}} |
| \end{Produc} |
| \label{vararg} |
| When a function is called, |
| the list of \Index{arguments} is adjusted to |
| the length of the list of parameters \see{adjust}, |
| unless the function is a \Def{vararg} function, |
| indicated by the dots (\ldots) at the end of its parameter list. |
| A vararg function does not adjust its argument list; |
| instead, it collects any extra arguments into an implicit parameter, |
| called \IndexVerb{arg}. |
| This parameter is always initialized as a table, |
| with a field \verb|n| whose value is the number of extra arguments, |
| and the extra arguments at positions 1,~2,~\ldots. |
| |
| As an example, suppose definitions like: |
| \begin{verbatim} |
| function f(a, b) end |
| function g(a, b, ...) end |
| function r() return 1,2,3 end |
| \end{verbatim} |
| Then, we have the following mapping from arguments to parameters: |
| \begin{verbatim} |
| CALL PARAMETERS |
| |
| 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, arg={n=0} |
| g(3, 4) a=3, b=4, arg={n=0} |
| g(3, 4, 5, 8) a=3, b=4, arg={5, 8; n=2} |
| g(5, r()) a=5, b=1, arg={2, 3; n=2} |
| \end{verbatim} |
| |
| Results are returned using the \verb|return| statement \see{return}. |
| If control reaches the end of a function without a return instruction, |
| then the function returns with no results. |
| |
| There is a special syntax for defining \Index{methods}, |
| that is, functions that have an implicit extra parameter \IndexVerb{self}: |
| \begin{Produc} |
| \produc{function}{\rwd{function} name \ter{:} name \ter{(} \opt{parlist1} |
| \ter{)} block \rwd{end}} |
| \end{Produc}% |
| Thus, a declaration like |
| \begin{verbatim} |
| function v:f (...) |
| ... |
| end |
| \end{verbatim} |
| is equivalent to |
| \begin{verbatim} |
| v.f = function (self, ...) |
| ... |
| end |
| \end{verbatim} |
| that is, the function gets an extra formal parameter called \verb|self|. |
| Note that the variable \verb|v| must have been |
| previously initialized with a table value. |
| |
| |
| \subsection{Visibility and Upvalues} \label{upvalue} |
| \index{Visibility} \index{Upvalues} |
| |
| A function body may refer to its own local variables |
| (which include its parameters) and to global variables, |
| as long as they are not shadowed by local |
| variables from enclosing functions. |
| A function \emph{cannot} access a local |
| variable from an enclosing function, |
| since such variables may no longer exist when the function is called. |
| However, a function may access the \emph{value} of a local variable |
| from an enclosing function, using \emph{upvalues}. |
| |
| \begin{Produc} |
| \produc{upvalue}{\ter{\%} name} |
| \end{Produc} |
| An upvalue is somewhat similar to a variable expression, |
| but whose value is frozen when the function wherein it |
| appears is instantiated. |
| The name used in an upvalue may be the name of any variable visible |
| at the point where the function is defined. |
| |
| Here are some examples: |
| \begin{verbatim} |
| a,b,c = 1,2,3 -- global variables |
| function f (x) |
| local b -- x and b are local to f |
| local g = function (a) |
| local y -- a and y are local to g |
| p = a -- OK, access local 'a' |
| p = c -- OK, access global 'c' |
| p = b -- ERROR: cannot access a variable in outer scope |
| p = %b -- OK, access frozen value of 'b' (local to 'f') |
| p = %c -- OK, access frozen value of global 'c' |
| p = %y -- ERROR: 'y' is not visible where 'g' is defined |
| end -- g |
| end -- f |
| \end{verbatim} |
| |
| |
| \subsection{Tag Methods} \label{tag-method} |
| |
| Lua provides a powerful mechanism to extend its semantics, |
| called \Def{tag methods}. |
| A tag method is a programmer-defined function |
| that is called at specific key points during the evaluation of a program, |
| allowing the programmer to change the standard Lua behavior at these points. |
| Each of these points is called an \Def{event}. |
| |
| The tag method called for any specific event is selected |
| according to the tag of the values involved |
| in the event \see{TypesSec}. |
| The function \IndexVerb{settagmethod} changes the tag method |
| associated with a given pair \M{(tag, event)}. |
| Its first parameter is the tag, the second parameter is the event name |
| (a string; see below), |
| and the third parameter is the new method (a function), |
| or \nil\ to restore the default behavior for the pair. |
| The function returns the previous tag method for that pair. |
| Another function, \IndexVerb{gettagmethod}, |
| receives a tag and an event name and returns the |
| current method associated with the pair. |
| |
| Tag methods are called in the following events, |
| identified by the given names. |
| The semantics of tag methods is better explained by a Lua function |
| describing the behavior of the interpreter at each event. |
| The function not only shows when a tag method is called, |
| but also its arguments, its results, and the default behavior. |
| Please notice that the code shown here is only illustrative; |
| the real behavior is hard coded in the interpreter, |
| and it is much more efficient than this simulation. |
| All functions used in these descriptions |
| (\verb|rawgetglobal|, \verb|tonumber|, \verb|call|, etc.) |
| are described in \See{predefined}. |
| |
| \begin{description} |
| |
| \item[``add'':]\index{add event} |
| called when a \verb|+| operation is applied to non numerical operands. |
| |
| The function \verb|getbinmethod| defines how Lua chooses a tag method |
| for a binary operation. |
| First, Lua tries the first operand. |
| If its tag does not define a tag method for the operation, |
| then Lua tries the second operand. |
| If it also fails, then it gets a tag method from tag~0: |
| \begin{verbatim} |
| function getbinmethod (op1, op2, event) |
| return gettagmethod(tag(op1), event) or |
| gettagmethod(tag(op2), event) or |
| gettagmethod(0, event) |
| end |
| \end{verbatim} |
| \begin{verbatim} |
| function add_event (op1, op2) |
| local o1, o2 = tonumber(op1), tonumber(op2) |
| if o1 and o2 then -- both operands are numeric |
| return o1+o2 -- '+' here is the primitive 'add' |
| else -- at least one of the operands is not numeric |
| local tm = getbinmethod(op1, op2, "add") |
| if tm then |
| -- call the method with both operands and an extra |
| -- argument with the event name |
| return tm(op1, op2, "add") |
| else -- no tag method available: default behavior |
| error("unexpected type at arithmetic operation") |
| end |
| end |
| end |
| \end{verbatim} |
| |
| \item[``sub'':]\index{sub event} |
| called when a \verb|-| operation is applied to non numerical operands. |
| Behavior similar to the \verb|"add"| event. |
| |
| \item[``mul'':]\index{mul event} |
| called when a \verb|*| operation is applied to non numerical operands. |
| Behavior similar to the \verb|"add"| event. |
| |
| \item[``div'':]\index{div event} |
| called when a \verb|/| operation is applied to non numerical operands. |
| Behavior similar to the \verb|"add"| event. |
| |
| \item[``pow'':]\index{pow event} |
| called when a \verb|^| operation is applied. |
| \begin{verbatim} |
| function pow_event (op1, op2) |
| local tm = getbinmethod(op1, op2, "pow") |
| if tm then |
| -- call the method with both operands and an extra |
| -- argument with the event name |
| return tm(op1, op2, "pow") |
| else -- no tag method available: default behavior |
| error("unexpected type at arithmetic operation") |
| end |
| end |
| \end{verbatim} |
| |
| \item[``unm'':]\index{unm event} |
| called when an unary \verb|-| operation is applied to a non numerical operand. |
| \begin{verbatim} |
| function unm_event (op) |
| local o = tonumber(op) |
| if o then -- operand is numeric |
| return -o -- '-' here is the primitive 'unm' |
| else -- the operand is not numeric. |
| -- Try to get a tag method from the operand; |
| -- if it does not have one, try a "global" one (tag 0) |
| local tm = gettagmethod(tag(op), "unm") or |
| gettagmethod(0, "unm") |
| if tm then |
| -- call the method with the operand, nil, and an extra |
| -- argument with the event name |
| return tm(op, nil, "unm") |
| else -- no tag method available: default behavior |
| error("unexpected type at arithmetic operation") |
| end |
| end |
| end |
| \end{verbatim} |
| |
| \item[``lt'':]\index{lt event} |
| called when an order operation is applied to non-numerical |
| or non-string operands. |
| It corresponds to the \verb|<| operator. |
| \begin{verbatim} |
| function lt_event (op1, op2) |
| if type(op1) == "number" and type(op2) == "number" then |
| return op1 < op2 -- numeric comparison |
| elseif type(op1) == "string" and type(op2) == "string" then |
| return op1 < op2 -- lexicographic comparison |
| else |
| local tm = getbinmethod(op1, op2, "lt") |
| if tm then |
| return tm(op1, op2, "lt") |
| else |
| error("unexpected type at comparison"); |
| end |
| end |
| end |
| \end{verbatim} |
| The other order operators use this tag method according to the |
| usual equivalences: |
| \begin{verbatim} |
| a>b <=> b<a |
| a<=b <=> not (b<a) |
| a>=b <=> not (a<b) |
| \end{verbatim} |
| |
| \item[``concat'':]\index{concatenation event} |
| called when a concatenation is applied to non string operands. |
| \begin{verbatim} |
| 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 -- primitive string concatenation |
| else |
| local tm = getbinmethod(op1, op2, "concat") |
| if tm then |
| return tm(op1, op2, "concat") |
| else |
| error("unexpected type for concatenation") |
| end |
| end |
| end |
| \end{verbatim} |
| |
| \item[``index'':]\index{index event} |
| called when Lua tries to retrieve the value of an index |
| not present in a table. |
| See event \verb|"gettable"| for its semantics. |
| |
| \item[``getglobal'':]\index{getglobal event} |
| called whenever Lua needs the value of a global variable. |
| This method can only be set for \nil\ and for tags |
| created by \verb|newtag|. |
| \begin{verbatim} |
| function getglobal (varname) |
| local value = rawgetglobal(varname) |
| local tm = gettagmethod(tag(value), "getglobal") |
| if not tm then |
| return value |
| else |
| return tm(varname, value) |
| end |
| end |
| \end{verbatim} |
| The function \verb|getglobal| is pre-defined in Lua \see{predefined}. |
| |
| \item[``setglobal'':]\index{setglobal event} |
| called whenever Lua assigns to a global variable. |
| This method cannot be set for numbers, strings, and tables and |
| userdata with default tags. |
| \begin{verbatim} |
| function setglobal (varname, newvalue) |
| local oldvalue = rawgetglobal(varname) |
| local tm = gettagmethod(tag(oldvalue), "setglobal") |
| if not tm then |
| rawsetglobal(varname, newvalue) |
| else |
| tm(varname, oldvalue, newvalue) |
| end |
| end |
| \end{verbatim} |
| Notice: the function \verb|setglobal| is pre-defined in Lua \see{predefined}. |
| |
| \item[``gettable'':]\index{gettable event} |
| called whenever Lua accesses an indexed variable. |
| This method cannot be set for tables with default tag. |
| \begin{verbatim} |
| function gettable_event (table, index) |
| local tm = gettagmethod(tag(table), "gettable") |
| if tm then |
| return tm(table, index) |
| elseif type(table) ~= "table" then |
| error("indexed expression not a table"); |
| else |
| local v = rawgettable(table, index) |
| tm = gettagmethod(tag(table), "index") |
| if v == nil and tm then |
| return tm(table, index) |
| else |
| return v |
| end |
| end |
| end |
| \end{verbatim} |
| |
| \item[``settable'':]\index{settable event} |
| called when Lua assigns to an indexed variable. |
| This method cannot be set for tables with default tag. |
| \begin{verbatim} |
| function settable_event (table, index, value) |
| local tm = gettagmethod(tag(table), "settable") |
| if tm then |
| tm(table, index, value) |
| elseif type(table) ~= "table" then |
| error("indexed expression not a table") |
| else |
| rawsettable(table, index, value) |
| end |
| end |
| \end{verbatim} |
| |
| \item[``function'':]\index{function event} |
| called when Lua tries to call a non function value. |
| \begin{verbatim} |
| function function_event (func, ...) |
| if type(func) == "function" then |
| return call(func, arg) |
| else |
| local tm = gettagmethod(tag(func), "function") |
| if tm then |
| for i=arg.n,1,-1 do |
| arg[i+1] = arg[i] |
| end |
| arg.n = arg.n+1 |
| arg[1] = func |
| return call(tm, arg) |
| else |
| error("call expression not a function") |
| end |
| end |
| end |
| \end{verbatim} |
| |
| \item[``gc'':]\index{gc event} |
| called when Lua is ``garbage collecting'' an userdata. |
| This tag method can be set only from C, |
| and cannot be set for an userdata with default tag. |
| For each userdata to be collected, |
| Lua does the equivalent of the following function: |
| \begin{verbatim} |
| function gc_event (obj) |
| local tm = gettagmethod(tag(obj), "gc") |
| if tm then |
| tm(obj) |
| end |
| end |
| \end{verbatim} |
| Moreover, at the end of a garbage collection cycle, |
| Lua does the equivalent of the call \verb|gc_event(nil)|. |
| |
| \end{description} |
| |
| |
| |
| \subsection{Error Handling} \label{error} |
| |
| Because Lua is an extension language, |
| all Lua actions start from C code in the host program |
| calling a function from the Lua library. |
| Whenever an error occurs during Lua compilation or execution, |
| function \verb|_ERRORMESSAGE| is called \Deffunc{_ERRORMESSAGE} |
| (provided it is different from \nil), |
| and then the corresponding function from the library |
| (\verb|lua_dofile|, \verb|lua_dostring|, |
| \verb|lua_dobuffer|, or \verb|lua_callfunction|) |
| is terminated, returning an error condition. |
| |
| The only argument to \verb|_ERRORMESSAGE| is a string |
| describing the error. |
| The default definition for |
| this function calls \verb|_ALERT|, \Deffunc{_ALERT} |
| which prints the message to \verb|stderr| \see{alert}. |
| The standard I/O library redefines \verb|_ERRORMESSAGE|, |
| and uses the debug facilities \see{debugI} |
| to print some extra information, |
| such as the call stack. |
| |
| To provide more information about errors, |
| Lua programs should include the compilation pragma \verb|$debug|. |
| \index{debug pragma}\label{pragma} |
| When an error occurs in a chunk compiled with this option, |
| the I/O error-message routine is able to print the number of the |
| lines where the calls (and the error) were made. |
| |
| Lua code can explicitly generate an error by calling the built-in |
| function \verb|error| \see{pdf-error}. |
| Lua code can ``catch'' an error using the built-in function |
| \verb|call| \see{pdf-call}. |
| |
| |
| |
| \section{The Application Program Interface} |
| |
| This section describes the API for Lua, that is, |
| the set of C functions available to the host program to communicate |
| with the Lua library. |
| The API functions can be classified in the following categories: |
| \begin{enumerate} |
| \item managing states; |
| \item exchanging values between C and Lua; |
| \item executing Lua code; |
| \item manipulating (reading and writing) Lua objects; |
| \item calling Lua functions; |
| \item defining C functions to be called by Lua; |
| \item manipulating references to Lua Objects. |
| \end{enumerate} |
| All API functions and related types and constants |
| are declared in the header file \verb|lua.h|. |
| |
| Even when we use the term \emph{function}, |
| \emph{any facility in the API may be provided as a macro instead}. |
| Any of such macros uses once and only once each of its arguments. |
| |
| |
| \subsection{States} \label{mangstate} |
| |
| The Lua library is reentrant. |
| It does not have any global variable. |
| The whole state of the Lua interpreter |
| (global variables, stack, tag methods, etc) |
| is stored in a dynamic structure \Deffunc{lua_State}; |
| this state must be passed as the first argument to almost |
| every function in the library. |
| |
| Before calling any API function, |
| you must create a state. |
| This is done by calling\Deffunc{lua_newstate} |
| \begin{verbatim} |
| lua_State *lua_newstate (const char *s, ...); |
| \end{verbatim} |
| The arguments to this function is a list of name-value options, |
| terminated with \verb|NULL|. |
| Currently, the function accepts the following options: |
| \begin{itemize} |
| \item \verb|"stack"| - the stack size. |
| Each function call needs one stack position for each local variable |
| and temporary variables, plus one position. |
| The stack must also have at least ten extra positions available. |
| For very small implementations, without recursive functions, |
| a size of 100 should be enough. |
| The default is 1K. |
| |
| \item \verb|"builtin"| - the value is a boolean (0 or 1) that |
| indicates whether the predefined functions should be loaded or not. |
| The default is to load those functions. |
| \end{itemize} |
| For instance, the call |
| \begin{verbatim} |
| lua_State *L = lua_newstate(NULL); |
| \end{verbatim} |
| creates a new state with a stack of 1K positions, |
| and with the predefined functions loaded; |
| the call |
| \begin{verbatim} |
| lua_State *L = lua_newstate("builtin", 0, "stack", 100, NULL); |
| \end{verbatim} |
| creates a new state with a stack of 100 positions, |
| without the predefined functions. |
| |
| To release a state, you call |
| \begin{verbatim} |
| void lua_close (lua_State *L); |
| \end{verbatim} |
| This function destroys all objects in the current Lua environment |
| (calling the correspondent garbage collector tag methods), |
| and frees all dynamic memory used by the state. |
| Usually, you do not need to call this function, |
| because these resources are naturally released when the program ends. |
| |
| With the exception of \verb|lua_newstate|, |
| all functions in the API get at its first argument a state. |
| However, most applications use a single state. |
| To avoid the burden of passing this only state explicitly to all |
| functions, and also to keep compatibility with old versions of Lua, |
| the API provides a set of macros and one global variable that |
| take care of this state argument for single-state applications: |
| \begin{verbatim} |
| #ifndef LUA_REENTRANT |
| \end{verbatim} |
| \begin{verbatim} |
| extern lua_State *lua_state; |
| \end{verbatim} |
| \begin{verbatim} |
| #define lua_close() (lua_close)(lua_state) |
| #define lua_dofile(filename) (lua_dofile)(lua_state, filename) |
| #define lua_dostring(str) (lua_dostring)(lua_state, str) |
| ... |
| \end{verbatim} |
| \begin{verbatim} |
| #endif |
| \end{verbatim} |
| For each function in the API, there is a macro with the same name |
| that supplies \verb|lua_state| as the first argument to the call. |
| (The parentheses around the function name avoid it being expanded |
| again as a macro.) |
| The only exception is \verb|lua_newstate|; |
| in this case, the corresponding macro is |
| \begin{verbatim} |
| #define lua_open() ((void)(lua_state?0:(lua_state=lua_newstate(0)))) |
| \end{verbatim} |
| It checks whether the global state has been initialized; |
| if not, it creates a new state with default settings and |
| assigns it to \verb|lua_newstate|. |
| |
| By default, those macros are all active. |
| If you will use multiple states, |
| and therefore will want to provide the state |
| argument explicitly for each call, |
| you should define \IndexVerb{LUA_REENTRANT} before |
| including \verb|lua.h| in your code: |
| \begin{verbatim} |
| #define LUA_REENTRANT |
| #include "lua.h" |
| \end{verbatim} |
| |
| In the sequel, we will show all functions in the single-state form |
| (therefore, they are actually macros). |
| When you define \verb|LUA_REENTRANT|, |
| all of them get a state as the first parameter. |
| |
| |
| \subsection{Exchanging Values between C and Lua} \label{valuesCLua} |
| Because Lua has no static type system, |
| all values passed between Lua and C have type |
| \verb|lua_Object|\Deffunc{lua_Object}, |
| which works like an abstract type in C that can hold any Lua value. |
| Values of type \verb|lua_Object| have no meaning outside Lua; |
| for instance, |
| you cannot compare two \verb|lua_Object's| directly. |
| Instead, you should use the next function: |
| \Deffunc{lua_equal} |
| \begin{verbatim} |
| int lua_equal (lua_Object o1, lua_Object o2); |
| \end{verbatim} |
| |
| To check the type of a \verb|lua_Object|, |
| the following functions are available: |
| \Deffunc{lua_isnil}\Deffunc{lua_isnumber}\Deffunc{lua_isstring} |
| \Deffunc{lua_istable}\Deffunc{lua_iscfunction}\Deffunc{lua_isuserdata} |
| \Deffunc{lua_isfunction} |
| \Deffunc{lua_type} |
| \begin{verbatim} |
| int lua_isnil (lua_Object object); |
| int lua_isnumber (lua_Object object); |
| int lua_isstring (lua_Object object); |
| int lua_istable (lua_Object object); |
| int lua_isfunction (lua_Object object); |
| int lua_iscfunction (lua_Object object); |
| int lua_isuserdata (lua_Object object); |
| const char *lua_type (lua_Object obj); |
| \end{verbatim} |
| The \verb|lua_is*| functions return 1 if the object is compatible |
| with the given type, and 0 otherwise. |
| The function \verb|lua_isnumber| accepts numbers and numerical strings, |
| \verb|lua_isstring| accepts strings and numbers \see{coercion}, |
| and \verb|lua_isfunction| accepts Lua functions and C functions. |
| To distinguish between Lua functions and C functions, |
| you should use \verb|lua_iscfunction|. |
| To distinguish between numbers and numerical strings, |
| you can use \verb|lua_type|. |
| The \verb|lua_type| returns one of the following strings, |
| describing the type of the given object: |
| \verb|"nil"|, \verb|"number"|, \verb|"string"|, \verb|"table"|, |
| \verb|"function"|, \verb|"userdata"|, or \verb|"NOOBJECT"|. |
| |
| To get the tag of a \verb|lua_Object|, |
| the following function is available: |
| \Deffunc{lua_tag} |
| \begin{verbatim} |
| int lua_tag (lua_Object object); |
| \end{verbatim} |
| |
| To translate a value from type \verb|lua_Object| to a specific C type, |
| you can use |
| \Deffunc{lua_getnumber}\Deffunc{lua_getstring}\Deffunc{lua_strlen} |
| \Deffunc{lua_getcfunction}\Deffunc{lua_getuserdata} |
| \begin{verbatim} |
| double lua_getnumber (lua_Object object); |
| const char *lua_getstring (lua_Object object); |
| long lua_strlen (lua_Object object); |
| lua_CFunction lua_getcfunction (lua_Object object); |
| void *lua_getuserdata (lua_Object object); |
| \end{verbatim} |
| |
| \verb|lua_getnumber| converts a \verb|lua_Object| to a floating-point number. |
| This \verb|lua_Object| must be a number or a string convertible to number |
| \see{coercion}; otherwise, \verb|lua_getnumber| returns~0. |
| |
| \verb|lua_getstring| converts a \verb|lua_Object| to a string |
| (\verb|const char*|). |
| This \verb|lua_Object| must be a string or a number; |
| otherwise, the function returns \verb|NULL|. |
| This function does not create a new string, |
| but returns a pointer to a string inside the Lua environment. |
| Those strings always have a 0 after their last character (like in C), |
| but may contain other zeros in their body. |
| If you do not know whether a string may contain zeros, |
| you can use \verb|lua_strlen| to get the actual length. |
| Because Lua has garbage collection, |
| there is no guarantee that the pointer returned by \verb|lua_getstring| |
| will be valid after the block ends |
| \see{GC}. |
| |
| \verb|lua_getcfunction| converts a \verb|lua_Object| to a C function. |
| This \verb|lua_Object| must have type \emph{CFunction}; |
| otherwise, \verb|lua_getcfunction| returns \verb|NULL|. |
| The type \verb|lua_CFunction| is explained in \See{LuacallC}. |
| |
| \verb|lua_getuserdata| converts a \verb|lua_Object| to \verb|void*|. |
| This \verb|lua_Object| must have type \emph{userdata}; |
| otherwise, \verb|lua_getuserdata| returns \verb|NULL|. |
| |
| \subsection{Garbage Collection}\label{GC} |
| Because Lua has automatic memory management and garbage collection, |
| a \verb|lua_Object| has a limited scope, |
| and is only valid inside the \emph{block} where it has been created. |
| A C function called from Lua is a block, |
| and its parameters are valid only until its end. |
| It is good programming practice to convert Lua objects to C values |
| as soon as they are available, |
| and never to store \verb|lua_Object|s in C global variables. |
| |
| A garbage collection cycle can be forced by: |
| \Deffunc{lua_collectgarbage} |
| \begin{verbatim} |
| long lua_collectgarbage (long limit); |
| \end{verbatim} |
| This function returns the number of objects collected. |
| The argument \verb|limit| makes the next cycle occur only |
| after that number of new objects have been created. |
| If \verb|limit| is 0, |
| then Lua uses an adaptive heuristics to set this limit. |
| |
| |
| All communication between Lua and C is done through two |
| abstract data types, called \Def{lua2C} and \Def{C2lua}. |
| The first one, as the name implies, is used to pass values |
| from Lua to C: |
| parameters when Lua calls C and results when C calls Lua. |
| The structure C2lua is used in the reverse direction: |
| parameters when C calls Lua and results when Lua calls C. |
| |
| The structure lua2C is an abstract array, |
| which can be indexed with the function: |
| \Deffunc{lua_lua2C} |
| \begin{verbatim} |
| lua_Object lua_lua2C (int number); |
| \end{verbatim} |
| where \verb|number| starts with 1. |
| When called with a number larger than the array size, |
| this function returns \verb|LUA_NOOBJECT|\Deffunc{LUA_NOOBJECT}. |
| In this way, it is possible to write C functions that receive |
| a variable number of parameters, |
| and to call Lua functions that return a variable number of results. |
| Note that the structure lua2C cannot be directly modified by C code. |
| |
| The second structure, C2lua, is an abstract stack. |
| Pushing elements into this stack |
| is done with the following functions: |
| \Deffunc{lua_pushnumber}\Deffunc{lua_pushlstring}\Deffunc{lua_pushstring} |
| \Deffunc{lua_pushcfunction}\Deffunc{lua_pushusertag} |
| \Deffunc{lua_pushnil}\Deffunc{lua_pushobject} |
| \Deffunc{lua_pushuserdata}\label{pushing} |
| \begin{verbatim} |
| void lua_pushnumber (double n); |
| void lua_pushlstring (const char *s, long len); |
| void lua_pushstring (const char *s); |
| void lua_pushusertag (void *u, int tag); |
| void lua_pushnil (void); |
| void lua_pushobject (lua_Object object); |
| void lua_pushcfunction (lua_CFunction f); /* macro */ |
| \end{verbatim} |
| All of them receive a C value, |
| convert it to a corresponding \verb|lua_Object|, |
| and leave the result on the top of C2lua. |
| In particular, functions \verb|lua_pushlstring| and \verb|lua_pushstring| |
| make an internal copy of the given string. |
| Function \verb|lua_pushstring| can only be used to push proper C strings |
| (that is, strings that end with a zero and do not contain embedded zeros); |
| otherwise you should use the more generic \verb|lua_pushlstring|. |
| The function |
| \Deffunc{lua_pop} |
| \begin{verbatim} |
| lua_Object lua_pop (void); |
| \end{verbatim} |
| returns a reference to the object at the top of the C2lua stack, |
| and pops it. |
| |
| As a general rule, all API functions pop from the stack |
| all elements they use. |
| |
| Because userdata are objects, |
| the function \verb|lua_pushusertag| may create a new userdata. |
| If Lua has a userdata with the given value (\verb|void*|) and tag, |
| that userdata is pushed. |
| Otherwise, a new userdata is created, with the given value and tag. |
| If this function is called with |
| \verb|tag| equal to \verb|LUA_ANYTAG|\Deffunc{LUA_ANYTAG}, |
| then Lua will try to find any userdata with the given value, |
| regardless of its tag. |
| If there is no userdata with that value, then a new one is created, |
| with tag equal to 0. |
| |
| Userdata can have different tags, |
| whose semantics are only known to the host program. |
| Tags are created with the function: |
| \Deffunc{lua_newtag} |
| \begin{verbatim} |
| int lua_newtag (void); |
| \end{verbatim} |
| The function \verb|lua_settag| changes the tag of |
| the object on the top of C2lua (and pops it); |
| the object must be a userdata or a table. |
| \Deffunc{lua_settag} |
| \begin{verbatim} |
| void lua_settag (int tag); |
| \end{verbatim} |
| \verb|tag| must be a value created with \verb|lua_newtag|. |
| |
| When C code calls Lua repeatedly, as in a loop, |
| objects returned by these calls can accumulate, |
| and may cause a stack overflow. |
| To avoid this, |
| nested blocks can be defined with the functions: |
| \begin{verbatim} |
| void lua_beginblock (void); |
| void lua_endblock (void); |
| \end{verbatim} |
| After the end of the block, |
| all \verb|lua_Object|'s created inside it are released. |
| The use of explicit nested blocks is good programming practice |
| and is strongly encouraged. |
| |
| \subsection{Executing Lua Code} |
| A host program can execute Lua chunks written in a file or in a string |
| using the following functions:% |
| \Deffunc{lua_dofile}\Deffunc{lua_dostring}\Deffunc{lua_dobuffer} |
| \begin{verbatim} |
| int lua_dofile (const char *filename); |
| int lua_dostring (const char *string); |
| int lua_dobuffer (const char *buff, int size, const char *name); |
| \end{verbatim} |
| All these functions return an error code: |
| 0, in case of success; non zero, in case of errors. |
| More specifically, \verb|lua_dofile| returns 2 if for any reason |
| it could not open the file. |
| When called with argument \verb|NULL|, |
| \verb|lua_dofile| executes the \verb|stdin| stream. |
| Functions \verb|lua_dofile| and \verb|lua_dobuffer| |
| are both able to execute pre-compiled chunks. |
| They automatically detect whether the chunk is text or binary, |
| and load it accordingly (see program \IndexVerb{luac}). |
| Function \verb|lua_dostring| executes only source code. |
| |
| The third parameter to \verb|lua_dobuffer| (\verb|name|) |
| is the ``name of the chunk'', |
| used in error messages and debug information. |
| If \verb|name| is \verb|NULL|, |
| Lua gives a default name to the chunk. |
| |
| These functions return, in structure lua2C, |
| any values eventually returned by the chunks. |
| They also empty the stack C2lua. |
| |
| |
| \subsection{Manipulating Lua Objects} |
| To read the value of any global Lua variable, |
| one uses the function: |
| \Deffunc{lua_getglobal} |
| \begin{verbatim} |
| lua_Object lua_getglobal (const char *varname); |
| \end{verbatim} |
| As in Lua, this function may trigger a tag method. |
| To read the real value of any global variable, |
| without invoking any tag method, |
| use the \emph{raw} version: |
| \Deffunc{lua_rawgetglobal} |
| \begin{verbatim} |
| lua_Object lua_rawgetglobal (const char *varname); |
| \end{verbatim} |
| |
| To store a value previously pushed onto C2lua in a global variable, |
| there is the function: |
| \Deffunc{lua_setglobal} |
| \begin{verbatim} |
| void lua_setglobal (const char *varname); |
| \end{verbatim} |
| As in Lua, this function may trigger a tag method. |
| To set the real value of any global variable, |
| without invoking any tag method, |
| use the \emph{raw} version: |
| \Deffunc{lua_rawgetglobal} |
| \begin{verbatim} |
| void lua_rawsetglobal (const char *varname); |
| \end{verbatim} |
| |
| Tables can also be manipulated via the API. |
| The function |
| \Deffunc{lua_gettable} |
| \begin{verbatim} |
| lua_Object lua_gettable (void); |
| \end{verbatim} |
| pops a table and an index from the stack C2lua, |
| and returns the contents of the table at that index. |
| As in Lua, this operation may trigger a tag method. |
| To get the real value of any table index, |
| without invoking any tag method, |
| use the \emph{raw} version: |
| \Deffunc{lua_rawgetglobal} |
| \begin{verbatim} |
| lua_Object lua_rawgettable (void); |
| \end{verbatim} |
| |
| To store a value in an index, |
| the program must push the table, the index, |
| and the value onto C2lua, |
| and then call the function |
| \Deffunc{lua_settable} |
| \begin{verbatim} |
| void lua_settable (void); |
| \end{verbatim} |
| Again, the tag method for ``settable'' may be called. |
| To set the real value of any table index, |
| without invoking any tag method, |
| use the \emph{raw} version: |
| \Deffunc{lua_rawsettable} |
| \begin{verbatim} |
| void lua_rawsettable (void); |
| \end{verbatim} |
| |
| Finally, the function |
| \Deffunc{lua_createtable} |
| \begin{verbatim} |
| lua_Object lua_createtable (void); |
| \end{verbatim} |
| creates and returns a new, empty table. |
| |
| |
| \subsection{Calling Lua Functions} |
| Functions defined in Lua by a chunk |
| can be called from the host program. |
| This is done using the following protocol: |
| first, the arguments to the function are pushed onto C2lua |
| \see{pushing}, in direct order, i.e., the first argument is pushed first. |
| Then, the function is called using |
| \Deffunc{lua_callfunction} |
| \begin{verbatim} |
| int lua_callfunction (lua_Object function); |
| \end{verbatim} |
| This function returns an error code: |
| 0, in case of success; non zero, in case of errors. |
| Finally, the results are returned in structure lua2C |
| (recall that a Lua function may return many values), |
| and can be retrieved with the macro \verb|lua_getresult|, |
| \Deffunc{lua_getresult} |
| which is just another name to function \verb|lua_lua2C|. |
| Note that function \verb|lua_callfunction| |
| pops all elements from the C2lua stack. |
| |
| The following example shows how a C program may do the |
| equivalent to the Lua code: |
| \begin{verbatim} |
| a,b = f("how", t.x, 4) |
| \end{verbatim} |
| \begin{verbatim} |
| lua_pushstring("how"); /* 1st argument */ |
| lua_pushobject(lua_getglobal("t")); /* push value of global 't' */ |
| lua_pushstring("x"); /* push the string 'x' */ |
| lua_pushobject(lua_gettable()); /* push result of t.x (2nd arg) */ |
| lua_pushnumber(4); /* 3rd argument */ |
| lua_callfunction(lua_getglobal("f")); /* call Lua function */ |
| lua_pushobject(lua_getresult(1)); /* push first result of the call */ |
| lua_setglobal("a"); /* set global variable 'a' */ |
| lua_pushobject(lua_getresult(2)); /* push second result of the call */ |
| lua_setglobal("b"); /* set global variable 'b' */ |
| \end{verbatim} |
| |
| Some special Lua functions have exclusive interfaces. |
| A C function can generate a Lua error calling the function |
| \Deffunc{lua_error} |
| \begin{verbatim} |
| void lua_error (const char *message); |
| \end{verbatim} |
| This function never returns. |
| If the C function has been called from Lua, |
| then the corresponding Lua execution terminates, |
| as if an error had occurred inside Lua code. |
| Otherwise, the whole host program terminates with a call to \verb|exit(1)|. |
| The \verb|message| is passed to the error handler function, |
| \verb|_ERRORMESSAGE|. |
| If \verb|message| is \verb|NULL|, |
| then \verb|_ERRORMESSAGE| is not called. |
| |
| Tag methods can be changed with: \Deffunc{lua_settagmethod} |
| \begin{verbatim} |
| lua_Object lua_settagmethod (int tag, const char *event); |
| \end{verbatim} |
| The first parameter is the tag, |
| and the second is the event name \see{tag-method}; |
| the new method is pushed from C2lua. |
| This function returns a \verb|lua_Object|, |
| which is the old tag method value. |
| To get just the current value of a tag method, |
| use the function \Deffunc{lua_gettagmethod} |
| \begin{verbatim} |
| lua_Object lua_gettagmethod (int tag, const char *event); |
| \end{verbatim} |
| |
| It is also possible to copy all tag methods from one tag |
| to another: \Deffunc{lua_copytagmethods} |
| \begin{verbatim} |
| int lua_copytagmethods (int tagto, int tagfrom); |
| \end{verbatim} |
| This function returns \verb|tagto|. |
| |
| You can traverse a table with the function \Deffunc{lua_next} |
| \begin{verbatim} |
| int lua_next (lua_Object t, int i); |
| \end{verbatim} |
| Its first argument is the table to be traversed, |
| and the second is a \emph{cursor}; |
| this cursor starts in 0, |
| and for each call the function returns a value to |
| be used in the next call, |
| or 0 to signal the end of the traverse. |
| The function also returns, in the Lua2C array, |
| a key-value pair from the table. |
| A typical traversal looks like the following code: |
| \begin{verbatim} |
| int i; |
| lua_Object t; |
| ... /* gets the table at `t' */ |
| i = 0; |
| lua_beginblock(); |
| while ((i = lua_next(t, i)) != 0) { |
| lua_Object key = lua_getresult(1); |
| lua_Object value = lua_getresult(2); |
| ... /* uses `key' and `value' */ |
| lua_endblock(); |
| lua_beginblock(); /* reopens a block */ |
| } |
| lua_endblock(); |
| \end{verbatim} |
| The pairs of \verb|lua_beginblock|/\verb|lua_endblock| remove the |
| results of each iteration from the stack. |
| Without them, a traversal of a large table will overflow the stack. |
| |
| To traverse the global variables, you use \Deffunc{lua_nextvar} |
| \begin{verbatim} |
| const char *lua_nextvar (const char *varname); |
| \end{verbatim} |
| Here, the cursor is a string; |
| in the first call you set it to \verb|NULL|; |
| for each call the function returns the name of a global variable, |
| to be used in the next call, |
| or \verb|NULL| to signal the end of the traverse. |
| The function also returns, in the Lua2C array, |
| the name (again) and the value of the global variable. |
| A typical traversal looks like the following code: |
| \begin{verbatim} |
| const char *name = NULL; |
| lua_beginblock(); |
| while ((name = lua_nextvar(name)) != NULL) { |
| lua_Object value = lua_getresult(2); |
| ... /* uses `name' and `value' */ |
| lua_endblock(); |
| lua_beginblock(); /* reopens a block */ |
| } |
| lua_endblock(); |
| \end{verbatim} |
| |
| |
| \subsection{Defining C Functions} \label{LuacallC} |
| To register a C function to Lua, |
| there is the following macro: |
| \Deffunc{lua_register} |
| \begin{verbatim} |
| #define lua_register(n,f) (lua_pushcfunction(f), lua_setglobal(n)) |
| /* const char *n; */ |
| /* lua_CFunction f; */ |
| \end{verbatim} |
| which receives the name the function will have in Lua, |
| and a pointer to the function. |
| This pointer must have type \verb|lua_CFunction|, |
| which is defined as |
| \Deffunc{lua_CFunction} |
| \begin{verbatim} |
| typedef void (*lua_CFunction) (void); |
| \end{verbatim} |
| that is, a pointer to a function with no parameters and no results. |
| |
| In order to communicate properly with Lua, |
| a C function must follow a protocol, |
| which defines the way parameters and results are passed. |
| |
| A C function receives its arguments in structure lua2C; |
| to access them, it uses the macro \verb|lua_getparam|, \Deffunc{lua_getparam} |
| again just another name for \verb|lua_lua2C|. |
| To return values, a C function just pushes them onto the stack C2lua, |
| in direct order \see{valuesCLua}. |
| Like a Lua function, a C function called by Lua can also return |
| many results. |
| |
| When a C function is created, |
| it is possible to associate some \emph{upvalues} to it, |
| thus creating a C closure; |
| then these values are passed to the function whenever it is called, |
| as common arguments. |
| To associate upvalues to a function, |
| first these values must be pushed on C2lua. |
| Then the function \Deffunc{lua_pushcclosure} |
| \begin{verbatim} |
| void lua_pushcclosure (lua_CFunction fn, int n); |
| \end{verbatim} |
| is used to put the C function on C2lua, |
| with the argument \verb|n| telling how many upvalues must be |
| associated with the function; |
| in fact, the macro \verb|lua_pushcfunction| is defined as |
| \verb|lua_pushcclosure| with \verb|n| set to 0. |
| Then, any time the function is called, |
| these upvalues are inserted as the first arguments to the function, |
| before the actual arguments provided in the call. |
| |
| For some examples of C functions, see files \verb|lstrlib.c|, |
| \verb|liolib.c| and \verb|lmathlib.c| in the official Lua distribution. |
| |
| \subsection{References to Lua Objects} |
| |
| As noted in \See{GC}, \verb|lua_Object|s are volatile. |
| If the C code needs to keep a \verb|lua_Object| |
| outside block boundaries, |
| then it must create a \Def{reference} to the object. |
| The routines to manipulate references are the following: |
| \Deffunc{lua_ref}\Deffunc{lua_getref} |
| \Deffunc{lua_unref} |
| \begin{verbatim} |
| int lua_ref (int lock); |
| lua_Object lua_getref (int ref); |
| void lua_unref (int ref); |
| \end{verbatim} |
| The function \verb|lua_ref| creates a reference |
| to the object that is on the top of the stack, |
| and returns this reference. |
| For a \nil{} object, |
| the reference is always \verb|LUA_REFNIL|;\Deffunc{LUA_REFNIL} |
| otherwise, it is a non-negative integer. |
| The constant \verb|LUA_NOREF| \Deffunc{LUA_NOREF} |
| is different from any valid reference. |
| If \verb|lock| is true, the object is \emph{locked}: |
| this means the object will not be garbage collected. |
| Note that an unlocked reference may be garbage collected. |
| Whenever the referenced object is needed, |
| a call to \verb|lua_getref| |
| returns a handle to it; |
| if the object has been collected, |
| \verb|lua_getref| returns \verb|LUA_NOOBJECT|. |
| |
| When a reference is no longer needed, |
| it can be released with a call to \verb|lua_unref|. |
| |
| |
| |
| \section{Predefined Functions and Libraries} |
| |
| The set of \Index{predefined functions} in Lua is small but powerful. |
| Most of them provide features that allow some degree of |
| \Index{reflexivity} in the language. |
| Some of these features cannot be simulated with the rest of the |
| language nor with the standard Lua API. |
| Others are just convenient interfaces to common API functions. |
| |
| The libraries, on the other hand, provide useful routines |
| that are implemented directly through the standard API. |
| Therefore, they are not necessary to the language, |
| and are provided as separate C modules. |
| Currently, there are three standard libraries: |
| \begin{itemize} |
| \item string manipulation; |
| \item mathematical functions (sin, log, etc); |
| \item input and output (plus some system facilities). |
| \end{itemize} |
| To have access to these libraries, |
| the C host program must call the functions |
| \verb|lua_strlibopen|, \verb|lua_mathlibopen|, |
| and \verb|lua_iolibopen|, declared in \verb|lualib.h|. |
| \Deffunc{lua_strlibopen}\Deffunc{lua_mathlibopen}\Deffunc{lua_iolibopen} |
| |
| |
| \subsection{Predefined Functions} \label{predefined} |
| |
| \subsubsection*{\ff \T{call (func, arg [, mode [, errhandler]])}}\Deffunc{call} |
| \label{pdf-call} |
| Calls function \verb|func| with |
| the arguments given by the table \verb|arg|. |
| The call is equivalent to |
| \begin{verbatim} |
| func(arg[1], arg[2], ..., arg[n]) |
| \end{verbatim} |
| where \verb|n| is the result of \verb|getn(arg)| \see{getn}. |
| |
| By default, |
| all results from \verb|func| are just returned by the call. |
| If the string \verb|mode| contains \verb|"p"|, |
| the results are \emph{packed} in a single table.\index{packed results} |
| That is, \verb|call| returns just one table; |
| at index \verb|n|, the table has the total number of results |
| from the call; |
| the first result is at index 1, etc. |
| For instance, the following calls produce the following results: |
| \begin{verbatim} |
| a = call(sin, {5}) --> a = 0.0871557 = sin(5) |
| a = call(max, {1,4,5; n=2}) --> a = 4 (only 1 and 4 are arguments) |
| a = call(max, {1,4,5; n=2}, "p") --> a = {4; n=1} |
| t = {x=1} |
| a = call(next, {t,nil;n=2}, "p") --> a={"x", 1; n=2} |
| \end{verbatim} |
| |
| By default, |
| if an error occurs during the function call, |
| the error is propagated. |
| If the string \verb|mode| contains \verb|"x"|, |
| then the call is \emph{protected}.\index{protected calls} |
| In this mode, function \verb|call| does not propagate an error, |
| regardless of what happens during the call. |
| Instead, it returns \nil\ to signal the error |
| (besides calling the appropriated error handler). |
| |
| If provided, |
| \verb|errhandler| is temporarily set as the error function |
| \verb|_ERRORMESSAGE|, while \verb|func| runs. |
| In particular, if \verb|errhandler| is \nil, |
| no error messages will be issued during the execution of the called function. |
| |
| \subsubsection*{\ff \T{collectgarbage ([limit])}}\Deffunc{collectgarbage} |
| Forces a garbage collection cycle. |
| Returns the number of objects collected. |
| An optional argument, \verb|limit|, is a number that |
| makes the next cycle occur only after that number of new |
| objects have been created. |
| If \verb|limit| is absent or equal to 0, |
| Lua uses an adaptive algorithm to set this limit. |
| \verb|collectgarbage| is equivalent to |
| the API function \verb|lua_collectgarbage|. |
| |
| \subsubsection*{\ff \T{dofile (filename)}}\Deffunc{dofile} |
| Receives a file name, |
| opens the file, and executes the file contents as a Lua chunk, |
| or as pre-compiled chunks. |
| When called without arguments, |
| \verb|dofile| executes the contents of the standard input (\verb|stdin|). |
| If there is any error executing the file, |
| then \verb|dofile| returns \nil. |
| Otherwise, it returns the values returned by the chunk, |
| or a non \nil\ value if the chunk returns no values. |
| It issues an error when called with a non string argument. |
| \verb|dofile| is equivalent to the API function \verb|lua_dofile|. |
| |
| \subsubsection*{\ff \T{dostring (string [, chunkname])}}\Deffunc{dostring} |
| Executes a given string as a Lua chunk. |
| If there is any error executing the string, |
| \verb|dostring| returns \nil. |
| Otherwise, it returns the values returned by the chunk, |
| or a non \nil\ value if the chunk returns no values. |
| An optional second parameter (\verb|chunkname|) |
| is the ``name of the chunk'', |
| used in error messages and debug information. |
| \verb|dostring| is equivalent to the API function \verb|lua_dostring|. |
| |
| \subsubsection*{\ff \T{newtag ()}}\Deffunc{newtag}\label{pdf-newtag} |
| Returns a new tag. |
| \verb|newtag| is equivalent to the API function \verb|lua_newtag|. |
| |
| \subsubsection*{\ff \T{next (table, [index])}}\Deffunc{next} |
| Allows a program to traverse all fields of a table. |
| Its first argument is a table and its second argument |
| is an index in this table. |
| It returns the next index of the table and the |
| value associated with the index. |
| When called with \nil\ as its second argument, |
| the function returns the first index |
| of the table (and its associated value). |
| When called with the last index, |
| or with \nil\ in an empty table, |
| it returns \nil. |
| If the second argument is absent, it is interpreted as \nil. |
| |
| Lua has no declaration of fields; |
| semantically, there is no difference between a |
| field not present in a table or a field with value \nil. |
| Therefore, the function only considers fields with non \nil\ values. |
| The order in which the indices are enumerated is not specified, |
| \emph{even for numeric indices} |
| (to traverse a table in numeric order, |
| use a counter or the function \verb|foreachi|). |
| If you create new indices in a table while |
| traversing it, |
| the semantics of \verb|next| is undefined. |
| |
| \subsubsection*{\ff \T{nextvar (name)}}\Deffunc{nextvar} |
| This function is similar to the function \verb|next|, |
| but iterates instead over the global variables. |
| Its single argument is the name of a global variable, |
| or \nil\ to get a first name. |
| If this argument is absent, it is interpreted as \nil. |
| Similarly to \verb|next|, it returns the name of another variable |
| and its value, |
| or \nil\ if there are no more variables. |
| If you create new global variables during the traversal, |
| the semantics of \verb|nextvar| is undefined. |
| |
| \subsubsection*{\ff \T{tostring (e)}}\Deffunc{tostring} |
| Receives an argument of any type and |
| converts it to a string in a reasonable format. |
| For complete control on how numbers are converted, |
| use function \verb|format|. |
| |
| \subsubsection*{\ff \T{print (e1, e2, ...)}}\Deffunc{print} |
| Receives any number of arguments, |
| and prints their values using the strings returned by \verb|tostring|. |
| This function is not intended for formatted output, |
| but only as a quick way to show a value, |
| for instance for debugging. |
| See \See{libio} for functions for formatted output. |
| |
| \subsubsection*{\ff \T{_ALERT (message)}}\Deffunc{alert}\label{alert} |
| Prints its only string argument to \IndexVerb{stderr}. |
| All error messages in Lua are printed through the function stored |
| in the \verb|_ALERT| global variable. |
| Therefore, a program may assign another function to this variable |
| to change the way such messages are shown |
| (for instance, for systems without \verb|stderr|). |
| |
| \subsubsection*{\ff \T{tonumber (e [, base])}}\Deffunc{tonumber} |
| Receives one argument, |
| and tries to convert it to a number. |
| If the argument is already a number or a string convertible |
| to a number, then \verb|tonumber| returns that number; |
| otherwise, it returns \nil. |
| |
| An optional argument specifies the base to interpret the numeral. |
| The base may be any integer between 2 and 36 inclusive. |
| In bases above 10, the letter `A' (either upper or lower case) |
| represents 10, `B' represents 11, and so forth, with `Z' representing 35. |
| |
| In base 10 (the default), the number may have a decimal part, |
| as well as an optional exponent part \see{coercion}. |
| In other bases, only unsigned integers are accepted. |
| |
| \subsubsection*{\ff \T{type (v)}}\Deffunc{type}\label{pdf-type} |
| Allows Lua to test the type of a value. |
| It receives one argument, and returns its type, coded as a string. |
| The possible results of this function are |
| \verb|"nil"| (a string, not the value \nil), |
| \verb|"number"|, |
| \verb|"string"|, |
| \verb|"table"|, |
| \verb|"function"|, |
| and \verb|"userdata"|. |
| |
| \subsubsection*{\ff \T{tag (v)}}\Deffunc{tag}\label{pdf-tag} |
| Allows Lua to test the tag of a value \see{TypesSec}. |
| It receives one argument, and returns its tag (a number). |
| \verb|tag| is equivalent to the API function \verb|lua_tag|. |
| |
| \subsubsection*{\ff \T{settag (t, tag)}}\Deffunc{settag} |
| Sets the tag of a given table \see{TypesSec}. |
| \verb|tag| must be a value created with \verb|newtag| |
| \see{pdf-newtag}. |
| It returns the value of its first argument (the table). |
| For security reasons, |
| it is impossible to change the tag of a userdata from Lua. |
| |
| |
| \subsubsection*{\ff \T{assert (v [, message])}}\Deffunc{assert} |
| Issues an \emph{``assertion failed!''} error |
| when its argument is \nil. |
| This function is equivalent to the following Lua function: |
| \begin{verbatim} |
| function assert (v, m) |
| if not v then |
| m = m or "" |
| error("assertion failed! " .. m) |
| end |
| end |
| \end{verbatim} |
| |
| \subsubsection*{\ff \T{error (message)}}\Deffunc{error}\label{pdf-error} |
| Calls the error handler and then terminates |
| the last protected function called |
| (in~C: \verb|lua_dofile|, \verb|lua_dostring|, |
| \verb|lua_dobuffer|, or \verb|lua_callfunction|; |
| in Lua: \verb|dofile|, \verb|dostring|, or \verb|call| in protected mode). |
| If \verb|message| is \nil, the error handler is not called. |
| Function \verb|error| never returns. |
| \verb|error| is equivalent to the API function \verb|lua_error|. |
| |
| \subsubsection*{\ff \T{rawgettable (table, index)}}\Deffunc{rawgettable} |
| Gets the real value of \verb|table[index]|, |
| without invoking any tag method. |
| \verb|table| must be a table, |
| and \verb|index| is any value different from \nil. |
| |
| \subsubsection*{\ff \T{rawsettable (table, index, value)}}\Deffunc{rawsettable} |
| Sets the real value of \verb|table[index]| to \verb|value|, |
| without invoking any tag method. |
| \verb|table| must be a table, |
| \verb|index| is any value different from \nil, |
| and \verb|value| is any Lua value. |
| |
| \subsubsection*{\ff \T{rawsetglobal (name, value)}}\Deffunc{rawsetglobal} |
| Assigns the given value to a global variable. |
| The string \verb|name| does not need to be a |
| syntactically valid variable name. |
| Therefore, |
| this function can set global variables with strange names like |
| \verb|"m v 1"| or \verb|34|. |
| |
| \subsubsection*{\ff \T{setglobal (name, value)}}\Deffunc{setglobal} |
| Assigns the given value to a global variable, |
| or calls a tag method. |
| Its full semantics is explained in \See{tag-method}. |
| The string \verb|name| does not need to be a |
| syntactically valid variable name. |
| |
| \subsubsection*{\ff \T{rawgetglobal (name)}}\Deffunc{rawgetglobal} |
| Retrieves the value of a global variable. |
| The string \verb|name| does not need to be a |
| syntactically valid variable name. |
| |
| \subsubsection*{\ff \T{getglobal (name)}}\Deffunc{getglobal} |
| Retrieves the value of a global variable, |
| or calls a tag method. |
| Its full semantics is explained in \See{tag-method}. |
| The string \verb|name| does not need to be a |
| syntactically valid variable name. |
| |
| \subsubsection*{\ff \T{settagmethod (tag, event, newmethod)}} |
| \Deffunc{settagmethod} |
| Sets a new tag method to the given pair \M{(tag, event)}. |
| It returns the old method. |
| If \verb|newmethod| is \nil, |
| \verb|settagmethod| restores the default behavior for the given event. |
| |
| \subsubsection*{\ff \T{gettagmethod (tag, event)}} |
| \Deffunc{gettagmethod} |
| Returns the current tag method |
| for a given pair \M{(tag, event)}. |
| |
| \subsubsection*{\ff \T{copytagmethods (tagto, tagfrom)}} |
| \Deffunc{copytagmethods} |
| Copies all tag methods from one tag to another; |
| it returns \verb|tagto|. |
| |
| \subsubsection*{\ff \T{getn (table)}}\Deffunc{getn}\label{getn} |
| Returns the ``size'' of a table, when seen as a list. |
| If the table has an \verb|n| field with a numeric value, |
| this is its ``size''. |
| Otherwise, the size is the largest numerical index with a non-nil |
| value in the table. |
| This function could be defined in Lua: |
| \begin{verbatim} |
| function getn (t) |
| if type(t.n) == 'number' then return t.n end |
| local max, i = 0, nil |
| while 1 do |
| i = next(t, i) |
| if not i then break end |
| if type(i) == 'number' and i>max then max=i end |
| end |
| return max |
| end |
| \end{verbatim} |
| |
| |
| \subsubsection*{\ff \T{foreach (table, function)}}\Deffunc{foreach} |
| Executes the given \verb|function| over all elements of \verb|table|. |
| For each element, the function is called with the index and |
| respective value as arguments. |
| If the function returns any non-\nil\ value, |
| the loop is broken, and the value is returned |
| as the final value of \verb|foreach|. |
| |
| This function could be defined in Lua: |
| \begin{verbatim} |
| function foreach (t, f) |
| local i, v = nil |
| while 1 do |
| i, v = next(t, i) |
| if not i then break end |
| local res = f(i, v) |
| if res then return res end |
| end |
| end |
| \end{verbatim} |
| |
| If you create new indices in a table while |
| traversing it, |
| the semantics of \verb|foreach| is undefined. |
| |
| |
| \subsubsection*{\ff \T{foreachi (table, function)}}\Deffunc{foreachi} |
| Executes the given \verb|function| over the |
| numerical indices of \verb|table|. |
| For each index, the function is called with the index and |
| respective value as arguments. |
| Indices are visited in sequential order, |
| from 1 to \verb|n|, |
| where \verb|n| is the result of \verb|getn(table)| \see{getn}. |
| If the function returns any non-\nil\ value, |
| the loop is broken, and the value is returned |
| as the final value of \verb|foreachi|. |
| |
| This function could be defined in Lua: |
| \begin{verbatim} |
| function foreachi (t, f) |
| for i=1,getn(t) do |
| local res = f(i, t[i]) |
| if res then return res end |
| end |
| end |
| \end{verbatim} |
| |
| \subsubsection*{\ff \T{foreachvar (function)}}\Deffunc{foreachvar} |
| Executes \verb|function| over all global variables. |
| For each variable, |
| the function is called with its name and its value as arguments. |
| If the function returns any non-nil value, |
| the loop is broken, and the value is returned |
| as the final value of \verb|foreachvar|. |
| |
| This function could be defined in Lua: |
| \begin{verbatim} |
| function foreachvar (f) |
| local n, v = nil |
| while 1 do |
| n, v = nextvar(n) |
| if not n then break end |
| local res = f(n, v) |
| if res then return res end |
| end |
| end |
| \end{verbatim} |
| |
| If you create new global variables during the traversal, |
| the semantics of \verb|foreachvar| is undefined. |
| |
| \subsubsection*{\ff \T{tinsert (table [, pos] , value)}}\Deffunc{tinsert} |
| |
| Inserts element \verb|value| at table position \verb|pos|, |
| shifting other elements to open space, if necessary. |
| The default value for \verb|pos| is \verb|n+1|, |
| where \verb|n| is the result of \verb|getn(table)| \see{getn}, |
| so that a call \verb|tinsert(t,x)| inserts \verb|x| at the end |
| of table \verb|t|. |
| |
| This function also sets or increments the field \verb|n| of the table, |
| to \verb|n+1|. |
| |
| This function is equivalent to the following Lua function, |
| except that the table accesses are all raw (that is, without tag methods): |
| \begin{verbatim} |
| function tinsert (t, ...) |
| local pos, value |
| local n = getn(t) |
| if arg.n == 1 then |
| pos, value = n+1, arg[1] |
| else |
| pos, value = arg[1], arg[2] |
| end |
| t.n = n+1; |
| for i=n,pos,-1 do |
| t[i+1] = t[i] |
| end |
| t[pos] = value |
| end |
| \end{verbatim} |
| |
| \subsubsection*{\ff \T{tremove (table [, pos])}}\Deffunc{tremove} |
| |
| Removes from \verb|table| the element at position \verb|pos|, |
| shifting other elements to close the space, if necessary. |
| Returns the value of the removed element. |
| The default value for \verb|pos| is \verb|n| |
| (where \verb|n| is the result of \verb|getn(table)| \see{getn}), |
| so that a call \verb|tremove(t)| removes the last element |
| of table \verb|t|. |
| |
| This function also sets or decrements the field \verb|n| of the table, |
| to \verb|n-1|. |
| |
| This function is equivalent to the following Lua function, |
| except that the table accesses are all raw (that is, without tag methods): |
| \begin{verbatim} |
| function tremove (t, pos) |
| local n = getn(t) |
| if n<=0 then return end |
| pos = pos or n |
| local value = t[pos] |
| for i=pos,n-1 do |
| t[i] = t[i+1] |
| end |
| t[n] = nil |
| t.n = n-1 |
| return value |
| end |
| \end{verbatim} |
| |
| \subsubsection*{\ff \T{sort (table [, comp])}}\Deffunc{sort} |
| Sorts table elements in a given order, \emph{in-place}, |
| from \verb|table[1]| to \verb|table[n]|, |
| where \verb|n| is the result of \verb|getn(table)| \see{getn}. |
| If \verb|comp| is given, |
| it must be a function that receives two table elements, |
| and returns true when the first is less than the second |
| (so that \verb|not comp(a[i+1], a[i])| will be true after the sort). |
| If \verb|comp| is not given, |
| the standard Lua operator \verb|<| is used instead. |
| |
| |
| \subsection{String Manipulation} |
| This library provides generic functions for string manipulation, |
| such as finding and extracting substrings and pattern matching. |
| When indexing a string, the first character is at position~1 |
| (not at~0, as in C). |
| |
| \subsubsection*{\ff \T{strfind (str, pattern [, init [, plain]])}} |
| \Deffunc{strfind} |
| Looks for the first \emph{match} of |
| \verb|pattern| in \verb|str|. |
| If it finds one, then it returns the indices on \verb|str| |
| where this occurrence starts and ends; |
| otherwise, it returns \nil. |
| If the pattern specifies captures, |
| the captured strings are returned as extra results. |
| A third optional numerical argument specifies where to start the search; |
| its default value is 1. |
| If \verb|init| is negative, |
| it is replaced by the length of the string minus its |
| absolute value plus 1. |
| Therefore, \Math{-1} points to the last character of \verb|str|. |
| A value of 1 as a fourth optional argument |
| turns off the pattern matching facilities, |
| so the function does a plain ``find substring'' operation, |
| with no characters in \verb|pattern| being considered ``magic''. |
| |
| \subsubsection*{\ff \T{strlen (s)}}\Deffunc{strlen} |
| Receives a string and returns its length. |
| |
| \subsubsection*{\ff \T{strsub (s, i [, j])}}\Deffunc{strsub} |
| Returns another string, which is a substring of \verb|s|, |
| starting at \verb|i| and running until \verb|j|. |
| If \verb|i| or \verb|j| are negative, |
| they are replaced by the length of the string minus their |
| absolute value plus 1. |
| Therefore, \Math{-1} points to the last character of \verb|s| |
| and \Math{-2} to the previous one. |
| If \verb|j| is absent, it is assumed to be equal to \Math{-1} |
| (which is the same as the string length). |
| In particular, |
| the call \verb|strsub(s,1,j)| returns a prefix of \verb|s| |
| with length \verb|j|, |
| and the call \verb|strsub(s, -i)| returns a suffix of \verb|s| |
| with length \verb|i|. |
| |
| \subsubsection*{\ff \T{strlower (s)}}\Deffunc{strlower} |
| Receives a string and returns a copy of that string with all |
| upper case letters changed to lower case. |
| All other characters are left unchanged. |
| The definition of what is an upper case |
| letter depends on the current locale. |
| |
| \subsubsection*{\ff \T{strupper (s)}}\Deffunc{strupper} |
| Receives a string and returns a copy of that string with all |
| lower case letters changed to upper case. |
| All other characters are left unchanged. |
| The definition of what is a lower case |
| letter depends on the current locale. |
| |
| \subsubsection*{\ff \T{strrep (s, n)}}\Deffunc{strrep} |
| Returns a string that is the concatenation of \verb|n| copies of |
| the string \verb|s|. |
| |
| \subsubsection*{\ff \T{strbyte (s [, i])}}\Deffunc{strbyte} |
| Returns the internal numerical code of the character \verb|s[i]|. |
| If \verb|i| is absent, then it is assumed to be 1. |
| If \verb|i| is negative, |
| it is replaced by the length of the string minus its |
| absolute value plus 1. |
| Therefore, \Math{-1} points to the last character of \verb|s|. |
| |
| Note that numerical codes are not necessarily portable across platforms. |
| |
| \subsubsection*{\ff \T{strchar (i1, i2, \ldots)}}\Deffunc{strchar} |
| Receives 0 or more integers. |
| Returns a string with length equal to the number of arguments, |
| wherein each character has the internal numerical code equal |
| to its correspondent argument. |
| |
| Note that numerical codes are not necessarily portable across platforms. |
| |
| \subsubsection*{\ff \T{format (formatstring, e1, e2, \ldots)}}\Deffunc{format} |
| \label{format} |
| Returns a formatted version of its variable number of arguments |
| following the description given in its first argument (which must be a string). |
| The format string follows the same rules as the \verb|printf| family of |
| standard C functions. |
| The only differences are that the options/modifiers |
| \verb|*|, \verb|l|, \verb|L|, \verb|n|, \verb|p|, |
| and \verb|h| are not supported, |
| and there is an extra option, \verb|q|. |
| This option formats a string in a form suitable to be safely read |
| back by the Lua interpreter: |
| The string is written between double quotes, |
| and all double quotes, returns and backslashes in the string |
| are correctly escaped when written. |
| For instance, the call |
| \begin{verbatim} |
| format('%q', 'a string with "quotes" and \n new line') |
| \end{verbatim} |
| will produce the string: |
| \begin{verbatim} |
| "a string with \"quotes\" and \ |
| new line" |
| \end{verbatim} |
| |
| Conversions can be applied to the n-th argument in the argument list, |
| rather than the next unused argument. |
| In this case, the conversion character \verb|%| is replaced |
| by the sequence \verb|%d$|, where \verb|d| is a |
| decimal digit in the range [1,9], |
| giving the position of the argument in the argument list. |
| For instance, the call \verb|format("%2$d -> %1$03d", 1, 34)| will |
| result in \verb|"34 -> 001"|. |
| The same argument can be used in more than one conversion. |
| |
| The options \verb|c|, \verb|d|, \verb|E|, \verb|e|, \verb|f|, |
| \verb|g|, \verb|G|, \verb|i|, \verb|o|, \verb|u|, \verb|X|, and \verb|x| all |
| expect a number as argument, |
| whereas \verb|q| and \verb|s| expect a string. |
| The \verb|*| modifier can be simulated by building |
| the appropriate format string. |
| For example, \verb|"%*g"| can be simulated with |
| \verb|"%"..width.."g"|. |
| |
| \emph{Note: function \T{format} can only be used with strings that do not |
| contain zeros (0).} |
| |
| \subsubsection*{\ff \T{gsub (s, pat, repl [, n])}} |
| \Deffunc{gsub} |
| Returns a copy of \verb|s|, |
| where all occurrences of the pattern \verb|pat| have been |
| replaced by a replacement string specified by \verb|repl|. |
| This function also returns, as a second value, |
| the total number of substitutions made. |
| |
| If \verb|repl| is a string, then its value is used for replacement. |
| Any sequence in \verb|repl| of the form \verb|%n| |
| with \verb|n| between 1 and 9 |
| stands for the value of the n-th captured substring. |
| |
| If \verb|repl| is a function, then this function is called every time a |
| match occurs, with all captured substrings passed as arguments, |
| in order (see below). |
| If the value returned by this function is a string, |
| then it is used as the replacement string; |
| otherwise, the replacement string is the empty string. |
| |
| A last optional parameter \verb|n| limits |
| the maximum number of substitutions to occur. |
| For instance, when \verb|n| is 1 only the first occurrence of |
| \verb|pat| is replaced. |
| |
| Here are some examples: |
| \begin{verbatim} |
| x = gsub("hello world", "(%w+)", "%1 %1") |
| --> x="hello hello world world" |
| |
| x = gsub("hello world", "(%w+)", "%1 %1", 1) |
| --> x="hello hello world" |
| |
| x = gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1") |
| --> x="world hello Lua from" |
| |
| x = gsub("home = $HOME, user = $USER", "%$(%w+)", getenv) |
| --> x="home = /home/roberto, user = roberto" (for instance) |
| |
| x = gsub("4+5 = $return 4+5$", "%$(.-)%$", dostring) |
| --> x="4+5 = 9" |
| |
| local t = {name="lua", version="3.2"} |
| x = gsub("$name - $version", "%$(%w+)", function (v) return %t[v] end) |
| --> x="lua - 3.2" |
| |
| t = {n=0} |
| gsub("first second word", "(%w+)", function (w) tinsert(%t, w) end) |
| --> t={"first", "second", "word"; n=3} |
| \end{verbatim} |
| |
| |
| \subsubsection*{Patterns} \label{pm} |
| |
| \paragraph{Character Class:} |
| a \Def{character class} is used to represent a set of characters. |
| The following combinations are allowed in describing a character class: |
| \begin{description} |
| \item[\emph{x}] (where \emph{x} is any character not in the list |
| \verb|^$()%.[]*+-?|) |
| --- represents the character \emph{x} itself. |
| \item[\T{.}] --- (a dot) represents all characters. |
| \item[\T{\%a}] --- represents all letters. |
| \item[\T{\%c}] --- represents all control characters. |
| \item[\T{\%d}] --- represents all digits. |
| \item[\T{\%l}] --- represents all lower case letters. |
| \item[\T{\%p}] --- represents all punctuation characters. |
| \item[\T{\%s}] --- represents all space characters. |
| \item[\T{\%u}] --- represents all upper case letters. |
| \item[\T{\%w}] --- represents all alphanumeric characters. |
| \item[\T{\%x}] --- represents all hexadecimal digits. |
| \item[\T{\%z}] --- represents the character with representation 0. |
| \item[\T{\%\M{x}}] (where \M{x} is any non alphanumeric character) --- |
| represents the character \M{x}. |
| This is the standard way to escape the magic characters \verb|()%.[]*-?|. |
| It is strongly recommended that any control character (even the non magic), |
| when used to represent itself in a pattern, should be preceded by a \verb|%|. |
| |
| \item[\T{[char-set]}] --- |
| Represents the class which is the union of all |
| characters in char-set. |
| A range of characters may be specified by |
| separating the end characters of the range with a \verb|-|. |
| All classes \verb|%|\emph{x} described above can also be used as |
| components in a char-set. |
| All other characters in char-set represent themselves. |
| E.g., \verb|[%w_]| (or \verb|[_%w]|) |
| represents all alphanumeric characters plus the underscore, |
| \verb|[0-7]| represents the octal digits, |
| and \verb|[0-7%l%-]| represents the octal digits plus |
| the lower case letters plus the \verb|-| character. |
| |
| The interaction between ranges and classes is not defined. |
| Therefore, patterns like \verb|[%a-z]| or \verb|[a-%%]| |
| have no meaning. |
| |
| \item[\T{[\^{ }char-set]}] --- |
| represents the complement of char-set, |
| where char-set is interpreted as above. |
| \end{description} |
| For all classes represented by single letters (\verb|%a|, \verb|%c|, \ldots), |
| the correspondent upper-case letter represents the complement of the class. |
| For instance, \verb|%S| represents all non-space characters. |
| |
| The definitions of letter, space, etc. depend on the current locale. |
| In particular, the class \verb|[a-z]| may not be equivalent to \verb|%l|. |
| The second form should be preferred for portability. |
| |
| \paragraph{Pattern Item:} |
| a \Def{pattern item} may be |
| \begin{itemize} |
| \item |
| a single character class, |
| which matches any single character in the class; |
| \item |
| a single character class followed by \verb|*|, |
| which matches 0 or more repetitions of characters in the class. |
| These repetition items will always match the longest possible sequence; |
| \item |
| a single character class followed by \verb|+|, |
| which matches 1 or more repetitions of characters in the class. |
| These repetition items will always match the longest possible sequence; |
| \item |
| a single character class followed by \verb|-|, |
| which also matches 0 or more repetitions of characters in the class. |
| Unlike \verb|*|, |
| these repetition items will always match the shortest possible sequence; |
| \item |
| a single character class followed by \verb|?|, |
| which matches 0 or 1 occurrence of a character in the class; |
| \item |
| \T{\%\M{n}}, for \M{n} between 1 and 9; |
| such item matches a sub-string equal to the n-th captured string |
| (see below); |
| \item |
| \T{\%b\M{xy}}, where \M{x} and \M{y} are two distinct characters; |
| such item matches strings that start with \M{x}, end with \M{y}, |
| and where the \M{x} and \M{y} are \emph{balanced}. |
| That means that, if one reads the string from left to write, |
| counting plus 1 for an \M{x} and minus 1 for a \M{y}, |
| the ending \M{y} is the first where the count reaches 0. |
| For instance, the item \verb|%b()| matches expressions with |
| balanced parentheses. |
| \end{itemize} |
| |
| \paragraph{Pattern:} |
| a \Def{pattern} is a sequence of pattern items. |
| A \verb|^| at the beginning of a pattern anchors the match at the |
| beginning of the subject string. |
| A \verb|$| at the end of a pattern anchors the match at the |
| end of the subject string. |
| |
| \paragraph{Captures:} |
| a pattern may contain sub-patterns enclosed in parentheses, |
| that describe \Def{captures}. |
| When a match succeeds, the sub-strings of the subject string |
| that match captures are stored (\emph{captured}) for future use. |
| Captures are numbered according to their left parentheses. |
| For instance, in the pattern \verb|"(a*(.)%w(%s*))"|, |
| the part of the string matching \verb|"a*(.)%w(%s*)"| is |
| stored as the first capture (and therefore has number~1); |
| the character matching \verb|.| is captured with number~2, |
| and the part matching \verb|%s*| has number~3. |
| |
| {\em Note: A pattern cannot contain zeros (\verb|'\0'|). |
| Use \verb|'%z'| instead.} |
| |
| |
| \subsection{Mathematical Functions} \label{mathlib} |
| |
| This library is an interface to some functions of the standard C math library. |
| In addition, it registers a tag method for the binary operator \verb|^| that |
| returns \Math{x^y} when applied to numbers \verb|x^y|. |
| |
| The library provides the following functions: |
| \Deffunc{abs}\Deffunc{acos}\Deffunc{asin}\Deffunc{atan} |
| \Deffunc{atan2}\Deffunc{ceil}\Deffunc{cos}\Deffunc{floor} |
| \Deffunc{log}\Deffunc{log10}\Deffunc{max}\Deffunc{min} |
| \Deffunc{mod}\Deffunc{sin}\Deffunc{sqrt}\Deffunc{tan} |
| \Deffunc{frexp}\Deffunc{ldexp} |
| \Deffunc{random}\Deffunc{randomseed} |
| \begin{verbatim} |
| abs acos asin atan atan2 ceil cos deg floor log log10 |
| max min mod rad sin sqrt tan frexp ldexp |
| random randomseed |
| \end{verbatim} |
| plus a global variable \IndexVerb{PI}. |
| Most of them |
| are only interfaces to the homonymous functions in the C library, |
| except that, for the trigonometric functions, |
| all angles are expressed in \emph{degrees}, not radians. |
| Functions \IndexVerb{deg} and \IndexVerb{rad} can be used to convert |
| between radians and degrees. |
| |
| The function \verb|max| returns the maximum |
| value of its numeric arguments. |
| Similarly, \verb|min| computes the minimum. |
| Both can be used with 1, 2 or more arguments. |
| |
| The functions \verb|random| and \verb|randomseed| are interfaces to |
| the simple random generator functions \verb|rand| and \verb|srand|, |
| provided by ANSI C. |
| The function \verb|random|, when called without arguments, |
| returns a pseudo-random real number in the range \Math{[0,1)}. |
| When called with a number \Math{n}, |
| \verb|random| returns a pseudo-random integer in the range \Math{[1,n]}. |
| When called with two arguments, \Math{l} and \Math{u}, |
| \verb|random| returns a pseudo-random integer in the range \Math{[l,u]}. |
| |
| |
| \subsection{I/O Facilities} \label{libio} |
| |
| All input and output operations in Lua are done, by default, |
| over two \Def{file handles}, one for reading and one for writing. |
| These handles are stored in two Lua global variables, |
| called \verb|_INPUT| and \verb|_OUTPUT|. |
| The global variables |
| \verb|_STDIN|, \verb|_STDOUT| and \verb|_STDERR| |
| are initialized with file descriptors for |
| \verb|stdin|, \verb|stdout| and \verb|stderr|. |
| Initially, \verb|_INPUT=_STDIN| and \verb|_OUTPUT=_STDOUT|. |
| \Deffunc{_INPUT}\Deffunc{_OUTPUT} |
| \Deffunc{_STDIN}\Deffunc{_STDOUT}\Deffunc{_STDERR} |
| |
| A file handle is a userdata containing the file stream \verb|FILE*|, |
| and with a distinctive tag created by the I/O library. |
| |
| Unless otherwise stated, |
| all I/O functions return \nil\ on failure and |
| some value different from \nil\ on success. |
| |
| \subsubsection*{\ff \T{openfile (filename, mode)}}\Deffunc{openfile} |
| |
| This function opens a file, |
| in the mode specified in the string \verb|mode|. |
| It returns a new file handle, |
| or, in case of errors, \nil\ plus a string describing the error. |
| This function does not modify either \verb|_INPUT| or \verb|_OUTPUT|. |
| |
| The string mode can be any of the following: |
| \begin{description} |
| \item[``r''] read mode; |
| \item[``w''] write mode; |
| \item[``a''] append mode; |
| \item[``r+''] update mode, all previous data is preserved; |
| \item[``w+''] update mode, all previous data is erased; |
| \item[``a+''] append update mode, previous data is preserved, |
| writing is only allowed at the end of file. |
| \end{description} |
| The string mode may also have a \verb|b| at the end, |
| which is needed in some systems to open the file in binary mode. |
| |
| \subsubsection*{\ff \T{closefile (handle)}}\Deffunc{closefile} |
| |
| This function closes the given file. |
| It does not modify either \verb|_INPUT| or \verb|_OUTPUT|. |
| |
| \subsubsection*{\ff \T{readfrom (filename)}}\Deffunc{readfrom} |
| |
| This function may be called in two ways. |
| When called with a file name, it opens the named file, |
| sets its handle as the value of \verb|_INPUT|, |
| and returns this value. |
| It does not close the current input file. |
| When called without parameters, |
| it closes the \verb|_INPUT| file, |
| and restores \verb|stdin| as the value of \verb|_INPUT|. |
| |
| If this function fails, it returns \nil, |
| plus a string describing the error. |
| |
| \begin{quotation} |
| \noindent |
| \emph{System dependent}: if \verb|filename| starts with a \verb-|-, |
| then a \Index{piped input} is opened, via function \IndexVerb{popen}. |
| Not all systems implement pipes. |
| Moreover, |
| the number of files that can be open at the same time is |
| usually limited and depends on the system. |
| \end{quotation} |
| |
| \subsubsection*{\ff \T{writeto (filename)}}\Deffunc{writeto} |
| |
| This function may be called in two ways. |
| When called with a file name, |
| it opens the named file, |
| sets its handle as the value of \verb|_OUTPUT|, |
| and returns this value. |
| It does not close the current output file. |
| Note that, if the file already exists, |
| then it will be \emph{completely erased} with this operation. |
| When called without parameters, |
| this function closes the \verb|_OUTPUT| file, |
| and restores \verb|stdout| as the value of \verb|_OUTPUT|. |
| \index{closing a file} |
| |
| If this function fails, it returns \nil, |
| plus a string describing the error. |
| |
| \begin{quotation} |
| \noindent |
| \emph{System dependent}: if \verb|filename| starts with a \verb-|-, |
| then a \Index{piped output} is opened, via function \IndexVerb{popen}. |
| Not all systems implement pipes. |
| Moreover, |
| the number of files that can be open at the same time is |
| usually limited and depends on the system. |
| \end{quotation} |
| |
| \subsubsection*{\ff \T{appendto (filename)}}\Deffunc{appendto} |
| |
| Opens a file named \verb|filename| and sets it as the |
| value of \verb|_OUTPUT|. |
| Unlike the \verb|writeto| operation, |
| this function does not erase any previous contents of the file. |
| If this function fails, it returns \nil, |
| plus a string describing the error. |
| |
| \subsubsection*{\ff \T{remove (filename)}}\Deffunc{remove} |
| |
| Deletes the file with the given name. |
| If this function fails, it returns \nil, |
| plus a string describing the error. |
| |
| \subsubsection*{\ff \T{rename (name1, name2)}}\Deffunc{rename} |
| |
| Renames file named \verb|name1| to \verb|name2|. |
| If this function fails, it returns \nil, |
| plus a string describing the error. |
| |
| \subsubsection*{\ff \T{flush ([filehandle])}}\Deffunc{flush} |
| |
| Saves any written data to the given file. |
| If \verb|filehandle| is not specified, |
| flushes all open files. |
| If this function fails, it returns \nil, |
| plus a string describing the error. |
| |
| \subsubsection*{\ff \T{seek (filehandle [, whence] [, offset])}}\Deffunc{seek} |
| |
| Sets and gets the file position, |
| measured in bytes from the beginning of the file, |
| to the position given by \verb|offset| plus a base |
| specified by the string \verb|whence|, as follows: |
| \begin{description} |
| \item[``set''] base is position 0 (beginning of the file); |
| \item[``cur''] base is current position; |
| \item[``end''] base is end of file; |
| \end{description} |
| In case of success, function \verb|seek| returns the final file position, |
| measured in bytes from the beginning of the file. |
| If the call fails, it returns \nil, |
| plus a string describing the error. |
| |
| The default value for \verb|whence| is \verb|"cur"|, |
| and for \verb|offset| is 0. |
| Therefore, the call \verb|seek(file)| returns the current |
| file position, without changing it; |
| the call \verb|seek(file, "set")| sets the position to the |
| beginning of the file (and returns 0); |
| and the call \verb|seek(file, "end")| sets the position to the |
| end of the file, and returns its size. |
| |
| \subsubsection*{\ff \T{tmpname ()}}\Deffunc{tmpname} |
| |
| Returns a string with a file name that can safely |
| be used for a temporary file. |
| The file must be explicitly opened before its use |
| and removed when no longer needed. |
| |
| \subsubsection*{\ff \T{read ([filehandle,] format1, ...)}}\Deffunc{read} |
| |
| Reads file \verb|_INPUT|, |
| or \verb|filehandle| if this argument is given, |
| according to the given formats, which specify what to read. |
| For each format, |
| the function returns a string (or a number) with the characters read, |
| or \nil\ if it cannot read data with the specified format. |
| When called without patterns, |
| it uses a default format that reads the next line |
| (see below). |
| |
| The available formats are |
| \begin{description} |
| \item[``*n''] reads a number; |
| this is the only format that returns a number instead of a string. |
| \item[``*l''] reads the next line |
| (skipping the end of line), or \nil\ on end of file. |
| This is the default format. |
| \item[``*a''] reads the whole file, starting at the current position. |
| On end of file, it returns the empty string. |
| \item[``*w''] reads the next word |
| (maximal sequence of non white-space characters), |
| skipping spaces if necessary, or \nil\ on end of file. |
| \end{description} |
| |
| \subsubsection*{\ff \T{write ([filehandle, ] value1, ...)}}\Deffunc{write} |
| |
| Writes the value of each of its arguments to |
| file \verb|_OUTPUT|, |
| or to \verb|filehandle| if this argument is given. |
| The arguments must be strings or numbers. |
| To write other values, |
| use \verb|tostring| or \verb|format| before \verb|write|. |
| If this function fails, it returns \nil, |
| plus a string describing the error. |
| |
| \subsubsection*{\ff \T{date ([format])}}\Deffunc{date} |
| |
| Returns a string containing date and time |
| formatted according to the given string \verb|format|, |
| following the same rules of the ANSI C function \verb|strftime|. |
| When called without arguments, |
| it returns a reasonable date and time representation that depends on |
| the host system and on the current locale. |
| |
| \subsubsection*{\ff \T{clock ()}}\Deffunc{clock} |
| |
| Returns an approximation of the amount of CPU time |
| used by the program, in seconds. |
| |
| \subsubsection*{\ff \T{exit ([code])}}\Deffunc{exit} |
| |
| Calls the C function \verb|exit|, |
| with an optional \verb|code|, |
| to terminate the program. |
| The default value for \verb|code| is the success code. |
| |
| \subsubsection*{\ff \T{getenv (varname)}}\Deffunc{getenv} |
| |
| Returns the value of the process environment variable \verb|varname|, |
| or \nil\ if the variable is not defined. |
| |
| \subsubsection*{\ff \T{execute (command)}}\Deffunc{execute} |
| |
| This function is equivalent to the C function \verb|system|. |
| It passes \verb|command| to be executed by an operating system shell. |
| It returns a status code, which is system-dependent. |
| |
| \subsubsection*{\ff \T{setlocale (locale [, category])}}\Deffunc{setlocale} |
| |
| This function is an interface to the ANSI C function \verb|setlocale|. |
| \verb|locale| is a string specifying a locale; |
| \verb|category| is an optional string describing which category to change: |
| \verb|"all"|, \verb|"collate"|, \verb|"ctype"|, |
| \verb|"monetary"|, \verb|"numeric"|, or \verb|"time"|; |
| the default category is \verb|"all"|. |
| The function returns the name of the new locale, |
| or \nil\ if the request cannot be honored. |
| |
| |
| \section{The Debugger Interface} \label{debugI} |
| |
| Lua has no built-in debugging facilities. |
| Instead, it offers a special interface, |
| by means of functions and \emph{hooks}, |
| which allows the construction of different |
| kinds of debuggers, profilers, and other tools |
| that need ``inside information'' from the interpreter. |
| This interface is declared in the header file \verb|luadebug.h|. |
| |
| \subsection{Stack and Function Information} |
| |
| \Deffunc{lua_getstack} |
| The main function to get information about the interpreter stack is |
| \begin{verbatim} |
| int lua_getstack (lua_State *L, int level, lua_Debug *ar); |
| \end{verbatim} |
| It fills parts of a structure (\verb|lua_Debug|) with |
| an identification of the \emph{activation record} |
| of the function executing at a given level. |
| Level~0 is the current running function, |
| while level \Math{n+1} is the function that has called level \Math{n}. |
| Usually, \verb|lua_getstack| returns 1; |
| when called with a level greater than the stack depth, |
| it returns 0. |
| |
| The structure \verb|lua_Debug| is used to carry different informations |
| about an active function: \Deffunc{lua_Debug} |
| \begin{verbatim} |
| struct lua_Debug { |
| const char *event; /* `call', `return' */ |
| const char *source; /* (S) */ |
| int linedefined; /* (S) */ |
| const char *what; /* (S) `Lua' function, `C' function, Lua `main' */ |
| int currentline; /* (l) */ |
| const char *name; /* (n) */ |
| const char *namewhat; /* (n) global, tag method, local, field */ |
| int nups; /* (u) number of upvalues */ |
| lua_Object func; /* (f) function being executed */ |
| /* private part */ |
| ... |
| }; |
| \end{verbatim} |
| The \verb|lua_getstack| function fills only the private part |
| of this structure, for future use. |
| To fill in the other fields of \verb|lua_Debug| with useful information, |
| you call \Deffunc{lua_getinfo} |
| \begin{verbatim} |
| int lua_getinfo (lua_State *L, const char *what, lua_Debug *ar); |
| \end{verbatim} |
| Each character in string \verb|what| selects some fields to be filled, |
| as indicated by the letter in parentheses in the structure definition; |
| that is, an \verb|S| fills the fields \verb|source| and \verb|linedefined|, |
| and \verb|l| fills the field \verb|currentline|, etc. |
| Next we describe each field: |
| \begin{description} |
| |
| \item[source] |
| If the function was defined in a string, |
| \verb|source| is that string; |
| if the function was defined in a file, |
| \verb|source| starts with a \verb|@| followed by the file name. |
| |
| \item[linedefined] |
| the line number where starts the definition of the function. |
| |
| \item[what] the string \verb|"Lua"| if this is a Lua function, |
| \verb|"C"| if this is a C function, |
| or \verb|"main"| if this is the main part of a chunk. |
| |
| \item[currentline] |
| the current line where the given function is executing. |
| It only works if the function has been compiled with debug |
| information. |
| When no line information is available, |
| \verb|currentline| is set to \Math{-1}. |
| |
| \item[name] |
| a reasonable name for the given function. |
| Because functions in Lua are first class values, |
| they do not have a fixed name: |
| Some functions may be the value of many global variables, |
| while others may be stored only in a table field. |
| The \verb|lua_getinfo| function checks whether the given |
| function is a tag method or the value of a global variable. |
| If the given function is a tag method, |
| \verb|name| points to the event name. |
| If the given function is the value of a global variable, |
| \verb|name| points to the variable name. |
| If the given function is neither a tag method nor a global variable, |
| \verb|name| is set to \verb|NULL|. |
| |
| \item[namewhat] |
| Explains the previous field. |
| If the function is a global variable, |
| \verb|namewhat| is \verb|"global"|; |
| if the function is a tag method, |
| \verb|namewhat| is \verb|"tag-method"|; |
| otherwise \verb|namewhat| is \verb|""| (the empty string). |
| |
| \item[nups] |
| Number of upvalues of a C function. |
| If the function is not a C function, |
| \verb|nups| is set to 0. |
| |
| \item[func] |
| The function being executed, as a \verb|lua_Object|. |
| |
| \end{description} |
| |
| The generation of debug information is controlled by an internal flag, |
| which can be switched with |
| \begin{verbatim} |
| int lua_setdebug (lua_State *L, int debug); |
| \end{verbatim} |
| This function sets the flag and returns its previous value. |
| This flag can also be set from Lua~\see{pragma}. |
| |
| \subsection{Manipulating Local Variables} |
| |
| For the manipulation of local variables, |
| \verb|luadebug.h| defines the following record: |
| \begin{verbatim} |
| struct lua_Localvar { |
| int index; |
| const char *name; |
| lua_Object value; |
| }; |
| \end{verbatim} |
| where \verb|index| is an index for local variables |
| (the first parameter has index 1, and so on, |
| until the last active local variable). |
| |
| \Deffunc{lua_getlocal}\Deffunc{lua_setlocal} |
| The following functions allow the manipulation of the |
| local variables of a given activation record. |
| They only work if the function has been compiled with debug |
| information \see{pragma}. |
| For these functions, a local variable becomes |
| visible in the line after its definition. |
| \begin{verbatim} |
| int lua_getlocal (lua_State *L, const lua_Debug *ar, lua_Localvar *v); |
| int lua_setlocal (lua_State *L, const lua_Debug *ar, lua_Localvar *v); |
| \end{verbatim} |
| The parameter \verb|ar| must be a valid activation record, |
| filled by a previous call to \verb|lua_getstack| or |
| given as argument to a hook (see next section). |
| To use \verb|lua_getlocal|, |
| you fill the \verb|index| field of \verb|v| with the index |
| of a local variable; then the function fills the fields |
| \verb|name| and \verb|value| with the name and the current |
| value of that variable. |
| For \verb|lua_setlocal|, |
| you fill the \verb|index| and the \verb|value| fields of \verb|v|, |
| and the function assigns that value to the variable. |
| Both functions return 0 on failure, that happens |
| if the index is greater than the number of active local variables, |
| or if the activation record has no debug information. |
| |
| As an example, the following function lists the names of all |
| local variables for a function in a given level of the stack: |
| \begin{verbatim} |
| int listvars (lua_State *L, int level) { |
| lua_Debug ar; |
| int i; |
| if (lua_getstack(L, level, &ar) == 0) |
| return 0; /* failure: no such level on the stack */ |
| for (i=1; ;i++) { |
| lua_Localvar v; |
| v.index = i; |
| if (lua_getlocal(L, &ar, &v) == 0) |
| return 1; /* no more locals, or no debug information */ |
| printf("%s\n", v.name); |
| } |
| } |
| \end{verbatim} |
| |
| |
| \subsection{Hooks} |
| |
| The Lua interpreter offers two hooks for debugging purposes: |
| a \emph{call} hook and a \emph{line} hook. |
| Both have the same type, |
| \begin{verbatim} |
| typedef void (*lua_Hook) (lua_State *L, lua_Debug *ar); |
| \end{verbatim} |
| and you can set them with the following functions: |
| \Deffunc{lua_Hook}\Deffunc{lua_setcallhook}\Deffunc{lua_setlinehook} |
| \begin{verbatim} |
| lua_Hook lua_setcallhook (lua_State *L, lua_Hook func); |
| lua_Hook lua_setlinehook (lua_State *L, lua_Hook func); |
| \end{verbatim} |
| A hook is disabled when its value is \verb|NULL|, |
| which is the initial value of both hooks. |
| The functions \verb|lua_setcallhook| and \verb|lua_setlinehook| |
| set their corresponding hooks and return their previous values. |
| |
| The call hook is called whenever the |
| interpreter enters or leaves a function. |
| The \verb|event| field of \verb|ar| has the strings \verb|"call"| |
| or \verb|"return"|. |
| This \verb|ar| can then be used in calls to \verb|lua_getinfo|, |
| \verb|lua_getlocal|, and \verb|lua_setlocal|, |
| to get more information about the function and to manipulate its |
| local variables. |
| |
| The line hook is called every time the interpreter changes |
| the line of code it is executing. |
| The \verb|currentline| field of \verb|ar| has the line number. |
| Again, you can use this \verb|ar| in other calls to the API. |
| This hook is called only if the active function |
| has been compiled with debug information~\see{pragma}. |
| |
| While Lua is running a hook, it disables other calls to hooks. |
| Therefore, if a hook calls Lua to execute a function or a chunk, |
| this execution ocurrs without any calls to hooks. |
| |
| A hook cannot call \T{lua_error}. |
| It must return to Lua through a regular return. |
| (There is no problem if the error is inside a chunk or a Lua function |
| called by the hook, because those errors are protected; |
| the control returns to the hook anyway.) |
| |
| |
| \subsection{The Reflexive Debugger Interface} |
| |
| The library \verb|ldblib| provides |
| the functionality of the debugger interface to Lua programs. |
| If you want to use this library, |
| your host application must open it, |
| by calling \verb|lua_dblibopen|. |
| |
| You should exert great care when using this library. |
| The functions provided here should be used exclusively for debugging |
| and similar tasks (e.g., profiling). |
| Please resist the temptation to use them as a |
| usual programming tool. |
| They are slow and violate some (otherwise) secure aspects of the |
| language (e.g., privacy of local variables). |
| As a general rule, if your program does not need this library, |
| do not open it. |
| |
| |
| \subsubsection*{\ff \T{getstack (level, what)}}\Deffunc{getstack} |
| |
| This function returns a table with informations about the function |
| running at level \verb|level| of the stack. |
| Level 0 is the current function (\verb|getstack| itself); |
| level 1 is the function that called \verb|getstack|. |
| If \verb|level| is larger than the number of active functions, |
| the function returns \nil. |
| The table contains all the fields returned by \verb|lua_getinfo|, |
| with the string \verb|what| describing what to get. |
| |
| For instance, the expression \verb|getstack(1, 'n').name| returns |
| the name of the current function. |
| |
| |
| \subsubsection*{\ff \T{getlocal (level, local)}}\Deffunc{getlocal} |
| |
| This function returns the name and the value of the local variable |
| with index \verb|local| of the function at level \verb|level| of the stack. |
| (The first parameter has index 1, and so on, |
| until the last active local variable.) |
| The function returns \nil\ if there is no local |
| variable with the given index, |
| and raises an error when called with a \verb|level| out of range. |
| (You can call \verb|getstack| to check wheter the level is valid.) |
| |
| \subsubsection*{\ff \T{setlocal (level, local, value)}}\Deffunc{setlocal} |
| |
| This function assigns the value \verb|value| to the local variable |
| with index \verb|local| of the function at level \verb|level| of the stack. |
| The function returns \nil\ if there is no local |
| variable with the given index, |
| and raises an error when called with a \verb|level| out of range. |
| |
| \subsubsection*{\ff \T{setcallhook (hook)}}\Deffunc{setcallhook} |
| |
| Sets the function \verb|hook| as the call hook; |
| this hook will be called every time the interpreter starts and |
| exits the execution of a function. |
| The only argument to this hook is the event name (\verb|"call"| or |
| \verb|"return"|). |
| You can call \verb|getstack| with level 2 to get more information about |
| the function being called or returning |
| (level 0 is the \verb|getstack| function, |
| and level 1 is the hook function). |
| |
| When called without arguments, |
| this function turns off call hooks. |
| |
| \subsubsection*{\ff \T{setlinehook (hook)}}\Deffunc{setlinehook} |
| |
| Sets the function \verb|hook| as the line hook; |
| this hook will be called every time the interpreter changes |
| the line of code it is executing. |
| The only argument to the hook is the line number the interpreter |
| is about to execute. |
| This hook is called only if the active function |
| has been compiled with debug information~\see{pragma}. |
| |
| When called without arguments, |
| this function turns off line hooks. |
| |
| |
| \section{\Index{Lua Stand-alone}} \label{lua-sa} |
| |
| Although Lua has been designed as an extension language, |
| the language is frequently used as a stand-alone interpreter. |
| An implementation of such an interpreter, |
| called simply \verb|lua|, |
| is provided with the standard distribution. |
| This program can be called with any sequence of the following arguments: |
| \begin{description} |
| \item[\T{-}] executes \verb|stdin| as a file; |
| \item[\T{-d}] turns on debug information; |
| \item[\T{-e stat}] executes string \verb|stat|; |
| \item[\T{-f filename}] executes file \verb|filename| with the |
| remaining arguments in table \verb|arg|; |
| \item[\T{-i}] enters interactive mode with prompt; |
| \item[\T{-q}] enters interactive mode without prompt; |
| \item[\T{-v}] prints version information; |
| \item[\T{var=value}] sets global \verb|var| to string \verb|"value"|; |
| \item[\T{filename}] executes file \verb|filename|. |
| \end{description} |
| When called without arguments, |
| Lua behaves as \verb|lua -v -i| when \verb|stdin| is a terminal, |
| and as \verb|lua -| otherwise. |
| |
| All arguments are handled in order. |
| For instance, an invocation like |
| \begin{verbatim} |
| $ lua -i a=test prog.lua |
| \end{verbatim} |
| will first interact with the user until an \verb|EOF|, |
| then will set \verb|a| to \verb|"test"|, |
| and finally will run the file \verb|prog.lua|. |
| |
| When the option \T{-f filename} is used, |
| all following arguments from the command line |
| are passed to the Lua program in a table called \verb|arg|. |
| The field \verb|n| gets the index of the last argument, |
| and the field 0 gets the \T{filename}. |
| For instance, in the call |
| \begin{verbatim} |
| $ lua a.lua -f b.lua t1 t3 |
| \end{verbatim} |
| the interpreter first runs the file \T{a.lua}, |
| then creates a table \T{arg}, |
| \begin{verbatim} |
| arg = {"t1", "t3"; n = 2, [0] = "b.lua"} |
| \end{verbatim} |
| and then runs the file \T{b.lua}. |
| |
| In interactive mode, |
| a multi-line statement can be written finishing intermediate |
| lines with a backslash (\verb|\|). |
| If the global variable \verb|_PROMPT| is defined as a string, |
| its value is used as the prompt. \Index{_PROMPT} |
| Therefore, the prompt can be changed like below: |
| \begin{verbatim} |
| $ lua _PROMPT='myprompt> ' -i |
| \end{verbatim} |
| |
| In Unix systems, Lua scripts can be made into executable programs |
| by using the \verb|#!| form, |
| as in \verb|#!/usr/local/bin/lua|, |
| or \verb|#!/usr/local/bin/lua -f| to get other arguments. |
| |
| |
| \section*{Acknowledgments} |
| |
| The authors would like to thank CENPES/PETROBRAS which, |
| jointly with \tecgraf, used extensively early versions of |
| this system and gave valuable comments. |
| The authors would also like to thank Carlos Henrique Levy, |
| who found the name of the game. |
| Lua means \emph{moon} in Portuguese. |
| |
| |
| |
| \appendix |
| |
| \section*{Incompatibilities with Previous Versions} |
| |
| Although great care has been taken to avoid incompatibilities with |
| the previous public versions of Lua, |
| some differences had to be introduced. |
| Here is a list of all these incompatibilities. |
| |
| \subsection*{Incompatibilities with \Index{version 3.2}} |
| \begin{itemize} |
| \item |
| |
| \item Old pre-compiled code is obsolete, and must be re-compiled. |
| |
| \end{itemize} |
| |
| % restore underscore to usual meaning |
| \catcode`\_=8 |
| |
| \newcommand{\indexentry}[2]{\item {#1} #2} |
| \begin{theindex} |
| \input{manual.id} |
| \end{theindex} |
| |
| |
| \end{document} |
| |
| |