| % $Id: manual.tex,v 1.50 2001/07/19 13:36:18 roberto Exp roberto $ |
| |
| \documentclass[11pt]{article} |
| \usepackage{fullpage} |
| \usepackage{bnf} |
| \usepackage{graphicx} |
| %\usepackage{times} |
| |
| \catcode`\_=12 |
| |
| %\newcommand{\See}[1]{Section~\ref{#1}} |
| \newcommand{\See}[1]{\S\ref{#1}} |
| \newcommand{\see}[1]{(see~\See{#1})} |
| \newcommand{\M}[1]{{\rm\emph{#1}}} |
| \newcommand{\T}[1]{{\tt #1}} |
| \newcommand{\Math}[1]{$#1$} |
| \newcommand{\nil}{{\bf nil}} |
| \def\tecgraf{{\sf TeC\kern-.21em\lower.7ex\hbox{Graf}}} |
| |
| \newcommand{\Index}[1]{#1\index{#1@{\lowercase{#1}}}} |
| \newcommand{\IndexVerb}[1]{\T{#1}\index{#1@{\tt #1}}} |
| \newcommand{\IndexEmph}[1]{\emph{#1}\index{#1@{\lowercase{#1}}}} |
| \newcommand{\IndexTM}[1]{\index{#1 event@{``#1'' event}}\index{tag method!#1}} |
| \newcommand{\Def}[1]{\emph{#1}\index{#1}} |
| \newcommand{\IndexAPI}[1]{\T{#1}\DefAPI{#1}} |
| \newcommand{\IndexLIB}[1]{\T{#1}\DefLIB{#1}} |
| \newcommand{\DefLIB}[1]{\index{#1@{\tt #1}}} |
| \newcommand{\DefAPI}[1]{\index{C API!#1@{\tt #1}}} |
| |
| \newcommand{\ff}{$\bullet$\ } |
| |
| \newcommand{\Version}{4.1 (alpha)} |
| |
| % LHF |
| \renewcommand{\ter}[1]{{\rm`{\tt#1}'}} |
| \newcommand{\NOTE}{\par\medskip\noindent\emph{NOTE}: } |
| |
| \makeindex |
| |
| \begin{document} |
| |
| %{=============================================================== |
| \thispagestyle{empty} |
| \pagestyle{empty} |
| |
| { |
| \parindent=0pt |
| \vglue1.5in |
| {\LARGE\bf |
| The Programming Language Lua} |
| \hfill |
| \vskip4pt \hrule height 4pt width \hsize \vskip4pt |
| \hfill |
| Reference Manual for Lua version \Version |
| \\ |
| \null |
| \hfill |
| Last revised on \today |
| \\ |
| \vfill |
| \centering |
| \includegraphics[width=0.7\textwidth]{nolabel.ps} |
| \vfill |
| \vskip4pt \hrule height 2pt width \hsize |
| } |
| |
| \newpage |
| \begin{quotation} |
| \parskip=10pt |
| \footnotesize |
| \null\vfill |
| |
| \noindent |
| Copyright \copyright\ 1994--2001 TeCGraf, PUC-Rio. All rights reserved. |
| |
| \noindent |
| Permission is hereby granted, without written agreement and without license |
| or royalty fees, to use, copy, modify, translate, and distribute |
| this software and its documentation (hereby called the "package") |
| 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 package. |
| |
| \item The origin of this package must not be misrepresented; you must not |
| claim that you wrote the original package. If you use this package 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 package. |
| \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 package 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 package |
| 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 in Brazil. |
| |
| \noindent |
| This implementation contains no third-party code. |
| |
| \noindent |
| Copies of this manual can be obtained at |
| \verb|http://www.lua.org|. |
| |
| \bigskip |
| \noindent |
| The Lua logo was designed by A. Nakonechny. |
| Copyright \copyright\ 1998. All rights reserved. |
| \end{quotation} |
| %}=============================================================== |
| \newpage |
| |
| \title{\Large\bf 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: 2001/07/19 13:36:18 $ $}} |
| |
| \maketitle |
| |
| \pagestyle{plain} |
| \pagenumbering{roman} |
| |
| \begin{abstract} |
| \noindent |
| Lua is a powerful, light-weight programming language |
| designed for extending applications. |
| Lua is 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 Application Program Interface (API) |
| that allows interaction between Lua programs and their host C~programs. |
| \end{abstract} |
| |
| \def\abstractname{Resumo} |
| \begin{abstract} |
| \noindent |
| Lua \'e uma linguagem de programa\c{c}\~ao |
| poderosa e leve, |
| projetada para estender aplica\c{c}\~oes. |
| Lua tamb\'em \'e frequentemente usada como uma linguagem de prop\'osito geral. |
| Lua combina programa\c{c}\~ao procedural |
| (com sintaxe semelhante \`a de Pascal) |
| com |
| poderosas constru\c{c}\~oes para descri\c{c}\~ao de dados, |
| baseadas em tabelas associativas e sem\^antica extens\'\i vel. |
| Lua \'e |
| tipada dinamicamente, |
| interpretada a partir de \emph{bytecodes}, |
| e tem gerenciamento autom\'atico de mem\'oria com coleta de lixo. |
| Essas caracter\'{\i}sticas fazem de Lua uma linguagem ideal para |
| configura\c{c}\~ao, |
| automa\c{c}\~ao (\emph{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{abstract} |
| |
| \newpage |
| \null |
| \newpage |
| \tableofcontents |
| |
| \newpage |
| \setcounter{page}{1} |
| \pagestyle{plain} |
| \pagenumbering{arabic} |
| |
| |
| \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 powerful, light-weight |
| 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 is provided as usual with no guarantees, |
| as stated in its copyright notice. |
| The implementation described in this manual is available |
| at the following URL's: |
| \begin{verbatim} |
| http://www.lua.org |
| ftp://ftp.lua.org |
| \end{verbatim} |
| |
| Like any other reference manual, |
| this document is dry in places. |
| For a discussion of the decisions behind the design of Lua, |
| see the papers below, |
| which are available at the web site above. |
| \begin{itemize} |
| \item |
| R.~Ierusalimschy, L.~H.~de Figueiredo, and W.~Celes. |
| Lua---an extensible extension language. |
| \emph{Software: Practice \& Experience} {\bf 26} \#6 (1996) 635--652. |
| \item |
| L.~H.~de Figueiredo, R.~Ierusalimschy, and W.~Celes. |
| The design and implementation of a language for extending applications. |
| \emph{Proceedings of XXI Brazilian Seminar on Software and Hardware} (1994) 273--283. |
| \item |
| L.~H.~de Figueiredo, R.~Ierusalimschy, and W.~Celes. |
| Lua: an extensible embedded language. |
| \emph{Dr. Dobb's Journal} {\bf 21} \#12 (Dec 1996) 26--33. |
| \end{itemize} |
| |
| \section{Environment and Chunks} |
| |
| All statements in Lua are executed in a \Def{global environment}. |
| This environment 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. |
| If necessary, |
| the host programmer can create multiple independent global |
| environments, and freely switch between them \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} in Lua do not need to be declared. |
| 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 \See{tag-method}). |
| A table is used to keep all global names and values |
| (tables are explained in \See{TypesSec}). |
| |
| The unit of execution of Lua is called a \Def{chunk}. |
| A chunk is simply a sequence of statements, |
| which are executed sequentially. |
| Each statement can be optionally followed by a semicolon: |
| \begin{Produc} |
| \produc{chunk}{\rep{stat \opt{\ter{;}}}} |
| \end{Produc}% |
| Statements are described in \See{stats}. |
| (The notation above is the usual extended BNF, |
| in which |
| \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. |
| The complete syntax of Lua is given on page~\pageref{BNF}.) |
| |
| A chunk may be stored in a file or in a string inside the host program. |
| When a chunk is executed, first it is pre-compiled into bytecodes for |
| a virtual machine, and then the statements are executed in sequential order, |
| by simulating the virtual machine. |
| All modifications a chunk effects on the global environment persist |
| after the chunk ends. |
| |
| Chunks may also be pre-compiled into binary form and stored in files; |
| 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 \emph{dynamically typed language}. |
| This means that |
| 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 \IndexEmph{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. |
| \index{eight-bit clean} |
| Lua is 8-bit clean, |
| and so strings may contain any 8-bit character, |
| including embedded zeros (\verb|'\0'|) \see{lexical}. |
| The \verb|type| function returns a string describing the type |
| of a given value \see{pdf-type}. |
| |
| Functions are considered \emph{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. |
| |
| The type \emph{userdata} is provided to allow |
| arbitrary \Index{C~pointers} to be stored in Lua variables. |
| This type corresponds to a \verb|void*| |
| and has no pre-defined operations in Lua, |
| except 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, graphs, trees, 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 \emph{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 |
| the table itself as the first parameter \see{func-def}. |
| |
| Note that tables are \emph{objects}, and not values. |
| Variables do not 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}. |
| |
| |
| \subsection{Tags} |
| |
| Each type has a \emph{name}, |
| and a numerical identifier, |
| called a \Index{tag}. |
| Tags are mainly used by C code, |
| to avoid the manipulation of strings. |
| Most operations over types, in the C API, |
| require a tag to identify the type. |
| In Lua, all operations over types work |
| both with type names or tags. |
| |
| |
| \subsection{User-defined Types} |
| |
| Lua programs can create new types, |
| called \Index{User-defined Types}. |
| A user-defined type is always based on a base type, |
| either a table or a userdata. |
| Objects of an extended type have an internal structure |
| identical to the corresponding base type, |
| but may have diferent semantics for each operation. |
| |
| The \verb|newtype| function creates a new type \see{pdf-newtype}. |
| Types created by Lua programs are always based upon tables; |
| types created by C can be based upon tables or upon userdata. |
| The \verb|settagmethod| function defines new semantics for |
| the operations of this new type \see{tag-method}. |
| The \verb|settype| function changes the type of a given object |
| \see{pdf-settype}. |
| |
| |
| \section{Garbage Collection}\label{GC} |
| |
| Lua does automatic memory management. |
| To do that, |
| Lua runs a \Index{garbage collector} from time to time. |
| All objects in Lua are subjected to automatic management: |
| tables, userdata, functions, and strings. |
| |
| Lua uses two numbers to control its garbage-collection cycles. |
| One number counts how many bytes of dynamic memory Lua is using, |
| and the other is a threshold. |
| When the number of bytes crosses the threshold, |
| Lua runs the garbage collector, |
| which reclaims the memory of all ``dead'' objects |
| (that is, objects no longer accessible from Lua). |
| The byte counter is corrected, |
| and then the threshold is reset to twice the value of the byte counter. |
| |
| Through the C API, you can consult those numbers, |
| and change the threshold \see{GC-API}. |
| Setting the threshold to zero actually forces an immediate |
| garbage-collection cycle, |
| while setting it to a huge number stops the garbage collector. |
| Using Lua code you have a more limited control of memory management, |
| through functions \verb|gcinfo| and \verb|collectgarbage|. |
| |
| |
| You can set garbage-collector tag methods for user-defined |
| types based on userdata \see{tag-method}. |
| Lua calls those functions when it is about to free a userdata |
| of the corresponding type. |
| Using this facility, you can coordinate Lua's garbage collection |
| with external resourse management |
| (such as closing files or freeing your own memory). |
| |
| |
| \subsection{Weak Tables}\label{weak-table} |
| |
| A \IndexEmph{weak table} is a table whose elements are |
| \IndexEmph{weak references}. |
| A weak reference is ignored by the garbage collector, |
| so that if the only references to an object are weak references, |
| the garbage collector will collect that object. |
| |
| A weak table can have weak keys, weak values, or both. |
| A table with weak keys allows the collection of its keys, |
| but avoids the collection of its values. |
| A table with both weak keys and weak values allow the collection of both. |
| In any case, if either the key or the value is collected, |
| the whole pair is removed from the table. |
| The weakness of a table is controled by the |
| function \verb|weakmode| \see{weakmode}. |
| |
| |
| \section{The Language} |
| |
| This section describes the lexis, the syntax, and the semantics of Lua. |
| |
| |
| \subsection{Lexical Conventions} \label{lexical} |
| |
| \IndexEmph{Identifiers} in Lua can be any string of letters, |
| digits, and underscores, |
| not beginning with a digit. |
| This coincides with the definition of identifiers in most languages, |
| except that |
| 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 \emph{reserved}, |
| and cannot be used as identifiers: |
| \index{reserved words} |
| \begin{verbatim} |
| and break do else elseif |
| end for function global if |
| in local nil not or |
| repeat return then until while |
| \end{verbatim} |
| (\rwd{global} is reserved for future use.) |
| |
| Lua is a case-sensitive language: |
| \T{and} is a reserved word, but \T{And} and \T{\'and} |
| (if the locale permits) are two different, valid identifiers. |
| As a convention, identifiers starting with underscore followed by |
| uppercase letters (such as \verb|_INPUT|) |
| are reserved for internal variables. |
| |
| The following strings denote other \Index{tokens}: |
| \begin{verbatim} |
| + - * / ^ % |
| ~= <= >= < > == = |
| ( ) { } [ ] |
| ; : , . .. ... |
| \end{verbatim} |
| |
| \IndexEmph{Literal strings} |
| can be delimited by matching single or double quotes, |
| and can contain the C-like escape sequences |
| `\verb|\a|' (bell), |
| `\verb|\b|' (backspace), |
| `\verb|\f|' (form feed), |
| `\verb|\n|' (newline), |
| `\verb|\r|' (carriage return), |
| `\verb|\t|' (horizontal tab), |
| `\verb|\v|' (vertical tab), |
| `\verb|\\|' (backslash), |
| `\verb|\"|' (double quote), |
| `\verb|\'|' (single quote), |
| and `\verb|\|\emph{newline}' (that is, a backslash followed by a real newline, |
| which results in a newline in the string). |
| A character in a string may also be specified by its numerical value, |
| through the escape sequence `\verb|\|\emph{ddd}', |
| where \emph{ddd} is a sequence of up to three \emph{decimal} digits. |
| Strings in Lua may contain any 8-bit value, including embedded zeros, |
| which can be specified as `\verb|\000|'. |
| |
| Literal strings can also be delimited by matching \verb|[[| \dots\ \verb|]]|. |
| Literals in this bracketed form may run for several lines, |
| may contain nested \verb|[[| \dots\ \verb|]]| pairs, |
| and do not interpret escape sequences. |
| When the \verb|[[| is immediatly followed by a newline, |
| this newline is not included in the string. |
| 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"]] |
| 4) [[ |
| alo |
| 123"]] |
| \end{verbatim} |
| |
| \IndexEmph{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}. |
| |
| \IndexEmph{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{\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. |
| The format is chosen so that |
| a conversion from number to string then back to number |
| reproduces the original number \emph{exactly}. |
| Thus, |
| the conversion does not necessarily produces nice-looking text for some numbers. |
| For complete control of how numbers are converted to strings, |
| use the \verb|format| function \see{format}. |
| |
| |
| |
| \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; |
| syntactically, a block is equal to a chunk: |
| \begin{Produc} |
| \produc{block}{chunk} |
| \end{Produc}% |
| |
| A block may be explicitly delimited: |
| \begin{Produc} |
| \produc{stat}{\rwd{do} block \rwd{end}} |
| \end{Produc}% |
| Explicit blocks are useful |
| to control the scope of local variables \see{localvar}. |
| Explicit blocks are also sometimes used to |
| add a \rwd{return} or \rwd{break} statement in the middle |
| of another block \see{control}. |
| |
| \subsubsection{\Index{Assignment}} \label{assignment} |
| Lua 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. |
| The elements in both lists are 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. |
| So, the code |
| \begin{verbatim} |
| i = 3 |
| i, a[i] = 4, 20 |
| \end{verbatim} |
| sets \verb|a[3]| to 20, but does not affect \verb|a[4]| |
| because the \verb|i| in \verb|a[i]| is evaluated |
| before it is assigned \verb|4|. |
| |
| Multiple assignment can be used to exchange two values, as in |
| \begin{verbatim} |
| x, y = y, x |
| \end{verbatim} |
| |
| Before the assignment, the list of values is adjusted to |
| the length of the list of variables. |
| If there are more values than are needed, |
| the excess values are thrown away. |
| If there are less values than are needed, |
| the list is extended with as many \nil's as needed. |
| If the list of expressions (\M{explist1}) ends with a function call, |
| all values returned by the function call enter in the list of values, |
| before the 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}{exp \ter{[} exp \ter{]}} |
| \end{Produc}% |
| The first expression (\M{exp}) should result in a table value, |
| from where the field indexed by the expression \M{exp} |
| value gets the assigned value. |
| |
| The syntax \verb|var.NAME| is just syntactic sugar for |
| \verb|var["NAME"]|: |
| \begin{Produc} |
| \produc{var}{exp \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)| and |
| 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 |
| (\verb|setglobal| is in the basic library; |
| \T{settable\_event} is used for explanatory purposes only). |
| |
| \subsubsection{Control Structures}\label{control} |
| The control structures |
| \rwd{if}, \rwd{while}, and \rwd{repeat} have the usual meaning and |
| familiar syntax |
| %(there is also a \rwd{for} statement; see \See{for}): |
| \index{while-do statement} |
| \index{repeat-until statement} |
| \index{if-then-else statement} |
| \begin{Produc} |
| \produc{stat}{\rwd{while} exp \rwd{do} block \rwd{end}} |
| \produc{stat}{\rwd{repeat} block \rwd{until} exp} |
| \produc{stat}{\rwd{if} exp \rwd{then} block |
| \rep{\rwd{elseif} exp \rwd{then} block} |
| \opt{\rwd{else} block} \rwd{end}} |
| \end{Produc}% |
| The \Index{condition expression} \M{exp} of a |
| control structure may return any value. |
| All values different from \nil\ are considered true; |
| only \nil\ is considered false. |
| |
| The \rwd{return} statement is used to return values |
| from a function or from a chunk. |
| \label{return}% |
| \index{return statement}% |
| Because functions or chunks may return more than one value, |
| the syntax for the \rwd{return} statement is |
| \begin{Produc} |
| \produc{stat}{\rwd{return} \opt{explist1}} |
| \end{Produc}% |
| |
| The \rwd{break} statement can be used to terminate the execution of a loop, |
| skipping to the next statement after the loop: |
| \index{break statement} |
| \begin{Produc} |
| \produc{stat}{\rwd{break}} |
| \end{Produc}% |
| A \rwd{break} ends the innermost enclosing loop |
| (\rwd{while}, \rwd{repeat}, or \rwd{for}). |
| |
| \NOTE |
| For syntactic reasons, \rwd{return} and \rwd{break} |
| statements can only be written as the \emph{last} statements of a block. |
| If it is really necessary to \rwd{return} or \rwd{break} in the |
| middle of a block, |
| an explicit inner block can used, |
| as in the idiom `\verb|do return end|', |
| because now \rwd{return} is last statement in the inner block. |
| |
| \subsubsection{For Statement} \label{for}\index{for statement} |
| |
| The \rwd{for} statement has two forms, |
| one for numbers and one for tables. |
| \newpage |
| The numerical \rwd{for} loop has the following syntax: |
| \begin{Produc} |
| \produc{stat}{\rwd{for} name \ter{=} exp \ter{,} exp \opt{\ter{,} exp} |
| \rwd{do} block \rwd{end}} |
| \end{Produc}% |
| A \rwd{for} statement like |
| \begin{verbatim} |
| for var = e1, e2, e3 do block end |
| \end{verbatim} |
| is equivalent to the code: |
| \begin{verbatim} |
| do |
| local var, _limit, _step = tonumber(e1), tonumber(e2), tonumber(e3) |
| if not (var and _limit and _step) then error() end |
| while (_step>0 and var<=_limit) or (_step<=0 and var>=_limit) do |
| block |
| var = var+_step |
| end |
| end |
| \end{verbatim} |
| Note the following: |
| \begin{itemize}\itemsep=0pt |
| \item \verb|_limit| and \verb|_step| are invisible variables. |
| The names are here for explanatory purposes only. |
| \item The behavior is \emph{undefined} if you assign to \verb|var| inside |
| the block. |
| \item If the third expression (the step) is absent, then a step of~1 is used. |
| \item Both the limit and the step are evaluated only once, |
| before the loop starts. |
| \item The variable \verb|var| is local to the statement; |
| you cannot use its value after the \rwd{for} ends. |
| \item You can use \rwd{break} to exit a \rwd{for}. |
| If you need the value of the index, |
| assign it to another variable before breaking. |
| \end{itemize} |
| |
| The table \rwd{for} statement traverses all pairs |
| (index,value) of a given table. |
| It has the following syntax: |
| \begin{Produc} |
| \produc{stat}{\rwd{for} name \ter{,} name \rwd{in} exp |
| \rwd{do} block \rwd{end}} |
| \end{Produc}% |
| A \rwd{for} statement like |
| \begin{verbatim} |
| for index, value in exp do block end |
| \end{verbatim} |
| is equivalent to the code: |
| \begin{verbatim} |
| do |
| local _t = exp |
| local index, value = next(_t, nil) |
| while index do |
| block |
| index, value = next(_t, index) |
| end |
| end |
| \end{verbatim} |
| Note the following: |
| \begin{itemize}\itemsep=0pt |
| \item \verb|_t| is an invisible variable. |
| The name is here for explanatory purposes only. |
| \item The behavior is \emph{undefined} if you assign to \verb|index| inside |
| the block. |
| \item The behavior is \emph{undefined} if you change |
| the table \verb|_t| during the traversal. |
| \item The variables \verb|index| and \verb|value| are local to the statement; |
| you cannot use their values after the \rwd{for} ends. |
| \item You can use \rwd{break} to exit a \rwd{for}. |
| If you need the value of \verb|index| or \verb|value|, |
| assign them to other variables before breaking. |
| \item The order that table elements are traversed is undefined, |
| \emph{even for numerical indices}. |
| If you want to traverse indices in numerical order, |
| use a numerical \rwd{for}. |
| \end{itemize} |
| |
| |
| \subsubsection{Function Calls as Statements} \label{funcstat} |
| Because of possible side-effects, |
| function calls can be executed as statements: |
| \begin{Produc} |
| \produc{stat}{functioncall} |
| \end{Produc}% |
| In this case, all returned values are thrown away. |
| Function calls are explained in \See{functioncall}. |
| |
| \subsubsection{Local Declarations} \label{localvar} |
| \Index{Local variables} may be declared anywhere inside a block. |
| 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. |
| |
| A chunk is also a block, |
| and so local variables can be declared outside any explicit block. |
| |
| The scope of local variables begins \emph{after} |
| the declaration and lasts until the end of the block. |
| Thus, the code |
| \verb|local print=print| |
| creates a local variable called \verb|print| whose |
| initial value is that of the \emph{global} variable of the same name. |
| |
| |
| \subsection{\Index{Expressions}} |
| |
| \subsubsection{\Index{Basic Expressions}} |
| The basic expressions in Lua are |
| \begin{Produc} |
| \produc{exp}{\ter{(} exp \ter{)}} |
| \produc{exp}{\rwd{nil}} |
| \produc{exp}{number} |
| \produc{exp}{literal} |
| \produc{exp}{var} |
| \produc{exp}{upvalue} |
| \produc{exp}{function} |
| \produc{exp}{functioncall} |
| \produc{exp}{tableconstructor} |
| \end{Produc}% |
| |
| An expression enclosed in parentheses always results |
| in only one value. |
| |
| Numbers (numerical constants) and |
| literal strings are explained in \See{lexical}; |
| variables are explained in \See{assignment}; |
| upvalues are explained in \See{upvalue}; |
| function definitions are explained in \See{func-def}; |
| function calls are explained in \See{functioncall}. |
| Table constructors are explained in \See{tableconstructor}. |
| |
| An access to a global variable \verb|x| is equivalent to a |
| call \verb|getglobal("x")| and |
| 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 |
| (\verb|getglobal| is in the basic library; |
| \T{gettable\_event} is used for explanatory purposes only). |
| |
| |
| \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} |
| The \Index{relational operators} in Lua are |
| \begin{verbatim} |
| == ~= < > <= >= |
| \end{verbatim} |
| These operators return \nil\ as false and a value different from \nil\ as true. |
| |
| Equality (\verb|==|) 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 \emph{same} table. |
| Every time you create a new table (or userdata, or function) this |
| new value is different from any previously existing value. |
| The operator \verb|~=| is exactly the negation of equality (\verb|==|). |
| |
| \NOTE |
| The conversion rules of \See{coercion} |
| \emph{do not} apply to equality comparisons. |
| Thus, \verb|"0"==0| evaluates to \emph{false}, |
| and \verb|t[0]| and \verb|t["0"]| denote different |
| entries in a table. |
| \medskip |
| |
| The order operators work as follows. |
| If both arguments are numbers, then they are compared as such. |
| Otherwise, if both arguments are strings, |
| then their values are compared using lexicographical order. |
| Otherwise, the ``lt'' tag method is called \see{tag-method}. |
| |
| \subsubsection{Logical Operators} |
| The \Index{logical operators} in Lua are |
| \index{and}\index{or}\index{not} |
| \begin{verbatim} |
| and or not |
| \end{verbatim} |
| Like the control structures, all logical operators |
| consider \nil\ as false and anything else as true. |
| |
| The conjunction operator \verb|and| returns \nil\ if its first argument is \nil; |
| otherwise, it returns its second argument. |
| The disjunction 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 if necessary. |
| |
| There are two useful Lua idioms that use logical operators. |
| The first idiom is |
| \begin{verbatim} |
| x = x or v |
| \end{verbatim} |
| which is equivalent to |
| \begin{verbatim} |
| if x == nil then x = v end |
| \end{verbatim} |
| This idiom sets \verb|x| to a default value \verb|v| when \verb|x| is not set. |
| |
| The second idiom is |
| \begin{verbatim} |
| x = a and b or c |
| \end{verbatim} |
| which should be read as \verb|x = (a and b) or c|. |
| This idiom is equivalent to |
| \begin{verbatim} |
| if a then x = b else x = c end |
| \end{verbatim} |
| provided that \verb|b| is not \nil. |
| |
| \subsubsection{Concatenation} \label{concat} |
| The string \Index{concatenation} operator in Lua is |
| denoted by two dots (`\IndexVerb{..}'). |
| If both operands are strings or numbers, then 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} in Lua 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. |
| \NOTE |
| The pre-compiler may rearrange the order of evaluation of |
| associative or commutative operators, |
| as long as these optimizations do not change normal results. |
| However, these optimizations may change some results |
| if you define non-associative (or non-commutative) |
| tag methods for these operators. |
| |
| \subsubsection{Table Constructors} \label{tableconstructor} |
| Table \Index{constructors} are expressions that create tables; |
| every time a constructor is evaluated, a new table is created. |
| Constructors can be used to create empty tables, |
| or to create a table and initialize some of its 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{explist1 \opt{\ter{,}}}} |
| \produc{ffieldlist}{\opt{ffieldlist1}} |
| \end{Produc}% |
| |
| The form \emph{explist1} is used to initialize lists. |
| 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} |
| If the last expression in the list is a function call, |
| all values returned by the call enter the list \see{functioncall}. |
| |
| 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-colon. |
| 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} in Lua has the following syntax: |
| \begin{Produc} |
| \produc{functioncall}{exp args} |
| \end{Produc}% |
| First, \M{exp} and \M{args} are evaluated. |
| If the value of \M{exp} 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{exp}, |
| followed by the original call arguments |
| \see{tag-method}. |
| |
| The form |
| \begin{Produc} |
| \produc{functioncall}{exp \ter{:} name args} |
| \end{Produc}% |
| can be used to call ``methods''. |
| A call \verb|v:name(...)| |
| is syntactic sugar for \verb|v.name(v, ...)|, |
| except that \verb|v| is evaluated only once. |
| |
| Arguments have the following syntax: |
| \begin{Produc} |
| \produc{args}{\ter{(} \opt{explist1} \ter{)}} |
| \produc{explist1}{\rep{exp \ter{,}} exp} |
| \produc{args}{tableconstructor} |
| \produc{args}{literal} |
| \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 argument 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 argument 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 they are 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 inside another expression, |
| or in the middle of a list of expressions, |
| then its return list is adjusted to~1, |
| thus discarding all returned values but the first one. |
| If the function is called as the last element of a list of expressions, |
| then no adjustment is made. |
| Here are some examples: |
| \begin{verbatim} |
| f() -- adjusted to 0 results |
| g(f(), x) -- f() is adjusted to 1 result |
| g(x, f()) -- g gets x plus all values returned by f() |
| a,b,c = f(), x -- f() is adjusted to 1 result (and c gets nil) |
| a,b,c = x, f() -- f() is adjusted to 2 |
| a,b,c = f() -- f() is adjusted to 3 |
| return f() -- returns all values returned by f() |
| return x,y,f() -- returns x, y, and all values returned by f() |
| {f()} -- creates a list with all values returned by f() |
| {f(), nil} -- f() is adjusted to 1 result |
| \end{verbatim} |
| |
| If you embrace a function call in parentheses, |
| then it is adjusted to return exactly one value: |
| \begin{verbatim} |
| return x, y, (f()) -- returns x, y, and one value from f() |
| {(f())} -- create a table with exactly one element |
| \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 \rep{\ter{.} name} \opt{\ter{:} name}} |
| \end{Produc}% |
| The statement |
| \begin{verbatim} |
| function f () ... end |
| \end{verbatim} |
| is just syntactic sugar for |
| \begin{verbatim} |
| f = function () ... end |
| \end{verbatim} |
| and the statement |
| \begin{verbatim} |
| function v.c.f () ... end |
| \end{verbatim} |
| is syntactic sugar for |
| \begin{verbatim} |
| v.c.f = function () ... end |
| \end{verbatim} |
| |
| A function definition is an executable expression, |
| whose value has type \emph{function}. |
| When Lua pre-compiles a chunk, |
| all its function bodies are pre-compiled too. |
| Then, whenever Lua executes the function definition, |
| its upvalues are fixed \see{upvalue}, |
| and the function is \emph{instantiated} (or \emph{closed}). |
| This function instance (or \emph{closure}) |
| is the final value of the expression. |
| Different instances of the same function |
| may have different upvalues. |
| |
| Parameters act as local variables, |
| initialized with the argument values: |
| \begin{Produc} |
| \produc{parlist1}{\ter{\ldots}} |
| \produc{parlist1}{name \rep{\ter{,} name} \opt{\ter{,} \ter{\ldots}}} |
| \end{Produc}% |
| \label{vararg}% |
| When a function is called, |
| the list of \Index{arguments} is adjusted to |
| the length of the list of parameters, |
| unless the function is a \Def{vararg function}, |
| which is |
| indicated by three dots (`\verb|...|') at the end of its parameter list. |
| A vararg function does not adjust its argument list; |
| instead, it collects all extra arguments into an implicit parameter, |
| called \IndexLIB{arg}. |
| The value of \verb|arg| is a table, |
| with a field~\verb|n| whose value is the number of extra arguments, |
| and the extra arguments at positions 1,~2,~\ldots,~\verb|n|. |
| |
| As an example, consider the following definitions: |
| \begin{verbatim} |
| function f(a, b) end |
| function g(a, b, ...) end |
| function r() return 1,2,3 end |
| \end{verbatim} |
| Then, we have the following mapping from arguments to parameters: |
| \begin{verbatim} |
| CALL PARAMETERS |
| |
| f(3) a=3, b=nil |
| f(3, 4) a=3, b=4 |
| f(3, 4, 5) a=3, b=4 |
| f(r(), 10) a=1, b=10 |
| f(r()) a=1, b=2 |
| |
| g(3) a=3, b=nil, arg={n=0} |
| g(3, 4) a=3, b=4, arg={n=0} |
| g(3, 4, 5, 8) a=3, b=4, arg={5, 8; n=2} |
| g(5, r()) a=5, b=1, arg={2, 3; n=2} |
| \end{verbatim} |
| |
| Results are returned using the \rwd{return} statement \see{return}. |
| If control reaches the end of a function |
| without encountering a \rwd{return} statement, |
| then the function returns with no results. |
| |
| The \emph{colon} syntax |
| is used for defining \IndexEmph{methods}, |
| that is, functions that have an implicit extra parameter \IndexVerb{self}. |
| |
| The statement |
| \begin{verbatim} |
| function v.c:f (...) ... end |
| \end{verbatim} |
| is just syntactic sugar for |
| \begin{verbatim} |
| v.c.f = function (self, ...) ... end |
| \end{verbatim} |
| Note that the function gets an extra formal parameter called \verb|self|. |
| |
| |
| \subsection{Visibility and Upvalues} \label{upvalue} |
| \index{visibility}\index{upvalues} |
| |
| A function body may refer to its own local variables |
| (which include its parameters) and to global variables, |
| as long as they are not \emph{shadowed} by local |
| variables with the same name 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}, |
| whose syntax is |
| \begin{Produc} |
| \produc{upvalue}{\ter{\%} name} |
| \end{Produc}% |
| |
| An upvalue is somewhat similar to a variable expression, |
| but whose value is \emph{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, |
| that is, |
| global variables and local variables |
| from the \emph{immediately enclosing} function. |
| Note that when the upvalue is a table, |
| only the \emph{reference} to that table |
| (which is the value of the upvalue) is frozen; |
| the table contents can be changed at will. |
| Using table values as upvalues is a technique for having |
| writable but private state attached to functions. |
| |
| Here are some examples: |
| \begin{verbatim} |
| a,b,c = 1,2,3 -- global variables |
| local d |
| function f (x) |
| local b = {} -- x and b are local to f; b shadows the global b |
| 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 function |
| p = %b -- OK, access frozen value of `b' (local to `f') |
| %b = 3 -- ERROR: cannot change an upvalue |
| %b.x = 3 -- OK, change the table contents |
| p = %c -- OK, access frozen value of global `c' |
| p = %y -- ERROR: `y' is not visible where `g' is defined |
| p = %d -- ERROR: `d' is not visible where `g' is defined |
| end -- g |
| end -- f |
| \end{verbatim} |
| |
| |
| \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, |
| the function \verb|_ERRORMESSAGE| is called \DefLIB{_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_call|) |
| is terminated, returning an error condition. |
| |
| Memory allocation errors are an exception to the previous rule. |
| When memory allocation fails, Lua may not be able to execute the |
| \verb|_ERRORMESSAGE| function. |
| So, for this kind of error, Lua does not call |
| the \verb|_ERRORMESSAGE| function; |
| instead, the corresponding function from the library |
| returns immediately with a special error code (\verb|LUA_ERRMEM|). |
| This and other error codes are defined in \verb|lua.h|; |
| \See{luado}. |
| |
| The only argument to \verb|_ERRORMESSAGE| is a string |
| describing the error. |
| The default definition for |
| this function calls \verb|_ALERT|, \DefLIB{_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 a call stack traceback. |
| |
| Lua code can explicitly generate an error by calling the |
| function \verb|error| \see{pdf-error}. |
| Lua code can ``catch'' an error using the function |
| \verb|call| \see{pdf-call}. |
| |
| |
| \subsection{Tag Methods} \label{tag-method}\index{tag method} |
| |
| A tag method is a programmer-defined function |
| that defines how Lua operations act over user-defined types |
| (and, sometimes, over basic types as well). |
| An \Def{event} is any operation that may invoke a tag method. |
| |
| Lua selects the tag method called for any specific event |
| according to the types of the values involved |
| in the event \see{TypesSec}. |
| The function \IndexLIB{settagmethod} changes the tag method |
| associated with a given pair \M{(type, event)}. |
| Its first parameter is the type (its name or its 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. |
| A companion function \IndexLIB{gettagmethod} |
| receives a type 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. |
| Each event-handler function shows how a tag method is called, |
| its arguments (that is, its signature), |
| its results, |
| and the default behavior in the absence of a tag method. |
| The code shown here in Lua 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|rawget|, \verb|tonumber|, \verb|call|, etc.) |
| are described in \See{predefined}. |
| |
| \begin{description} |
| |
| \item[``add'':]\IndexTM{add} |
| called when a \verb|+| operation is applied to non-numerical operands. |
| |
| The function \verb|getbinmethod| below defines how Lua chooses a tag method |
| for a binary operation. |
| First, Lua tries the first operand. |
| If its type 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} |
| Using this function, |
| the tag method for the ``add'' event is |
| \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 |
| return tm(op1, op2) |
| else -- no tag method available: default behavior |
| error("unexpected type at arithmetic operation") |
| end |
| end |
| end |
| \end{verbatim} |
| |
| \item[``sub'':]\IndexTM{sub} |
| called when a \verb|-| operation is applied to non-numerical operands. |
| Behavior similar to the ``add'' event. |
| |
| \item[``mul'':]\IndexTM{mul} |
| called when a \verb|*| operation is applied to non-numerical operands. |
| Behavior similar to the ``add'' event. |
| |
| \item[``div'':]\IndexTM{div} |
| called when a \verb|/| operation is applied to non-numerical operands. |
| Behavior similar to the ``add'' event. |
| |
| \item[``pow'':]\IndexTM{pow} |
| called when a \verb|^| operation (exponentiation) is applied, |
| even for numerical operands. |
| \begin{verbatim} |
| function pow_event (op1, op2) |
| local tm = getbinmethod(op1, op2, "pow") |
| if tm then |
| -- call the method with both operands |
| return tm(op1, op2) |
| else -- no tag method available: default behavior |
| error("unexpected type at arithmetic operation") |
| end |
| end |
| \end{verbatim} |
| |
| \item[``unm'':]\IndexTM{unm} |
| called when a 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 and nil |
| return tm(op, nil) |
| else -- no tag method available: default behavior |
| error("unexpected type at arithmetic operation") |
| end |
| end |
| end |
| \end{verbatim} |
| |
| \item[``lt'':]\IndexTM{lt} |
| called when an order operation is applied to non-numerical |
| or non-string operands. |
| It corresponds to the \verb|<| operator. |
| \begin{verbatim} |
| function lt_event (op1, op2) |
| if type(op1) == "number" and type(op2) == "number" then |
| return op1 < op2 -- numeric comparison |
| elseif type(op1) == "string" and type(op2) == "string" then |
| return op1 < op2 -- lexicographic comparison |
| else |
| local tm = getbinmethod(op1, op2, "lt") |
| if tm then |
| return tm(op1, op2) |
| else |
| error("unexpected type at comparison"); |
| end |
| end |
| end |
| \end{verbatim} |
| The other order operators use the \verb|"lt"| tag method |
| according to the usual equivalences: |
| \begin{verbatim} |
| a>b <=> b<a |
| a<=b <=> not (b<a) |
| a>=b <=> not (a<b) |
| \end{verbatim} |
| |
| \item[``concat'':]\IndexTM{concatenation} |
| 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) |
| else |
| error("unexpected type for concatenation") |
| end |
| end |
| end |
| \end{verbatim} |
| |
| \item[``index'':]\IndexTM{index} |
| called when Lua tries to retrieve the value of an index |
| not present in a table. |
| See the ``gettable'' event for its semantics. |
| |
| \item[``getglobal'':]\IndexTM{getglobal} |
| called whenever Lua needs the value of a global variable. |
| This method can only be set for \nil\ and for user-defined types. |
| Note that |
| the tag is that of the \emph{current value} of the global variable. |
| \begin{verbatim} |
| function getglobal (varname) |
| -- access the table of globals |
| local value = rawget(globals(), 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 defined in the basic library~\see{predefined}. |
| \NOTE |
| \verb|getglobal| is ``overloaded'' here. |
| It is the name both of the event and |
| of the function that handles the event |
| to call an eventual tag method |
| (called \verb|tm| in the above code). |
| |
| \item[``setglobal'':]\IndexTM{setglobal} |
| called whenever Lua assigns to a global variable. |
| This method cannot be set for numbers, strings, and tables and |
| userdata with the default tag. |
| \begin{verbatim} |
| function setglobal (varname, newvalue) |
| local oldvalue = rawget(globals(), varname) |
| local tm = gettagmethod(tag(oldvalue), "setglobal") |
| if not tm then |
| rawset(globals(), varname, newvalue) |
| else |
| tm(varname, oldvalue, newvalue) |
| end |
| end |
| \end{verbatim} |
| The function \verb|setglobal| is defined in the basic library~\see{predefined}. |
| \NOTE |
| See previous note. |
| |
| \item[``gettable'':]\IndexTM{gettable} |
| called whenever Lua accesses an indexed variable. |
| This method cannot be set for tables with the 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 = rawget(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'':]\IndexTM{settable} |
| called when Lua assigns to an indexed variable. |
| This method cannot be set for tables with the 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 |
| rawset(table, index, value) |
| end |
| end |
| \end{verbatim} |
| |
| \item[``function'':]\IndexTM{function} |
| called when Lua tries to call a non-function value. |
| \begin{verbatim} |
| function function_event (func, ...) |
| if type(func) == "function" then |
| return call(func, arg) |
| else |
| local tm = gettagmethod(tag(func), "function") |
| if tm then |
| for i=arg.n,1,-1 do |
| arg[i+1] = arg[i] |
| end |
| arg.n = arg.n+1 |
| arg[1] = func |
| return call(tm, arg) |
| else |
| error("call expression not a function") |
| end |
| end |
| end |
| \end{verbatim} |
| |
| \item[``gc'':]\IndexTM{gc} |
| called when Lua is ``garbage collecting'' a userdata. |
| This tag method can be set only from~C, |
| and cannot be set for a userdata with the default tag. |
| For each userdata to be collected, |
| Lua does the equivalent of the following function: |
| \begin{verbatim} |
| function gc_event (obj) |
| local tm = gettagmethod(tag(obj), "gc") |
| if tm then |
| tm(obj) |
| end |
| end |
| \end{verbatim} |
| In a garbage-collection cycle, |
| the tag methods for userdata are called in \emph{reverse} |
| order of type creation, |
| that is, the first tag methods to be called are those associated |
| with the last type created in the program. |
| Moreover, at the end of the cycle, |
| Lua does the equivalent of the call \verb|gc_event(nil)|. |
| |
| \end{description} |
| |
| |
| |
| |
| \section{The Application Program Interface} |
| \index{C API} |
| This section describes the API for Lua, that is, |
| the set of C~functions available to the host program to communicate |
| with Lua. |
| All API functions and related types and constants |
| are declared in the header file \verb|lua.h|. |
| |
| \NOTE |
| Even when we use the term ``function'', |
| any facility in the API may be provided as a \emph{macro} instead. |
| All such macros use each of its arguments exactly once |
| (except for the first argument, which is always a state), |
| and so do not generate hidden side-effects. |
| |
| |
| \subsection{States} \label{mangstate} |
| |
| The Lua library is fully reentrant: |
| it does not have any global variables. |
| \index{state} |
| The whole state of the Lua interpreter |
| (global variables, stack, tag methods, etc.) |
| is stored in a dynamically allocated structure of type \verb|lua_State|; |
| \DefAPI{lua_State} |
| this state must be passed as the first argument to |
| every function in the library (except \verb|lua_open| below). |
| |
| Before calling any API function, |
| you must create a state by calling |
| \begin{verbatim} |
| lua_State *lua_open (int stacksize); |
| \end{verbatim} |
| \DefAPI{lua_open} |
| The sole argument to this function is the stack size for the interpreter. |
| (Each function call needs one stack position for each argument, local variable, |
| and temporary value, plus one position for book-keeping. |
| The stack must also have some 20 extra positions available. |
| For very small implementations, without recursive functions, |
| a stack size of~100 should be enough.) |
| If \verb|stacksize| is zero, |
| then a default size of~1024 is used. |
| |
| To release a state created with \verb|lua_open|, call |
| \begin{verbatim} |
| void lua_close (lua_State *L); |
| \end{verbatim} |
| \DefAPI{lua_close} |
| This function destroys all objects in the given Lua environment |
| (calling the corresponding garbage-collection tag methods, if any) |
| and frees all dynamic memory used by that state. |
| Usually, you do not need to call this function, |
| because all resources are naturally released when your program ends. |
| On the other hand, |
| long-running programs --- |
| like a daemon or a web server --- |
| might need to release states as soon as they are not needed, |
| to avoid growing too big. |
| |
| With the exception of \verb|lua_open|, |
| all functions in the Lua API need a state as their first argument. |
| |
| |
| \subsection{Threads} |
| |
| Lua offers a partial support for multiple threads. |
| If you have a C library that offers multi-threading or co-routines, |
| Lua can cooperate with it to implement the equivalent facility in Lua. |
| The following function creates a new ``thread'' in Lua: |
| \begin{verbatim} |
| lua_State *lua_newthread (lua_State *L, int stacksize); |
| \end{verbatim} |
| \DefAPI{lua_newthread} |
| The new state returned by this function shares with the original state |
| all global environment (such as tables, tag methods, etc.), |
| but has an independent stack. |
| (The use of these multiple stacks must be ``syncronized'' with C. |
| How to explain that? TO BE WRITTEN.) |
| |
| Each thread has an independent table for global variables. |
| When you create a thread this table is the same as of the given state, |
| but you can change each one independently. |
| |
| You destroy threads with \verb|lua_close|. |
| When you destroy the last thread of a global state, |
| the state itself is also destroyed. |
| |
| |
| \subsection{The Stack and Indices} |
| |
| Lua uses a \emph{stack} to pass values to and from C. |
| Each element in this stack represents a Lua value |
| (nil, number, string, etc.). |
| |
| For convenience, |
| most query operations in the API do not follow a strict stack discipline. |
| Instead, they can refer to any element in the stack by using an \emph{index}: |
| A positive index represents an \emph{absolute} stack position |
| (starting at~1, not 0 as in C); |
| a negative index represents an \emph{offset} from the top of the stack. |
| More specifically, if the stack has \M{n} elements, |
| index~1 represents the first element |
| (that is, the first element pushed onto the stack), |
| and |
| index~\M{n} represents the last element; |
| index~\Math{-1} also represents the last element |
| (that is, the element at the top), |
| and index \Math{-n} represents the first element. |
| We say that an index is \emph{valid} |
| if it lies between~1 and the stack top |
| (that is, if \verb|1 <= abs(index) <= top|). |
| \index{stack index} \index{valid index} |
| |
| At any time, you can get the index of the top element by calling |
| \begin{verbatim} |
| int lua_gettop (lua_State *L); |
| \end{verbatim} |
| \DefAPI{lua_gettop} |
| Because indices start at~1, |
| the result of \verb|lua_gettop| is equal to the number of elements in the stack |
| (and so 0~means an empty stack). |
| |
| When you interact with Lua API, |
| \emph{you are responsible for controlling stack overflow}. |
| The function |
| \begin{verbatim} |
| int lua_stackspace (lua_State *L); |
| \end{verbatim} |
| \DefAPI{lua_stackspace} |
| returns the number of stack positions still available. |
| Whenever Lua calls C, \DefAPI{LUA_MINSTACK} |
| it ensures that |
| at least \verb|LUA_MINSTACK| positions are still available. |
| \verb|LUA_MINSTACK| is defined in \verb|lua.h| and is at least~16, |
| so that usually you have to worry about stack space only |
| when your code has loops pushing elements onto the stack. |
| |
| Most query functions accept as indices any value inside the |
| available stack space. |
| Such indices are called \emph{acceptable indices}. |
| More formally, we can define an \IndexEmph{acceptable index} |
| as |
| \begin{verbatim} |
| (index < 0 && abs(index) <= top) || (index > 0 && index <= top + stackspace) |
| \end{verbatim} |
| Note that 0 is not an acceptable index. |
| |
| \subsection{Stack Manipulation} |
| The API offers the following functions for basic stack manipulation: |
| \begin{verbatim} |
| void lua_settop (lua_State *L, int index); |
| void lua_pushvalue (lua_State *L, int index); |
| void lua_remove (lua_State *L, int index); |
| void lua_insert (lua_State *L, int index); |
| \end{verbatim} |
| \DefAPI{lua_settop}\DefAPI{lua_pushvalue} |
| \DefAPI{lua_remove}\DefAPI{lua_insert} |
| |
| \verb|lua_settop| accepts any acceptable index, |
| or 0, |
| and sets the stack top to that index. |
| If the new top is larger than the old one, |
| then the new elements are filled with \nil. |
| If \verb|index| is 0, then all stack elements are removed. |
| A useful macro defined in the API is |
| \begin{verbatim} |
| #define lua_pop(L,n) lua_settop(L, -(n)-1) |
| \end{verbatim} |
| \DefAPI{lua_pop} |
| which pops \verb|n| elements from the stack. |
| |
| \verb|lua_pushvalue| pushes onto the stack a \emph{copy} of the element |
| at the given index. |
| \verb|lua_remove| removes the element at the given position, |
| shifting down the elements on top of that position to fill in the gap. |
| \verb|lua_insert| moves the top element into the given position, |
| shifting up the elements on top of that position to open space. |
| These functions accept only valid indices. |
| As an example, if the stack starts as \verb|10 20 30 40 50| |
| (from bottom to top), |
| then |
| \begin{verbatim} |
| lua_pushvalue(L, 3) --> 10 20 30 40 50 30 |
| lua_pushvalue(L, -1) --> 10 20 30 40 50 30 30 |
| lua_remove(L, -3) --> 10 20 30 40 30 30 |
| lua_remove(L, 6) --> 10 20 30 40 30 |
| lua_insert(L, 1) --> 30 10 20 30 40 |
| lua_insert(L, -1) --> 30 10 20 30 40 (no effect) |
| lua_settop(L, -3) --> 30 10 20 |
| lua_settop(L, 6) --> 30 10 20 nil nil nil |
| \end{verbatim} |
| |
| |
| \subsection{Querying the Stack} |
| |
| To check the type of a stack element, |
| the following functions are available: |
| \begin{verbatim} |
| int lua_tag (lua_State *L, int index); |
| int lua_rawtag (lua_State *L, int index); |
| const char *lua_type (lua_State *L, int index); |
| int lua_isnil (lua_State *L, int index); |
| int lua_isnumber (lua_State *L, int index); |
| int lua_isstring (lua_State *L, int index); |
| int lua_istable (lua_State *L, int index); |
| int lua_isfunction (lua_State *L, int index); |
| int lua_iscfunction (lua_State *L, int index); |
| int lua_isuserdata (lua_State *L, int index); |
| \end{verbatim} |
| \DefAPI{lua_type}\DefAPI{lua_tag} |
| \DefAPI{lua_isnil}\DefAPI{lua_isnumber}\DefAPI{lua_isstring} |
| \DefAPI{lua_istable} |
| \DefAPI{lua_isfunction}\DefAPI{lua_iscfunction}\DefAPI{lua_isuserdata} |
| These functions can be called with any acceptable index. |
| |
| \verb|lua_tag| returns the tag of a value in the stack, |
| or \verb|LUA_TNONE| for a non-valid index |
| (that is, if that stack position is ``empty''). |
| The tags for the basic types are the following constants: |
| \verb|LUA_TNIL|, |
| \verb|LUA_TNUMBER|, |
| \verb|LUA_TSTRING|, |
| \verb|LUA_TTABLE|, |
| \verb|LUA_TFUNCTION|, |
| \verb|LUA_TUSERDATA|. |
| \verb|lua_rawtag| is similar to \verb|lua_tag|, |
| but it returns the tag of the basic (raw) type of a value. |
| \verb|lua_type| is similar to \verb|lua_tag|, |
| but it returns the type name of the given value. |
| |
| The \verb|lua_is*| functions return~1 if the object is compatible |
| with the given type, and 0 otherwise. |
| They always return 0 for a non-valid index. |
| \verb|lua_isnumber| accepts numbers and numerical strings, |
| \verb|lua_isstring| accepts strings and numbers \see{coercion}, |
| and \verb|lua_isfunction| accepts both Lua functions and C~functions. |
| To distinguish between Lua functions and C~functions, |
| you should use \verb|lua_iscfunction|. |
| To distinguish between numbers and numerical strings, |
| you can use \verb|lua_rawtag| (or \verb|lua_tag|). |
| |
| The API also has functions to compare two values in the stack: |
| \begin{verbatim} |
| int lua_equal (lua_State *L, int index1, int index2); |
| int lua_lessthan (lua_State *L, int index1, int index2); |
| \end{verbatim} |
| \DefAPI{lua_equal} \DefAPI{lua_lessthan} |
| These functions are equivalent to their counterparts in Lua. |
| Specifically, \verb|lua_lessthan| is equivalent to the \verb|lt_event| |
| described in \See{tag-method}. |
| Both functions return 0 if any of the indices are non-valid. |
| |
| To translate a value in the stack to a specific C~type, |
| you can use the following conversion functions: |
| \begin{verbatim} |
| double lua_tonumber (lua_State *L, int index); |
| const char *lua_tostring (lua_State *L, int index); |
| size_t lua_strlen (lua_State *L, int index); |
| lua_CFunction lua_tocfunction (lua_State *L, int index); |
| void *lua_touserdata (lua_State *L, int index); |
| \end{verbatim} |
| \DefAPI{lua_tonumber}\DefAPI{lua_tostring}\DefAPI{lua_strlen} |
| \DefAPI{lua_tocfunction}\DefAPI{lua_touserdata} |
| These functions can be called with any acceptable index. |
| When called with a non-valid index, |
| they act as if the given value had an incorrect type. |
| |
| \verb|lua_tonumber| converts the value at the given index |
| to a floating-point number. |
| This value must be a number or a string convertible to number |
| \see{coercion}; otherwise, \verb|lua_tonumber| returns~0. |
| |
| \verb|lua_tostring| converts a Lua value to a string |
| (\verb|const char*|). |
| This value must be a string or a number; |
| otherwise, the function returns \verb|NULL|. |
| If the value is a number, |
| \verb|lua_tostring| also changes the |
| actual value in the stack to a string. |
| This function returns a pointer to a string inside the Lua environment. |
| This pointer is always fully aligned. |
| The strings always have a zero (\verb|'\0'|) |
| after their last character (as 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 its actual length. |
| Because Lua has garbage collection, |
| there is no guarantee that the pointer returned by \verb|lua_tostring| |
| will be valid after the respective value is removed from the stack. |
| |
| \verb|lua_tocfunction| converts a value in the stack to a C~function. |
| This value must be a C~function; |
| otherwise, \verb|lua_tocfunction| returns \verb|NULL|. |
| The type \verb|lua_CFunction| is explained in \See{LuacallC}. |
| |
| \verb|lua_touserdata| converts a value to \verb|void*|. |
| This value must have type \emph{userdata}; |
| otherwise, \verb|lua_touserdata| returns \verb|NULL|. |
| |
| |
| |
| \subsection{Pushing values onto the Stack} |
| |
| The API has the following functions to |
| push C~values onto the stack: |
| \begin{verbatim} |
| void lua_pushnumber (lua_State *L, double n); |
| void lua_pushlstring (lua_State *L, const char *s, size_t len); |
| void lua_pushstring (lua_State *L, const char *s); |
| void lua_pushnil (lua_State *L); |
| void lua_pushcfunction (lua_State *L, lua_CFunction f); |
| \end{verbatim} |
| \DefAPI{lua_pushnumber}\DefAPI{lua_pushlstring}\DefAPI{lua_pushstring} |
| \DefAPI{lua_pushcfunction}\DefAPI{lua_pushusertag} |
| \DefAPI{lua_pushnil}\label{pushing} |
| These functions receive a C~value, |
| convert it to a corresponding Lua value, |
| and push the result onto the stack. |
| In particular, \verb|lua_pushlstring| and \verb|lua_pushstring| |
| make an \emph{internal copy} of the given string. |
| \verb|lua_pushstring| can only be used to push proper C~strings |
| (that is, strings that end with a zero and do not contain embedded zeros); |
| otherwise you should use the more general \verb|lua_pushlstring|, |
| which accepts an explicit size. |
| |
| |
| \subsection{Garbage Collection API}\label{GC-API} |
| |
| Lua uses two numbers to control its garbage collection \see{GC}. |
| You can access the current values of these two numbers through the |
| following functions: |
| \begin{verbatim} |
| int lua_getgccount (lua_State *L); |
| int lua_getgcthreshold (lua_State *L); |
| \end{verbatim} |
| \DefAPI{lua_getgcthreshold} \DefAPI{lua_getgccount} |
| Both return their respective values in Kbytes. |
| You can change the threshold value with |
| \begin{verbatim} |
| void lua_setgcthreshold (lua_State *L, int newthreshold); |
| \end{verbatim} |
| \DefAPI{lua_setgcthreshold} |
| Again, the \verb|newthreshold| value is given in Kbytes. |
| When you call this function, |
| Lua sets the new threshold and checks it against the byte counter. |
| If the new threshold is smaller than the byte counter, |
| then Lua immediately runs the garbage collector; |
| after the collection, |
| a new threshold is set according to the previous rule. |
| |
| If you want to change the adaptive behavior of the garbage collector, |
| you can use the garbage-collection tag method for \nil\ % |
| to set your own threshold |
| (the tag method is called after Lua resets the threshold). |
| |
| |
| \subsection{Userdata} |
| |
| You can create new userdata with the following functions: |
| \begin{verbatim} |
| void *lua_newuserdata (lua_State *L, size_t size); |
| void lua_newuserdatabox (lua_State *L, void *u); |
| \end{verbatim} |
| \DefAPI{lua_newuserdata}\DefAPI{lua_newuserdatabox} |
| The first function, \verb|lua_newuserdata|, |
| allocates a new block of memory with the given size, |
| pushes on the stack a new userdata with the block address, |
| and returns this address. |
| The second function, \verb|lua_newuserdatabox|, |
| gets a pointer and pushes on the stack a new userdata |
| with that pointer. |
| In this case, Lua does not care about the pointer's value. |
| By default, all userdata are created with a standard tag, |
| \verb|LUA_TUSERDATA|. |
| |
| When Lua collects a userdata created by \verb|lua_newuserdata|, |
| it automatically frees its corresponding memory. |
| On the other hand, Lua never uses pointers in |
| userdata created with \verb|lua_newuserdatabox|; |
| it is up to you to free any associated memory, |
| setting a garbage-collection tag method, for instance. |
| |
| |
| \subsection{Types and Tags} |
| |
| User-defined types are created with the function |
| \begin{verbatim} |
| int lua_newtype (lua_State *L, const char *name, int basictype); |
| \end{verbatim} |
| \DefAPI{lua_newtype} |
| \verb|name| is the name of the new type, |
| and \verb|basictype| is the basic type for objects with this new type, |
| which can be \verb|LUA_TUSERDATA| or \verb|LUA_TTABLE|. |
| |
| The function \verb|lua_settag| changes the tag (i.e., the type) of |
| the object on top of the stack (without popping it): |
| \begin{verbatim} |
| void lua_settag (lua_State *L, int tag); |
| \end{verbatim} |
| \DefAPI{lua_settag} |
| The given \verb|tag| must be a user-defined tag, |
| and the basic type of the object must be the basic type for that |
| tag (userdata or table). |
| |
| The following functions allow you to translate a tag to a type name |
| and a type name to a tag: |
| \begin{verbatim} |
| int lua_name2tag (lua_State *L, const char *name); |
| const char *lua_tag2name (lua_State *L, int tag); |
| \end{verbatim} |
| \DefAPI{lua_name2tag}\DefAPI{lua_tag2name} |
| |
| |
| \subsection{Executing Lua Code}\label{luado} |
| A host program can execute Lua chunks written in a file or in a string |
| by using the following functions:% |
| \begin{verbatim} |
| int lua_dofile (lua_State *L, const char *filename); |
| int lua_dostring (lua_State *L, const char *string); |
| int lua_dobuffer (lua_State *L, const char *buff, |
| size_t size, const char *name); |
| \end{verbatim} |
| \DefAPI{lua_dofile}\DefAPI{lua_dostring}\DefAPI{lua_dobuffer}% |
| These functions return |
| 0 in case of success, or one of the following error codes if they fail: |
| \begin{itemize} |
| \item \IndexAPI{LUA_ERRRUN} --- |
| error while running the chunk. |
| \item \IndexAPI{LUA_ERRSYNTAX} --- |
| syntax error during pre-compilation. |
| \item \IndexAPI{LUA_ERRMEM} --- |
| memory allocation error. |
| For such errors, Lua does not call \verb|_ERRORMESSAGE| \see{error}. |
| \item \IndexAPI{LUA_ERRERR} --- |
| error while running \verb|_ERRORMESSAGE|. |
| For such errors, Lua does not call \verb|_ERRORMESSAGE| again, to avoid loops. |
| \item \IndexAPI{LUA_ERRFILE} --- |
| error opening the file (only for \verb|lua_dofile|). |
| In this case, |
| you may want to |
| check \verb|errno|, |
| call \verb|strerror|, |
| or call \verb|perror| to tell the user what went wrong. |
| \end{itemize} |
| These constants are defined in \verb|lua.h|. |
| |
| When called with argument \verb|NULL|, |
| \verb|lua_dofile| executes the \verb|stdin| stream. |
| \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}). |
| \verb|lua_dostring| executes only source code, |
| given in textual form. |
| |
| The fourth parameter to \verb|lua_dobuffer| |
| is the ``name of the chunk'', |
| which is used in error messages and debug information. |
| If \verb|name| is \verb|NULL|, |
| then Lua gives a default name to the chunk. |
| |
| These functions push onto the stack |
| any values eventually returned by the chunk. |
| A chunk may return any number of values; |
| Lua takes care that these values fit into the stack space, |
| but after the call the responsibility is back to you. |
| If you need to push other elements after calling any of these functions, |
| and you want to ``play safe'', |
| you must either check the stack space |
| with \verb|lua_stackspace| |
| or remove the returned elements |
| from the stack (if you do not need them). |
| For instance, the following code |
| loads a chunk in a file and discards all results returned by this chunk, |
| leaving the stack as it was before the call: |
| \begin{verbatim} |
| { |
| int oldtop = lua_gettop(L); |
| lua_dofile(L, filename); |
| lua_settop(L, oldtop); |
| } |
| \end{verbatim} |
| |
| |
| \subsection{Manipulating Global Variables in Lua} |
| |
| To read the value of a global Lua variable, |
| you call |
| \begin{verbatim} |
| void lua_getglobal (lua_State *L, const char *varname); |
| \end{verbatim} |
| \DefAPI{lua_getglobal} |
| which pushes onto the stack the value of the given variable. |
| As in Lua, this function may trigger a tag method |
| for the ``getglobal'' event \see{tag-method}. |
| To read the real value of a global variable, |
| without invoking any tag method, |
| use \verb|lua_rawget| over the table of globals |
| (see below). |
| |
| To store a value in a global variable, |
| you call |
| \begin{verbatim} |
| void lua_setglobal (lua_State *L, const char *varname); |
| \end{verbatim} |
| \DefAPI{lua_setglobal} |
| which pops from the stack the value to be stored in the given variable. |
| As in Lua, this function may trigger a tag method |
| for the ``setglobal'' event \see{tag-method}. |
| To set the real value of a global variable, |
| without invoking any tag method, |
| use \verb|lua_rawset| over the table of globals |
| (see below). |
| |
| All global variables are kept in an ordinary Lua table. |
| You can get this table calling |
| \begin{verbatim} |
| void lua_getglobals (lua_State *L); |
| \end{verbatim} |
| \DefAPI{lua_getglobals} |
| which pushes the current table of globals onto the stack. |
| To set another table as the table of globals, |
| you call |
| \begin{verbatim} |
| void lua_setglobals (lua_State *L); |
| \end{verbatim} |
| \DefAPI{lua_setglobals} |
| The table to be used is popped from the stack. |
| |
| \subsection{Manipulating Tables in Lua} |
| Lua tables can also be manipulated through the API. |
| |
| To read a value from a table, call |
| \begin{verbatim} |
| void lua_gettable (lua_State *L, int index); |
| \end{verbatim} |
| \DefAPI{lua_gettable} |
| where \verb|index| refers to the table. |
| \verb|lua_gettable| pops a key from the stack, |
| and returns (on the stack) the contents of the table at that key. |
| As in Lua, this operation may trigger a tag method |
| for the ``gettable'' event. |
| To get the real value of any table key, |
| without invoking any tag method, |
| use the \emph{raw} version: |
| \begin{verbatim} |
| void lua_rawget (lua_State *L, int index); |
| \end{verbatim} |
| \DefAPI{lua_rawget} |
| |
| To store a value into a table that resides somewhere in the stack, |
| you push the key and the value onto the stack |
| (in this order), |
| and then call |
| \begin{verbatim} |
| void lua_settable (lua_State *L, int index); |
| \end{verbatim} |
| \DefAPI{lua_settable} |
| where \verb|index| refers to the table. |
| \verb|lua_settable| pops from the stack both the key and the value. |
| As in Lua, this operation may trigger a tag method |
| for the ``settable'' event. |
| To set the real value of any table index, |
| without invoking any tag method, |
| use the \emph{raw} version: |
| \begin{verbatim} |
| void lua_rawset (lua_State *L, int index); |
| \end{verbatim} |
| \DefAPI{lua_rawset} |
| |
| Finally, the function |
| \begin{verbatim} |
| void lua_newtable (lua_State *L); |
| \end{verbatim} |
| \DefAPI{lua_newtable} |
| creates a new, empty table and pushes it onto the stack. |
| |
| \subsection{Using Tables as Arrays} |
| The API has functions that help to use Lua tables as arrays, |
| that is, |
| tables indexed by numbers only: |
| \begin{verbatim} |
| void lua_rawgeti (lua_State *L, int index, int n); |
| void lua_rawseti (lua_State *L, int index, int n); |
| int lua_getn (lua_State *L, int index); |
| \end{verbatim} |
| \DefAPI{lua_rawgeti} |
| \DefAPI{lua_rawseti} |
| \DefAPI{lua_getn} |
| |
| \verb|lua_rawgeti| pushes the value of the \M{n}-th element of the table |
| at stack position \verb|index|. |
| |
| \verb|lua_rawseti| sets the value of the \M{n}-th element of the table |
| at stack position \verb|index| to the value at the top of the stack, |
| removing the value from the stack. |
| |
| \verb|lua_getn| returns the number of elements in the table |
| at stack position \verb|index|. |
| This number is the value of the table field \verb|n|, |
| if it has a numeric value, |
| or the largest numerical index with a non-nil value in the table. |
| |
| \subsection{Calling Lua Functions} |
| |
| Functions defined in Lua |
| (and C~functions registered in Lua) |
| can be called from the host program. |
| This is done using the following protocol: |
| First, the function to be called is pushed onto the stack; |
| then, the arguments to the function are pushed |
| \see{pushing} in \emph{direct order}, that is, the first argument is pushed first. |
| Finally, the function is called using |
| \begin{verbatim} |
| int lua_call (lua_State *L, int nargs, int nresults); |
| \end{verbatim} |
| \DefAPI{lua_call} |
| This function returns the same error codes as \verb|lua_dostring| and |
| friends \see{luado}. |
| If you want to propagate the error, |
| instead of returning an error code, |
| use |
| \begin{verbatim} |
| void lua_rawcall (lua_State *L, int nargs, int nresults); |
| \end{verbatim} |
| \DefAPI{lua_rawcall} |
| |
| In both functions, |
| \verb|nargs| is the number of arguments that you pushed onto the stack. |
| All arguments and the function value are popped from the stack, |
| and the function results are pushed. |
| The number of results are adjusted to \verb|nresults|, |
| unless \verb|nresults| is \IndexAPI{LUA_MULTRET}. |
| In that case, \emph{all} results from the function are pushed. |
| The function results are pushed in direct order |
| (the first result is pushed first), |
| so that after the call the last result is on the top. |
| |
| The following example shows how the host program may do the |
| equivalent to the Lua code: |
| \begin{verbatim} |
| a,b = f("how", t.x, 4) |
| \end{verbatim} |
| Here it is in~C: |
| \begin{verbatim} |
| lua_getglobal(L, "t"); /* global `t' (for later use) */ |
| lua_getglobal(L, "f"); /* function to be called */ |
| lua_pushstring(L, "how"); /* 1st argument */ |
| lua_pushstring(L, "x"); /* push the string `x' */ |
| lua_gettable(L, -4); /* push result of t.x (2nd arg) */ |
| lua_pushnumber(L, 4); /* 3rd argument */ |
| lua_call(L, 3, 2); /* call function with 3 arguments and 2 results */ |
| lua_setglobal(L, "b"); /* set global variable `b' */ |
| lua_setglobal(L, "a"); /* set global variable `a' */ |
| lua_pop(L, 1); /* remove `t' from the stack */ |
| \end{verbatim} |
| Notice that the code above is ``balanced'': |
| at its end, the stack is back to its original configuration. |
| This is considered good programming practice. |
| |
| \medskip |
| |
| |
| Some special Lua functions have their own C~interfaces. |
| The host program can generate a Lua error calling the function |
| \begin{verbatim} |
| void lua_error (lua_State *L, const char *message); |
| \end{verbatim} |
| \DefAPI{lua_error} |
| This function never returns. |
| If \verb|lua_error| is called from a C~function that 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(EXIT_FAILURE)|. |
| Before terminating execution, |
| the \verb|message| is passed to the error handler function, |
| \verb|_ERRORMESSAGE| \see{error}. |
| If \verb|message| is \verb|NULL|, |
| then \verb|_ERRORMESSAGE| is not called. |
| |
| \medskip |
| |
| Tag methods can be changed with |
| \begin{verbatim} |
| void lua_settagmethod (lua_State *L, int tag, const char *event); |
| \end{verbatim} |
| \DefAPI{lua_settagmethod} |
| The second parameter is the tag, |
| and the third is the event name \see{tag-method}; |
| the new method is popped from the stack. |
| To get the current value of a tag method, |
| use the function |
| \begin{verbatim} |
| void lua_gettagmethod (lua_State *L, int tag, const char *event); |
| \end{verbatim} |
| \DefAPI{lua_gettagmethod} |
| |
| It is also possible to copy all tag methods from one tag |
| to another: |
| \begin{verbatim} |
| int lua_copytagmethods (lua_State *L, int tagto, int tagfrom); |
| \end{verbatim} |
| \DefAPI{lua_copytagmethods} |
| This function returns \verb|tagto|. |
| |
| \medskip |
| |
| You can traverse a table with the function |
| \begin{verbatim} |
| int lua_next (lua_State *L, int index); |
| \end{verbatim} |
| \DefAPI{lua_next} |
| where \verb|index| refers to the table to be traversed. |
| The function pops a key from the stack, |
| and pushes a key-value pair from the table |
| (the ``next'' pair after the given key). |
| If there are no more elements, then the function returns 0 |
| (and pushes nothing). |
| A typical traversal looks like this: |
| \begin{verbatim} |
| /* table is in the stack at index `t' */ |
| lua_pushnil(L); /* first key */ |
| while (lua_next(L, t) != 0) { |
| /* `key' is at index -2 and `value' at index -1 */ |
| printf("%s - %s\n", |
| lua_typename(L, lua_type(L, -2)), lua_typename(L, lua_type(L, -1))); |
| lua_pop(L, 1); /* removes `value'; keeps `index' for next iteration */ |
| } |
| \end{verbatim} |
| |
| The function |
| \begin{verbatim} |
| void lua_concat (lua_State *L, int n); |
| \end{verbatim} |
| \DefAPI{lua_concat} |
| concatenates the \verb|n| values at the top of the stack, |
| pops them, and leaves the result at the top; |
| \verb|n|~must be at least 2. |
| Concatenation is done following the usual semantics of Lua |
| \see{concat}. |
| |
| |
| \subsection{Defining C Functions} \label{LuacallC} |
| To register a C~function to Lua, |
| there is the following convenience macro: |
| \begin{verbatim} |
| #define lua_register(L, n, f) (lua_pushcfunction(L, f), lua_setglobal(L, n)) |
| /* const char *n; */ |
| /* lua_CFunction f; */ |
| \end{verbatim} |
| \DefAPI{lua_register} |
| 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 |
| \begin{verbatim} |
| typedef int (*lua_CFunction) (lua_State *L); |
| \end{verbatim} |
| \DefAPI{lua_CFunction} |
| that is, a pointer to a function with integer result and a single argument, |
| a Lua environment. |
| |
| In order to communicate properly with Lua, |
| a C~function must follow the following protocol, |
| which defines the way parameters and results are passed: |
| A C~function receives its arguments from Lua in the stack, |
| in direct order (the first argument is pushed first). |
| To return values to Lua, a C~function just pushes them onto the stack, |
| in direct order (the first result is pushed first), |
| and returns the number of results. |
| Like a Lua function, a C~function called by Lua can also return |
| many results. |
| |
| As an example, the following function receives a variable number |
| of numerical arguments and returns their average and sum: |
| \begin{verbatim} |
| static int foo (lua_State *L) { |
| int n = lua_gettop(L); /* number of arguments */ |
| double sum = 0; |
| int i; |
| for (i = 1; i <= n; i++) { |
| if (!lua_isnumber(L, i)) |
| lua_error(L, "incorrect argument to function `average'"); |
| sum += lua_tonumber(L, i); |
| } |
| lua_pushnumber(L, sum/n); /* first result */ |
| lua_pushnumber(L, sum); /* second result */ |
| return 2; /* number of results */ |
| } |
| \end{verbatim} |
| This function may be registered in Lua as `\verb|average|' by calling |
| \begin{verbatim} |
| lua_register(L, "average", foo); |
| \end{verbatim} |
| |
| |
| When a C~function is created, |
| it is possible to associate some \emph{upvalues} to it |
| \see{upvalue}, |
| thus creating a \IndexEmph{C~closure}; |
| these values are passed to the function whenever it is called, |
| as ordinary arguments. |
| To associate upvalues to a C~function, |
| first these values should be pushed onto the stack |
| (when there are multiple upvalues, |
| the first upvalue is pushed first). |
| Then the function |
| \begin{verbatim} |
| void lua_pushcclosure (lua_State *L, lua_CFunction fn, int n); |
| \end{verbatim} |
| \DefAPI{lua_pushcclosure} |
| is used to push the C~function onto the stack, |
| with the argument \verb|n| telling how many upvalues should be |
| associated with the function |
| (these upvalues are popped from the stack); |
| in fact, the macro \verb|lua_pushcfunction| is defined as |
| \verb|lua_pushcclosure| with \verb|n| set to 0. |
| Then, whenever the C~function is called, |
| these upvalues are inserted as the \emph{last} arguments to the function, |
| after the actual arguments provided in the call. |
| This makes it easy to get the upvalues without knowing how many arguments |
| the function received (recall that functions in Lua can receive any number of |
| arguments): The \M{i}-th upvalue is in the stack at index \Math{i-(n+1)}, |
| where \M{n} is the number of upvalues. |
| |
| For more examples of C~functions and closures, see files |
| \verb|lbaselib.c|, \verb|liolib.c|, \verb|lmathlib.c|, and \verb|lstrlib.c| |
| in the official Lua distribution. |
| |
| \subsection{References to Lua Objects} |
| |
| If the C~code needs to keep a Lua value |
| outside the life span of a C~function, |
| then it must create a \Def{reference} to the value. |
| The functions to manipulate references are the following: |
| \begin{verbatim} |
| int lua_ref (lua_State *L, int lock); |
| int lua_getref (lua_State *L, int ref); |
| void lua_unref (lua_State *L, int ref); |
| \end{verbatim} |
| \DefAPI{lua_ref}\DefAPI{lua_getref}\DefAPI{lua_unref} |
| |
| \verb|lua_ref| pops a value from |
| the stack, creates a reference to it, |
| and returns this reference. |
| For a \nil\ value, |
| the reference is always \verb|LUA_REFNIL|.\DefAPI{LUA_REFNIL} |
| (\verb|lua.h| also defines a constant \verb|LUA_NOREF| \DefAPI{LUA_NOREF} |
| that |
| is different from any valid reference.) |
| If \verb|lock| is not zero, then the object is \emph{locked}: |
| this means the object will not be garbage collected. |
| \emph{Unlocked references may be garbage collected}. |
| |
| Whenever the referenced object is needed in~C, |
| a call to \verb|lua_getref| |
| pushes that object onto the stack; |
| if the object has been collected, |
| \verb|lua_getref| returns 0 (and does not push anything). |
| |
| When a reference is no longer needed, |
| it should be released with a call to \verb|lua_unref|. |
| |
| |
| \subsubsection*{Registry} |
| |
| When Lua starts, it registers a table at position |
| \IndexAPI{LUA_REFREGISTRY}. |
| It can be accessed through the macro |
| \begin{verbatim} |
| #define lua_getregistry(L) lua_getref(L, LUA_REFREGISTRY) |
| \end{verbatim} |
| \DefAPI{lua_getregistry} |
| This table can be used by C~libraries as a general registry mechanism. |
| Any C~library can store data into this table, |
| as long as it chooses a key different from other libraries. |
| |
| |
| |
| \subsection{Weak Tables} |
| |
| The following constants and functions control the weak mode of a table: |
| \begin{verbatim} |
| #define LUA_WEAK_KEY ... |
| #define LUA_WEAK_VALUE ... |
| \end{verbatim} |
| \begin{verbatim} |
| void lua_setweakmode (lua_State *L, int mode); |
| int lua_getweakmode (lua_State *L, int index); |
| \end{verbatim} |
| \DefAPI{lua_setweakmode}\DefAPI{lua_getweakmode} |
| Both functions operate over the table at the top of the stack. |
| Modes are described as bit sets, so that |
| \verb|LUA_WEAK_KEY| means weak keys, |
| \verb|LUA_WEAK_VALUE| means weak values, |
| \verb|LUA_WEAK_KEY | LUA_WEAK_VALUE| means both, |
| and zero means none. |
| |
| |
| \section{Standard Libraries} |
| |
| The standard libraries provide useful functions |
| that are implemented directly through the standard API. |
| Therefore, they are not necessary to the language, |
| and are provided as separate C~modules. |
| Currently, Lua has the following standard libraries: |
| \begin{itemize} |
| \item basic library; |
| \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_baselibopen|, |
| \verb|lua_strlibopen|, \verb|lua_mathlibopen|, |
| and \verb|lua_iolibopen|, which are declared in \verb|lualib.h|. |
| \DefAPI{lua_baselibopen} |
| \DefAPI{lua_strlibopen} |
| \DefAPI{lua_mathlibopen} |
| \DefAPI{lua_iolibopen} |
| |
| \subsection{Basic Functions} \label{predefined} |
| |
| The basic library provides some core functions to Lua. |
| Therefore, if you do not include this library in your application, |
| you should check carefully whether you need to provide some alternative |
| implementation for some facilities. |
| (For instance, |
| without function \verb|_ERRORMESSAGE|, |
| Lua is unable to show error messages.) |
| |
| \subsubsection*{\ff \T{_ALERT (message)}}\DefLIB{alert}\label{alert} |
| Prints its only string argument to \IndexVerb{stderr}. |
| All error messages in Lua are printed through the function stored |
| in the \verb|_ALERT| global variable |
| \see{error}. |
| Therefore, a program may assign another function to this variable |
| to change the way such messages are shown |
| (for instance, for systems without \verb|stderr|). |
| |
| \subsubsection*{\ff \T{assert (v [, message])}}\DefLIB{assert} |
| Issues an \emph{``assertion failed!''} error |
| when its argument \verb|v| is \nil; |
| otherwise, returns this argument. |
| 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 |
| return v |
| end |
| \end{verbatim} |
| |
| \subsubsection*{\ff \T{call (func, arg [, mode [, errhandler]])}}\DefLIB{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}. |
| All results from \verb|func| are simply returned by \verb|call|. |
| |
| By default, |
| if an error occurs during the call to \verb|func|, |
| 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 \verb|errhandler| is provided, |
| the error function \verb|_ERRORMESSAGE| is temporarily set to \verb|errhandler|, |
| 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])}}\DefLIB{collectgarbage} |
| |
| Sets the garbage-collection threshold for the given limit |
| (in Kbytes), and checks it against the byte counter. |
| If the new threshold is smaller than the byte counter, |
| then Lua immediately runs the garbage collector \see{GC}. |
| If \verb|limit| is absent, it defaults to zero |
| (thus forcing a garbage-collection cycle). |
| %\verb|collectgarbage| is equivalent to |
| %the API function \verb|lua_setgcthreshold|. |
| |
| \subsubsection*{\ff \T{copytagmethods (tagto, tagfrom)}} |
| \DefLIB{copytagmethods} |
| Copies all tag methods from one tag to another; |
| returns \verb|tagto|. |
| |
| \subsubsection*{\ff \T{dofile (filename)}}\DefLIB{dofile} |
| Receives a file name, |
| opens the named file, and executes its 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{} plus one of the following strings |
| describing the error: |
| \verb|"file error"|, \verb|"run-time error"|, |
| \verb|"syntax error"|, \verb|"memory error"|, or |
| \verb|"error in error handling"|. |
| 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. |
| |
| \subsubsection*{\ff \T{dostring (string [, chunkname])}}\DefLIB{dostring} |
| Executes a given string as a Lua chunk. |
| If there is any error executing the string, |
| then \verb|dostring| returns \nil plus a string describing |
| the error (see \verb|dofile|). |
| Otherwise, it returns the values returned by the chunk, |
| or a non-\nil\ value if the chunk returns no values. |
| The optional parameter \verb|chunkname| |
| is the ``name of the chunk'', |
| used in error messages and debug information. |
| |
| \subsubsection*{\ff \T{error (message)}}\DefLIB{error}\label{pdf-error} |
| Calls the error handler \see{error} 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, then 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{foreach (table, func)}}\DefLIB{foreach} |
| Executes the given \verb|func| 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, |
| then the loop is broken, and this value is returned |
| as the final value of \verb|foreach|. |
| This function could be defined in Lua: |
| \begin{verbatim} |
| function foreach (t, f) |
| for i, v in t do |
| local res = f(i, v) |
| if res then return res end |
| end |
| end |
| \end{verbatim} |
| |
| The behavior of \verb|foreach| is \emph{undefined} if you change |
| the table \verb|t| during the traversal. |
| |
| |
| \subsubsection*{\ff \T{foreachi (table, func)}}\DefLIB{foreachi} |
| Executes the given \verb|func| 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 below). |
| If the function returns any non-\nil\ value, |
| then the loop is broken, and this value is returned |
| as the final value of \verb|foreachi|. |
| This function could be defined in Lua: |
| \begin{verbatim} |
| function foreachi (t, f) |
| for i=1,getn(t) do |
| local res = f(i, t[i]) |
| if res then return res end |
| end |
| end |
| \end{verbatim} |
| |
| \subsubsection*{\ff \T{gcinfo ()}}\DefLIB{gcinfo} |
| Returns the number of Kbytes of dynamic memory Lua is using, |
| and (as a second result) the |
| current garbage collector threshold (also in Kbytes). |
| |
| \subsubsection*{\ff \T{getglobal (name)}}\DefLIB{getglobal} |
| Gets the value of a global variable, |
| or calls a tag method for ``getglobal''. |
| 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{getn (table)}}\DefLIB{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 value is the ``size'' of the table. |
| 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 |
| for i, _ in t do |
| if type(i) == "number" and i>max then max=i end |
| end |
| return max |
| end |
| \end{verbatim} |
| |
| \subsubsection*{\ff \T{gettagmethod (tag, event)}} |
| \DefLIB{gettagmethod} |
| Returns the current tag method |
| for a given pair \M{(tag, event)}. |
| This function cannot be used to get a tag method for the ``gc'' event. |
| (Such tag methods can only be manipulated by C~code.) |
| |
| \subsubsection*{\ff \T{globals ([table])}}\DefLIB{globals} |
| Returns the current table of globals. |
| If the argument \verb|table| is given, |
| then it also sets this table as the table of globals. |
| |
| \subsubsection*{\ff \T{newtype (name)}}\DefLIB{newtype}\label{pdf-newtype} |
| Creates a new type with the given name |
| (which can be used only for table objects). |
| Returns the tag of the new type. |
| |
| \subsubsection*{\ff \T{next (table, [index])}}\DefLIB{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. |
| \verb|next| returns the next index of the table and the |
| value associated with the index. |
| When called with \nil\ as its second argument, |
| \verb|next| returns the first index |
| of the table and its associated value. |
| When called with the last index, |
| or with \nil\ in an empty table, |
| \verb|next| returns \nil. |
| If the second argument is absent, then it is interpreted as \nil. |
| |
| Lua has no declaration of fields; |
| semantically, there is no difference between a |
| field not present in a table or a field with value \nil. |
| Therefore, \verb|next| 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 numerical \rwd{for} or the function \verb|foreachi|). |
| |
| The behavior of \verb|next| is \emph{undefined} if you change |
| the table during the traversal. |
| |
| \subsubsection*{\ff \T{print (e1, e2, ...)}}\DefLIB{print} |
| Receives any number of arguments, |
| and prints their values in \verb|stdout|, |
| 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{rawget (table, index)}}\DefLIB{rawget} |
| 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{rawset (table, index, value)}}\DefLIB{rawset} |
| 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{rawtype (v)}}\DefLIB{rawtype} |
| Returns the basic (raw) type of its only argument, 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{require (module)}}\DefLIB{require} |
| |
| TO BE WRITTEN. |
| |
| \subsubsection*{\ff \T{setglobal (name, value)}}\DefLIB{setglobal} |
| Sets the named global variable to the given value, |
| or calls a tag method for ``setglobal''. |
| 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{settype (t, type)}}\DefLIB{settype}\label{pdf-settype} |
| Sets the type of a given table \see{TypesSec}. |
| \verb|type| must be the name or the tag of a user-defined type. |
| \verb|settag| returns the value of its first argument (the table). |
| For the safety of host programs, |
| it is impossible to change the tag of a userdata from Lua. |
| |
| \subsubsection*{\ff \T{settagmethod (tag, event, newmethod)}} |
| \DefLIB{settagmethod} |
| Sets a new tag method to the given pair \M{(tag, event)} and |
| returns the old method. |
| If \verb|newmethod| is \nil, |
| then \verb|settagmethod| restores the default behavior for the given event. |
| This function cannot be used to set a tag method for the ``gc'' event. |
| (Such tag methods can only be manipulated by C~code.) |
| |
| \subsubsection*{\ff \T{sort (table [, comp])}}\DefLIB{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, |
| then it must be a function that receives two table elements, |
| and returns true (that is, a value different from \nil) |
| 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, |
| then the standard Lua operator \verb|<| is used instead. |
| |
| The sort algorithm is \emph{not} stable |
| (that is, elements considered equal by the given order |
| may have their relative positions changed by the sort). |
| |
| \subsubsection*{\ff \T{tag (v)}}\DefLIB{tag}\label{pdf-tag} |
| Allows Lua programs 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{tonumber (e [, base])}}\DefLIB{tonumber} |
| Tries to convert its argument to a number. |
| If the argument is already a number or a string convertible |
| to a number, then \verb|tonumber| returns that number; |
| otherwise, it returns \nil. |
| |
| An optional argument specifies the base to interpret the numeral. |
| The base may be any integer between 2 and 36, inclusive. |
| In bases above~10, the letter `A' (either upper or lower case) |
| represents~10, `B' represents~11, and so forth, with `Z' representing 35. |
| In base 10 (the default), the number may have a decimal part, |
| as well as an optional exponent part \see{coercion}. |
| In other bases, only unsigned integers are accepted. |
| |
| \subsubsection*{\ff \T{tostring (e)}}\DefLIB{tostring} |
| Receives an argument of any type and |
| converts it to a string in a reasonable format. |
| For complete control of how numbers are converted, |
| use function \verb|format|. |
| |
| |
| \subsubsection*{\ff \T{tinsert (table, [pos,] value)}}\DefLIB{tinsert} |
| |
| Inserts element \verb|value| at table position \verb|pos|, |
| shifting other elements to open space, if necessary. |
| The default value for \verb|pos| is \verb|n+1|, |
| where \verb|n| is the result of \verb|getn(table)| \see{getn}, |
| so that a call \verb|tinsert(t,x)| inserts \verb|x| at the end |
| of table \verb|t|. |
| This function also sets or increments the field \verb|n| of the table |
| to \verb|n+1|. |
| This function is equivalent to the following Lua function, |
| except that the table accesses are all \emph{raw} |
| (that is, without tag methods): |
| \begin{verbatim} |
| function tinsert (t, ...) |
| local pos, value |
| local n = getn(t) |
| if arg.n == 1 then |
| pos, value = n+1, arg[1] |
| else |
| pos, value = arg[1], arg[2] |
| end |
| t.n = n+1; |
| for i=n,pos,-1 do |
| t[i+1] = t[i] |
| end |
| t[pos] = value |
| end |
| \end{verbatim} |
| |
| \subsubsection*{\ff \T{tremove (table [, pos])}}\DefLIB{tremove} |
| |
| Removes from \verb|table| the element at position \verb|pos|, |
| shifting other elements to close the space, if necessary. |
| Returns the value of the removed element. |
| The default value for \verb|pos| is \verb|n|, |
| where \verb|n| is the result of \verb|getn(table)| \see{getn}, |
| so that a call \verb|tremove(t)| removes the last element |
| of table \verb|t|. |
| This function also sets or decrements the field \verb|n| of the table |
| to \verb|n-1|. |
| |
| This function is equivalent to the following Lua function, |
| except that the table accesses are all \emph{raw} |
| (that is, without tag methods): |
| \begin{verbatim} |
| function tremove (t, pos) |
| local n = getn(t) |
| if n<=0 then return end |
| pos = pos or n |
| local value = t[pos] |
| for i=pos,n-1 do |
| t[i] = t[i+1] |
| end |
| t[n] = nil |
| t.n = n-1 |
| return value |
| end |
| \end{verbatim} |
| |
| \subsubsection*{\ff \T{type (v)}}\DefLIB{type}\label{pdf-type} |
| Returns the type name of its only argument. |
| |
| \subsubsection*{\ff \T{unpack (list)}}\DefLIB{unpack} |
| Returns all elements from the given list. |
| This function is equivalent to |
| \begin{verbatim} |
| return list[1], list[2], ..., list[n] |
| \end{verbatim} |
| except that the above code can be valid only for a fixed \M{n}. |
| The number of returned values, \M{n}, |
| is the result of \verb|getn(list)| \see{getn}, |
| |
| \subsubsection*{\ff \T{weakmode (table, mode)}}\DefLIB{weakmode}\label{weakmode} |
| |
| Controls the weakness of a table. |
| When \verb|mode| is \verb|"?"|, |
| returns the current mode of the table, as a string; |
| otherwise, sets the weakmode of the table to the given mode (also a string). |
| Valid mode strings are \verb|"k"| for weak keys, |
| \verb|"v"| for weak values, |
| \verb|"kv"| for both, |
| and \verb|""| for none (that is, for ``normal'' tables). |
| |
| |
| \subsection{String Manipulation} |
| This library provides generic functions for string manipulation, |
| such as finding and extracting substrings and pattern matching. |
| When indexing a string in Lua, the first character is at position~1 |
| (not at~0, as in C). |
| Also, |
| indices are allowed to be negative and are interpreted as indexing backwards, |
| from the end of the string. Thus, the last character is at position \Math{-1}, |
| and so on. |
| |
| \subsubsection*{\ff \T{strbyte (s [, i])}}\DefLIB{strbyte} |
| Returns the internal numerical code of the \M{i}-th character of \verb|s|. |
| If \verb|i| is absent, then it is assumed to be~1. |
| \verb|i| may be negative. |
| |
| \NOTE |
| Numerical codes are not necessarily portable across platforms. |
| |
| \subsubsection*{\ff \T{strchar (i1, i2, \ldots)}}\DefLIB{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 |
| Numerical codes are not necessarily portable across platforms. |
| |
| \subsubsection*{\ff \T{strfind (s, pattern [, init [, plain]])}} |
| \DefLIB{strfind} |
| Looks for the first \emph{match} of |
| \verb|pattern| in \verb|s|. |
| If it finds one, then \verb|strfind| returns the indices of \verb|s| |
| where this occurrence starts and ends; |
| otherwise, it returns \nil. |
| If the pattern specifies captures (see \verb|gsub| below), |
| the captured strings are returned as extra results. |
| A third, optional numerical argument \verb|init| specifies |
| where to start the search; |
| its default value is~1, and may be negative. |
| A value of~1 as a fourth, optional argument \verb|plain| |
| turns off the pattern matching facilities, |
| so the function does a plain ``find substring'' operation, |
| with no characters in \verb|pattern| being considered ``magic''. |
| Note that if \verb|plain| is given, then \verb|init| must be given too. |
| |
| \subsubsection*{\ff \T{strlen (s)}}\DefLIB{strlen} |
| Receives a string and returns its length. |
| The empty string \verb|""| has length 0. |
| Embedded zeros are counted, |
| and so \verb|"a\000b\000c"| has length 5. |
| |
| \subsubsection*{\ff \T{strlower (s)}}\DefLIB{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{strrep (s, n)}}\DefLIB{strrep} |
| Returns a string that is the concatenation of \verb|n| copies of |
| the string \verb|s|. |
| |
| \subsubsection*{\ff \T{strsub (s, i [, j])}}\DefLIB{strsub} |
| Returns another string, which is a substring of \verb|s|, |
| starting at \verb|i| and running until \verb|j|; |
| \verb|i| and \verb|j| may be negative, |
| If \verb|j| is absent, then 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{strupper (s)}}\DefLIB{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{format (formatstring, e1, e2, \ldots)}}\DefLIB{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|. |
| The \verb|q| 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} |
| |
| 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"|. |
| |
| \NOTE |
| String values to be formatted with |
| \verb|%s| cannot contain embedded zeros. |
| |
| \subsubsection*{\ff \T{gsub (s, pat, repl [, n])}} |
| \DefLIB{gsub} |
| Returns a copy of \verb|s| |
| in which all occurrences of the pattern \verb|pat| have been |
| replaced by a replacement string specified by \verb|repl|. |
| \verb|gsub| 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 \M{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. |
| |
| The 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="4.0"} |
| x = gsub("$name - $version", "%$(%w+)", function (v) return %t[v] end) |
| --> x="lua - 4.0" |
| |
| 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 not one of the magic characters |
| \verb|^$()%.[]*+-?|) |
| --- represents the character \emph{x} itself. |
| \item[\T{.}] --- (a dot) represents all characters. |
| \item[\T{\%a}] --- represents all letters. |
| \item[\T{\%c}] --- represents all control characters. |
| \item[\T{\%d}] --- represents all digits. |
| \item[\T{\%l}] --- represents all lower case letters. |
| \item[\T{\%p}] --- represents all punctuation characters. |
| \item[\T{\%s}] --- represents all space characters. |
| \item[\T{\%u}] --- represents all upper case letters. |
| \item[\T{\%w}] --- represents all alphanumeric characters. |
| \item[\T{\%x}] --- represents all hexadecimal digits. |
| \item[\T{\%z}] --- represents the character with representation 0. |
| \item[\T{\%\M{x}}] (where \M{x} is any non-alphanumeric character) --- |
| represents the character \M{x}. |
| This is the standard way to escape the magic characters. |
| We recommend that any punctuation character (even the non magic) |
| should be preceded by a \verb|%| |
| when used to represent itself in a pattern. |
| |
| \item[\T{[char-set]}] --- |
| represents the class which is the union of all |
| characters in \verb|char-set|. |
| A range of characters may be specified by |
| separating the end characters of the range with a \verb|-|. |
| All classes \verb|%|\emph{x} described above may also be used as |
| components in a char-set. |
| All other characters in char-set represent themselves. |
| For example, \verb|[%w_]| (or \verb|[_%w]|) |
| represents all alphanumeric characters plus the underscore, |
| \verb|[0-7]| represents the octal digits, |
| and \verb|[0-7%l%-]| represents the octal digits plus |
| the lower case letters plus the \verb|-| character. |
| |
| The interaction between ranges and classes is not defined. |
| Therefore, patterns like \verb|[%a-z]| or \verb|[a-%%]| |
| have no meaning. |
| |
| \item[\T{[\^\null char-set]}] --- |
| represents the complement of \verb|char-set|, |
| where \verb|char-set| is interpreted as above. |
| \end{description} |
| For all classes represented by single letters (\verb|%a|, \verb|%c|, \ldots), |
| the corresponding upper-case letter represents the complement of the class. |
| For instance, \verb|%S| represents all non-space characters. |
| |
| The definitions of letter, space, etc. depend on the current locale. |
| In particular, the class \verb|[a-z]| may not be equivalent to \verb|%l|. |
| The second form should be preferred for portability. |
| |
| \paragraph{Pattern Item:} |
| a \Def{pattern item} may be |
| \begin{itemize} |
| \item |
| a single character class, |
| which matches any single character in the class; |
| \item |
| a single character class followed by \verb|*|, |
| which matches 0 or more repetitions of characters in the class. |
| These repetition items will always match the longest possible sequence; |
| \item |
| a single character class followed by \verb|+|, |
| which matches 1 or more repetitions of characters in the class. |
| These repetition items will always match the longest possible sequence; |
| \item |
| a single character class followed by \verb|-|, |
| which also matches 0 or more repetitions of characters in the class. |
| Unlike \verb|*|, |
| these repetition items will always match the shortest possible sequence; |
| \item |
| a single character class followed by \verb|?|, |
| which matches 0 or 1 occurrence of a character in the class; |
| \item |
| \T{\%\M{n}}, for \M{n} between 1 and 9; |
| such item matches a sub-string equal to the \M{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}. |
| This means that, if one reads the string from left to right, |
| counting \Math{+1} for an \M{x} and \Math{-1} for a \M{y}, |
| the ending \M{y} is the first \M{y} 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. |
| At other positions, |
| \verb|^| and \verb|$| have no special meaning and represent themselves. |
| |
| \paragraph{Captures:} |
| A pattern may contain sub-patterns enclosed in parentheses, |
| they 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. |
| |
| \NOTE |
| A pattern cannot contain embedded zeros. Use \verb|%z| instead. |
| |
| |
| \subsection{Mathematical Functions} \label{mathlib} |
| |
| This library is an interface to some functions of the standard C~math library. |
| In addition, it registers a tag method for the binary operator \verb|^| that |
| returns \Math{x^y} when applied to numbers \verb|x^y|. |
| |
| The library provides the following functions: |
| \DefLIB{abs}\DefLIB{acos}\DefLIB{asin}\DefLIB{atan} |
| \DefLIB{atan2}\DefLIB{ceil}\DefLIB{cos}\DefLIB{def}\DefLIB{exp} |
| \DefLIB{floor}\DefLIB{log}\DefLIB{log10}\DefLIB{max}\DefLIB{min} |
| \DefLIB{mod}\DefLIB{rad}\DefLIB{sin}\DefLIB{sqrt}\DefLIB{tan} |
| \DefLIB{frexp}\DefLIB{ldexp}\DefLIB{random}\DefLIB{randomseed} |
| \begin{verbatim} |
| abs acos asin atan atan2 ceil cos deg exp floor log log10 |
| max min mod rad sin sqrt tan frexp ldexp random randomseed |
| \end{verbatim} |
| plus a global variable \IndexLIB{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. |
| The functions \verb|deg| and \verb|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. |
| (No guarantees can be given for their statistical properties.) |
| 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|. |
| \DefLIB{_INPUT}\DefLIB{_OUTPUT} |
| \DefLIB{_STDIN}\DefLIB{_STDOUT}\DefLIB{_STDERR} |
| |
| A file handle is a userdata containing the file stream (\verb|FILE*|), |
| and with a distinctive tag created by the I/O library. |
| |
| Unless otherwise stated, |
| all I/O functions return \nil\ on failure and |
| some value different from \nil\ on success. |
| |
| \subsubsection*{\ff \T{openfile (filename, mode)}}\DefLIB{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 \verb|mode| string 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 \verb|mode| string may also have a \verb|b| at the end, |
| which is needed in some systems to open the file in binary mode. |
| This string is exactly what is used in the standard~C function \verb|fopen|. |
| |
| \subsubsection*{\ff \T{closefile (handle)}}\DefLIB{closefile} |
| |
| This function closes the given file. |
| It does not modify either \verb|_INPUT| or \verb|_OUTPUT|. |
| |
| \subsubsection*{\ff \T{readfrom (filename)}}\DefLIB{readfrom} |
| |
| This function may be called in two ways. |
| When called with a file name, it opens the named file (in text mode), |
| 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. |
| |
| \NOTE |
| 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. |
| |
| \subsubsection*{\ff \T{writeto (filename)}}\DefLIB{writeto} |
| |
| This function may be called in two ways. |
| When called with a file name, |
| it opens the named file (in text mode), |
| 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. |
| |
| \NOTE |
| 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. |
| |
| \subsubsection*{\ff \T{appendto (filename)}}\DefLIB{appendto} |
| |
| Opens a file named \verb|filename| (in text mode) |
| and sets its handle as the value of \verb|_OUTPUT|. |
| Unlike the \verb|writeto| operation, |
| this function does not erase any previous contents of the file; |
| instead, anything written to the file is appended to its end. |
| If this function fails, it returns \nil, |
| plus a string describing the error. |
| |
| \subsubsection*{\ff \T{remove (filename)}}\DefLIB{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)}}\DefLIB{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])}}\DefLIB{flush} |
| |
| Saves any written data to the given file. |
| If \verb|filehandle| is not specified, |
| then \verb|flush| flushes all open files. |
| If this function fails, it returns \nil, |
| plus a string describing the error. |
| |
| \subsubsection*{\ff \T{seek (filehandle [, whence] [, offset])}}\DefLIB{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{tmpfile ()}}\DefLIB{tmpfile} |
| |
| Returns a handle for a temporary file. |
| This file is open in read/write mode, |
| and it is automatically removed when the program ends. |
| |
| \subsubsection*{\ff \T{tmpname ()}}\DefLIB{tmpname} |
| |
| Returns a string with a file name that can |
| be used for a temporary file. |
| The file must be explicitly opened before its use |
| and removed when no longer needed. |
| |
| This function is equivalent to the \verb|tmpnam| C function, |
| and many people advise against its use, |
| because between the time you call the function |
| and the time you open the file, |
| it is possible for another process |
| to create a file with the same name. |
| |
| \subsubsection*{\ff \T{read ([filehandle,] format1, ...)}}\DefLIB{read} |
| |
| Reads file \verb|_INPUT|, |
| or \verb|filehandle| if this argument is given, |
| according to the given formats, which specify what to read. |
| For each format, |
| the function returns a string (or a number) with the characters read, |
| or \nil\ if it cannot read data with the specified format. |
| When called without formats, |
| it uses a default format that reads the next line |
| (see below). |
| |
| The available formats are |
| \begin{description} |
| \item[``*n''] reads a number; |
| this is the only format that returns a number instead of a string. |
| \item[``*a''] reads the whole file, starting at the current position. |
| On end of file, it returns the empty string. |
| \item[``*u\emph{string}''] reads until the first occurence of |
| \emph{string} in the file. |
| The string itself is read, but it is not included in the result. |
| If it cannot finds the string, |
| reads (and returns) the file until its end, |
| or \nil\ if the file was already on its end. |
| \item[``*l''] equivalent to \verb|"*u\n"|. |
| Reads the next line (skipping the end of line), |
| returning \nil\ on end of file. |
| This is the default format. |
| \item[\emph{number}] reads a string with up to that number of characters, |
| or \nil\ on end of file. |
| Particularly, if number is zero, |
| reads nothing and returns an empty string, |
| or \nil\ on end of file. |
| \end{description} |
| |
| \subsubsection*{\ff \T{write ([filehandle, ] value1, ...)}}\DefLIB{write} |
| |
| Writes the value of each of its arguments to |
| filehandle \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. |
| |
| \subsection{System Facilities} \label{libiosys} |
| |
| \subsubsection*{\ff \T{clock ()}}\DefLIB{clock} |
| |
| Returns an approximation of the amount of CPU time |
| used by the program, in seconds. |
| |
| \subsubsection*{\ff \T{date ([format [, time]])}}\DefLIB{date} |
| |
| Returns a string or a table containing date and time, |
| formatted according to the given string \verb|format|. |
| |
| If the \verb|time| argument is present, |
| this is the time to be formatted |
| (see the \verb|time| function for a description of this value). |
| Otherwise, \verb|date| formats the current time. |
| |
| If \verb|format| starts with \verb|!|, |
| the date is formatted in Coordinated Universal Time. |
| |
| After that optional character, |
| if \verb|format| is \verb|*t|, |
| the function returns a table with the following fields: |
| \verb|year|, \verb|month| (1-12), \verb|day| (1-31), |
| \verb|hour| (0-23), \verb|min| (0-59), \verb|sec| (0-59), |
| \verb|wday| (weekday, Sunday is 1), |
| \verb|yday| (day of the year), |
| and \verb|isdst| (daylight saving flag). |
| |
| If format is not \verb|*t|, the function returns the date |
| as a string, formatted according with the |
| same rules of the ANSI~C function \verb|strftime|. |
| When called without arguments, |
| it returns a reasonable date and time representation that depends on |
| the host system and on the current locale. |
| |
| \subsubsection*{\ff \T{difftime (t1, t2)}}\DefLIB{difftime} |
| |
| Returns the number of seconds from time \verb|t1| to time \verb|t2|. |
| In Posix, Windows, and some other systems, |
| this value is exactly \Math{t1-t2}. |
| |
| \subsubsection*{\ff \T{execute (command)}}\DefLIB{execute} |
| |
| This function is equivalent to the C~function \verb|system|. |
| It passes \verb|command| to be executed by an operating system shell. |
| It returns a status code, which is system-dependent. |
| |
| \subsubsection*{\ff \T{exit ([code])}}\DefLIB{exit} |
| |
| Calls the C~function \verb|exit|, |
| with an optional \verb|code|, |
| to terminate the program. |
| The default value for \verb|code| is the success code. |
| |
| \subsubsection*{\ff \T{getenv (varname)}}\DefLIB{getenv} |
| |
| Returns the value of the process environment variable \verb|varname|, |
| or \nil\ if the variable is not defined. |
| |
| \subsubsection*{\ff \T{setlocale (locale [, category])}}\DefLIB{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. |
| |
| \subsubsection*{\ff \T{time ([table])}}\DefLIB{time} |
| |
| Returns the current time (when called without arguments), |
| or a time representing the date/time specified by the given table. |
| This table must have fields \verb|year|, \verb|month|, and \verb|day|, |
| and may have fields \verb|hour|, \verb|min|, \verb|sec|, and \verb|isdst| |
| (for a description of these fields, see the \verb|date| function). |
| |
| The returned value is a number, whose meaning depends on your system. |
| In Posix, Windows, and some other systems, this number counts the number |
| of seconds since some given start time (the ``epoch''). |
| In other systems, the meaning is not specified, |
| and such number can be used only as an argument to |
| functions \verb|date| and \verb|difftime|. |
| |
| |
| \section{The Debug 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 \verb|luadebug.h|. |
| |
| \subsection{Stack and Function Information} |
| |
| The main function to get information about the interpreter stack is |
| \begin{verbatim} |
| int lua_getstack (lua_State *L, int level, lua_Debug *ar); |
| \end{verbatim} |
| \DefAPI{lua_getstack} |
| It fills parts of a \verb|lua_Debug| structure with |
| an identification of the \emph{activation record} |
| of the function executing at a given level. |
| Level~0 is the current running function, |
| whereas level \Math{n+1} is the function that has called level \Math{n}. |
| Usually, \verb|lua_getstack| returns 1; |
| when called with a level greater than the stack depth, |
| it returns 0. |
| |
| The structure \verb|lua_Debug| is used to carry different pieces of |
| information about an active function: |
| \begin{verbatim} |
| typedef struct lua_Debug { |
| const char *event; /* "call", "return" */ |
| int currentline; /* (l) */ |
| const char *name; /* (n) */ |
| const char *namewhat; /* (n) global, tag method, local, field */ |
| int nups; /* (u) number of upvalues */ |
| int linedefined; /* (S) */ |
| const char *what; /* (S) "Lua" function, "C" function, Lua "main" */ |
| const char *source; /* (S) */ |
| char short_src[LUA_IDSIZE]; /* (S) */ |
| |
| /* private part */ |
| ... |
| } lua_Debug; |
| \end{verbatim} |
| \DefAPI{lua_Debug} |
| \verb|lua_getstack| fills only the private part |
| of this structure, for future use. |
| To fill in the other fields of \verb|lua_Debug| with useful information, |
| call |
| \begin{verbatim} |
| int lua_getinfo (lua_State *L, const char *what, lua_Debug *ar); |
| \end{verbatim} |
| \DefAPI{lua_getinfo} |
| This function returns 0 on error |
| (e.g., an invalid option in \verb|what|). |
| Each character in the string \verb|what| |
| selects some fields of \verb|ar| to be filled, |
| as indicated by the letter in parentheses in the definition of \verb|lua_Debug|: |
| `\verb|S|' fills in the fields \verb|source|, \verb|linedefined|, |
| and \verb|what|; |
| `\verb|l|' fills in the field \verb|currentline|, etc. |
| Moreover, `\verb|f|' pushes onto the stack the function that is |
| running at the given level. |
| |
| To get information about a function that is not active (that is, |
| it is not in the stack), |
| you push the function onto the stack, |
| and start the \verb|what| string with the character \verb|>|. |
| For instance, to know in which line a function \verb|f| was defined, |
| you can write |
| \begin{verbatim} |
| lua_Debug ar; |
| lua_getglobal(L, "f"); |
| lua_getinfo(L, ">S", &ar); |
| printf("%d\n", ar.linedefined); |
| \end{verbatim} |
| The fields of \verb|lua_Debug| have the following meaning: |
| \begin{description} |
| |
| \item[source] |
| If the function was defined in a string, |
| \verb|source| is that string; |
| if the function was defined in a file, |
| \verb|source| starts with a \verb|@| followed by the file name. |
| |
| \item[short\_src] |
| A ``printable'' version of \verb|source|, to be used in error messages. |
| |
| \item[linedefined] |
| the line number where the definition of the function starts. |
| |
| \item[what] the string \verb|"Lua"| if this is a Lua function, |
| \verb|"C"| if this is a C~function, |
| or \verb|"main"| if this is the main part of a chunk. |
| |
| \item[currentline] |
| the current line where the given function is executing. |
| When no line information is available, |
| \verb|currentline| is set to \Math{-1}. |
| |
| \item[name] |
| a reasonable name for the given function. |
| Because functions in Lua are first class values, |
| they do not have a fixed name: |
| Some functions may be the value of many global variables, |
| while others may be stored only in a table field. |
| The \verb|lua_getinfo| function checks whether the given |
| function is a tag method or the value of a global variable. |
| If the given function is a tag method, |
| then \verb|name| points to the event name. |
| If the given function is the value of a global variable, |
| then \verb|name| points to the variable name. |
| If the given function is neither a tag method nor a global variable, |
| then \verb|name| is set to \verb|NULL|. |
| |
| \item[namewhat] |
| Explains the previous field. |
| If the function is a global variable, |
| \verb|namewhat| is \verb|"global"|; |
| if the function is a tag method, |
| \verb|namewhat| is \verb|"tag-method"|; |
| otherwise \verb|namewhat| is \verb|""| (the empty string). |
| |
| \item[nups] |
| Number of upvalues of a function. |
| |
| \end{description} |
| |
| |
| \subsection{Manipulating Local Variables} |
| |
| For the manipulation of local variables, |
| \verb|luadebug.h| uses indices: |
| The first parameter or local variable has index~1, and so on, |
| until the last active local variable. |
| |
| The following functions allow the manipulation of the |
| local variables of a given activation record. |
| \begin{verbatim} |
| const char *lua_getlocal (lua_State *L, const lua_Debug *ar, int n); |
| const char *lua_setlocal (lua_State *L, const lua_Debug *ar, int n); |
| \end{verbatim} |
| \DefAPI{lua_getlocal}\DefAPI{lua_setlocal} |
| The parameter \verb|ar| must be a valid activation record, |
| filled by a previous call to \verb|lua_getstack| or |
| given as argument to a hook \see{sub-hooks}. |
| Function \verb|lua_getlocal| gets the index of a local variable |
| (\verb|n|), pushes its value onto the stack, |
| and returns its name. |
| For \verb|lua_setlocal|, |
| you push the new value onto the stack, |
| and the function assigns that value to the variable and returns its name. |
| Both functions return \verb|NULL| on failure; |
| that happens if the index is greater than |
| the number of active local variables. |
| |
| As an example, the following function lists the names of all |
| local variables for a function at a given level of the stack: |
| \begin{verbatim} |
| int listvars (lua_State *L, int level) { |
| lua_Debug ar; |
| int i = 1; |
| const char *name; |
| if (lua_getstack(L, level, &ar) == 0) |
| return 0; /* failure: no such level in the stack */ |
| while ((name = lua_getlocal(L, &ar, i++)) != NULL) { |
| printf("%s\n", name); |
| lua_pop(L, 1); /* remove variable value */ |
| } |
| return 1; |
| } |
| \end{verbatim} |
| |
| |
| \subsection{Hooks}\label{sub-hooks} |
| |
| The Lua interpreter offers two hooks for debugging purposes: |
| a \emph{call} hook and a \emph{line} hook. |
| Both have the same type, |
| \begin{verbatim} |
| typedef void (*lua_Hook) (lua_State *L, lua_Debug *ar); |
| \end{verbatim} |
| \DefAPI{lua_Hook} |
| and you can set them with the following functions: |
| \begin{verbatim} |
| lua_Hook lua_setcallhook (lua_State *L, lua_Hook func); |
| lua_Hook lua_setlinehook (lua_State *L, lua_Hook func); |
| \end{verbatim} |
| \DefAPI{lua_setcallhook}\DefAPI{lua_setlinehook} |
| A hook is disabled when its value is \verb|NULL|, |
| which is the initial value of both hooks. |
| The functions \verb|lua_setcallhook| and \verb|lua_setlinehook| |
| set their corresponding hooks and return their previous values. |
| |
| The call hook is called whenever the |
| interpreter enters or leaves a function. |
| The \verb|event| field of \verb|ar| has the strings \verb|"call"| |
| or \verb|"return"|. |
| This \verb|ar| can then be used in calls to \verb|lua_getinfo|, |
| \verb|lua_getlocal|, and \verb|lua_setlocal| |
| to get more information about the function and to manipulate its |
| local variables. |
| |
| The line hook is called every time the interpreter changes |
| the line of code it is executing. |
| The \verb|event| field of \verb|ar| has the string \verb|"line"|, |
| and the \verb|currentline| field has the line number. |
| Again, you can use this \verb|ar| in other calls to the debug API. |
| |
| While Lua is running a hook, it disables other calls to hooks. |
| Therefore, if a hook calls Lua to execute a function or a chunk, |
| this execution ocurrs without any calls to hooks. |
| |
| |
| \subsection{The Reflexive Debug Interface} |
| |
| The library \verb|ldblib| provides |
| the functionality of the debug interface to Lua programs. |
| If you want to use this library, |
| your host application must open it, |
| by calling \verb|lua_dblibopen|. |
| \DefAPI{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 can be \emph{very} slow. |
| Moreover, \verb|setlocal| and \verb|getlocal| |
| violate the privacy of local variables, |
| and therefore can compromise some (otherwise) secure code. |
| |
| |
| \subsubsection*{\ff \T{getinfo (function, [what])}}\DefLIB{getinfo} |
| |
| This function returns a table with information about a function. |
| You can give the function directly, |
| or you can give a number as the value of \verb|function|, |
| which means the function running at level \verb|function| of the stack: |
| Level 0 is the current function (\verb|getinfo| itself); |
| level 1 is the function that called \verb|getinfo|; |
| and so on. |
| If \verb|function| is a number larger than the number of active functions, |
| then \verb|getinfo| returns \nil. |
| |
| The returned table contains all the fields returned by \verb|lua_getinfo|, |
| with the string \verb|what| describing what to get. |
| The default for \verb|what| is to get all information available. |
| The option \verb|f|, if present, |
| adds a field named \verb|func| with the function itself. |
| |
| For instance, the expression \verb|getinfo(1,"n").name| returns |
| the name of the current function, if a reasonable name can be found, |
| and \verb|getinfo(print)| returns a table with all available information |
| about the \verb|print| function. |
| |
| |
| \subsubsection*{\ff \T{getlocal (level, local)}}\DefLIB{getlocal} |
| |
| This function returns the name and the value of the local variable |
| with index \verb|local| of the function at level \verb|level| of the stack. |
| (The first parameter or local variable has index~1, and so on, |
| until the last active local variable.) |
| The function returns \nil\ if there is no local |
| variable with the given index, |
| and raises an error when called with a \verb|level| out of range. |
| (You can call \verb|getinfo| to check whether the level is valid.) |
| |
| \subsubsection*{\ff \T{setlocal (level, local, value)}}\DefLIB{setlocal} |
| |
| This function assigns the value \verb|value| to the local variable |
| with index \verb|local| of the function at level \verb|level| of the stack. |
| The function returns \nil\ if there is no local |
| variable with the given index, |
| and raises an error when called with a \verb|level| out of range. |
| |
| \subsubsection*{\ff \T{setcallhook (hook)}}\DefLIB{setcallhook} |
| |
| Sets the function \verb|hook| as the call hook; |
| this hook will be called every time the interpreter starts and |
| exits the execution of a function. |
| The only argument to the call hook is the event name (\verb|"call"| or |
| \verb|"return"|). |
| You can call \verb|getinfo| with level 2 to get more information about |
| the function being called or returning |
| (level~0 is the \verb|getinfo| function, |
| and level~1 is the hook function). |
| When called without arguments, |
| this function turns off call hooks. |
| \verb|setcallhook| returns the old hook. |
| |
| \subsubsection*{\ff \T{setlinehook (hook)}}\DefLIB{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 line hook is the line number the interpreter |
| is about to execute. |
| When called without arguments, |
| this function turns off line hooks. |
| \verb|setlinehook| returns the old hook. |
| |
| |
| \section{\Index{Lua Stand-alone}} \label{lua-sa} |
| |
| Although Lua has been designed as an extension language, |
| to be embedded in a host C~program, |
| it is frequently used as a stand-alone language. |
| An interpreter for Lua as a stand-alone language, |
| called simply \verb|lua|, |
| is provided with the standard distribution. |
| This program can be called with any sequence of the following arguments: |
| \begin{description}\leftskip=20pt |
| \item[\T{-sNUM}] sets the stack size to \T{NUM} |
| (if present, this must be the first option); |
| \item[\T{-} ] executes \verb|stdin| as a file; |
| \item[\T{-c}] calls \verb|lua_close| after running all arguments; |
| \item[\T{-e} \rm\emph{stat}] executes string \verb|stat|; |
| \item[\T{-f filename}] executes file \verb|filename| with the |
| remaining arguments in table \verb|arg|; |
| \item[\T{-i}] enters interactive mode with prompt; |
| \item[\T{-q}] enters interactive mode without prompt; |
| \item[\T{-v}] prints version information; |
| \item[\T{var=value}] sets global \verb|var| to string \verb|"value"|; |
| \item[\T{filename}] executes file \verb|filename|. |
| \end{description} |
| When called without arguments, |
| \verb|lua| behaves as \verb|lua -v -i| when \verb|stdin| is a terminal, |
| and as \verb|lua -| otherwise. |
| |
| All arguments are handled in order, except \verb|-c|. |
| 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| in \verb|stdin|, |
| then will set \verb|a| to \verb|"test"|, |
| and finally will run the file \verb|prog.lua|. |
| (Here, |
| \verb|$| is the shell prompt. Your prompt may be different.) |
| |
| When the option \T{-f filename} is used, |
| all remaining arguments in the command line |
| are passed to the Lua program \verb|filename| in a table called \verb|arg|. |
| In this table, |
| the field \verb|n| gets the index of the last argument, |
| and the field 0 gets \verb|"filename"|. |
| For instance, in the call |
| \begin{verbatim} |
| $ lua a.lua -f b.lua t1 t3 |
| \end{verbatim} |
| the interpreter first runs the file \T{a.lua}, |
| then creates a table |
| \begin{verbatim} |
| arg = {"t1", "t3"; n = 2, [0] = "b.lua"} |
| \end{verbatim} |
| and finally runs the file \T{b.lua}. |
| \DefLIB{getargs} |
| The stand-alone interpreter also provides a \verb|getargs| function that |
| can be used to access \emph{all} command line arguments. |
| For instance, if you call Lua with the line |
| \begin{verbatim} |
| $ lua -c a b |
| \end{verbatim} |
| then a call to \verb|getargs| in \verb|a| or \verb|b| will return the table |
| \begin{verbatim} |
| {[0] = "lua", [1] = "-c", [2] = "a", [3] = "b", n = 3} |
| \end{verbatim} |
| |
| In interactive mode, |
| a multi-line statement can be written finishing intermediate |
| lines with a backslash (`\verb|\|'). |
| If the global variable \IndexVerb{_PROMPT} is defined as a string, |
| then its value is used as the prompt. |
| Therefore, the prompt can be changed directly on the command line: |
| \begin{verbatim} |
| $ lua _PROMPT='myprompt> ' -i |
| \end{verbatim} |
| or in any Lua programs by assigning to \verb|_PROMPT|. |
| |
| In Unix systems, Lua scripts can be made into executable programs |
| by using \verb|chmod +x| and the~\verb|#!| form, |
| as in \verb|#!/usr/local/bin/lua|, |
| or \verb|#!/usr/local/bin/lua -f| to get other arguments. |
| |
| |
| \section*{Acknowledgments} |
| |
| The authors would like to thank CENPES/PETROBRAS which, |
| jointly with \tecgraf, used early versions of |
| this system extensively and gave valuable comments. |
| The authors would also like to thank Carlos Henrique Levy, |
| who found the name of the game. |
| Lua means ``moon'' in Portuguese. |
| |
| |
| \appendix |
| |
| \section*{Incompatibilities with Previous Versions} |
| \addcontentsline{toc}{section}{Incompatibilities with Previous Versions} |
| |
| We took a great care to avoid incompatibilities with |
| the previous public versions of Lua, |
| but some differences had to be introduced. |
| Here is a list of all these incompatibilities. |
| |
| |
| \subsection*{Incompatibilities with \Index{version 4.0}} |
| |
| \subsubsection*{Changes in the Language} |
| \begin{itemize} |
| |
| \item |
| Function calls written between parentheses result in exactly one value. |
| |
| \item |
| A function call as the last expression in a list constructor |
| (like \verb|{a,b,f()}}|) has all its return values inserted in the list. |
| |
| \item |
| \rwd{global} and \rwd{in} are reserved words. |
| |
| \item |
| When a literal string of the form \verb|[[...]]| starts with a newline, |
| this newline is ignored. |
| |
| \item Old pre-compiled code is obsolete, and must be re-compiled. |
| |
| \end{itemize} |
| |
| |
| \subsubsection*{Changes in the Libraries} |
| \begin{itemize} |
| |
| \item |
| The \verb|read| option \verb|*w| is obsolete. |
| |
| \item |
| The \verb|format| option \verb|%n$| is obsolete. |
| |
| \item |
| \verb|newtag| is deprecated, being replaced by \verb|newtype|. |
| Tags created in Lua with \verb|newtype| (or \verb|newtag|) can only |
| be used for tables. |
| |
| \end{itemize} |
| |
| |
| \subsubsection*{Changes in the API} |
| \begin{itemize} |
| |
| \item |
| The \verb|lua_pushuserdata| function has been replaced by |
| \verb|lua_newuserdatabox|. |
| |
| \end{itemize} |
| |
| %{=============================================================== |
| \section*{The Complete Syntax of Lua} \label{BNF} |
| |
| \addcontentsline{toc}{section}{The Complete Syntax of Lua} |
| |
| \renewenvironment{Produc}{\vspace{0.8ex}\par\noindent\hspace{3ex}\it\begin{tabular}{rrl}}{\end{tabular}\vspace{0.8ex}\par\noindent} |
| |
| \renewcommand{\OrNL}{\\ & \Or & } |
| %\newcommand{\Nter}[1]{{\rm{\tt#1}}} |
| \newcommand{\Nter}[1]{#1} |
| |
| \index{grammar} |
| |
| |
| |
| \begin{Produc} |
| |
| \produc{chunk}{\rep{stat \opt{\ter{;}}}} |
| |
| \produc{block}{chunk} |
| |
| \produc{stat}{% |
| varlist1 \ter{=} explist1 |
| \OrNL functioncall |
| \OrNL \rwd{do} block \rwd{end} |
| \OrNL \rwd{while} exp \rwd{do} block \rwd{end} |
| \OrNL \rwd{repeat} block \rwd{until} exp |
| \OrNL \rwd{if} exp \rwd{then} block |
| \rep{\rwd{elseif} exp \rwd{then} block} |
| \opt{\rwd{else} block} \rwd{end} |
| \OrNL \rwd{return} \opt{explist1} |
| \OrNL \rwd{break} |
| \OrNL \rwd{for} \Nter{name} \ter{=} exp \ter{,} exp \opt{\ter{,} exp} |
| \rwd{do} block \rwd{end} |
| \OrNL \rwd{for} \Nter{name} \ter{,} \Nter{name} \rwd{in} exp |
| \rwd{do} block \rwd{end} |
| \OrNL \rwd{function} funcname \ter{(} \opt{parlist1} \ter{)} block \rwd{end} |
| \OrNL \rwd{local} declist \opt{init} |
| } |
| |
| \produc{funcname}{\Nter{name} \rep{\ter{.} \Nter{name}} |
| \opt{\ter{:} \Nter{name}}} |
| |
| \produc{varlist1}{var \rep{\ter{,} var}} |
| |
| \produc{var}{% |
| \Nter{name} |
| \Or varorfunc \ter{[} exp \ter{]} |
| \Or varorfunc \ter{.} \Nter{name} |
| } |
| |
| \produc{varorfunc}{var \Or functioncall} |
| |
| \produc{declist}{\Nter{name} \rep{\ter{,} \Nter{name}}} |
| |
| \produc{init}{\ter{=} explist1} |
| |
| \produc{explist1}{\rep{exp \ter{,}} exp} |
| |
| \produc{exp}{% |
| \rwd{nil} |
| \Or \Nter{number} |
| \Or \Nter{literal} |
| \Or var |
| \Or function |
| \Or upvalue |
| \OrNL functioncall |
| \Or tableconstructor |
| \Or \ter{(} exp \ter{)} |
| \Or exp binop exp |
| \Or unop exp |
| } |
| |
| |
| \produc{functioncall}{% |
| varorfunc args |
| \Or varorfunc \ter{:} \Nter{name} args |
| } |
| |
| \produc{args}{% |
| \ter{(} \opt{explist1} \ter{)} |
| \Or tableconstructor |
| \Or \Nter{literal} |
| } |
| |
| \produc{function}{\rwd{function} \ter{(} \opt{parlist1} \ter{)} block \rwd{end}} |
| |
| \produc{parlist1}{% |
| \ter{\ldots} |
| \Or \Nter{name} \rep{\ter{,} \Nter{name}} \opt{\ter{,} \ter{\ldots}} |
| } |
| |
| \produc{upvalue}{\ter{\%} \Nter{name}} |
| |
| \produc{tableconstructor}{\ter{\{} fieldlist \ter{\}}} |
| \produc{fieldlist}{% |
| lfieldlist |
| \Or ffieldlist |
| \Or lfieldlist \ter{;} ffieldlist |
| \Or ffieldlist \ter{;} lfieldlist |
| } |
| \produc{lfieldlist}{\opt{explist1 \opt{\ter{,}}}} |
| \produc{ffieldlist}{\opt{ffieldlist1}} |
| \produc{ffieldlist1}{ffield \rep{\ter{,} ffield} \opt{\ter{,}}} |
| \produc{ffield}{% |
| \ter{[} exp \ter{]} \ter{=} exp |
| \Or \Nter{name} \ter{=} exp |
| } |
| |
| \produc{binop}{\ter{+} \Or \ter{-} \Or \ter{*} \Or \ter{/} \Or \ter{\^{ }} \Or |
| \ter{..} \OrNL \ter{<} \Or \ter{<=} \Or \ter{>} \Or \ter{>=} |
| \Or \ter{==} \Or \ter{\~{ }=} \OrNL \rwd{and} \Or \rwd{or}} |
| |
| \produc{unop}{\ter{-} \Or \rwd{not}} |
| |
| \end{Produc} |
| %}=============================================================== |
| |
| % Index |
| |
| \newpage |
| \addcontentsline{toc}{section}{Index} |
| \input{manual.id} |
| |
| \end{document} |