| % $Id: manual.tex,v 1.32 1999/05/11 20:46:28 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}{3.2} |
| |
| \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: 1999/05/11 20:46:28 $ $}} |
| |
| \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 bytecodes, |
| 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 bytecodes, |
| 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--1999 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_open| 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 function \verb|type| 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 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 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} can have |
| as many different tags as needed \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 do else elseif |
| end 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 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'| (new line), |
| \verb|'\r'| (carriage return), |
| \verb|'\t'| (horizontal tab), |
| \verb|'\v'| (vertical tab), |
| \verb|'\\'|, (backslash), |
| \verb|'\"'|, (double quote), |
| and \verb|'\''| (single quote). |
| 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 0. |
| |
| 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[\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 optionally followed by a semicolon: |
| \begin{Produc} |
| \produc{block}{\rep{stat sc} \opt{ret}} |
| \produc{sc}{\opt{\ter{;}}} |
| \end{Produc}% |
| For syntactic reasons, a \IndexVerb{return} statement can only be written |
| as the last statement of a block. |
| This restriction also avoids some ``statement not reached'' conditions. |
| |
| 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}. |
| |
| \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} |
| |
| A \T{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{ret}{\rwd{return} \opt{explist1} \opt{sc}} |
| \end{Produc} |
| |
| \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}} |
| Basic expressions 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|==|). |
| Note that 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 other 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 ``order'' 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. |
| |
| A useful Lua idiom 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. |
| |
| \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. |
| |
| \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 parameters. |
| |
| 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}{exp1 \rep{\ter{,} exp1}} |
| \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. |
| Note that the only place that can hold many values |
| is the last (or the only) expression in an assignment |
| or in a return statement; see examples below. |
| \begin{verbatim} |
| f(); -- adjusted to 0 |
| g(x, f()); -- f() is adjusted to 1 |
| 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} |
| |
| 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 ``closed''). |
| This function instance (or ``closure'') |
| is the final value of the expression. |
| Different instances of a 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 |
| \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 |
| |
| 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} |
| \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 includes 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 a \verb|<| operation is applied to non numerical |
| or non string operands. |
| \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} |
| |
| \item[``gt'':]\index{gt event} |
| called when a \verb|>| operation is applied to non numerical |
| or non string operands. |
| Behavior similar to the \verb|"lt"| event. |
| |
| \item[``le'':]\index{le event} |
| called when a \verb|<=| operation is applied to non numerical |
| or non string operands. |
| Behavior similar to the \verb|"lt"| event. |
| |
| \item[``ge'':]\index{ge event} |
| called when a \verb|>=| operation is applied to non numerical |
| or non string operands. |
| Behavior similar to the \verb|"lt"| event. |
| |
| \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 |
| return rawsetglobal(varname, newvalue) |
| else |
| return 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 |
| local i = arg.n |
| while i > 0 do |
| arg[i+1] = arg[i] |
| i = i-1 |
| 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 object. |
| This method cannot be set for strings, numbers, functions, |
| and userdata with default tag. |
| For each object 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|, |
| 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 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 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|. |
| |
| \subsection{Managing States} \label{mangstate} |
| The whole state of the Lua interpreter |
| (global variables, stack, tag methods, etc) |
| is stored in a dynamic structure pointed by\Deffunc{lua_state} |
| \begin{verbatim} |
| typedef struct lua_State lua_State; |
| extern lua_State *lua_state; |
| \end{verbatim} |
| The variable \verb|lua_state| is the only C global variable in |
| the Lua library. |
| |
| Before calling any API function, |
| this state must be initialized. |
| This is done by calling\Deffunc{lua_open} |
| \begin{verbatim} |
| void lua_open (void); |
| \end{verbatim} |
| This function allocates and initializes some internal structures, |
| and defines all pre-defined functions of Lua. |
| If \verb|lua_state| is already different from \verb|NULL|, |
| \verb|lua_open| has no effect; |
| therefore, it is safe to call this function multiple times. |
| All standard libraries call \verb|lua_open| when they are opened. |
| |
| Function \verb|lua_setstate| is used to change the current state |
| of Lua:\Deffunc{lua_setstate} |
| \begin{verbatim} |
| lua_State *lua_setstate (lua_State *st); |
| \end{verbatim} |
| It sets \verb|lua_state| to \verb|st| and returns the old state. |
| |
| Multiple, independent states may be created. |
| For that, you must set \verb|lua_state| back to \verb|NULL| before |
| calling \verb|lua_open|. |
| An easy way to do that is defining an auxiliary function: |
| \begin{verbatim} |
| lua_State *lua_newstate (void) { |
| lua_State *old = lua_setstate(NULL); |
| lua_open(); |
| return lua_setstate(old); |
| } |
| \end{verbatim} |
| This function creates a new state without changing the current state |
| of the interpreter. |
| Note that any new state is created with all predefined functions, |
| but any additional library (such as the standard libraries) must be |
| explicitly open in the new state, if needed. |
| |
| If necessary, a state may be released by calling\Deffunc{lua_close} |
| \begin{verbatim} |
| void lua_close (void); |
| \end{verbatim} |
| This function destroys all objects in the current Lua environment |
| (calling the correspondent garbage collector tag methods), |
| frees all dynamic memory used by the state, |
| and then sets \verb|lua_state| to \verb|NULL|. |
| Usually, there is no need to call this function, |
| since these resources are naturally released when the program ends. |
| If \verb|lua_state| is already \verb|NULL|, |
| \verb|lua_close| has no effect. |
| |
| If you are using multiple states, |
| you may find useful to define the following function, |
| which releases a given state: |
| \begin{verbatim} |
| void lua_freestate (lua_State *st) { |
| lua_State *old = lua_setstate(st); |
| lua_close(); |
| if (old != st) lua_setstate(old); |
| } |
| \end{verbatim} |
| |
| \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, |
| the comparison of two \verb|lua_Object's| is undefined. |
| |
| 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} |
| \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); |
| \end{verbatim} |
| These 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, |
| whereas |
| \verb|lua_isstring| accepts strings and numbers \see{coercion}, |
| and \verb|lua_isfunction| accepts Lua functions and C functions. |
| |
| 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, |
| the programmer 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); |
| 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|char*|). |
| This \verb|lua_Object| must be a string or a number; |
| otherwise, the function returns~0 (the \verb|NULL| pointer). |
| 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 0 (the \verb|NULL| pointer). |
| 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 0 (the \verb|NULL| pointer). |
| |
| \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|=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 (char *s, long len); |
| void lua_pushstring (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 do not contain zeros and end with a zero); |
| 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 (char *filename); |
| int lua_dostring (char *string); |
| int lua_dobuffer (char *buff, int size, 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 (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 (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 (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 (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 (a Lua function may return many values) |
| are returned in structure lua2C, |
| 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 (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, 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, 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|. |
| |
| |
| \subsection{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)) |
| /* 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. |
| 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. |
| |
| 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 the table indices are modified in any way during a traversal, |
| the semantics of \verb|next| is undefined. |
| |
| This function cannot be written with the standard API. |
| |
| \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. |
| Similarly to \verb|next|, it returns the name of another variable |
| and its value, |
| or \nil\ if there are no more variables. |
| There can be no creation of new global variables during the traversal; |
| otherwise the semantics of \verb|nextvar| is undefined. |
| |
| This function cannot be written with the standard API. |
| |
| \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 this function. |
| Therefore, a program may redefine it |
| 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 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} |
| 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|. |
| Function \verb|rawsetglobal| returns the value of its second argument. |
| |
| \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. |
| Function \verb|setglobal| returns the value of its second argument. |
| |
| \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 = 0 |
| local i = next(t, nil) |
| while i do |
| if type(i) == 'number' and i>max then max=i end |
| i = next(t, i) |
| 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 = next(t, nil) |
| while i do |
| local res = f(i, v) |
| if res then return res end |
| i, v = next(t, i) |
| end |
| end |
| \end{verbatim} |
| |
| |
| \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) |
| local i, n = 1, getn(t) |
| while i <= n do |
| local res = f(i, t[i]) |
| if res then return res end |
| i = i+1 |
| 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 = nextvar(nil) |
| while n do |
| local res = f(n, v) |
| if res then return res end |
| n, v = nextvar(n) |
| end |
| end |
| \end{verbatim} |
| |
| \subsubsection*{\ff \T{tinsert (table [, pos] , value)}}\Deffunc{tinsert} |
| |
| Inserts element \verb|value| at table position \verb|pos|, |
| shifting other elements to open space. |
| 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 = n+1; value = arg[1] |
| else |
| pos = arg[1]; value = arg[2] |
| end |
| t.n = n+1; |
| while n >= pos do |
| t[n+1] = t[n] |
| n = n-1 |
| 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. |
| 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) |
| pos = pos or n |
| local value = t[pos] |
| if n<=0 then return end |
| while pos < n do |
| t[pos] = t[pos+1] |
| pos = pos+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 \verb|<| Lua operator is used instead. |
| |
| Function \verb|sort| returns the (sorted) table. |
| |
| |
| \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.} |
| |
| \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 hexa-decimal 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. |
| To include a \verb|]| in char-set, it must be the first character. |
| A range of characters may be specified by |
| separating the end characters of the range with a \verb|-|. |
| If \verb|-| appears as the first or last character of char-set, |
| then it represents itself. |
| 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., assuming an \emph{ascii} character set, |
| \verb|[%dA-Fa-f]| specifies the hexa-decimal digits. |
| \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 more portable programs. |
| |
| \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. |
| |
| |
| \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. |
| Whenever a file handle is collected by the garbage collector, |
| its correspondent stream is automatically closed. |
| |
| 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 content 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 removed when no longer needed. |
| |
| \subsubsection*{\ff \T{read ([filehandle,] readpattern1, ...)}}\Deffunc{read} |
| |
| Reads file \verb|_INPUT|, |
| or \verb|filehandle| if this argument is given, |
| according to read patterns, which specify how much to read. |
| For each pattern, |
| the function returns a string with the characters read, |
| even if the pattern succeeds only partially, |
| or \nil\ if the read pattern fails \emph{and} |
| the result string would be empty. |
| When called without patterns, |
| it uses a default pattern that reads the next line |
| (see below). |
| |
| A \Def{read pattern} is a sequence of read pattern items. |
| An item may be a single character class |
| or a character class followed by \verb|?|, by \verb|*|, or by \verb|+|. |
| A single character class reads the next character from the input |
| if it belongs to the class, otherwise it fails. |
| A character class followed by \verb|?| reads the next character |
| from the input if it belongs to the class; |
| it never fails. |
| A character class followed by \verb|*| reads until a character that |
| does not belong to the class, or end of file; |
| since it can match a sequence of zero characters, it never fails. |
| A character class followed by \verb|+| reads until a character that |
| does not belong to the class, or end of file; |
| it fails if it cannot read at least one character. |
| Note that the behavior of read patterns is slightly different from |
| the regular pattern matching behavior, |
| where a \verb|*| expands to the maximum length \emph{such that} |
| the rest of the pattern does not fail. |
| With the read pattern behavior |
| there is no need for backtracking the reading. |
| |
| A pattern item may contain sub-patterns enclosed in curly brackets, |
| that describe \Def{skips}. |
| Characters matching a skip are read, |
| but are not included in the resulting string. |
| |
| There are some predefined patterns, as follows: |
| \begin{description} |
| \item[``*n''] reads a number; |
| this is the only pattern that returns a number instead of a string. |
| \item[``*l''] returns the next line |
| (skipping the end of line), or \nil\ on end of file. |
| This is the default pattern. |
| It is equivalent to the pattern \verb|"[^\n]*{\n}"|. |
| \item[``*a''] reads the whole file. |
| It is equivalent to the pattern \verb|".*"|. |
| \item[``*w''] returns the next word |
| (maximal sequence of non white-space characters), |
| skipping spaces if necessary, or \nil\ on end of file. |
| It is equivalent to the pattern \verb|"{%s*}%S+"|. |
| \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 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 1. |
| |
| \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 an error 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} |
| |
| The main function to get information about the interpreter stack |
| is |
| \begin{verbatim} |
| lua_Function lua_stackedfunction (int level); |
| \end{verbatim} |
| It returns a handle (\verb|lua_Function|) to 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}. |
| When called with a level greater than the stack depth, |
| \verb|lua_stackedfunction| returns \verb|LUA_NOOBJECT|. |
| |
| The type \verb|lua_Function| is just another name |
| to \verb|lua_Object|. |
| Although, in this library, |
| a \verb|lua_Function| can be used wherever a \verb|lua_Object| is required, |
| when a parameter has type \verb|lua_Function| |
| it accepts only a handle returned by |
| \verb|lua_stackedfunction|. |
| |
| Three other functions produce extra information about a function: |
| \begin{verbatim} |
| void lua_funcinfo (lua_Object func, char **source, int *linedefined); |
| int lua_currentline (lua_Function func); |
| char *lua_getobjname (lua_Object o, char **name); |
| \end{verbatim} |
| \verb|lua_funcinfo| gives the source and the line where the |
| given function has been defined: |
| 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. |
| If the ``function'' is in fact the main code of a chunk, |
| then \verb|linedefined| is 0. |
| If the function is a C function, |
| then \verb|linedefined| is \Math{-1}, and \verb|filename| is \verb|"(C)"|. |
| |
| The function \verb|lua_currentline| gives the current line where |
| a given function is executing. |
| It only works if the function has been compiled with debug |
| information. |
| When no line information is available, |
| \verb|lua_currentline| returns \Math{-1}. |
| |
| The generation of debug information is controled by an internal flag, |
| which can be switched with |
| \begin{verbatim} |
| int lua_setdebug (int debug); |
| \end{verbatim} |
| This function sets the flag and returns its previous value. |
| This flag can also be set from Lua~\see{pragma}. |
| |
| Function \verb|lua_getobjname| tries to find a reasonable name for |
| a 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. |
| Function \verb|lua_getobjname| checks whether the given |
| function is a tag method or the value of a global variable. |
| If the given function is a tag method, then \verb|lua_getobjname| |
| returns the string \verb|"tag-method"|, |
| and \verb|name| is set to point to the event name. |
| If the given function is the value of a global variable, |
| then \verb|lua_getobjname| returns the string \verb|"global"|, |
| and \verb|name| points to the variable name. |
| If the given function is neither a tag method nor a global variable, |
| then \verb|lua_getobjname| returns the empty string, |
| and \verb|name| is set to \verb|NULL|. |
| |
| \subsection{Manipulating Local Variables} |
| |
| 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}. |
| Moreover, for these functions, a local variable becomes |
| visible in the line after its definition. |
| \begin{verbatim} |
| lua_Object lua_getlocal (lua_Function func, int local_number, char **name); |
| int lua_setlocal (lua_Function func, int local_number); |
| \end{verbatim} |
| \verb|lua_getlocal| returns the value of a local variable, |
| and sets \verb|name| to point to the variable name. |
| \verb|local_number| is an index for local variables. |
| The first parameter has index 1, and so on, until the |
| last active local variable. |
| When called with a \verb|local_number| greater than the |
| number of active local variables, |
| or if the activation record has no debug information, |
| \verb|lua_getlocal| returns \verb|LUA_NOOBJECT|. |
| Formal parameters are the first local variables. |
| |
| The function \verb|lua_setlocal| sets the local variable |
| \verb|local_number| to the value previously pushed on the stack |
| \see{valuesCLua}. |
| If the function succeeds, then it returns 1. |
| If \verb|local_number| is greater than the number |
| of active local variables, |
| or if the activation record has no debug information, |
| then this function fails and returns 0. |
| |
| \subsection{Hooks} |
| |
| The Lua interpreter offers two hooks for debugging purposes: |
| \begin{verbatim} |
| typedef void (*lua_CHFunction) (lua_Function func, char *file, int line); |
| lua_CHFunction lua_setcallhook (lua_CHFunction func); |
| |
| typedef void (*lua_LHFunction) (int line); |
| lua_LHFunction lua_setlinehook (lua_LHFunction func); |
| \end{verbatim} |
| The first hook is called whenever the interpreter enters or leaves a |
| function. |
| When entering a function, |
| its parameters are a handle to the function activation record, |
| plus the file and the line where the function is defined |
| (the same information which is provided by \verb|lua_funcinfo|); |
| when leaving a function, \verb|func| is \verb|LUA_NOOBJECT|, |
| \verb|file| is \verb|"(return)"|, and \verb|line| is 0. |
| |
| The other hook is called every time the interpreter changes |
| the line of code it is executing. |
| Its only parameter is the line number |
| (the same information which is provided by the call |
| \verb|lua_currentline(lua_stackedfunction(0))|). |
| This second hook is called only if the active function |
| has been compiled with debug information \see{pragma}. |
| |
| A hook is disabled when its value is \verb|NULL|, |
| which is the initial value of both hooks. |
| Both \verb|lua_setcallhook| and \verb|lua_setlinehook| |
| set their corresponding hooks and return their previous values. |
| |
| |
| |
| \subsection{The Reflexive Debugger Interface} |
| |
| The library \verb|ldblib| provides |
| the functionallity of the debugger interface to Lua programs. |
| If you want to use this library, |
| your host application must open it, |
| 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{funcinfo (function)}}\Deffunc{funcinfo} |
| |
| This function returns a table with information about the given function. |
| The table contains the following fields: |
| \begin{description} |
| \item[kind]: may be \verb|"C"|, if this is a C function, |
| \verb|"chunk"|, if this is the main part of a chunk, |
| or \verb|"Lua"| if this is a Lua function. |
| |
| \item[source] the source where the function was defined. |
| 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[def\_line] the line where the function was defined in the source |
| (only valid if this is a Lua function). |
| |
| \item[where] can be \verb|"global"| if this function has a global name, |
| or \verb|"tag-method"| if this function is a tag method handler. |
| |
| \item[name] if \verb|where| = \verb|global|, |
| \verb|name| is the global name of the function; |
| if \verb|where| = \verb|tag-method|, |
| \verb|name| is the event name of the tag method. |
| \end{description} |
| |
| \subsubsection*{\ff \T{getstack (index)}}\Deffunc{getstack} |
| |
| This function returns a table with informations about the function |
| running at level \verb|index| of the stack. |
| Index 0 is the current function (\verb|getstack| itself). |
| If \verb|index| is bigger than the number of active functions, |
| the function returns \nil. |
| The table contains all the fields returned by \verb|funcinfo|, |
| plus the following: |
| \begin{description} |
| \item[func] the function at that level. |
| \item[current] the current line on the function execution; |
| this will be available only when the function is |
| precompiled with debug information. |
| \end{description} |
| |
| \subsubsection*{\ff \T{getlocal (index [, local])}}\Deffunc{getlocal} |
| |
| This function returns information about the local variables of the |
| function at level \verb|index| of the stack. |
| It can be called in three ways. |
| When called without a \verb|local| argument, |
| it returns a table, which associates variable names to their values. |
| When called with a name (a string) as \verb|local|, |
| it returns the value of the local variable with that name. |
| Finally, when called with an index (a number), |
| it returns the value and the name of the local variable |
| with that index. |
| (The first parameter has index 1, and so on, |
| until the last active local variable.) |
| In that case, the function returns \nil\ if there is no local |
| variable with the given index. |
| The specification by index is the only way to distinguish |
| homonym variables in a function. |
| |
| \subsubsection*{\ff \T{setlocal (index, local, newvalue)}}\Deffunc{setlocal} |
| |
| This function changes the values of the local variables of the |
| function at level \verb|index| of the stack. |
| The local variable can be specified by name or by index; |
| see function \verb|getlocal|. |
| |
| \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. |
| When Lua enters a function, |
| the hook is called with the function been called, |
| plus the source and the line where the function is defined. |
| When Lua exits a function, |
| the hook is called with no arguments. |
| |
| 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 execut. |
| 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 can also be 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{-v}] prints version information. |
| \item[\T{-d}] turns on debug information. |
| \item[\T{-e stat}] executes \verb|stat| as a Lua chunk. |
| \item[\T{-i}] runs interactively, |
| accepting commands from standard input until an \verb|EOF|. |
| Each line entered is immediately executed. |
| \item[\T{-q}] same as \T{-i}, but without a prompt (quiet mode). |
| \item[\T{-}] executes \verb|stdin| as a file. |
| \item[\T{var=value}] sets global \verb|var| with string \verb|"value"|. |
| \item[\T{filename}] executes file \verb|filename| as a Lua chunk. |
| \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 in interactive mode, |
| a multi-line statement can be written finishing intermediate |
| lines with a backslash (\verb|\|). |
| The prompt presented is the value of the global variable \verb|_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|. |
| |
| \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.1}} |
| \begin{itemize} |
| \item |
| In the debug API, the old variables \verb|lua_debug|, |
| \verb|lua_callhook| and \verb|lua_linehook| now live inside \verb|lua_state|. |
| Therefore, they are no longer directly accessible, and must be |
| manipulated only through the new functions \verb|lua_setdebug|, |
| \verb|lua_setcallhook| and \verb|lua_setlinehook|. |
| |
| \item Old pre-compiled code is obsolete, and must be re-compiled. |
| \end{itemize} |
| |
| \subsection*{Incompatibilities with \Index{version 3.0}} |
| \begin{itemize} |
| |
| \item To support multiple contexts, |
| Lua 3.1 must be explicitly opened before used, |
| with function \verb|lua_open|. |
| However, all standard libraries check whether Lua is already opened, |
| so any existing program that opens at least one standard |
| library before calling Lua does not need to be modified. |
| |
| \item Function \verb|dostring| no longer accepts an optional second argument, |
| with a temporary error handler. |
| This facility is now provided by function \verb|call|. |
| |
| \item Function \verb|gsub| no longer accepts an optional fourth argument |
| (a callback data, a table). |
| Closures replace this feature with advantage. |
| |
| \item The syntax for function declaration is now more restricted; |
| for instance, the old syntax \verb|function f[exp] (x) ... end| is not |
| accepted in Lua 3.1. |
| In these cases, |
| programs should use an explicit assignment instead, such as |
| \verb|f[exp] = function (x) ... end|. |
| |
| \item Old pre-compiled code is obsolete, and must be re-compiled. |
| |
| \item The option \verb|a=b| in Lua stand-alone now sets \verb|a| to the |
| \M{string} \verb|b|, and not to the value of \verb|b|. |
| |
| \end{itemize} |
| |
| % restore underscore to usual meaning |
| \catcode`\_=8 |
| |
| \newcommand{\indexentry}[2]{\item {#1} #2} |
| \begin{theindex} |
| \input{manual.id} |
| \end{theindex} |
| |
| |
| \end{document} |
| |
| |