| % $Id: manual.tex,v 1.63 2002/11/18 14:39:34 roberto Exp roberto $ |
| %{[( |
| |
| \documentclass[11pt,twoside]{article} |
| \usepackage{fullpage} |
| \usepackage{bnf} |
| \usepackage{graphicx} |
| |
| % no need for subscripts... |
| \catcode`\_=12 |
| |
| %\newcommand{\See}[1]{Section~\ref{#1}} |
| \newcommand{\See}[1]{\S\ref{#1}} |
| %\newcommand{\see}[1]{(see~\See{#1} on page \pageref{#1})} |
| \newcommand{\see}[1]{(see~\See{#1})} |
| \newcommand{\seepage}[1]{(see page~\pageref{#1})} |
| \newcommand{\M}[1]{{\rm\emph{#1}}} |
| \newcommand{\T}[1]{{\tt #1}} |
| \newcommand{\Math}[1]{$#1$} |
| \newcommand{\nil}{{\bf nil}} |
| \newcommand{\False}{{\bf false}} |
| \newcommand{\True}{{\bf true}} |
| %\def\tecgraf{{\sf TeC\kern-.21em\lower.7ex\hbox{Graf}}} |
| \def\tecgraf{{\sf Tecgraf}} |
| |
| \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{metamethod!#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{\IndexKW}[1]{\index{keywords!#1@{\tt #1}}} |
| |
| \newcommand{\ff}{$\bullet$\ } |
| |
| \newcommand{\Version}{5.0 (beta)} |
| |
| % changes to bnf.sty by LHF |
| \renewcommand{\Or}{$|$ } |
| \renewcommand{\rep}[1]{{\rm\{}\,#1\,{\rm\}}} |
| \renewcommand{\opt}[1]{{\rm [}\,#1\,{\,\rm]}} |
| \renewcommand{\ter}[1]{{\rm`{\tt#1}'}} |
| \newcommand{\Nter}[1]{{\tt#1}} |
| \newcommand{\NOTE}{\par\medskip\noindent\emph{NOTE}: } |
| |
| \makeindex |
| |
| \begin{document} |
| |
| %{=============================================================== |
| \thispagestyle{empty} |
| \pagestyle{empty} |
| |
| { |
| \parindent=0pt |
| \vglue1.5in |
| {\LARGE\bf |
| The Lua Programming Language} |
| \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 |
| \parindent=0pt |
| \footnotesize |
| \null\vfill |
| |
| \noindent |
| Copyright \copyright\ 2002 Tecgraf, PUC-Rio. All rights reserved. |
| |
| Permission is hereby granted, free of charge, |
| to any person obtaining a copy of this software |
| and associated documentation files (the "Software"), |
| to deal in the Software without restriction, |
| including without limitation the rights to use, copy, modify, |
| merge, publish, distribute, sublicense, |
| and/or sell copies of the Software, |
| and to permit persons to whom the Software is furnished to do so, |
| subject to the following conditions: |
| |
| The above copyright notice and this permission notice shall be |
| included in all copies or substantial portions of the Software. |
| |
| THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, |
| EXPRESS OR IMPLIED, |
| INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, |
| FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. |
| IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE |
| FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, |
| WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, |
| ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE |
| OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| |
| |
| Copies of this manual can be obtained at |
| Lua's official web site, |
| \verb|www.lua.org|. |
| |
| \bigskip |
| 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\qquad |
| Luiz Henrique de Figueiredo\qquad |
| 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: 2002/11/18 14:39:34 $ $}} |
| |
| \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 opcodes, |
| and has automatic memory management with garbage collection, |
| making it ideal for |
| configuration, |
| scripting, |
| and |
| rapid prototyping. |
| |
| This document describes version \Version\ of the Lua programming language |
| and the 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{opcodes}, |
| 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} or simply the \emph{host}. |
| This host program can invoke functions to execute a piece of Lua code, |
| 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 software, |
| and is provided as usual with no guarantees, |
| as stated in its copyright notice. |
| The implementation described in this manual is available |
| at Lua's official web site, \verb|www.lua.org|. |
| |
| 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 Lua's web site. |
| \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. |
| \item |
| R.~Ierusalimschy, L.~H.~de Figueiredo, and W.~Celes. |
| The evolution of an extension language: a history of Lua, |
| \emph{Proceedings of V Brazilian Symposium on Programming Languages} (2001) B-14--B-28. |
| \end{itemize} |
| |
| Lua means ``moon'' in Portuguese. |
| |
| %------------------------------------------------------------------------------ |
| \section{Lua Concepts}\label{concepts} |
| |
| This section describes the main concepts of Lua as a language. |
| The syntax and semantics of Lua are described in \See{language}. |
| The discussion below is not purely conceptual; |
| it includes references to the C~API \see{API}, |
| because Lua is designed to be embedded in host programs. |
| It also includes references to the standard libraries \see{libraries}. |
| |
| |
| \subsection{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. |
| The host program can create multiple independent global |
| environments, and freely switch between them \see{mangstate}. |
| |
| The unit of execution of Lua is called a \Def{chunk}. |
| A chunk is simply a sequence of statements. |
| Statements are described in \See{stats}. |
| |
| 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 opcodes for |
| a virtual machine, |
| and then the compiled statements are executed |
| by an interpreter for the virtual machine. |
| All modifications a chunk makes to 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. |
| Programs in source and compiled forms are interchangeable; |
| Lua automatically detects the file type and acts accordingly. |
| \index{pre-compilation} |
| |
| |
| \subsection{Table of Globals} \label{global-table} |
| |
| ???? |
| |
| \subsection{\Index{Values and Types}} \label{TypesSec} |
| |
| Lua is a \emph{dynamically typed language}. |
| That means that |
| variables do not have types; only values do. |
| There are no type definitions in the language. |
| All values carry their own type. |
| |
| There are eight \Index{basic types} in Lua: |
| \Def{nil}, \Def{boolean}, \Def{number}, |
| \Def{string}, \Def{function}, \Def{userdata}, \Def{thread}, and \Def{table}. |
| \emph{Nil} is the type of the value \nil, |
| whose main property is to be different from any other value; |
| usually it represents the absence of a useful value. |
| \emph{Boolean} is the type of the values \False{} and \True. |
| In Lua, both \nil{} and \False{} make a condition false, |
| and any other value makes it true. |
| \emph{Number} represents real (double-precision floating-point) numbers. |
| \emph{String} represents arrays of characters. |
| \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}. |
| |
| Functions are \emph{first-class values} in Lua. |
| That 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 |
| \see{functioncall}. |
| |
| The type \emph{userdata} is provided to allow arbitrary C data to |
| be stored in Lua variables. |
| This type corresponds to a block of raw memory |
| and has no pre-defined operations in Lua, |
| except assignment and identity test. |
| However, by using \emph{metatables}, |
| the programmer can define operations for userdata values |
| \see{metatable}. |
| Userdata values cannot be created or modified in Lua, |
| only through the C~API. |
| This guarantees the integrity of data owned by the host program. |
| |
| The type \Def{thread} represents independent threads of execution, |
| and it is used to implement coroutines. |
| (This is an experimental area; it needs more documentation, |
| and is subject to changes in the future.) |
| |
| 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). |
| Moreover, |
| tables can be \emph{heterogeneous}, |
| that is, they can contain values of all types. |
| Tables are the sole data structuring mechanism in Lua; |
| they may be used not only to represent ordinary arrays, |
| but also symbol tables, sets, records, graphs, trees, etc. |
| 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"]|. |
| There are several convenient ways to create tables in Lua |
| \see{tableconstructor}. |
| |
| Like indices, the value of a table field can be of any type. |
| In particular, |
| because functions are first class values, |
| table fields may contain functions. |
| So, tables may also carry \emph{methods} \see{func-def}. |
| |
| Tables, functions, and userdata values are \emph{objects}: |
| variables do not actually \emph{contain} these values, |
| only \emph{references} to them. |
| Assignment, parameter passing, and function returns |
| always manipulate references to these values, |
| and do not imply any kind of copy. |
| |
| The library function \verb|type| returns a string describing the type |
| of a given value \see{pdf-type}. |
| |
| |
| \subsubsection{Metatables} |
| |
| Each table and userdata object in Lua may have a \Index{metatable}. |
| |
| You can change several aspects of the behavior |
| of an object by setting specific fields in its metatable. |
| For instance, when an object is the operand of an addition, |
| Lua checks for a function in the field \verb|"__add"| in its metatable. |
| If it finds one, |
| Lua calls that function to perform the addition. |
| |
| We call the keys in a metatable \Index{events}, |
| and the values \Index{metamethods}. |
| In the previous example, \verb|"add"| is the event, |
| and the function is the metamethod that performs the addition. |
| |
| A metatable controls how an object behaves in arithmetic operations, |
| order comparisons, concatenation, and indexing. |
| A metatable can also define a function to be called when a userdata |
| is garbage collected. |
| \See{metatable} gives a detailed description of which events you |
| can control with metatables. |
| |
| You can query and change the metatable of an object |
| through the \verb|setmetatable| and \verb|getmetatable| |
| functions \see{pdf-getmetatable}. |
| |
| |
| |
| \subsection{Coercion} \label{coercion} |
| |
| Lua provides automatic conversion between |
| string and number 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, |
| the 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}. |
| For complete control of how numbers are converted to strings, |
| use the \verb|format| function \see{format}. |
| |
| |
| \subsection{Variables} |
| |
| There are two kinds of variables in Lua: |
| global variables |
| and local variables. |
| Variables are assumed to be global unless explicitly declared local |
| \see{localvar}. |
| Before the first assignment, the value of a variable is \nil. |
| |
| All global variables live as fields in ordinary Lua tables. |
| Usually, globals live in a table called \Index{table of globals}. |
| However, a function can individually change its global table, |
| so that all global variables in that function will refer to that table. |
| This mechanism allows the creation of \Index{namespaces} and other |
| modularization facilities. |
| |
| \Index{Local variables} are lexically scoped. |
| Therefore, local variables can be freely accessed by functions |
| defined inside their scope \see{visibility}. |
| |
| |
| \subsection{Garbage Collection}\label{GC} |
| |
| Lua does automatic memory management. |
| That means that |
| you do not have to worry about allocating memory for new objects |
| and freeing it when the objects are no longer needed. |
| Lua manages memory automatically by running |
| a \Index{garbage collector} from time to time |
| and |
| collecting all dead objects |
| (all objects that are no longer accessible from Lua). |
| All objects in Lua are subject to automatic management: |
| tables, userdata, functions, and strings. |
| |
| Using the C~API, |
| you can set garbage-collector metamethods for userdata \see{metatable}. |
| When it is about to free a userdata, |
| Lua calls the metamethod associated with event \verb|gc| in the |
| userdata's metatable. |
| Using such facility, you can coordinate Lua's garbage collection |
| with external resource management |
| (such as closing files, network or database connections, |
| or freeing your own memory). |
| |
| 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. |
| 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 query 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 effectively stops the garbage collector. |
| Using Lua code you have a more limited control over garbage-collection cycles, |
| through the functions \verb|gcinfo| and \verb|collectgarbage| |
| \see{predefined}. |
| |
| |
| \subsubsection{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. |
| In other words, |
| if the only references to an object are weak references, |
| then 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 prevents the collection of its values. |
| A table with both weak keys and weak values allows the collection of |
| both keys and values. |
| 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 value of the |
| \verb|__mode| field of its metatable. |
| If the \verb|__mode| field is a string containing the \verb|k| character, |
| the keys in the table are weak. |
| If \verb|__mode| contains \verb|v|, |
| the values in the table are weak. |
| |
| |
| %------------------------------------------------------------------------------ |
| \section{The Language}\label{language} |
| |
| This section describes the lexis, the syntax, and the semantics of Lua. |
| In other words, |
| this section describes |
| which tokens are valid, |
| how they can be combined, |
| and what their combinations mean. |
| |
| \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. |
| (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 \IndexEmph{keywords} are reserved, |
| and cannot be used as identifiers: |
| \index{reserved words} |
| \begin{verbatim} |
| and break do else elseif |
| end false for function if |
| in local nil not or |
| repeat return then true until |
| while |
| \end{verbatim} |
| |
| Lua is a case-sensitive language: |
| \T{and} is a reserved word, but \T{And} and \T{\'and} |
| (if the locale permits) are two different, valid identifiers. |
| As a convention, identifiers starting with an underscore followed by |
| uppercase letters (such as \verb|_VERSION|) |
| 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|\0|'. |
| |
| Literal strings can also be delimited by matching \verb|[[| $\ldots$ \verb|]]|. |
| Literals in this bracketed form may run for several lines, |
| may contain nested \verb|[[| $\ldots$ \verb|]]| pairs, |
| and do not interpret escape sequences. |
| For convenience, |
| when the opening \verb|[[| is immediately followed by a newline, |
| the newline is not included in the string. % ]] |
| That form is specially convenient for |
| writing strings that contain program pieces or |
| other quoted strings. |
| As an example, in a system using ASCII |
| (in which `\verb|a|' is coded as~97, |
| newline is coded as~10, and `\verb|1|' is coded as~49), |
| the four literals below denote the same string: |
| \begin{verbatim} |
| (1) "alo\n123\"" |
| (2) '\97lo\10\04923"' |
| (3) [[alo |
| 123"]] |
| (4) [[ |
| alo |
| 123"]] |
| \end{verbatim} |
| |
| \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} |
| |
| \IndexEmph{Comments} start anywhere outside a string with a |
| double hyphen (\verb|--|); |
| If the text after \verb|--| is different from \verb|[[|, |
| the comment is a short comment, |
| that runs until the end of the line. |
| Otherwise, it is a long comment, |
| that runs until the corresponding \verb|]]|. |
| Long comments may run for several lines, |
| and may contain nested \verb|[[| $\ldots$ \verb|]]| pairs. |
| For convenience, |
| 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}. |
| |
| |
| \subsection{Variables}\label{variables} |
| |
| Variables are places that store values. |
| %In Lua, variables are given by simple identifiers or by table fields. |
| |
| A single name can denote a global variable, a local variable, |
| or a formal parameter in a function |
| (formal parameters are just local variables): |
| \begin{Produc} |
| \produc{var}{\Nter{Name}} |
| \end{Produc}% |
| Square brackets are used to index a table: |
| \begin{Produc} |
| \produc{var}{prefixexp \ter{[} exp \ter{]}} |
| \end{Produc}% |
| The first expression should result in a table value, |
| and the second expression identifies a specific entry inside that table. |
| |
| The syntax \verb|var.NAME| is just syntactic sugar for |
| \verb|var["NAME"]|: |
| \begin{Produc} |
| \produc{var}{prefixexp \ter{.} \Nter{Name}} |
| \end{Produc}% |
| |
| The expression denoting the table to be indexed has a restricted syntax; |
| \See{expressions} for details. |
| |
| The meaning of assignments and evaluations of global and |
| indexed variables can be changed via metatables. |
| An assignment to a global variable \verb|x = val| |
| is equivalent to the assignment |
| \verb|_glob.x = val|, |
| where \verb|_glob| is the table of globals of the running function |
| (\see{global-table} for a discussion about the table of globals). |
| An assignment to an indexed variable \verb|t[i] = val| is equivalent to |
| \verb|settable_event(t,i,val)|. |
| An access to a global variable \verb|x| |
| is equivalent to \verb|_glob.x| |
| (again, \see{global-table} for a discussion about \verb|_glob|). |
| An access to an indexed variable \verb|t[i]| is equivalent to |
| a call \verb|gettable_event(t,i)|. |
| See \See{metatable} for a complete description of the |
| \verb|settable_event| and \verb|gettable_event| functions. |
| (These functions are not defined in Lua. |
| We use them here only for explanatory purposes.) |
| |
| |
| \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 |
| and variable declarations. |
| |
| \subsubsection{Chunks}\label{chunks} |
| 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}% |
| |
| \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 to produce a single statement: |
| \begin{Produc} |
| \produc{stat}{\rwd{do} block \rwd{end}} |
| \end{Produc}% |
| \IndexKW{do} |
| Explicit blocks are useful |
| to control the scope of variable declarations. |
| 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}} |
| \produc{explist1}{exp \rep{\ter{,} exp}} |
| \end{Produc}% |
| Expressions are discussed in \See{expressions}. |
| |
| Before the assignment, |
| the list of values is \emph{adjusted} to the length of |
| the list of variables.\index{adjustment} |
| If there are more values than needed, |
| the excess values are thrown away. |
| If there are less values than needed, |
| the list is extended with as many \nil's as needed. |
| If the list of expressions ends with a function call, |
| then all values returned by that function call enter in the list of values, |
| before the adjust |
| (except when the call is enclosed in parentheses; see \See{expressions}). |
| |
| The assignment statement first evaluates all its expressions, |
| and only then makes the assignments. |
| So, the code |
| \begin{verbatim} |
| i = 3 |
| i, a[i] = i+1, 20 |
| \end{verbatim} |
| sets \verb|a[3]| to 20, without affecting \verb|a[4]| |
| because the \verb|i| in \verb|a[i]| is evaluated |
| before it is assigned 4. |
| Similarly, the line |
| \begin{verbatim} |
| x, y = y, x |
| \end{verbatim} |
| exchanges the values of \verb|x| and \verb|y|. |
| |
| \subsubsection{Control Structures}\label{control} |
| The control structures |
| \rwd{if}, \rwd{while}, and \rwd{repeat} have the usual meaning and |
| familiar syntax: |
| \index{while-do statement}\IndexKW{while} |
| \index{repeat-until statement}\IndexKW{repeat}\IndexKW{until} |
| \index{if-then-else statement}\IndexKW{if}\IndexKW{else}\IndexKW{elseif} |
| \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}% |
| Lua also has a \rwd{for} statement, in two flavors \see{for}. |
| |
| The \Index{condition expression} \M{exp} of a |
| control structure may return any value. |
| All values different from \nil{} and \False{} are considered true |
| (in particular, the number 0 and the empty string are also true); |
| both \False{} and \nil{} are considered false. |
| |
| The \rwd{return} statement is used to return values |
| from a function or from a chunk.\IndexKW{return} |
| \label{return}% |
| \index{return statement}% |
| Functions and chunks may return more than one value, |
| and so 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 |
| \rwd{while}, \rwd{repeat}, or \rwd{for} loop, |
| skipping to the next statement after the loop:\IndexKW{break} |
| \index{break statement} |
| \begin{Produc} |
| \produc{stat}{\rwd{break}} |
| \end{Produc}% |
| A \rwd{break} ends the innermost enclosing loop. |
| |
| \NOTE |
| For syntactic reasons, \rwd{return} and \rwd{break} |
| statements can only be written as the \emph{last} statement of a block. |
| If it is really necessary to \rwd{return} or \rwd{break} in the |
| middle of a block, |
| then an explicit inner block can used, |
| as in the idioms |
| `\verb|do return end|' and |
| `\verb|do break end|', |
| because now \rwd{return} and \rwd{break} are the last statements in |
| their (inner) blocks. |
| In practice, |
| those idioms are only used during debugging. |
| (For instance, a line `\verb|do return end|' can be added at the |
| beginning of a chunk for syntax checking only.) |
| |
| \subsubsection{For Statement} \label{for}\index{for statement} |
| |
| The \rwd{for} statement has two forms, |
| one for numbers and one generic. |
| \IndexKW{for}\IndexKW{in} |
| |
| The numerical \rwd{for} loop repeats a block of code while a |
| control variable runs through an arithmetic progression. |
| It has the following syntax: |
| \begin{Produc} |
| \produc{stat}{\rwd{for} \Nter{Name} \ter{=} exp \ter{,} exp \opt{\ter{,} exp} |
| \rwd{do} block \rwd{end}} |
| \end{Produc}% |
| The \emph{block} is repeated for \emph{name} starting at the value of |
| the first \emph{exp}, until it reaches the second \emph{exp} by steps of the |
| third \emph{exp}. |
| More precisely, 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 Both the limit and the step are evaluated only once, |
| before the loop starts. |
| \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 You can use \rwd{break} to exit a \rwd{for} loop. |
| \item The loop variable \verb|var| is local to the statement; |
| you cannot use its value after the \rwd{for} ends or is broken. |
| If you need the value of the loop variable \verb|var|, |
| then assign it to another variable before breaking or exiting the loop. |
| \end{itemize} |
| |
| The generic \rwd{for} statement works over functions, |
| called \Index{generators}. |
| It calls its generator to produce a new value for each iteration, |
| stopping when the new value is \nil. |
| It has the following syntax: |
| \begin{Produc} |
| \produc{stat}{\rwd{for} \Nter{Name} \rep{\ter{,} \Nter{Name}} \rwd{in} explist1 |
| \rwd{do} block \rwd{end}} |
| \end{Produc}% |
| A \rwd{for} statement like |
| \begin{verbatim} |
| for var_1, ..., var_n in explist do block end |
| \end{verbatim} |
| is equivalent to the code: |
| \begin{verbatim} |
| do |
| local _f, _s, var_1, ..., var_n = explist |
| while 1 do |
| var_1, ..., var_n = _f(_s, var_1) |
| if var_1 == nil then break end |
| block |
| end |
| end |
| \end{verbatim} |
| Note the following: |
| \begin{itemize}\itemsep=0pt |
| \item \verb|explist| is evaluated only once. |
| Its results are a ``generator'' function, |
| a ``state'', and an initial value for the ``iterator variable''. |
| \item \verb|_f| and \verb|_s| are invisible variables. |
| The names are here for explanatory purposes only. |
| \item The behavior is \emph{undefined} if you assign to any |
| \verb|var_i| inside the block. |
| \item You can use \rwd{break} to exit a \rwd{for} loop. |
| \item The loop variables \verb|var_i| are local to the statement; |
| you cannot use their values after the \rwd{for} ends. |
| If you need these values, |
| then assign them to other variables before breaking or exiting the loop. |
| \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:\IndexKW{local} |
| \begin{Produc} |
| \produc{stat}{\rwd{local} namelist \opt{\ter{=} explist1}} |
| \produc{namelist}{\Nter{Name} \rep{\ter{,} \Nter{Name}}} |
| \end{Produc}% |
| If present, an initial assignment has the same semantics |
| of a multiple assignment \see{assignment}. |
| Otherwise, all variables are initialized with \nil. |
| |
| A chunk is also a block \see{chunks}, |
| and so local variables can be declared outside any explicit block. |
| Such local variables die when the chunk ends. |
| |
| Visibility rules for local variables are explained in \See{visibility}. |
| |
| |
| \subsection{\Index{Expressions}}\label{expressions} |
| |
| %\subsubsection{\Index{Basic Expressions}} |
| The basic expressions in Lua are the following: |
| \begin{Produc} |
| \produc{exp}{prefixexp} |
| \produc{exp}{\rwd{nil} \Or \rwd{false} \Or \rwd{true}} |
| \produc{exp}{Number} |
| \produc{exp}{Literal} |
| \produc{exp}{function} |
| \produc{exp}{tableconstructor} |
| \produc{prefixexp}{var \Or functioncall \Or \ter{(} exp \ter{)}} |
| \end{Produc}% |
| \IndexKW{nil}\IndexKW{false}\IndexKW{true} |
| |
| An expression enclosed in parentheses always results in only one value. |
| Thus, |
| \verb|(f(x,y,z))| is always a single value, |
| even if \verb|f| returns several values. |
| (The value of \verb|(f(x,y,z))| is the first value returned by \verb|f| |
| or \nil{} if \verb|f| does not return any values.) |
| |
| \emph{Numbers} and \emph{literal strings} are explained in \See{lexical}; |
| variables are explained in \See{variables}; |
| function definitions are explained in \See{func-def}; |
| function calls are explained in \See{functioncall}; |
| table constructors are explained in \See{tableconstructor}. |
| |
| Expressions can also be built with arithmetic operators, relational operators, |
| and logical operadors, all of which are explained below. |
| |
| \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 \see{coercion}, |
| then all operations except exponentiation have the usual meaning, |
| while exponentiation calls a global function \verb|pow|; ?? |
| otherwise, an appropriate metamethod is called \see{metatable}. |
| The standard mathematical library defines function \verb|pow|, |
| giving the expected meaning to \Index{exponentiation} |
| \see{mathlib}. |
| |
| \subsubsection{Relational Operators}\label{rel-ops} |
| The \Index{relational operators} in Lua are |
| \begin{verbatim} |
| == ~= < > <= >= |
| \end{verbatim} |
| These operators always result in \False{} or \True. |
| |
| Equality (\verb|==|) first compares the type of its operands. |
| If the types are different, then the result is \False. |
| Otherwise, the values of the operands are compared. |
| Numbers and strings are compared in the usual way. |
| Tables, userdata, and functions are compared \emph{by reference}, |
| that is, |
| two tables are considered equal only if they are the \emph{same} table. |
| |
| %% TODO eq metamethod |
| |
| Every time you create a new table (or userdata, or function), |
| this new value is different from any previously existing value. |
| |
| \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 operator \verb|~=| is exactly the negation of equality (\verb|==|). |
| |
| 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 according to the current locale. |
| Otherwise, the ``lt'' or the ``le'' metamethod is called \see{metatable}. |
| |
| |
| \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 \see{control}, |
| all logical operators consider both \False{} and \nil{} as false |
| and anything else as true. |
| \IndexKW{and}\IndexKW{or}\IndexKW{not} |
| |
| The operator \rwd{not} always return \False{} or \True. |
| |
| The conjunction operator \rwd{and} returns its first argument |
| if its value is \False{} or \nil; |
| otherwise, \rwd{and} returns its second argument. |
| The disjunction operator \rwd{or} returns its first argument |
| if it is different from \nil and \False; |
| otherwise, \rwd{or} returns its second argument. |
| Both \rwd{and} and \rwd{or} use \Index{short-cut evaluation}, |
| that is, |
| the second operand is evaluated only if necessary. |
| For example, |
| \begin{verbatim} |
| 10 or error() -> 10 |
| nil or "a" -> "a" |
| nil and 10 -> nil |
| false and error() -> false |
| false and nil -> false |
| false or nil -> nil |
| 10 and 20 -> 20 |
| \end{verbatim} |
| |
| \subsubsection{Concatenation} \label{concat} |
| The string \Index{concatenation} operator in Lua is |
| denoted by two dots (`\verb|..|'). |
| If both operands are strings or numbers, then they are converted to |
| strings according to the rules mentioned in \See{coercion}. |
| Otherwise, the ``concat'' metamethod is called \see{metatable}. |
| |
| \subsubsection{Precedence} |
| \Index{Operator precedence} in Lua follows the table below, |
| from lower to higher priority: |
| \begin{verbatim} |
| or |
| and |
| < > <= >= ~= == |
| .. |
| + - |
| * / |
| not - (unary) |
| ^ |
| \end{verbatim} |
| The \verb|..| (concatenation) and \verb|^| (exponentiation) |
| operators are right associative. |
| All other binary operators are left associative. |
| |
| \subsubsection{Table Constructors} \label{tableconstructor} |
| Table \Index{constructors} are expressions that create tables; |
| every time a constructor is evaluated, a new table is created. |
| Constructors can be used to create empty tables, |
| or to create a table and initialize some of its fields. |
| The general syntax for constructors is |
| \begin{Produc} |
| \produc{tableconstructor}{\ter{\{} \opt{fieldlist} \ter{\}}} |
| \produc{fieldlist}{field \rep{fieldsep field} \opt{fieldsep}} |
| \produc{field}{\ter{[} exp \ter{]} \ter{=} exp \Or |
| \Nter{Name} \ter{=} exp \Or exp} |
| \produc{fieldsep}{\ter{,} \Or \ter{;}} |
| \end{Produc}% |
| |
| Each field of the form \verb|[exp1] = exp2| adds to the new table an entry |
| with key \verb|exp1| and value \verb|exp2|. |
| A field of the form \verb|name = exp| is equivalent to |
| \verb|["name"] = exp|. |
| Finally, fields of the form \verb|exp| are equivalent to |
| \verb|[i] = exp|, where \verb|i| are consecutive numerical integers, |
| starting with 1. |
| Fields in the other formats do not affect this counting. |
| For example, |
| \begin{verbatim} |
| a = {[f(1)] = g; "x", "y"; x = 1, f(x), [30] = 23; 45} |
| \end{verbatim} |
| is equivalent to |
| \begin{verbatim} |
| do |
| local temp = {} |
| temp[f(1)] = g |
| temp[1] = "x" -- 1st exp |
| temp[2] = "y" -- 2nd exp |
| temp.x = 1 -- temp["x"] = 1 |
| temp[3] = f(x) -- 3rd exp |
| temp[30] = 23 |
| temp[4] = 45 -- 4th exp |
| a = temp |
| end |
| \end{verbatim} |
| |
| If the last expression in the list is a function call, |
| then all values returned by the call enter the list consecutively |
| \see{functioncall}. |
| If you want to avoid this, |
| enclose the function call in parentheses. |
| |
| The field list may have an optional trailing separator, |
| as a convenience for machine-generated code. |
| |
| |
| \subsubsection{Function Calls} \label{functioncall} |
| A \Index{function call} in Lua has the following syntax: |
| \begin{Produc} |
| \produc{functioncall}{prefixexp args} |
| \end{Produc}% |
| In a function call, |
| first \M{prefixexp} and \M{args} are evaluated. |
| If the value of \M{prefixexp} has type \emph{function}, |
| then that function is called, |
| with the given arguments. |
| Otherwise, its ``call'' metamethod is called, |
| having as first parameter the value of \M{prefixexp}, |
| followed by the original call arguments |
| \see{metatable}. |
| |
| The form |
| \begin{Produc} |
| \produc{functioncall}{prefixexp \ter{:} \Nter{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{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 elements, |
| 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 element, |
| 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 |
| (unless the call is enclosed in parentheses). |
| |
| 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 enclose a function call in parentheses, |
| then it is adjusted to return exactly one value: |
| \begin{verbatim} |
| return x,y,(f()) -- returns x, y, and the first value from f() |
| {(f())} -- creates a table with exactly one element |
| \end{verbatim} |
| |
| As an exception to the format-free syntax of Lua, |
| you cannot put a line break before the \verb|(| in a function call. |
| That restriction avoids some ambiguities in the language. |
| If you write |
| \begin{verbatim} |
| a = f |
| (g).x(a) |
| \end{verbatim} |
| Lua would read that as \verb|a = f(g).x(a)|. |
| So, if you want two statements, you must add a semi-colon between them. |
| If you actually want to call \verb|f|, |
| you must remove the line break before \verb|(g)|. |
| |
| |
| \subsubsection{\Index{Function Definitions}} \label{func-def} |
| |
| The syntax for function definition is\IndexKW{function} |
| \begin{Produc} |
| \produc{function}{\rwd{function} funcbody} |
| \produc{funcbody}{\ter{(} \opt{parlist1} \ter{)} block \rwd{end}} |
| \end{Produc}% |
| |
| The following syntactic sugar simplifies function definitions: |
| \begin{Produc} |
| \produc{stat}{\rwd{function} funcname funcbody} |
| \produc{stat}{\rwd{local} \rwd{function} \Nter{name} funcbody} |
| \produc{funcname}{\Nter{name} \rep{\ter{.} \Nter{name}} \opt{\ter{:} \Nter{name}}} |
| \end{Produc}% |
| The statement |
| \begin{verbatim} |
| function f () ... end |
| \end{verbatim} |
| translates to |
| \begin{verbatim} |
| f = function () ... end |
| \end{verbatim} |
| The statement |
| \begin{verbatim} |
| function t.a.b.c.f () ... end |
| \end{verbatim} |
| translates to |
| \begin{verbatim} |
| t.a.b.c.f = function () ... end |
| \end{verbatim} |
| The statement |
| \begin{verbatim} |
| local function f () ... end |
| \end{verbatim} |
| translates to |
| \begin{verbatim} |
| local f; 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, |
| 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 refer to different non-local variables \see{visibility} |
| and may have different tables of globals \see{global-table}. |
| |
| Parameters act as local variables, |
| initialized with the argument values: |
| \begin{Produc} |
| \produc{parlist1}{namelist \opt{\ter{,} \ter{\ldots}}} |
| \produc{parlist1}{\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}. |
| Thus, the statement |
| \begin{verbatim} |
| function t.a.b.c:f (...) ... end |
| \end{verbatim} |
| is syntactic sugar for |
| \begin{verbatim} |
| t.a.b.c.f = function (self, ...) ... end |
| \end{verbatim} |
| |
| |
| \subsection{Visibility Rules} \label{visibility} |
| \index{visibility} |
| |
| Lua is a lexically scoped language. |
| The scope of variables begins at the first statement \emph{after} |
| their declaration and lasts until the end of the innermost block that |
| includes the declaration. |
| For instance: |
| \begin{verbatim} |
| x = 10 -- global variable |
| do -- new block |
| local x = x -- new `x', with value 10 |
| print(x) --> 10 |
| x = x+1 |
| do -- another block |
| local x = x+1 -- another `x' |
| print(x) --> 12 |
| end |
| print(x) --> 11 |
| end |
| print(x) --> 10 (the global one) |
| \end{verbatim} |
| Notice that, in a declaration like \verb|local x = x|, |
| the new \verb|x| being declared is not in scope yet, |
| so the second \verb|x| refers to the ``outside'' variable. |
| |
| Because of those \Index{lexical scoping} rules, |
| local variables can be freely accessed by functions |
| defined inside their scope. |
| For instance: |
| \begin{verbatim} |
| local counter = 0 |
| function inc (x) |
| counter = counter + x |
| return counter |
| end |
| \end{verbatim} |
| |
| Notice that each execution of a \rwd{local} statement |
| ``creates'' new local variables. |
| Consider the following example: |
| \begin{verbatim} |
| a = {} |
| local x = 20 |
| for i=1,10 do |
| local y = 0 |
| a[i] = function () y=y+1; return x+y end |
| end |
| \end{verbatim} |
| In that code, |
| each function uses a different \verb|y| variable, |
| while all of them share the same \verb|x|. |
| |
| \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 \see{pcall}. |
| Whenever an error occurs during Lua compilation or execution, |
| control returns to C, |
| which can take appropriate measures |
| (such as to print an error message). |
| |
| Lua code can explicitly generate an error by calling the |
| function \verb|error| \see{pdf-error}. |
| If you need to catch errors in Lua, |
| you can use the \verb|pcall| function \see{pdf-pcall}. |
| |
| |
| \subsection{Metatables} \label{metatable} |
| |
| Every table and userdata value in Lua may have a \emph{metatable}. |
| This \IndexEmph{metatable} is a table that defines the behavior of |
| the original table and userdata under some operations. |
| You can query and change the metatable of an object with |
| functions \verb|setmetatable| and \verb|getmetatable| \see{pdf-getmetatable}. |
| |
| For each of those operations Lua associates a specific key, |
| called an \emph{event}. |
| When Lua performs one of those operations over a table or a userdata, |
| if checks whether that object has a metatable with the corresponding event. |
| If so, the value associated with that key (the \IndexEmph{metamethod}) |
| controls how Lua will perform the operation. |
| |
| Metatables control the operations listed next. |
| Each operation is identified by its corresponding name. |
| The key for each operation is a string with its name prefixed by |
| two underscores; |
| for instance, the key for operation ``add'' is the |
| string \verb|"__add"|. |
| The semantics of these operations is better explained by a Lua function |
| describing how the interpreter executes that operation. |
| %Each function shows how a handler is called, |
| %its arguments (that is, its signature), |
| %its results, |
| %and the default behavior in the absence of a handler. |
| 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|, etc.) |
| are described in \See{predefined}. |
| |
| \begin{description} |
| |
| \item[``add'':]\IndexTM{add} |
| the \verb|+| operation. |
| |
| The function \verb|getbinhandler| below defines how Lua chooses a handler |
| for a binary operation. |
| First, Lua tries the first operand. |
| If its type does not define a handler for the operation, |
| then Lua tries the second operand. |
| \begin{verbatim} |
| function getbinhandler (op1, op2, event) |
| return metatable(op1)[event] or metatable(op2)[event] |
| end |
| \end{verbatim} |
| Using that function, |
| the behavior of the ``add'' operation 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 h = getbinhandler(op1, op2, "__add") |
| if h then |
| -- call the handler with both operands |
| return h(op1, op2) |
| else -- no handler available: default behavior |
| error("unexpected type at arithmetic operation") |
| end |
| end |
| end |
| \end{verbatim} |
| |
| \item[``sub'':]\IndexTM{sub} |
| the \verb|-| operation. |
| Behavior similar to the ``add'' operation. |
| |
| \item[``mul'':]\IndexTM{mul} |
| the \verb|*| operation. |
| Behavior similar to the ``add'' operation. |
| |
| \item[``div'':]\IndexTM{div} |
| the \verb|/| operation. |
| Behavior similar to the ``add'' operation. |
| |
| \item[``pow'':]\IndexTM{pow} |
| the \verb|^| operation (exponentiation) operation. |
| \begin{verbatim} ?? |
| function pow_event (op1, op2) |
| local h = getbinhandler(op1, op2, "__pow") ??? |
| if h then |
| -- call the handler with both operands |
| return h(op1, op2) |
| else -- no handler available: default behavior |
| error("unexpected type at arithmetic operation") |
| end |
| end |
| \end{verbatim} |
| |
| \item[``unm'':]\IndexTM{unm} |
| the unary \verb|-| operation. |
| \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 handler from the operand; |
| local h = metatable(op).__unm |
| if h then |
| -- call the handler with the operand and nil |
| return h(op, nil) |
| else -- no handler available: default behavior |
| error("unexpected type at arithmetic operation") |
| end |
| end |
| end |
| \end{verbatim} |
| |
| \item[``lt'':]\IndexTM{lt} |
| the \verb|<| operation. |
| \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 h = getbinhandler(op1, op2, "__lt") |
| if h then |
| return h(op1, op2) |
| else |
| error("unexpected type at comparison"); |
| end |
| end |
| end |
| \end{verbatim} |
| \verb|a>b| is equivalent to \verb|b<a|. |
| |
| \item[``le'':]\IndexTM{lt} |
| the \verb|<=| operation. |
| \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 h = getbinhandler(op1, op2, "__le") |
| if h then |
| return h(op1, op2) |
| else |
| h = getbinhandler(op1, op2, "__lt") |
| if h then |
| return not h(op2, op1) |
| else |
| error("unexpected type at comparison"); |
| end |
| end |
| end |
| end |
| \end{verbatim} |
| \verb|a>=b| is equivalent to \verb|b<=a|. |
| Notice that, in the absence of a ``le'' metamethod, |
| Lua tries the ``lt'', assuming that \verb|a<=b| is |
| equivalent to \verb|not (b<a)|. |
| |
| |
| \item[``concat'':]\IndexTM{concatenation} |
| the \verb|..| (concatenation) operation. |
| \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 h = getbinhandler(op1, op2, "__concat") |
| if h then |
| return h(op1, op2) |
| else |
| error("unexpected type for concatenation") |
| end |
| end |
| end |
| \end{verbatim} |
| |
| \item[``index'':]\IndexTM{index} |
| The ``gettable'' operation \verb|table[key]|. |
| \begin{verbatim} |
| function gettable_event (table, key) |
| local h |
| if type(table) == "table" then |
| local v = rawget(table, key) |
| if v ~= nil then return v end |
| h = metatable(table).__index |
| if h == nil then return nil end |
| else |
| h = metatable(table).__index |
| if h == nil then |
| error("indexed expression not a table"); |
| end |
| end |
| if type(h) == "function" then |
| return h(table, key) -- call the handler |
| else return h[key] -- or repeat operation with it |
| end |
| \end{verbatim} |
| |
| \item[``newindex'':]\IndexTM{index} |
| The ``settable'' operation \verb|table[key] = value|. |
| \begin{verbatim} |
| function settable_event (table, key, value) |
| local h |
| if type(table) == "table" then |
| local v = rawget(table, key) |
| if v ~= nil then rawset(table, key, value); return end |
| h = metatable(table).__newindex |
| if h == nil then rawset(table, key, value); return end |
| else |
| h = metatable(table).__newindex |
| if h == nil then |
| error("indexed expression not a table"); |
| end |
| end |
| if type(h) == "function" then |
| return h(table, key,value) -- call the handler |
| else h[key] = value -- or repeat operation with it |
| end |
| \end{verbatim} |
| |
| |
| \item[``call'':]\IndexTM{call} |
| called when Lua calls a value. |
| \begin{verbatim} |
| function function_event (func, ...) |
| if type(func) == "function" then |
| return func(unpack(arg)) -- regular call |
| else |
| local h = metatable(func).__call |
| if h then |
| tinsert(arg, 1, func) |
| return h(unpack(arg)) |
| else |
| error("call expression not a function") |
| end |
| end |
| end |
| \end{verbatim} |
| |
| \end{description} |
| |
| \subsubsection{Metatables and Garbage collection} |
| |
| Metatables may also define \IndexEmph{finalizer} methods |
| for userdata values. |
| For each userdata to be collected, |
| Lua does the equivalent of the following function: |
| \begin{verbatim} |
| function gc_event (obj) |
| local h = metatable(obj).__gc |
| if h then |
| h(obj) |
| end |
| end |
| \end{verbatim} |
| In a garbage-collection cycle, |
| the finalizers for userdata are called in \emph{reverse} |
| order of their creation, |
| that is, the first finalizer to be called is the one associated |
| with the last userdata created in the program |
| (among those to be collected in the same cycle). |
| |
| |
| |
| \subsection{Coroutines} |
| |
| Lua supports coroutines, |
| also called \emph{semi-coroutines}, \emph{generators}, |
| or \emph{colaborative multithreading}. |
| A coroutine in Lua represents an independent thread of execution. |
| Unlike ``real'' threads, however, |
| a coroutine only suspends its execution by explicitly calling |
| an yield function. |
| |
| You create a coroutine with a call to \IndexVerb{coroutine.create}. |
| Its sole argument is a function, |
| which is the main function of the coroutine. |
| The \verb|coroutine.create| only creates a new coroutine and |
| returns a handle to it (an object of type \emph{thread}). |
| It does not start the coroutine execution. |
| |
| When you first call \IndexVerb{coroutine.resume}, |
| passing as argument the thread returned by \verb|coroutine.create|, |
| the coroutine starts its execution, |
| at the first line of its main function. |
| Extra arguments passed to \verb|coroutine.resume| are given as |
| parameters for the coroutine main function. |
| After the coroutine starts running, |
| it runs until it terminates or it \emph{yields}. |
| |
| A coroutine can terminate its execution in two ways: |
| Normally, when its main function returns |
| (explicitly or implicitly, after the last instruction); |
| and abnormally, if there is an unprotected error. |
| In the first case, \verb|coroutine.resume| returns \True, |
| plus any values returned by the coroutine main function. |
| In case of errors, \verb|coroutine.resume| returns \False |
| plus an error message. |
| |
| A coroutine yields calling \IndexVerb{coroutine.yield}. |
| When a coroutine yields, |
| the corresponding \verb|coroutine.resume| returns immediately, |
| even if the yield happens inside nested function calls |
| (that is, not in the main function, |
| but in a function directly or indirectly called by the main function). |
| In the case of a yield, \verb|coroutine.resume| also returns \True, |
| plus any values passed to \verb|coroutine.yield|. |
| The next time you resume the same coroutine, |
| it continues its execution from the point where it yielded, |
| with the call to \verb|coroutine.yield| returning any extra |
| arguments passed to \verb|coroutine.resume|. |
| |
| The \IndexVerb{coroutine.wrap} function creates a coroutine |
| like \verb|coroutine.create|, |
| but instead of returning the coroutine itself, |
| it returns a function that, when called, resumes the coroutine. |
| Any arguments passed to that function |
| go as extra arguments to resume. |
| The function returns all the values returned by resume, |
| but the first one (the boolean error code). |
| Unlike \verb|coroutine.resume|, |
| this function does not catch errors; |
| any error is propagated to the caller. |
| |
| As a complete example, |
| consider the next code: |
| \begin{verbatim} |
| function foo1 (a) |
| print("foo", a) |
| return coroutine.yield(2*a) |
| end |
| |
| co = coroutine.create(function (a,b) |
| print("co-body", a, b) |
| local r = foo1(a+1) |
| print("co-body", r) |
| local r, s = coroutine.yield(a+b, a-b) |
| print("co-body", r, s) |
| return b, "end" |
| end) |
| |
| a, b = coroutine.resume(co, 1, 10) |
| print("main", a, b) |
| a, b, c = coroutine.resume(co, "r") |
| print("main", a, b, c) |
| a, b, c = coroutine.resume(co, "x", "y") |
| print("main", a, b, c) |
| a, b = coroutine.resume(co, "x", "y") |
| print("main", a, b) |
| \end{verbatim} |
| When you run it, it produces the following output: |
| \begin{verbatim} |
| co-body 1 10 |
| foo 2 |
| main true 4 |
| co-body r |
| main true 11 -9 |
| co-body x y |
| main true 10 end |
| main false cannot resume dead coroutine |
| \end{verbatim} |
| |
| |
| |
| %------------------------------------------------------------------------------ |
| \section{The Application Program Interface}\label{API} |
| \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 Lua state), |
| and so do not generate hidden side-effects. |
| |
| |
| \subsection{States} \label{mangstate} |
| |
| The Lua library is fully reentrant: |
| it has no global variables. |
| \index{state} |
| The whole state of the Lua interpreter |
| (global variables, stack, 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 (void); |
| \end{verbatim} |
| \DefAPI{lua_open} |
| |
| 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 metamethods, if any) |
| and frees all dynamic memory used by that state. |
| On several platforms, you may not need to call this function, |
| because all resources are naturally released when the host 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 large. |
| |
| 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 of execution. |
| If you have a C~library that offers multi-threading, |
| then Lua can cooperate with it to implement the equivalent facility in Lua. |
| Also, Lua implements its own coroutine system on top of threads. |
| The following function creates a new ``thread'' in Lua: |
| \begin{verbatim} |
| lua_State *lua_newthread (lua_State *L); |
| \end{verbatim} |
| \DefAPI{lua_newthread} |
| The new state returned by this function shares with the original state |
| all global environment (such as tables), |
| but has an independent run-time 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 that of the given state, |
| but you can change each one independently. |
| |
| You destroy threads with \DefAPI{lua_closethread} |
| \begin{verbatim} |
| void lua_closethread (lua_State *L, lua_State *thread); |
| \end{verbatim} |
| You cannot close the sole (or last) thread of a state. |
| Instead, you must close the state itself. |
| |
| |
| \subsection{The Stack and Indices} |
| |
| Lua uses a virtual \emph{stack} to pass values to and from C. |
| Each element in this stack represents a Lua value |
| (\nil, number, string, etc.). |
| |
| Each C invocation has its own stack. |
| Whenever Lua calls C, the called function gets a new stack, |
| which is independent of previous stacks or of stacks of still |
| active C functions. |
| That stack contains initially any arguments to the C function, |
| and it is where the C function pushes its results \see{LuacallC}. |
| |
| 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); |
| a negative index represents an \emph{offset} from the top of the stack. |
| More specifically, if the stack has \M{n} elements, |
| then index~1 represents the first element |
| (that is, the element that was pushed onto the stack first), |
| 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_checkstack (lua_State *L, int extra); |
| \end{verbatim} |
| \DefAPI{lua_checkstack} |
| grows the stack size to \verb|top + extra| elements; |
| it returns false if it cannot grow the stack to that size. |
| This function never shrinks the stack; |
| if the stack is already bigger than the new size, |
| it is left unchanged. |
| |
| Whenever Lua calls C, \DefAPI{LUA_MINSTACK} |
| it ensures that \verb|lua_checkstack(L, LUA_MINSTACK)| is true, |
| that is, |
| at least \verb|LUA_MINSTACK| positions are still available. |
| \verb|LUA_MINSTACK| is defined in \verb|lua.h| as 20, |
| so that usually you do not have to worry about stack space |
| unless your code has loops pushing elements onto the stack. |
| |
| Most query functions accept as indices any value inside the |
| available stack space, that is, indices up to the maximum stack size |
| you (or Lua) have set through \verb|lua_checkstack|. |
| Such indices are called \emph{acceptable indices}. |
| More formally, we define an \IndexEmph{acceptable index} |
| as follows: |
| \begin{verbatim} |
| (index < 0 && abs(index) <= top) || (index > 0 && index <= top + stackspace) |
| \end{verbatim} |
| Note that 0 is never an acceptable index. |
| |
| Unless otherwise noticed, |
| any function that accepts valid indices can also be called with |
| \Index{pseudo-indices}, |
| which represent some Lua values that are accessible to the C~code |
| but are not in the stack. |
| Pseudo-indices are used to access the table of globals \see{globals}, |
| the registry, and the upvalues of a C function \see{c-closure}. |
| |
| \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); |
| void lua_replace (lua_State *L, int index); |
| \end{verbatim} |
| \DefAPI{lua_settop}\DefAPI{lua_pushvalue} |
| \DefAPI{lua_remove}\DefAPI{lua_insert}\DefAPI{lua_replace} |
| |
| \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 \verb|lua.h| 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 copy of the element |
| at the given index. |
| \verb|lua_remove| removes the element at the given position, |
| shifting down the elements above that position to fill the gap. |
| \verb|lua_insert| moves the top element into the given position, |
| shifting up the elements above that position to open space. |
| \verb|lua_replace| moves the top element into the given position, |
| without shifting any element (therefore replacing the value at |
| the given position). |
| These functions accept only valid indices. |
| (Obviously, you cannot call \verb|lua_remove| or \verb|lua_insert| with |
| pseudo-indices, as they do not represent a stack position.) |
| |
| As an example, if the stack starts as \verb|10 20 30 40 50*| |
| (from bottom to top; the \verb|*| marks the 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_replace(L, 2) --> 30 40 20 30* |
| lua_settop(L, -3) --> 30 40* |
| lua_settop(L, 6) --> 30 40 nil 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_type (lua_State *L, int index); |
| int lua_isnil (lua_State *L, int index); |
| int lua_isboolean (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); |
| int lua_islightuserdata (lua_State *L, int index); |
| \end{verbatim} |
| \DefAPI{lua_type} |
| \DefAPI{lua_isnil}\DefAPI{lua_isnumber}\DefAPI{lua_isstring} |
| \DefAPI{lua_istable}\DefAPI{lua_isboolean} |
| \DefAPI{lua_isfunction}\DefAPI{lua_iscfunction} |
| \DefAPI{lua_isuserdata}\DefAPI{lua_islightuserdata} |
| These functions can be called with any acceptable index. |
| |
| \verb|lua_type| returns the type of a value in the stack, |
| or \verb|LUA_TNONE| for a non-valid index |
| (that is, if that stack position is ``empty''). |
| The types are coded by the following constants |
| defined in \verb|lua.h|: |
| \verb|LUA_TNIL|, |
| \verb|LUA_TNUMBER|, |
| \verb|LUA_TBOOLEAN|, |
| \verb|LUA_TSTRING|, |
| \verb|LUA_TTABLE|, |
| \verb|LUA_TFUNCTION|, |
| \verb|LUA_TUSERDATA|, |
| \verb|LUA_TLIGHTUSERDATA|. |
| The following function translates such constants to a type name: |
| \begin{verbatim} |
| const char *lua_typename (lua_State *L, int type); |
| \end{verbatim} |
| \DefAPI{lua_typename} |
| |
| The \verb|lua_is*| functions return~1 if the object is compatible |
| with the given type, and 0 otherwise. |
| \verb|lua_isboolean| is an exception to this rule, |
| and it succeeds only for boolean values |
| (otherwise it would be useless, |
| as any value has a boolean value). |
| 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}, |
| \verb|lua_isfunction| accepts both Lua functions and C~functions, |
| and \verb|lua_isuserdata| accepts both full and ligth userdata. |
| To distinguish between Lua functions and C~functions, |
| you should use \verb|lua_iscfunction|. |
| To distinguish between full and ligth userdata, |
| you can use \verb|lua_islightuserdata|. |
| To distinguish between numbers and numerical strings, |
| you can use \verb|lua_type|. |
| |
| 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 \see{rel-ops}. |
| Both functions return 0 if any of the indices are non-valid. |
| |
| \subsection{Getting Values from the Stack}\label{lua-to} |
| |
| To translate a value in the stack to a specific C~type, |
| you can use the following conversion functions: |
| \begin{verbatim} |
| int lua_toboolean (lua_State *L, int index); |
| lua_Number 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}\DefAPI{lua_toboolean} |
| 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_toboolean| converts the Lua value at the given index |
| to a C ``boolean'' value (that is, 0 or 1). |
| Like all tests in Lua, it returns 1 for any Lua value different from |
| \False{} and \nil; |
| otherwise it returns 0. |
| It also returns 0 when called with a non-valid index. |
| (If you want to accept only real boolean values, |
| use \verb|lua_isboolean| to test the type of the value.) |
| |
| \verb|lua_tonumber| converts the Lua value at the given index |
| to a number (by default, \verb|lua_Number| is \verb|double|). |
| \DefAPI{lua_Number} |
| The Lua value must be a number or a string convertible to number |
| \see{coercion}; otherwise, \verb|lua_tonumber| returns~0. |
| |
| \verb|lua_tostring| converts the Lua value at the given index to a string |
| (\verb|const char*|). |
| The Lua value must be a string or a number; |
| otherwise, the function returns \verb|NULL|. |
| If the value is a number, |
| then \verb|lua_tostring| also |
| \emph{changes the actual value in the stack to a string}. |
| (This change confuses \verb|lua_next| |
| when \verb|lua_tostring| is applied to keys.) |
| \verb|lua_tostring| returns a fully aligned pointer |
| to a string inside the Lua environment. |
| This string always has a zero (\verb|'\0'|) |
| after its last character (as in~C), |
| but may contain other zeros in its 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 corresponding value is removed from the stack. |
| So, if you need the string after the current function returns, |
| then you should duplicate it (or put it into the registry \see{registry}). |
| |
| \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| is explained in \See{userdata}. |
| |
| |
| \subsection{Pushing Values onto the Stack} |
| |
| The API has the following functions to |
| push C~values onto the stack: |
| \begin{verbatim} |
| void lua_pushboolean (lua_State *L, int b); |
| void lua_pushnumber (lua_State *L, lua_Number 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); |
| void lua_pushlightuserdata (lua_State *L, void *p); |
| \end{verbatim} |
| |
| \DefAPI{lua_pushnumber}\DefAPI{lua_pushlstring}\DefAPI{lua_pushstring} |
| \DefAPI{lua_pushcfunction}\DefAPI{lua_pushlightuserdata}\DefAPI{lua_pushboolean} |
| \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 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. |
| |
| You can also push ``formatted'' strings: |
| \begin{verbatim} |
| const char *lua_pushfstring (lua_State *L, const char *fmt, ...); |
| const char *lua_pushvfstring (lua_State *L, const char *fmt, |
| va_list argp); |
| \end{verbatim} |
| \DefAPI{lua_pushfstring}\DefAPI{lua_pushvfstring} |
| Both functions push onto the stack a formatted string, |
| and return a pointer to that string. |
| These functions are similar to \verb|sprintf| and \verb|vsprintf|, |
| but with some important differences: |
| \begin{itemize} |
| \item You do not have to allocate the space for the result; |
| the result is a Lua string, and Lua takes care of memory allocation |
| (and deallocation, later). |
| \item The conversion specifiers are quite restricted. |
| There are no flags, widths, or precisions. |
| The conversion specifiers can be simply |
| \verb|%%| (inserts a \verb|%| in the string), |
| \verb|%s| (inserts a zero-terminated string, with no size restrictions), |
| \verb|%f| (inserts a \verb|lua_Number|), |
| \verb|%d| (inserts an \verb|int|), |
| \verb|%c| (inserts an \verb|int| as a character). |
| \end{itemize} |
| |
| |
| \subsection{Controlling Garbage Collection}\label{GC-API} |
| |
| Lua uses two numbers to control its garbage collection: |
| the \emph{count} and the \emph{threshold} \see{GC}. |
| The first counts the ammount of memory in use by Lua; |
| when the count reaches the threshold, |
| Lua runs its garbage collector. |
| After the collection, the count is updated, |
| and the threshold is set to twice the count value. |
| |
| 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. |
| In particular |
| \verb|lua_setgcthreshold(L,0)| forces a garbage collectiion. |
| After the collection, |
| a new threshold is set according to the previous rule. |
| |
| %% TODO do we need a new way to do that?? |
| % 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}\label{userdata} |
| |
| Userdata represents C values in Lua. |
| Lua supports two types of userdata: |
| \Def{full userdata} and \Def{light userdata}. |
| |
| A full userdata represents a block of memory. |
| It is an object (like a table): |
| You must create it, it can have its own metatable, |
| you can detect when it is being collected. |
| A full userdata is only equal to itself. |
| |
| A light userdata represents a pointer. |
| It is a value (like a number): |
| You do not create it, it has no metatables, |
| it is not collected (as it was never created). |
| A light userdata is equal to ``any'' |
| light userdata with the same address. |
| |
| In Lua code, there is no way to test whether a userdata is full or light; |
| both have type \verb|userdata|. |
| In C code, \verb|lua_type| returns \verb|LUA_TUSERDATA| for full userdata, |
| and \verb|LUA_LIGHTUSERDATA| for light userdata. |
| |
| You can create new full userdata with the following function: |
| \begin{verbatim} |
| void *lua_newuserdata (lua_State *L, size_t size); |
| \end{verbatim} |
| \DefAPI{lua_newuserdata} |
| It 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. |
| |
| To push a light userdata into the stack you use |
| \verb|lua_pushlightuserdata| \see{pushing}. |
| |
| \verb|lua_touserdata| \see{lua-to} retrieves the value of a userdata. |
| When applied on a full userdata, it returns the address of its block; |
| when applied on a light userdata, it returns its pointer; |
| when applied on a non-userdata value, it returns \verb|NULL|. |
| |
| When Lua collects a full userdata, |
| it calls its \verb|gc| metamethod, if any, |
| and then it frees its corresponding memory. |
| |
| |
| \subsection{Metatables} |
| |
| The following functions allow you do manipulate the metatables |
| of an object: |
| \begin{verbatim} |
| int lua_getmetatable (lua_State *L, int objindex); |
| int lua_setmetatable (lua_State *L, int objindex); |
| \end{verbatim} |
| \DefAPI{lua_getmetatable}\DefAPI{lua_setmetatable} |
| Both get at \verb|objindex| a valid index for an object. |
| \verb|lua_getmetatable| pushes on the stack the metatable of that object; |
| \verb|lua_setmetatable| sets the table on the top of the stack as the |
| new metatable for that object (and pops the table). |
| |
| If the object does not have a metatable, |
| \verb|lua_getmetatable| returns 0, and pushes nothing on the stack. |
| \verb|lua_setmetatable| returns 0 when it cannot |
| set the metatable of the given object |
| (that is, when the object is not a userdata nor a table); |
| even then it pops the table from the stack. |
| |
| \subsection{Loading Lua Chunks} |
| |
| You can load a Lua chunk with |
| \begin{verbatim} |
| typedef const char * (*lua_Chunkreader) |
| (lua_State *L, void *data, size_t *size); |
| |
| int lua_load (lua_State *L, lua_Chunkreader reader, void *data, |
| const char *chunkname); |
| \end{verbatim} |
| \DefAPI{Chunkreader}\DefAPI{lua_load} |
| The return values of \verb|lua_load| are: |
| \begin{itemize} |
| \item 0 --- no errors; |
| \item \IndexAPI{LUA_ERRSYNTAX} --- |
| syntax error during pre-compilation. |
| \item \IndexAPI{LUA_ERRMEM} --- |
| memory allocation error. |
| \end{itemize} |
| If there are no errors, |
| \verb|lua_load| pushes the compiled chunk as a Lua |
| function on top of the stack. |
| Otherwise, it pushes an error message. |
| |
| \verb|lua_load| automatically detects whether the chunk is text or binary, |
| and loads it accordingly (see program \IndexVerb{luac}). |
| |
| \verb|lua_load| uses the \emph{reader} to read the chunk. |
| Everytime it needs another piece of the chunk, |
| it calls the reader, |
| passing along its \verb|data| parameter. |
| The reader must return a pointer to a block of memory |
| with a new part of the chunk, |
| and set \verb|size| to the block size. |
| To signal the end of the chunk, the reader must return \verb|NULL|. |
| The reader function may return pieces of any size greater than zero. |
| |
| In the current implementation, |
| the reader function cannot call any Lua function; |
| to ensure that, it always receives \verb|NULL| as the Lua state. |
| |
| The \emph{chunkname} is used for error messages |
| and debug information \see{debugI}. |
| |
| See the auxiliar library (\verb|lauxlib|) |
| for examples of how to use \verb|lua_load|, |
| and for some ready-to-use functions to load chunks |
| from files and from strings. |
| |
| \subsection{Manipulating Tables} |
| |
| Tables are created by calling |
| the function |
| \begin{verbatim} |
| void lua_newtable (lua_State *L); |
| \end{verbatim} |
| \DefAPI{lua_newtable} |
| This function creates a new, empty table and pushes it onto the stack. |
| |
| To read a value from a table that resides somewhere in the stack, |
| call |
| \begin{verbatim} |
| void lua_gettable (lua_State *L, int index); |
| \end{verbatim} |
| \DefAPI{lua_gettable} |
| where \verb|index| points 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. |
| The table is left where it was in the stack; |
| this is convenient for getting multiple values from a table. |
| |
| As in Lua, this function may trigger a metamethod |
| for the ``gettable'' or ``index'' events \see{metatable}. |
| To get the real value of any table key, |
| without invoking any metamethod, |
| 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| points to the table. |
| \verb|lua_settable| pops from the stack both the key and the value. |
| The table is left where it was in the stack; |
| this is convenient for setting multiple values in a table. |
| |
| As in Lua, this operation may trigger a metamethod |
| for the ``settable'' or ``newindex'' events. |
| To set the real value of any table index, |
| without invoking any metamethod, |
| use the \emph{raw} version: |
| \begin{verbatim} |
| void lua_rawset (lua_State *L, int index); |
| \end{verbatim} |
| \DefAPI{lua_rawset} |
| |
| 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| points 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 \verb|lua_next| returns 0 |
| (and pushes nothing). |
| Use a \nil{} key to signal the start of a traversal. |
| |
| 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 `key' for next iteration */ |
| } |
| \end{verbatim} |
| |
| NOTE: |
| While traversing a table, |
| do not call \verb|lua_tostring| on a key, |
| unless you know the key is actually a string. |
| Recall that \verb|lua_tostring| \emph{changes} the value at the given index; |
| this confuses the next call to \verb|lua_next|. |
| |
| \subsection{Manipulating Global Variables} \label{globals} |
| |
| All global variables are kept in an ordinary Lua table. |
| This table is always at pseudo-index \IndexAPI{LUA_GLOBALSINDEX}. |
| |
| To access and change the value of global variables, |
| you can use regular table operations over the global table. |
| For instance, to access the value of a global variable, do |
| \begin{verbatim} |
| lua_pushstring(L, varname); |
| lua_gettable(L, LUA_GLOBALSINDEX); |
| \end{verbatim} |
| |
| You can change the global table of a Lua thread using \verb|lua_replace|. |
| |
| |
| \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); |
| \end{verbatim} |
| \DefAPI{lua_rawgeti} |
| \DefAPI{lua_rawseti} |
| |
| \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 this value from the stack. |
| |
| |
| \subsection{Calling 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 |
| in \emph{direct order}, that is, the first argument is pushed first. |
| Finally, the function is called using |
| \begin{verbatim} |
| void lua_call (lua_State *L, int nargs, int nresults); |
| \end{verbatim} |
| \DefAPI{lua_call} |
| \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. |
| Lua takes care that the returned values fit into the stack space. |
| The function results are pushed onto the stack 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 = f("how", t.x, 14) |
| \end{verbatim} |
| Here it is in~C: |
| \begin{verbatim} |
| lua_pushstring(L, "t"); |
| lua_gettable(L, LUA_GLOBALSINDEX); /* global `t' (for later use) */ |
| lua_pushstring(L, "a"); /* var name */ |
| lua_pushstring(L, "f"); /* function name */ |
| lua_gettable(L, LUA_GLOBALSINDEX); /* function to be called */ |
| lua_pushstring(L, "how"); /* 1st argument */ |
| lua_pushstring(L, "x"); /* push the string "x" */ |
| lua_gettable(L, -5); /* push result of t.x (2nd arg) */ |
| lua_pushnumber(L, 14); /* 3rd argument */ |
| lua_call(L, 3, 1); /* call function with 3 arguments and 1 result */ |
| lua_settable(L, LUA_GLOBALSINDEX); /* 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. |
| |
| (We did this example using only the raw functions provided by Lua's API, |
| to show all the details. |
| Usually programmers use several macros and auxiliar functions that |
| provide higher level access to Lua.) |
| |
| |
| \subsection{Protected Calls}\label{pcall} |
| |
| When you call a function with \verb|lua_call|, |
| any error inside the called function is propagated upwards |
| (with a \verb|longjmp|). |
| If you need to handle errors, |
| then you should use \verb|lua_pcall|: |
| \begin{verbatim} |
| int lua_pcall (lua_State *L, int nargs, int nresults, int errfunc); |
| \end{verbatim} |
| Both \verb|nargs| and \verb|nresults| have the same meaning as |
| in \verb|lua_call|. |
| If there are no errors during the call, |
| \verb|lua_pcall| behaves exactly like \verb|lua_call|. |
| Like \verb|lua_call|, |
| \verb|lua_pcall| always removes the function |
| and its arguments from the stack. |
| However, if there is any error, |
| \verb|lua_pcall| catches it, |
| pushes a single value at the stack (the error message), |
| and returns an error code. |
| |
| If \verb|errfunc| is 0, |
| then the error message returned is exactly the original error message. |
| Otherwise, \verb|errfunc| gives the stack index for an |
| \emph{error handler function}. |
| (In the current implementation, that index cannot be a pseudo-index.) |
| In case of runtime errors, |
| that function will be called with the error message, |
| and its return value will be the message returned by \verb|lua_pcall|. |
| |
| Typically, the error handler function is used to add more debug |
| information to the error message, such as a stack traceback. |
| Such information cannot be gathered after the return of \verb|lua_pcall|, |
| since by then the stack has unwound. |
| |
| The \verb|lua_pcall| function returns 0 in case of success, |
| or one of the following error codes |
| (defined in \verb|lua.h|): |
| \begin{itemize} |
| \item \IndexAPI{LUA_ERRRUN} --- a runtime error. |
| \item \IndexAPI{LUA_ERRMEM} --- memory allocation error. |
| For such errors, Lua does not call the error handler function. |
| \item \IndexAPI{LUA_ERRERR} --- |
| error while running the error handler function. |
| \end{itemize} |
| |
| |
| \medskip |
| |
| >>>> |
| %% TODO: mover essas 2 para algum lugar melhor. |
| 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); |
| \end{verbatim} |
| \DefAPI{lua_error} |
| The error message (which actually can be any type of object) |
| is popped from the stack. |
| 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)|. |
| %% TODO: at_panic |
| |
| 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. |
| If \verb|n| is 1, the result is that single string |
| (that is, the function does nothing); |
| if \verb|n| is 0, the result is the empty string. |
| Concatenation is done following the usual semantics of Lua |
| \see{concat}. |
| |
| |
| \subsection{Defining C Functions} \label{LuacallC} |
| |
| Lua can be extended with functions written in~C. |
| These functions must be of type \verb|lua_CFunction|, |
| which is defined as |
| \begin{verbatim} |
| typedef int (*lua_CFunction) (lua_State *L); |
| \end{verbatim} |
| \DefAPI{lua_CFunction} |
| A C~function receives a Lua environment and returns an integer, |
| the number of values it has returned to Lua. |
| |
| 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 its stack, |
| in direct order (the first argument is pushed first). |
| So, when the function starts, |
| its first argument (if any) is at index 1. |
| 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 */ |
| lua_Number sum = 0; |
| int i; |
| for (i = 1; i <= n; i++) { |
| if (!lua_isnumber(L, i)) { |
| lua_pushstring(L, "incorrect argument to function `average'"); |
| lua_error(L); |
| } |
| 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} |
| |
| To register a C~function to Lua, |
| there is the following convenience macro: |
| \begin{verbatim} |
| #define lua_register(L,n,f) \ |
| (lua_pushstring(L, n), \ |
| lua_pushcfunction(L, f), \ |
| lua_settable(L, LUA_GLOBALSINDEX)) |
| /* 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. |
| Thus, |
| the C~function `\verb|foo|' above may be registered in Lua as `\verb|average|' |
| by calling |
| \begin{verbatim} |
| lua_register(L, "average", foo); |
| \end{verbatim} |
| |
| \subsection{Defining C Closures} \label{c-closure} |
| |
| When a C~function is created, |
| it is possible to associate some values to it, |
| thus creating a \IndexEmph{C~closure}; |
| these values are then accessible to the function whenever it is called. |
| To associate values to a C~function, |
| first these values should be pushed onto the stack |
| (when there are multiple values, the first value 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 values should be |
| associated with the function |
| (\verb|lua_pushcclosure| also pops these values 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, |
| those values are located at specific pseudo-indices. |
| Those pseudo-indices are produced by a macro \IndexAPI{lua_upvalueindex}. |
| The first value associated with a function is at position |
| \verb|lua_upvalueindex(1)|, and so on. |
| |
| For 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. |
| |
| |
| \subsubsection*{Registry} \label{registry} |
| |
| Lua provides a pre-defined table that can be used by any C~code to |
| store whatever Lua value it needs to store, |
| especially if the C~code needs to keep that Lua value |
| outside the life span of a C~function. |
| This table is always located at pseudo-index |
| \IndexAPI{LUA_REGISTRYINDEX}. |
| Any C~library can store data into this table, |
| as long as it chooses keys different from other libraries. |
| Typically, you should use as key a string containing your library name, |
| or a light userdata with the address of a C object in your code. |
| |
| The integer keys in the registry are used by the reference mechanism, |
| implemented by the auxiliar library, |
| and therefore should not be used by other purposes. |
| |
| |
| %------------------------------------------------------------------------------ |
| \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. |
| |
| \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} |
| This function 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 { |
| int event; |
| const char *name; /* (n) */ |
| const char *namewhat; /* (n) `global', `local', `field', `method' */ |
| const char *what; /* (S) `Lua' function, `C' function, Lua `main' */ |
| const char *source; /* (S) */ |
| int currentline; /* (l) */ |
| int nups; /* (u) number of upvalues */ |
| int linedefined; /* (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 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 |
| (for instance, 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| |
| above: |
| `\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_pushstring(L, "f"); |
| lua_gettable(L, LUA_GLOBALSINDEX); /* get global `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}\leftskip=20pt |
| |
| \item[source] |
| If the function was defined in a string, |
| then \verb|source| is that string; |
| if the function was defined in a file, |
| then \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 how the function was |
| called or whether it is the value of a global variable to |
| find a suitable name. |
| If it cannot find a name, |
| then \verb|name| is set to \verb|NULL|. |
| |
| \item[namewhat] |
| Explains the previous field. |
| It can be \verb|"global"|, \verb|"local"|, \verb|"method"|, |
| \verb|"field"|, or \verb|""| (the empty string), |
| according to how the function was called. |
| (Lua uses the empty string when no other option seems to apply.) |
| |
| \item[nups] |
| Number of upvalues of the 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}. |
| \verb|lua_getlocal| gets the index \verb|n| of a local variable, |
| pushes its value onto the stack, |
| and returns its name. |
| \verb|lua_setlocal| assigns the value at the top of the stack |
| to the variable and returns its name. |
| Both functions return \verb|NULL| on failure, |
| that is |
| when 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 a mechanism of hooks: |
| user-defined C functions that are called during the program execution. |
| A hook may be called in four different events: |
| a \emph{call} event, when Lua calls a function; |
| a \emph{return} event, when Lua returns from a function; |
| a \emph{line} event, when Lua starts executing a new line of code; |
| and a \emph{count} event, that happens every ``count'' instructions. |
| Lua identifies them with the following constants: |
| \DefAPI{LUA_HOOKCALL}, \DefAPI{LUA_HOOKRET}, |
| \DefAPI{LUA_HOOKLINE}, and \DefAPI{LUA_HOOKCOUNT}. |
| |
| A hook has type \verb|lua_Hook|, defined as follows: |
| \begin{verbatim} |
| typedef void (*lua_Hook) (lua_State *L, lua_Debug *ar); |
| \end{verbatim} |
| \DefAPI{lua_Hook} |
| You can set the hook with the following function: |
| \begin{verbatim} |
| int lua_sethook (lua_State *L, lua_Hook func, unsigned long mask); |
| \end{verbatim} |
| \DefAPI{lua_sethook} |
| \verb|func| is the hook, |
| and \verb|mask| specifies at which events it will be called. |
| It is formed by a disjunction of the constants |
| \verb|LUA_MASKCALL|, |
| \verb|LUA_MASKRET|, |
| \verb|LUA_MASKLINE|, |
| plus the macro \verb|LUA_MASKCOUNT(count)|. |
| For each event, the hook is called as explained below: |
| \begin{description} |
| \item{call hook} called when the interpreter calls a function. |
| The hook is called just after Lua ``enters'' the new function. |
| \item{return hook} called when the interpreter returns from a function. |
| The hook is called just before Lua ``leaves'' the function. |
| \item{line hook} called when the interpreter is about to |
| start the execution of a new line of code, |
| or when it jumps back (even for the same line). |
| (For obvious reasons, this event does not happens while Lua is executing |
| a C function.) |
| \item{count hook} called after the interpreter executes every |
| \verb|count| instructions. |
| (For obvious reasons, this event does not happens while Lua is executing |
| a C function.) |
| \end{description} |
| |
| A hook is disabled with the mask zero. |
| |
| You can get the current hook and the current mask with the next functions: |
| \begin{verbatim} |
| lua_Hook lua_gethook (lua_State *L); |
| unsigned long lua_gethookmask (lua_State *L); |
| \end{verbatim} |
| \DefAPI{lua_gethook}\DefAPI{lua_gethookmask} |
| You can get the count inside a mask with the macro \verb|lua_getmaskcount|. |
| |
| Whenever a hook is called, its \verb|ar| argument has its field |
| \verb|event| set to the specific event that triggered the hook. |
| Moreover, for line events, the field \verb|currentline| is also set. |
| For the value of any other field, the hook must call \verb|lua_getinfo|. |
| |
| 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, |
| that execution ocurrs without any calls to hooks. |
| |
| |
| %------------------------------------------------------------------------------ |
| \section{Standard Libraries}\label{libraries} |
| |
| The standard libraries provide useful functions |
| that are implemented directly through the standard C~API. |
| Some of these functions provide essential services to the language |
| (e.g. \verb|type| and \verb|getmetatable|); |
| others provide access to ``outside'' servides (e.g. I/O); |
| and others could be implemented in Lua itself, |
| but are quite useful or have critical performance to |
| deserve an implementation in C (e.g. \verb|sort|). |
| |
| All libraries are implemented through the official C API, |
| and are provided as separate C~modules. |
| Currently, Lua has the following standard libraries: |
| \begin{itemize} |
| \item basic library; |
| \item string manipulation; |
| \item table manipulation; |
| \item mathematical functions (sin, log, etc.); |
| \item input and output; |
| \item operating system facilities; |
| \item debug facilities. |
| \end{itemize} |
| Except for the basic library, |
| each library provides all its functions as fields of a global table |
| or as methods of its objects. |
| |
| To have access to these libraries, |
| the C~host program must call the functions |
| \verb|lua_baselibopen| (for the basic library), |
| \verb|lua_strlibopen| (for the string library), |
| \verb|lua_tablibopen| (for the table library), |
| \verb|lua_mathlibopen| (for the mathematical library), |
| \verb|lua_iolibopen| (for the I/O and the Operating System libraries), |
| and \verb|lua_dblibopen| (for the debug library), |
| which are declared in \verb|lualib.h|. |
| \DefAPI{lua_baselibopen} |
| \DefAPI{lua_strlibopen} |
| \DefAPI{lua_tablibopen} |
| \DefAPI{lua_mathlibopen} |
| \DefAPI{lua_iolibopen} |
| \DefAPI{lua_dblibopen} |
| |
| |
| \subsection{Basic Functions} \label{predefined} |
| |
| The basic library provides some core functions to Lua. |
| 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. |
| |
| The basic library also defines a global variable \IndexLIB{_VERSION} |
| with a string containing the current interpreter version. |
| The current content of this string is {\tt "Lua \Version"}. |
| |
| \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 |
| error(m or "assertion failed!") |
| end |
| return v |
| end |
| \end{verbatim} |
| |
| \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). |
| |
| \subsubsection*{\ff \T{dofile (filename)}}\DefLIB{dofile} |
| Receives a file name, |
| opens the named file, and executes its contents as a Lua chunk. |
| When called without arguments, |
| \verb|dofile| executes the contents of the standard input (\verb|stdin|). |
| Returns any value returned by the chunk. |
| |
| \subsubsection*{\ff \T{error (message [, level])}} |
| DefLIB{error}\label{pdf-error} |
| Terminates the last protected function called, |
| and returns \verb|message| as the error message. |
| Function \verb|error| never returns. |
| |
| The \verb|level| argument affects to where the error |
| message points the error. |
| With level 1 (the default), the error position is where the |
| \verb|error| function was called. |
| Level 2 points the error to where the function |
| that called \verb|error| was called; and so on. |
| |
| \subsubsection*{\ff \T{getglobals (function)}}\DefLIB{getglobals} |
| Returns the current table of globals in use by the function. |
| \verb|function| can be a Lua function or a number, |
| meaning the function at that stack level: |
| Level 1 is the function calling \verb|getglobals|. |
| If the given function is not a Lua function, |
| returns the ``global'' table of globals. |
| The default for \verb|function| is 1. |
| |
| \subsubsection*{\ff \T{getmetatable (object)}} |
| \DefLIB{getmetatable}\label{pdf-getmetatable} |
| |
| Returns the metatable of the given object. |
| If the object does not have a metatable, returns \nil. |
| |
| \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{ipairs (t)}}\DefLIB{ipairs} |
| |
| Returns a generator function and the table \verb|t|, |
| so that the construction |
| \begin{verbatim} |
| for i,v in ipairs(t) do ... end |
| \end{verbatim} |
| will iterate over the pairs \verb|1, t[1]|, \verb|2, t[2]|, \ldots, |
| up to the first nil value of the table. |
| |
| \subsubsection*{\ff \T{loadfile (filename)}}\DefLIB{loadfile} |
| Loads a file as a Lua chunk. |
| If there is no errors, |
| returns the compiled chunk as a function; |
| otherwise, returns \nil{} plus an error message. |
| |
| \subsubsection*{\ff \T{loadstring (string [, chunkname])}}\DefLIB{loadstring} |
| Loads a string as a Lua chunk. |
| If there is no errors, |
| returns the compiled chunk as a function; |
| otherwise, returns \nil{} plus an error message. |
| |
| The optional parameter \verb|chunkname| |
| is the ``name of the chunk'', |
| used in error messages and debug information. |
| |
| To load and run a given string, use the idiom |
| \begin{verbatim} |
| assert(loadstring(s))() |
| \end{verbatim} |
| |
| \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|ipairs|). |
| |
| The behavior of \verb|next| is \emph{undefined} if you change |
| the table during the traversal. |
| |
| \subsubsection*{\ff \T{pairs (t)}}\DefLIB{pairs} |
| |
| Returns the function \verb|next| and the table \verb|t|, |
| so that the construction |
| \begin{verbatim} |
| for k,v in pairs(t) do ... end |
| \end{verbatim} |
| will iterate over all pairs of key--value of table \verb|t|. |
| |
| \subsubsection*{\ff \T{pcall (func, arg1, arg2, ...)}}\DefLIB{pcall} |
| \label{pdf-pcall} |
| Calls function \verb|func| with |
| the given arguments in protected mode. |
| That means that any error inside \verb|func| is not propagated; |
| instead, \verb|pcall| catches the error, |
| returning a status code. |
| Its first result is the status code (a boolean), |
| true if the call succeeds without errors. |
| In such case, \verb|pcall| also returns all results from the call, |
| after this first result. |
| In case of any error, \verb|pcall| returns false plus the error message. |
| |
| \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, |
| typically for debugging. |
| For formatted output, see \verb|format| \see{format}. |
| |
| \subsubsection*{\ff \T{rawget (table, index)}}\DefLIB{rawget} |
| Gets the real value of \verb|table[index]|, |
| without invoking any metamethod. |
| \verb|table| must be a table; |
| \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 metamethod. |
| \verb|table| must be a table; |
| \verb|index| is any value different from \nil; |
| and \verb|value| is any Lua value. |
| |
| \subsubsection*{\ff \T{require (packagename)}}\DefLIB{require} |
| |
| Loads the given package. |
| The function starts by looking into the table \IndexVerb{_LOADED} |
| whether \verb|packagename| is already loaded. |
| If it is, then \verb|require| is done. |
| Otherwise, it searches a path looking for a file to load. |
| |
| If the global variable \IndexVerb{LUA_PATH} is a string, |
| this string is the path. |
| Otherwise, \verb|require| tries the environment variable \verb|LUA_PATH|. |
| In the last resort, it uses a predefined path. |
| |
| The path is a sequence of \emph{templates} separated by semicolons. |
| For each template, \verb|require| will change an eventual interrogation |
| mark in the template to \verb|packagename|, |
| and then will try to load the resulting file name. |
| So, for instance, if the path is |
| \begin{verbatim} |
| "./?.lua;./?.lc;/usr/local/?/init.lua;/lasttry" |
| \end{verbatim} |
| a \verb|require "mod"| will try to load the files |
| \verb|./mod.lua|, |
| \verb|./mod.lc|, |
| \verb|/usr/local/mod/init.lua|, |
| and \verb|/lasttry|, in that order. |
| |
| The function stops the search as soon as it can load a file, |
| and then it runs the file. |
| If there is any error loading or running the file, |
| or if it cannot find any file in the path, |
| then \verb|require| signals an error. |
| Otherwise, it marks in table \verb|_LOADED| |
| that the package is loaded, and returns. |
| |
| While running a packaged file, |
| \verb|require| defines the global variable \IndexVerb{_REQUIREDNAME} |
| with the package name. |
| |
| \subsubsection*{\ff \T{setglobals (function, table)}}\DefLIB{setglobals} |
| Sets the current table of globals to be used by the given function. |
| \verb|function| can be a Lua function or a number, |
| meaning the function at that stack level: |
| Level 1 is the function calling \verb|setglobals|. |
| |
| \subsubsection*{\ff \T{setmetatable (table, metatable)}}\DefLIB{setmetatable} |
| |
| Sets the metatable for the given table. |
| (You cannot change the metatable of a userdata from Lua.) |
| If \verb|metatable| is \nil, removes the metatable of the given table. |
| |
| \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' (in 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 \verb|format| \see{format}. |
| |
| \subsubsection*{\ff \T{type (v)}}\DefLIB{type}\label{pdf-type} |
| Returns the 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{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 \M{n} of returned values |
| is either the value of \verb|list.n|, if it is a number, |
| or one less the index of the first absent (\nil) value. |
| |
| \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). |
| 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. |
| |
| The string library provides all its functions inside the table |
| \IndexLIB{string}. |
| |
| \subsubsection*{\ff \T{string.byte (s [, i])}}\DefLIB{string.byte} |
| 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{string.char (i1, i2, \ldots)}}\DefLIB{string.char} |
| Receives 0 or more integers. |
| Returns a string with length equal to the number of arguments, |
| in which each character has the internal numerical code equal |
| to its correspondent argument. |
| |
| \NOTE |
| Numerical codes are not necessarily portable across platforms. |
| |
| \subsubsection*{\ff \T{string.find (s, pattern [, init [, plain]])}} |
| \DefLIB{string.find} |
| Looks for the first \emph{match} of |
| \verb|pattern| in the string \verb|s|. |
| If it finds one, then \verb|find| returns the indices of \verb|s| |
| where this occurrence starts and ends; |
| otherwise, it returns \nil. |
| If the pattern specifies captures (see \verb|string.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 \True{} 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{string.len (s)}}\DefLIB{string.len} |
| 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{string.lower (s)}}\DefLIB{string.lower} |
| Receives a string and returns a copy of that string with all |
| uppercase letters changed to lowercase. |
| All other characters are left unchanged. |
| The definition of what is an uppercase letter depends on the current locale. |
| |
| \subsubsection*{\ff \T{string.rep (s, n)}}\DefLIB{string.rep} |
| Returns a string that is the concatenation of \verb|n| copies of |
| the string \verb|s|. |
| |
| \subsubsection*{\ff \T{string.sub (s, i [, j])}}\DefLIB{string.sub} |
| 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|string.sub(s,1,j)| returns a prefix of \verb|s| |
| with length \verb|j|, |
| and the call \verb|string.sub(s, -i)| returns a suffix of \verb|s| |
| with length \verb|i|. |
| |
| \subsubsection*{\ff \T{string.upper (s)}}\DefLIB{string.upper} |
| Receives a string and returns a copy of that string with all |
| lowercase letters changed to uppercase. |
| All other characters are left unchanged. |
| The definition of what is a lowercase letter depends on the current locale. |
| |
| \subsubsection*{\ff \T{string.format (formatstring, e1, e2, \ldots)}} |
| \DefLIB{string.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} |
| string.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{string.gfind (s, pat)}} |
| |
| Returns a generator function that, |
| each time it is called, |
| returns the next captures from pattern \verb|pat| over string \verb|s|. |
| |
| If \verb|pat| specifies no captures, |
| then the whole match is produced in each call. |
| |
| As an example, the following loop |
| \begin{verbatim} |
| s = "hello world from Lua" |
| for w in string.gfind(s, "%a+") do |
| print(w) |
| end |
| \end{verbatim} |
| will iterate over all the words from string \verb|s|, |
| printing each one in a line. |
| The next example collects all pairs \verb|key=value| from the |
| given string into a table: |
| \begin{verbatim} |
| t = {} |
| s = "from=world, to=Lua" |
| for k, v in string.gfind(s, "(%w+)=(%w+)") do |
| t[k] = v |
| end |
| \end{verbatim} |
| |
| \subsubsection*{\ff \T{string.gsub (s, pat, repl [, n])}} |
| \DefLIB{string.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|%|\M{n}, |
| with \M{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 pattern specifies no captures, |
| then the whole match is passed as a sole argument. |
| 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 = string.gsub("hello world", "(%w+)", "%1 %1") |
| --> x="hello hello world world" |
| |
| x = string.gsub("hello world", "(%w+)", "%1 %1", 1) |
| --> x="hello hello world" |
| |
| x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1") |
| --> x="world hello Lua from" |
| |
| x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv) |
| --> x="home = /home/roberto, user = roberto" (for instance) |
| |
| x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s) |
| return loadstring(s)() |
| end) |
| --> x="4+5 = 9" |
| |
| local t = {name="Lua", version="5.0"} |
| x = string.gsub("$name - $version", "%$(%w+)", function (v) |
| return t[v] |
| end) |
| --> x="Lua - 5.0" |
| \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}\leftskip=20pt |
| \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 lowercase letters. |
| \item[\T{\%p}] --- represents all punctuation characters. |
| \item[\T{\%s}] --- represents all space characters. |
| \item[\T{\%u}] --- represents all uppercase 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{[\M{set}]}] --- |
| represents the class which is the union of all |
| characters in \M{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 \M{set}. |
| All other characters in \M{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 lowercase 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\M{set}]}] --- |
| represents the complement of \M{set}, |
| where \M{set} is interpreted as above. |
| \end{description} |
| For all classes represented by single letters (\verb|%a|, \verb|%c|, \ldots), |
| the corresponding uppercase 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 \emph{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 substring 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 substrings 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. |
| |
| As a special case, the empty capture \verb|()| captures |
| the current string position (a number). |
| For instance, if we apply the pattern \verb|"()aa()"| on the |
| string \verb|"flaaap"|, there will be two captures: 3 and 5. |
| |
| \NOTE |
| A pattern cannot contain embedded zeros. Use \verb|%z| instead. |
| |
| |
| \subsection{Table Manipulation} |
| This library provides generic functions for table manipulation, |
| It provides all its functions inside the table \IndexLIB{table}. |
| |
| Most functions in the table library library assume that the table |
| represents an array or a list. |
| For those functions, an important concept is the \emph{size} of the array. |
| There are three ways to specify that size: |
| \begin{itemize} |
| \item the field \verb|"n"| --- |
| When the table has a field \verb|"n"| with a numerical value, |
| that value is assumed as its size. |
| \item \verb|setn| --- |
| You can call the \verb|table.setn| function to explicitly set |
| the size of a table. |
| \item implicit size --- |
| Otherwise, the size of the object is one less the first integer index |
| with a \nil{} value. |
| \end{itemize} |
| For more details, see the descriptions of the \verb|table.getn| and |
| \verb|table.setn| functions. |
| |
| \subsubsection*{\ff \T{table.concat (table [, sep [, i [, j]]])}} |
| \DefLIB{table.concat} |
| Returns \verb|table[i]..sep..table[i+1] ... sep..table[j]|. |
| The default value for \verb|sep| is the empty string, |
| the default for \verb|i| is 1, |
| and the default for \verb|j| is the size of the table. |
| If \verb|i| is greater than \verb|j|, returns the empty string. |
| |
| \subsubsection*{\ff \T{table.foreach (table, func)}}\DefLIB{table.foreach} |
| Executes the given \verb|func| over all elements of \verb|table|. |
| For each element, \verb|func| is called with the index and |
| respective value as arguments. |
| If \verb|func| returns a non-\nil{} value, |
| then the loop is broken, and this value is returned |
| as the final value of \verb|foreach|. |
| |
| The behavior of \verb|foreach| is \emph{undefined} if you change |
| the table \verb|t| during the traversal. |
| |
| |
| \subsubsection*{\ff \T{table.foreachi (table, func)}}\DefLIB{table.foreachi} |
| Executes the given \verb|func| over the |
| numerical indices of \verb|table|. |
| For each index, \verb|func| 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 size of the table \see{getn}. |
| If \verb|func| returns a non-\nil{} value, |
| then the loop is broken, and this value is returned |
| as the final value of \verb|foreachi|. |
| |
| \subsubsection*{\ff \T{table.getn (table)}}\DefLIB{table.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, if there was a previous call to |
| \verb|table.getn| or to \verb|table.setn| over this table, |
| the respective value is returned. |
| Otherwise, the ``size'' is one less the first integer index with |
| a \nil{} value. |
| |
| Notice that the last option happens only once for a table. |
| If you call \verb|table.getn| again over the same table, |
| it will return the same previous result, |
| even if the table has been modified. |
| The only way to change the value of \verb|table.getn| is by calling |
| \verb|table.setn| or assigning to field \verb|"n"| in the table. |
| |
| \subsubsection*{\ff \T{table.sort (table [, comp])}}\DefLIB{table.sort} |
| Sorts table elements in a given order, \emph{in-place}, |
| from \verb|table[1]| to \verb|table[n]|, |
| where \verb|n| is the size of the table \see{getn}. |
| If \verb|comp| is given, |
| then it must be a function that receives two table elements, |
| and returns true |
| when the first is less than the second |
| (so that \verb|not comp(a[i+1],a[i])| will be true after the sort). |
| If \verb|comp| is not given, |
| 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{table.insert (table, [pos,] value)}}\DefLIB{table.insert} |
| |
| Inserts element \verb|value| at position \verb|pos| in \verb|table|, |
| shifting other elements up to open space, if necessary. |
| The default value for \verb|pos| is \verb|n+1|, |
| where \verb|n| is the size of the table \see{getn}, |
| so that a call \verb|table.insert(t,x)| inserts \verb|x| at the end |
| of table \verb|t|. |
| This function also updates the size of the table, |
| calling \verb|table.setn(table, n+1)|. |
| |
| \subsubsection*{\ff \T{table.remove (table [, pos])}}\DefLIB{table.remove} |
| |
| Removes from \verb|table| the element at position \verb|pos|, |
| shifting other elements down 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 size of the table \see{getn}, |
| so that a call \verb|tremove(t)| removes the last element |
| of table \verb|t|. |
| This function also updates the size of the table, |
| calling \verb|table.setn(table, n-1)|. |
| |
| \subsubsection*{\ff \T{table.setn (table, n)}}\DefLIB{table.setn} |
| |
| Updates the ``size'' of a table. |
| If the table has a field \verb|"n"| with a numerical value, |
| that value is changed to the given \verb|n|. |
| Otherwise, it updates an internal state of the \verb|table| library |
| so that subsequent calls to \verb|table.getn(table)| return \verb|n|. |
| |
| |
| \subsection{Mathematical Functions} \label{mathlib} |
| |
| This library is an interface to most functions of the standard C~math library. |
| (Some have slightly different names.) |
| It provides all its functions inside the table \DefLIB{math}. |
| In addition, |
| it registers a ??tag method for the binary exponentiation operator \verb|^| |
| that returns \Math{x^y} when applied to numbers \verb|x^y|. |
| |
| The library provides the following functions: |
| \DefLIB{math.abs}\DefLIB{math.acos}\DefLIB{math.asin}\DefLIB{math.atan} |
| \DefLIB{math.atan2}\DefLIB{math.ceil}\DefLIB{math.cos} |
| \DefLIB{math.def}\DefLIB{math.exp} |
| \DefLIB{math.floor}\DefLIB{math.log}\DefLIB{math.log10} |
| \DefLIB{math.max}\DefLIB{math.min} |
| \DefLIB{math.mod}\DefLIB{math.rad}\DefLIB{math.sin} |
| \DefLIB{math.sqrt}\DefLIB{math.tan} |
| \DefLIB{math.frexp}\DefLIB{math.ldexp}\DefLIB{math.random} |
| \DefLIB{math.randomseed} |
| \begin{verbatim} |
| math.abs math.acos math.asin math.atan math.atan2 |
| math.ceil math.cos math.deg math.exp math.floor |
| math.log math.log10 math.max math.min math.mod |
| math.rad math.sin math.sqrt math.tan math.frexp |
| math.ldexp math.random math.randomseed |
| \end{verbatim} |
| plus a variable \IndexLIB{math.pi}. |
| Most of them |
| are only interfaces to the homonymous functions in the C~library. |
| All trigonometric functions work in radians. |
| The functions \verb|math.deg| and \verb|math.rad| convert |
| between radians and degrees. |
| |
| The function \verb|math.max| returns the maximum |
| value of its numeric arguments. |
| Similarly, \verb|math.min| computes the minimum. |
| Both can be used with 1, 2, or more arguments. |
| |
| The functions \verb|math.random| and \verb|math.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.) |
| When called without arguments, |
| \verb|math.random| returns a pseudo-random real number |
| in the range \Math{[0,1)}. %] |
| When called with a number \Math{n}, |
| \verb|math.random| returns a pseudo-random integer in the range \Math{[1,n]}. |
| When called with two arguments, \Math{l} and \Math{u}, |
| \verb|math.random| returns a pseudo-random integer in the range \Math{[l,u]}. |
| The \verb|math.randomseed| function sets a ``seed'' |
| for the pseudo-random generator: |
| Equal seeds produce equal sequences of numbers. |
| |
| |
| \subsection{Input and Output Facilities} \label{libio} |
| |
| The I/O library provides two different styles for file manipulation. |
| The first one uses implicit file descriptors; |
| that is, there are operations to set a default input file and a |
| default output file, |
| and all input/output operations are over those default files. |
| The second style uses explicit file descriptors. |
| |
| When using implicit file descriptors, |
| all operations are supplied by table \IndexLIB{io}. |
| When using explicit file descriptors, |
| the operation \IndexLIB{io.open} returns a file descriptor, |
| and then all operations are supplied as methods by the file descriptor. |
| |
| Moreover, the table \verb|io| also provides |
| three predefined file descriptors: |
| \IndexLIB{io.stdin}, \IndexLIB{io.stdout}, and \IndexLIB{io.stderr}, |
| with their usual meaning from C. |
| |
| A file handle is a userdata containing the file stream (\verb|FILE*|), |
| with a distinctive metatable created by the I/O library. |
| |
| Unless otherwise stated, |
| all I/O functions return \nil{} on failure |
| (plus an error message as a second result) |
| and some value different from \nil{} on success. |
| |
| \subsubsection*{\ff \T{io.close ([handle])}}\DefLIB{io.close} |
| |
| Equivalent to \verb|file:close()|. |
| Without a \verb|handle|, closes the default output file. |
| |
| \subsubsection*{\ff \T{io.flush ()}}\DefLIB{io.flush} |
| |
| Equivalent to \verb|file:flush| over the default output file. |
| |
| \subsubsection*{\ff \T{io.input ([file])}}\DefLIB{io.input} |
| |
| When called with a file name, it opens the named file (in text mode), |
| and sets its handle as the default input file |
| (and returns nothing). |
| When called with a file handle, |
| it simply sets that file handle as the default input file. |
| When called without parameters, |
| it returns the current default input file. |
| |
| In case of errors this function raises the error, |
| instead of returning an error code. |
| |
| \subsubsection*{\ff \T{io.lines ([filename])}}\DefLIB{io.lines} |
| |
| Opens the given file name in read mode, |
| and returns a generator function that, |
| each time it is called, |
| returns a new line from the file. |
| Therefore, the construction |
| \begin{verbatim} |
| for lines in io.lines(filename) do ... end |
| \end{verbatim} |
| will iterate over all lines of the file. |
| When the generator function detects the end of file, |
| it returns nil (to finish the loop) and automatically closes the file. |
| |
| The call \verb|io.lines()| (without a file name) is equivalent |
| to \verb|io.input():lines()|, that is, it iterates over the |
| lines of the default input file. |
| |
| \subsubsection*{\ff \T{io.open (filename, mode)}}\DefLIB{io.open} |
| |
| 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 an error message. |
| |
| The \verb|mode| string can be any of the following: |
| \begin{description}\leftskip=20pt |
| \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{io.output ([file])}}\DefLIB{io.output} |
| |
| Similar to \verb|io.input|, but operates over the default output file. |
| |
| \subsubsection*{\ff \T{io.read (format1, ...)}}\DefLIB{io.read} |
| |
| Equivalent to \verb|file:read| over the default input file. |
| |
| \subsubsection*{\ff \T{io.tmpfile ()}}\DefLIB{io.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{io.write (value1, ...)}}\DefLIB{io.write} |
| |
| Equivalent to \verb|file:write| over the default output file. |
| |
| |
| |
| \subsubsection*{\ff \T{file:close ()}}\DefLIB{file:close} |
| |
| Closes the file \verb|file|. |
| |
| \subsubsection*{\ff \T{file:flush ()}}\DefLIB{file:flush} |
| |
| Saves any written data to the file \verb|file|. |
| |
| \subsubsection*{\ff \T{file:lines ()}}\DefLIB{file:lines} |
| |
| Returns a generator function that, |
| each time it is called, |
| returns a new line from the file. |
| Therefore, the construction |
| \begin{verbatim} |
| for lines in file:lines() do ... end |
| \end{verbatim} |
| will iterate over all lines of the file. |
| (Unlike \verb|io.lines|, this function does not close the file |
| when the loop ends.) |
| |
| \subsubsection*{\ff \T{file:read (format1, ...)}}\DefLIB{file:read} |
| |
| Reads the file \verb|file|, |
| 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 entire next line |
| (see below). |
| |
| The available formats are |
| \begin{description}\leftskip=20pt |
| \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[``*l''] 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. |
| If number is zero, |
| it reads nothing and returns an empty string, |
| or \nil{} on end of file. |
| \end{description} |
| |
| \subsubsection*{\ff \T{file:seek ([whence] [, offset])}}\DefLIB{file: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}\leftskip=20pt |
| \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 this function 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|file:seek()| returns the current |
| file position, without changing it; |
| the call \verb|file:seek("set")| sets the position to the |
| beginning of the file (and returns 0); |
| and the call \verb|file:seek("end")| sets the position to the |
| end of the file, and returns its size. |
| |
| \subsubsection*{\ff \T{file:write (value1, ...)}}\DefLIB{file:write} |
| |
| Writes the value of each of its arguments to |
| the filehandle \verb|file|. |
| 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{Operating System Facilities} \label{libiosys} |
| |
| This library is implemented through table \IndexLIB{os}. |
| |
| \subsubsection*{\ff \T{os.clock ()}}\DefLIB{os.clock} |
| |
| Returns an approximation of the amount of CPU time |
| used by the program, in seconds. |
| |
| \subsubsection*{\ff \T{os.date ([format [, time]])}}\DefLIB{os.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|!|, |
| then the date is formatted in Coordinated Universal Time. |
| |
| After that optional character, |
| if \verb|format| is \verb|*t|, |
| then \verb|date| returns a table with the following fields: |
| \verb|year| (four digits), \verb|month| (1--12), \verb|day| (1--31), |
| \verb|hour| (0--23), \verb|min| (0--59), \verb|sec| (0--61), |
| \verb|wday| (weekday, Sunday is 1), |
| \verb|yday| (day of the year), |
| and \verb|isdst| (daylight saving flag, a boolean). |
| |
| If format is not \verb|*t|, |
| then \verb|date| returns the date as a string, |
| formatted according with the same rules as the C~function \verb|strftime|. |
| When called without arguments, |
| \verb|date| returns a reasonable date and time representation that depends on |
| the host system and on the current locale |
| (that is, \verb|os.date()| is equivalent to \verb|os.date("%c")|). |
| |
| \subsubsection*{\ff \T{os.difftime (t1, t2)}}\DefLIB{os.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 \verb|t1|\Math{-}\verb|t2|. |
| |
| \subsubsection*{\ff \T{os.execute (command)}}\DefLIB{os.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{os.exit ([code])}}\DefLIB{os.exit} |
| |
| Calls the C~function \verb|exit|, |
| with an optional \verb|code|, |
| to terminate the host program. |
| The default value for \verb|code| is the success code. |
| |
| \subsubsection*{\ff \T{os.getenv (varname)}}\DefLIB{os.getenv} |
| |
| Returns the value of the process environment variable \verb|varname|, |
| or \nil{} if the variable is not defined. |
| |
| \subsubsection*{\ff \T{os.remove (filename)}}\DefLIB{os.remove} |
| |
| Deletes the file with the given name. |
| If this function fails, it returns \nil, |
| plus a string describing the error. |
| |
| \subsubsection*{\ff \T{os.rename (name1, name2)}}\DefLIB{os.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{os.setlocale (locale [, category])}}\DefLIB{os.setlocale} |
| |
| This function is an interface to the 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{os.time ([table])}}\DefLIB{os.time} |
| |
| Returns the current time when called without arguments, |
| or a time representing the date and 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|os.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 the number returned bt \verb|time| can be used only as an argument to |
| \verb|date| and \verb|difftime|. |
| |
| \subsubsection*{\ff \T{os.tmpname ()}}\DefLIB{os.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 (and even some compilers!) 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. |
| |
| |
| \subsection{The Reflexive Debug Interface} |
| |
| The library \verb|ldblib| provides |
| the functionality of the debug interface to Lua programs. |
| You should exert great care when using this library. |
| The functions provided here should be used exclusively for debugging |
| and similar tasks, such as profiling. |
| Please resist the temptation to use them as a |
| usual programming tool: |
| They can be very slow. |
| Moreover, \verb|setlocal| and \verb|getlocal| |
| violate the privacy of local variables, |
| and therefore can compromise some (otherwise) secure code. |
| |
| All functions in this library are provided |
| inside a \IndexVerb{debug} table. |
| |
| |
| \subsubsection*{\ff \T{debug.getinfo (function, [what])}}\DefLIB{debug.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. |
| If present, |
| the option \verb|f| |
| 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{debug.getlocal (level, local)}}\DefLIB{debug.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{debug.setlocal (level, local, value)}} |
| \DefLIB{debug.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. |
| (You can call \verb|getinfo| to check whether the level is valid.) |
| |
| \subsubsection*{\ff \T{debug.sethook (hook, mask [, count])}} |
| \DefLIB{debug.sethook} |
| |
| Sets the given function as a hook. |
| The string \verb|mask| and the number \verb|count| describe |
| when the hook will be called. |
| The string mask may have the following characters, |
| with the given meaning: |
| \begin{description} |
| \item[{\tt "c"}] The hook is called every time Lua calls a function; |
| \item[{\tt "r"}] The hook is called every time Lua returns from a function; |
| \item[{\tt "l"}] The hook is called every time Lua enters a new line of code. |
| \end{description} |
| With a \verb|count| different from zero, |
| the hook is called after every \verb|count| instructions. |
| |
| When called without arguments, |
| the \verb|debug.sethook| function turns off the hook. |
| |
| When the hook is called, its first parameter is always a string |
| describing the event that triggered its call: |
| \verb|"call"|, \verb|"return"|, \verb|"line"|, and \verb|"count"|. |
| Moreover, for line events, |
| it also gets as its second parameter the new line number. |
| Inside a hook, |
| you can call \verb|getinfo| with level 2 to get more information about |
| the running function |
| (level~0 is the \verb|getinfo| function, |
| and level~1 is the hook function). |
| |
| \subsubsection*{\ff \T{debug.gethook ()}}\DefLIB{debug.gethook} |
| |
| Returns the current hook settings, as three values: |
| the current hook function, the current hook mask, |
| and the current hook count (as set by the \verb|debug.sethook| function). |
| |
| |
| %------------------------------------------------------------------------------ |
| \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 also 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. |
| The stand-alone interpreter includes |
| all standard libraries plus the reflexive debug interface. |
| Its usage is: |
| \begin{verbatim} |
| lua [options] [script [args]] |
| \end{verbatim} |
| The options are: |
| \begin{description}\leftskip=20pt |
| \item[\T{-} ] executes \verb|stdin| as a file; |
| \item[\T{-e} \rm\emph{stat}] executes string \emph{stat}; |
| \item[\T{-l} \rm\emph{file}] ``requires'' \emph{file}; |
| \item[\T{-i}] enters interactive mode after running \emph{script}; |
| \item[\T{-v}] prints version information; |
| \item[\T{--}] stop handling options. |
| \end{description} |
| After handling its options, \verb|lua| runs the given \emph{script}, |
| passing to it the given \emph{args}. |
| When called without arguments, |
| \verb|lua| behaves as \verb|lua -v -i| when \verb|stdin| is a terminal, |
| and as \verb|lua -| otherwise. |
| |
| Before running any argument, |
| the intepreter checks for an environment variable \IndexVerb{LUA_INIT}. |
| If its format is \verb|@|\emph{filename}, |
| then lua executes the file. |
| Otherwise, lua executes the string itself. |
| |
| All options are handled in order, except \verb|-i|. |
| For instance, an invocation like |
| \begin{verbatim} |
| $ lua -e'a=1' -e 'print(a)' script.lua |
| \end{verbatim} |
| will first set \verb|a| to 1, then print \verb|a|, |
| and finally run the file \verb|script.lua|. |
| (Here, \verb|$| is the shell prompt. Your prompt may be different.) |
| |
| Before starting to run the script, |
| \verb|lua| collects all arguments in the command line |
| in a global table called \verb|arg|. |
| The script name is stored in index 0, |
| the first argument after the script name goes to index 1, |
| and so on. |
| The field \verb|n| gets the number of arguments after the script name. |
| Any arguments before the script name |
| (that is, the interpreter name plus the options) |
| go to negative indices. |
| For instance, in the call |
| \begin{verbatim} |
| $ lua -la.lua b.lua t1 t2 |
| \end{verbatim} |
| the interpreter first runs the file \T{a.lua}, |
| then creates a table |
| \begin{verbatim} |
| arg = { [-2] = "lua", [-1] = "-la.lua", [0] = "b.lua", |
| [1] = "t1", [2] = "t2"; n = 2 } |
| \end{verbatim} |
| and finally runs the file \T{b.lua}. |
| |
| In interactive mode, |
| if you write an incomplete statement, |
| the interpreter waits for its completion. |
| |
| 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 -e"_PROMPT='myprompt> '" -i |
| \end{verbatim} |
| (the first pair of quotes is for the shell, |
| the second is for Lua), |
| or in any Lua programs by assigning to \verb|_PROMPT|. |
| Note the use of \verb|-i| to enter interactive mode; otherwise, |
| the program would end just after the assignment 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 |
| \begin{verbatim} |
| #!/usr/local/bin/lua |
| \end{verbatim} |
| (Of course, |
| the location of the Lua interpreter may be different in your machine. |
| If \verb|lua| is in your \verb|PATH|, |
| then a more portable solution is |
| \begin{verbatim} |
| #!/usr/bin/env lua |
| \end{verbatim} |
| |
| |
| %------------------------------------------------------------------------------ |
| \section*{Acknowledgments} |
| |
| The Lua team is grateful to \tecgraf{} for its continued support to Lua. |
| We thank everyone at \tecgraf{}, |
| specially the head of the group, Marcelo Gattass. |
| At the risk of omitting several names, |
| we also thank the following individuals for supporting, |
| contributing to, and spreading the word about Lua: |
| Alan Watson. |
| Andr\'e Clinio, |
| Andr\'e Costa, |
| Antonio Scuri, |
| Bret Mogilefsky, |
| Cameron Laird, |
| Carlos Cassino, |
| Carlos Henrique Levy, |
| Claudio Terra, |
| David Jeske, |
| Edgar Toernig, |
| Erik Hougaard, |
| Jim Mathies, |
| John Belmonte, |
| John Passaniti, |
| John Roll, |
| Jon Erickson, |
| Jon Kleiser, |
| Mark Ian Barlow, |
| Nick Trout, |
| Noemi Rodriguez, |
| Norman Ramsey, |
| Philippe Lhoste, |
| Renata Ratton, |
| Renato Borges, |
| Renato Cerqueira, |
| Reuben Thomas, |
| Stephan Herrmann, |
| Steve Dekorte, |
| Thatcher Ulrich, |
| Tom\'as Gorham, |
| Vincent Penquerc'h, |
| Thank you! |
| |
| |
| \appendix |
| |
| \section*{Incompatibilities with Previous Versions} |
| \addcontentsline{toc}{section}{Incompatibilities with Previous Versions} |
| |
| \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 |
| The precedence of \rwd{or} is smaller than the precedence of \rwd{and}. |
| |
| \item |
| \rwd{in} is a reserved word. |
| |
| \item |
| The old construction \verb|for k,v in t|, where \verb|t| is a table, |
| is deprecated (although it is still supported). |
| Use \verb|for k,v in pairs(t)| instead. |
| |
| \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 |
| Most library functions now are defined inside tables. |
| There is a compatibility script (\verb|compat.lua|) that |
| redefine most of them as global names. |
| |
| \item |
| In the math library, angles are expressed in radians. |
| With the compatibility script (\verb|compat.lua|), |
| functions still work in degrees. |
| |
| \item |
| The \verb|call| function is deprecated. |
| Use \verb|f(unpack(tab))| instead of \verb|call(f, tab)| |
| for unprotected calls, |
| or the new \verb|pcall| function for protected calls. |
| |
| \item |
| \verb|dofile| do not handle errors, but simply propagate them. |
| |
| \item |
| The \verb|read| option \verb|*w| is obsolete. |
| |
| \item |
| The \verb|format| option \verb|%n$| is obsolete. |
| |
| \end{itemize} |
| |
| |
| \subsubsection*{Changes in the API} |
| \begin{itemize} |
| |
| \item |
| Userdata!! |
| |
| \end{itemize} |
| |
| %{=============================================================== |
| \newpage |
| \section*{The Complete Syntax of Lua} \label{BNF} |
| \addcontentsline{toc}{section}{The Complete Syntax of Lua} |
| |
| The notation used here is the usual extended BNF, |
| in which |
| \rep{\emph{a}}~means 0 or more \emph{a}'s, and |
| \opt{\emph{a}}~means an optional \emph{a}. |
| Non-terminals are shown in \emph{italics}, |
| keywords are shown in {\bf bold}, |
| and other terminal symbols are shown in {\tt typewriter} font, |
| enclosed in single quotes. |
| |
| |
| \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]{\ter{#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} \rep{\ter{,} \Nter{Name}} \rwd{in} explist1 |
| \rwd{do} block \rwd{end} |
| \OrNL \rwd{function} funcname funcbody |
| \OrNL \rwd{local} \rwd{function} \Nter{Name} funcbody |
| \OrNL \rwd{local} namelist \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 prefixexp \ter{[} exp \ter{]} |
| \Or prefixexp \ter{.} \Nter{Name} |
| } |
| |
| \produc{namelist}{\Nter{Name} \rep{\ter{,} \Nter{Name}}} |
| |
| \produc{init}{\ter{=} explist1} |
| |
| \produc{explist1}{\rep{exp \ter{,}} exp} |
| |
| \produc{exp}{% |
| \rwd{nil} |
| \rwd{false} |
| \rwd{true} |
| \Or \Nter{Number} |
| \OrNL \Nter{Literal} |
| \Or function |
| \Or prefixexp |
| \OrNL tableconstructor |
| \Or exp binop exp |
| \Or unop exp |
| } |
| |
| \produc{prefixexp}{var \Or functioncall \Or \ter{(} exp \ter{)}} |
| |
| \produc{functioncall}{% |
| prefixexp args |
| \Or prefixexp \ter{:} \Nter{Name} args |
| } |
| |
| \produc{args}{% |
| \ter{(} \opt{explist1} \ter{)} |
| \Or tableconstructor |
| \Or \Nter{Literal} |
| } |
| |
| \produc{function}{\rwd{function} funcbody} |
| |
| \produc{funcbody}{\ter{(} \opt{parlist1} \ter{)} block \rwd{end}} |
| |
| \produc{parlist1}{% |
| \Nter{Name} \rep{\ter{,} \Nter{Name}} \opt{\ter{,} \ter{\ldots}} |
| \Or \ter{\ldots} |
| } |
| |
| \produc{tableconstructor}{\ter{\{} \opt{fieldlist} \ter{\}}} |
| \produc{fieldlist}{field \rep{fieldsep field} \opt{fieldsep}} |
| \produc{field}{\ter{[} exp \ter{]} \ter{=} exp \Or name \ter{=} exp \Or exp} |
| \produc{fieldsep}{\ter{,} \Or \ter{;}} |
| |
| \produc{binop}{\ter{+} \Or \ter{-} \Or \ter{*} \Or \ter{/} \Or \ter{\^{ }} \Or |
| \ter{..} \Or \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} |
| %)]} |