rusefi
/
lua
mirror of https://github.com/rusefi/lua.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

new pattern matching facilities; new version of i/o lib; 

other small corrections.
This commit is contained in:
Roberto Ierusalimschy 1996-11-01 15:02:10 -02:00
parent d106f3f43c
commit 2f44cc9f4d
1 changed files with 357 additions and 183 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

540
manual.tex
View File

@ -1,4 +1,4 @@
% $Id: manual.tex,v 1.18 1996/06/18 20:08:40 roberto Exp roberto $ % $Id: manual.tex,v 1.19 1996/08/28 20:46:26 roberto Exp roberto $
\documentstyle[fullpage,11pt,bnf]{article} \documentstyle[fullpage,11pt,bnf]{article}
@ -13,7 +13,9 @@
\newcommand{\Def}[1]{{\em #1}\index{#1}} \newcommand{\Def}[1]{{\em #1}\index{#1}}
\newcommand{\Deffunc}[1]{\index{#1}} \newcommand{\Deffunc}[1]{\index{#1}}
\newcommand{\Version}{2.4} \newcommand{\ff}{$\bullet$\ }
\newcommand{\Version}{2.5 (beta)}
\makeindex \makeindex
@ -24,7 +26,7 @@
\author{% \author{%
Roberto Ierusalimschy\quad Roberto Ierusalimschy\quad
Luiz Henrique de Figueiredo\quad Luiz Henrique de Figueiredo\quad
Waldemar Celes Filho Waldemar Celes
\vspace{1.0ex}\\ \vspace{1.0ex}\\
%\small \tecgraf \ --- PUC-Rio\\ %\small \tecgraf \ --- PUC-Rio\\
\smallskip \smallskip
@ -34,7 +36,7 @@ Waldemar Celes Filho
\tecgraf\ --- Departamento de Inform\'atica --- PUC-Rio \tecgraf\ --- Departamento de Inform\'atica --- PUC-Rio
} }
\date{\small \verb$Date: 1996/06/18 20:08:40 $} \date{\small \verb$Date: 1996/08/28 20:46:26 $}
\maketitle \maketitle
@ -72,11 +74,8 @@ general procedural programming features with data description
facilities. facilities.
It is intended to be used as a configuration language for any It is intended to be used as a configuration language for any
program that needs one. program that needs one.
%Its main extensions are related to object-oriented facilities,
%and fallbacks,
%but it has some other minor contributions.
Lua has been designed and implemented by Lua has been designed and implemented by
W.~Celes~F., L.~H.~de Figueiredo and R.~Ierusalimschy. W.~Celes, L.~H.~de Figueiredo and R.~Ierusalimschy.
Lua is implemented as a library, written in C. Lua is implemented as a library, written in C.
Being an extension language, Lua has no notion of a ``main'' program: Being an extension language, Lua has no notion of a ``main'' program:
@ -123,10 +122,11 @@ The syntax%
one or more {\em a\/}'s.} one or more {\em a\/}'s.}
for chunks is: for chunks is:
\begin{Produc} \begin{Produc}
\produc{chunk}{\rep{statement \Or function}} \produc{chunk}{\rep{statement \Or function} \opt{ret}}
\end{Produc}% \end{Produc}%
A chunk may contain statements and function definitions, A chunk may contain statements and function definitions,
and may be in a file or in a string inside the host program. and may be in a file or in a string inside the host program.
A chunk may optionally ends with a return statement (\see{return}).
When a chunk is executed, first all its functions and statements are compiled, When a chunk is executed, first all its functions and statements are compiled,
then the statements are executed in sequential order. then the statements are executed in sequential order.
All modifications a chunk effects on the global environment persist All modifications a chunk effects on the global environment persist
@ -231,6 +231,10 @@ and do not interpret escape sequences.
\Index{Comments} start anywhere outside a string with a \Index{Comments} start anywhere outside a string with a
double hyphen (\verb'--') and run until the end of the line. double hyphen (\verb'--') and run until the end of the line.
Moreover, if the first line of a chunk file starts with \verb'#',
this line is skiped%
\footnote{This facility allows the use of Lua as a script interpreter
in Unix systems.}.
\Index{Numerical constants} may be written with an optional decimal part, \Index{Numerical constants} may be written with an optional decimal part,
and an optional decimal exponent. and an optional decimal exponent.
@ -281,7 +285,7 @@ and local variable declarations (Section~\ref{localvar}).
A \Index{block} is a list of statements, which is executed sequentially. A \Index{block} is a list of statements, which is executed sequentially.
Any statement can be optionally followed by a semicolon: Any statement can be optionally followed by a semicolon:
\begin{Produc} \begin{Produc}
\produc{block}{\rep{stat sc} \opt{ret sc}} \produc{block}{\rep{stat sc} \opt{ret}}
\produc{sc}{\opt{\ter{;}}} \produc{sc}{\opt{\ter{;}}}
\end{Produc}% \end{Produc}%
For syntactic reasons, a \IndexVerb{return} statement can only be written For syntactic reasons, a \IndexVerb{return} statement can only be written
@ -344,11 +348,12 @@ All values different from \nil\ are considered true;
\produc{elseif}{\rwd{elseif} exp1 \rwd{then} block} \produc{elseif}{\rwd{elseif} exp1 \rwd{then} block}
\end{Produc} \end{Produc}
A {\tt return} is used to return values from a function. \label{return} A {\tt return} is used to return values from a function or a chunk.
Because a function may return more than one value, \label{return}
Because they may return more than one value,
the syntax for a \Index{return statement} is: the syntax for a \Index{return statement} is:
\begin{Produc} \begin{Produc}
\produc{ret}{\rwd{return} explist} \produc{ret}{\rwd{return} explist \opt{sc}}
\end{Produc} \end{Produc}
\subsubsection{Function Calls as Statements} \label{funcstat} \subsubsection{Function Calls as Statements} \label{funcstat}
@ -434,7 +439,12 @@ The \Index{logical operators} are:
\begin{verbatim} \begin{verbatim}
and or not and or not
\end{verbatim} \end{verbatim}
The operators \verb'and' and \verb'or' use \Index{short-cut evaluation}, The operator \verb'and' returns \nil\ if its first argument is \nil;
otherwise it returns its second argument.
The operator \verb'or' returns its first argument
if it is different from \nil;
otherwise it returns its second argument.
Both \verb'and' and \verb'or' use \Index{short-cut evaluation},
that is, that is,
the second operand is evaluated only if necessary. the second operand is evaluated only if necessary.
@ -485,7 +495,7 @@ For example:
\begin{verbatim} \begin{verbatim}
a = {"v1", "v2", 34} a = {"v1", "v2", 34}
\end{verbatim} \end{verbatim}
is equivalent to: is roughly equivalent to:
\begin{verbatim} \begin{verbatim}
temp = {} temp = {}
temp[1] = "v1" temp[1] = "v1"
@ -503,11 +513,11 @@ For example:
\begin{verbatim} \begin{verbatim}
a = {x = 1, y = 3} a = {x = 1, y = 3}
\end{verbatim} \end{verbatim}
is equivalent to: is roughly equivalent to:
\begin{verbatim} \begin{verbatim}
temp = {} temp = {}
temp.x = 1 temp.x = 1 -- or temp["x"] = 1
temp.y = 3 temp.y = 3 -- or temp["y"] = 3
a = temp a = temp
\end{verbatim} \end{verbatim}
@ -518,7 +528,7 @@ A \Index{function call} has the following syntax:
\produc{functioncall}{var realParams} \produc{functioncall}{var realParams}
\end{Produc}% \end{Produc}%
Here, \verb'var' can be any variable (global, local, indexed, etc). Here, \verb'var' can be any variable (global, local, indexed, etc).
If its type is {\em function\/} or {\em CFunction\/}, If its value has type {\em function\/} or {\em CFunction\/},
then this function is called. then this function is called.
Otherwise, the ``function'' fallback is called, Otherwise, the ``function'' fallback is called,
having as first parameter the value of \verb'var', having as first parameter the value of \verb'var',
@ -630,7 +640,7 @@ and one of the following strings describing the offended operator:
add sub mul div pow unm add sub mul div pow unm
\end{verbatim} \end{verbatim}
Its return value is the final result of the arithmetic operation. Its return value is the final result of the arithmetic operation.
The default function issues an error. The default handler issues an error.
\item[``order'':]\index{order fallback} \item[``order'':]\index{order fallback}
called when an order comparison is applied to non numerical or called when an order comparison is applied to non numerical or
non string operands. non string operands.
@ -641,40 +651,40 @@ one of the following strings describing the offended operator:
lt gt le ge lt gt le ge
\end{verbatim} \end{verbatim}
Its return value is the final result of the comparison operation. Its return value is the final result of the comparison operation.
The default function issues an error. The default handler issues an error.
\item[``concat'':]\index{concatenation fallback} \item[``concat'':]\index{concatenation fallback}
called when a concatenation is applied to non string operands. called when a concatenation is applied to non string operands.
It receives the two operands as arguments. It receives the two operands as arguments.
Its return value is the final result of the concatenation operation. Its return value is the final result of the concatenation operation.
The default function issues an error. The default handler issues an error.
\item[``index'':]\index{index fallback} \item[``index'':]\index{index fallback}
called when Lua tries to retrieve the value of an index called when Lua tries to retrieve the value of an index
not present in a table. not present in a table.
It receives as arguments the table and the index. It receives as arguments the table and the index.
Its return value is the final result of the indexing operation. Its return value is the final result of the indexing operation.
The default function returns nil. The default handler returns nil.
\item[``getglobal'':]\index{index getglobal} \item[``getglobal'':]\index{index getglobal}
called when Lua tries to retrieve the value of a global variable called when Lua tries to retrieve the value of a global variable
which has a nil value (or which has not been initialized). which has a nil value (or which has not been initialized).
It receives as argument the name of the variable. It receives as argument the name of the variable.
Its return value is the final result of the expression. Its return value is the final result of the expression.
The default function returns nil. The default handler returns nil.
\item[``gettable'':]\index{gettable fallback} \item[``gettable'':]\index{gettable fallback}
called when Lua tries to index a non table value. called when Lua tries to index a non table value.
It receives as arguments the non table value and the index. It receives as arguments the non table value and the index.
Its return value is the final result of the indexing operation. Its return value is the final result of the indexing operation.
The default function issues an error. The default handler issues an error.
\item[``settable'':]\index{settable fallback} \item[``settable'':]\index{settable fallback}
called when Lua tries to assign indexed a non table value. called when Lua tries to assign indexed a non table value.
It receives as arguments the non table value, It receives as arguments the non table value,
the index, and the assigned value. the index, and the assigned value.
The default function issues an error. The default handler issues an error.
\item[``function'':]\index{function falback} \item[``function'':]\index{function falback}
called when Lua tries to call a non function value. called when Lua tries to call a non function value.
It receives as arguments the non function value and the It receives as arguments the non function value and the
arguments given in the original call. arguments given in the original call.
Its return values are the final results of the call operation. Its return values are the final results of the call operation.
The default function issues an error. The default handler issues an error.
\item[``gc'':] \item[``gc'':]
called during garbage collection. called during garbage collection.
It receives as argument the table being collected. It receives as argument the table being collected.
@ -683,17 +693,17 @@ Because this function operates during garbage collection,
it must be used with great care, it must be used with great care,
and programmers should avoid the creation of new objects and programmers should avoid the creation of new objects
(tables or strings) in this function. (tables or strings) in this function.
The default function does nothing. The default handler does nothing.
\item[``error'':]\index{error fallback} \item[``error'':]\index{error fallback}
called when an error occurs. called when an error occurs.
It receives as argument a string describing the error. It receives as argument a string describing the error.
The default function prints the message on the standard error output. The default handler prints the message on the standard error output.
\end{description} \end{description}
The function \IndexVerb{setfallback} is used to change a fallback function. The function \IndexVerb{setfallback} is used to change a fallback handler.
Its first argument is the name of a fallback condition, Its first argument is the name of a fallback condition,
and the second argument is the new function to be called. and the second argument is the new function to be called.
It returns the old function for the given fallback. It returns the old handler function for the given fallback.
Section \ref{exfallback} shows an example of the use of fallbacks. Section \ref{exfallback} shows an example of the use of fallbacks.
@ -706,7 +716,7 @@ Whenever an error occurs during Lua compilation or execution,
an ``error'' fallback function is called, an ``error'' fallback function is called,
and then the corresponding function from the library and then the corresponding function from the library
(\verb'lua_dofile', \verb'lua_dostring', (\verb'lua_dofile', \verb'lua_dostring',
\verb'lua_call', and \verb'lua_callfunction') \verb'lua_call', or \verb'lua_callfunction')
is terminated returning an error condition. is terminated returning an error condition.
The only argument to the ``error'' fallback function is a string The only argument to the ``error'' fallback function is a string
@ -722,10 +732,10 @@ This pragma must be written in a line by itself.
When an error occurs in a program compiled with this option, When an error occurs in a program compiled with this option,
the error routine is able to print also the lines where the calls the error routine is able to print also the lines where the calls
(and the error) were made. (and the error) were made.
If needed, it is possible to change the ``error'' fallback routine If needed, it is possible to change the ``error'' fallback handler
(\see{fallback}). (\see{fallback}).
Lua code can generate an error by calling the built-in Lua code can explicitly generate an error by calling the built-in
function \verb'error' (\see{pdf-error}). function \verb'error' (\see{pdf-error}).
@ -917,16 +927,6 @@ As in Lua, if the first object is not a table,
or the index is not present in the table, or the index is not present in the table,
the corresponding fallback is called. the corresponding fallback is called.
%For compatibility with previous versions of the API,
%the following macros are supported:
%\Deffunc{lua_getindexed}\Deffunc{lua_getfield}
%\begin{verbatim}
%lua_Object lua_getindexed (lua_Object table, float index);
%lua_Object lua_getfield (lua_Object table, char *field);
%\end{verbatim}
%The first one is used for numeric indices,
%while the second can be used for any string index.
To store a value in an index, To store a value in an index,
the program must push onto the stack the table, the index, the program must push onto the stack the table, the index,
and the value, and the value,
@ -1133,20 +1133,24 @@ declared in \verb-lualib.h-.
\subsection{Predefined Functions} \subsection{Predefined Functions}
\subsubsection*{{\tt dofile (filename)}}\Deffunc{dofile} \subsubsection*{\ff{\tt dofile (filename)}}\Deffunc{dofile}
This function receives a file name, This function receives a file name,
opens it, and executes its contents as a Lua chunk, opens it, and executes its contents as a Lua chunk,
or as pre-compiled chunks. or as pre-compiled chunks.
When called without arguments, When called without arguments,
it executes the contents of the standard input (\verb'stdin'). it executes the contents of the standard input (\verb'stdin').
It returns 1 if there are no errors, \nil\ otherwise. If there is any error executing the file, it returns \nil.
Otherwise, it returns the values returned by the chunk,
or a non \nil\ value if the chunk returns no values.
It issues an error when called with a non string argument. It issues an error when called with a non string argument.
\subsubsection*{{\tt dostring (string)}}\Deffunc{dostring} \subsubsection*{\ff{\tt dostring (string)}}\Deffunc{dostring}
This function executes a given string as a Lua chunk. This function executes a given string as a Lua chunk.
It returns 1 if there are no errors, \nil\ otherwise. If there is any error executing the string, it returns \nil.
Otherwise, it returns the values returned by the chunk,
or a non \nil\ value if the chunk returns no values.
\subsubsection*{{\tt next (table, index)}}\Deffunc{next} \subsubsection*{\ff{\tt next (table, index)}}\Deffunc{next}
This function allows a program to traverse all fields of a table. This function allows a program to traverse all fields of a table.
Its first argument is a table and its second argument Its first argument is a table and its second argument
is an index in this table. is an index in this table.
@ -1167,7 +1171,7 @@ The order the indices are enumerated is not specified,
See Section \ref{exnext} for an example of the use of this function. See Section \ref{exnext} for an example of the use of this function.
\subsubsection*{{\tt nextvar (name)}}\Deffunc{nextvar} \subsubsection*{\ff{\tt nextvar (name)}}\Deffunc{nextvar}
This function is similar to the function \verb'next', This function is similar to the function \verb'next',
but iterates over the global variables. but iterates over the global variables.
Its single argument is the name of a global variable, Its single argument is the name of a global variable,
@ -1177,11 +1181,11 @@ and its value,
or \nil\ if there are no more variables. or \nil\ if there are no more variables.
See Section \ref{exnext} for an example of the use of this function. See Section \ref{exnext} for an example of the use of this function.
\subsubsection*{{\tt tostring (e)}}\Deffunc{tostring} \subsubsection*{\ff{\tt tostring (e)}}\Deffunc{tostring}
This function receives an argument of any type and This function receives an argument of any type and
converts it to a string in a reasonable format. converts it to a string in a reasonable format.
\subsubsection*{{\tt print (e1, e2, ...)}}\Deffunc{print} \subsubsection*{\ff{\tt print (e1, e2, ...)}}\Deffunc{print}
This function receives any number of arguments, This function receives any number of arguments,
and prints their values in a reasonable format. and prints their values in a reasonable format.
Each value is printed in a new line. Each value is printed in a new line.
@ -1190,14 +1194,14 @@ but as a quick way to show a value,
for instance for error messages or debugging. for instance for error messages or debugging.
See Section~\ref{libio} for functions for formatted output. See Section~\ref{libio} for functions for formatted output.
\subsubsection*{{\tt tonumber (e)}}\Deffunc{tonumber} \subsubsection*{\ff{\tt tonumber (e)}}\Deffunc{tonumber}
This function receives one argument, This function receives one argument,
and tries to convert it to a number. and tries to convert it to a number.
If the argument is already a number or a string convertible If the argument is already a number or a string convertible
to a number (\see{coercion}), then it returns that number; to a number (\see{coercion}), then it returns that number;
otherwise, it returns \nil. otherwise, it returns \nil.
\subsubsection*{{\tt type (v)}}\Deffunc{type} \subsubsection*{\ff{\tt type (v)}}\Deffunc{type}
This function allows Lua to test the type of a value. This function allows Lua to test the type of a value.
It receives one argument, and returns its type, coded as a string. It receives one argument, and returns its type, coded as a string.
The possible results of this function are The possible results of this function are
@ -1214,54 +1218,59 @@ This tag can be used to distinguish between user
data with different tags, data with different tags,
and between C functions and Lua functions. and between C functions and Lua functions.
\subsubsection*{{\tt assert (v)}}\Deffunc{assert} \subsubsection*{\ff{\tt assert (v)}}\Deffunc{assert}
This function issues an {\em ``assertion failed!''} error This function issues an {\em ``assertion failed!''} error
when its argument is \nil. when its argument is \nil.
\subsubsection*{{\tt error (message)}}\Deffunc{error}\label{pdf-error} \subsubsection*{\ff{\tt error (message)}}\Deffunc{error}\label{pdf-error}
This function issues an error message and terminates This function issues an error message and terminates
the last called function from the library the last called function from the library
(\verb'lua_dofile', \verb'lua_dostring', \ldots). (\verb'lua_dofile', \verb'lua_dostring', \ldots).
It never returns. It never returns.
\subsubsection*{{\tt setglobal (name, value)}}\Deffunc{setglobal} \subsubsection*{\ff{\tt setglobal (name, value)}}\Deffunc{setglobal}
This function assigns the given value to a global variable. This function assigns the given value to a global variable.
The string \verb'name' does not need to be a syntactically valid variable name. The string \verb'name' does not need to be a syntactically valid variable name.
Therefore, this function can set global variables with strange names like Therefore, this function can set global variables with strange names like
\verb'm v 1' or \verb'34'. \verb|`m v 1'| or \verb'34'.
It returns the value of its second argument. It returns the value of its second argument.
\subsubsection*{{\tt getglobal (name)}}\Deffunc{getglobal} \subsubsection*{\ff{\tt getglobal (name)}}\Deffunc{getglobal}
This function retrieves the value of a global variable. This function retrieves the value of a global variable.
The string \verb'name' does not need to be a syntactically valid variable name. The string \verb'name' does not need to be a syntactically valid variable name.
\subsubsection*{{\tt setfallback (fallbackname, newfallback)}} \subsubsection*{\ff{\tt setfallback (fallbackname, newfallback)}}
\Deffunc{setfallback} \Deffunc{setfallback}
This function sets a new fallback function to the given fallback. This function sets a new fallback function to the given fallback.
It returns the old fallback function. It returns the old fallback function.
\subsection{String Manipulation} \subsection{String Manipulation}
This library provides generic functions for string manipulation, This library provides generic functions for string manipulation,
such as finding and extracting substrings. such as finding and extracting substrings and pattern matching.
When indexing a string, the first character has position 1. When indexing a string, the first character has position 1.
See Section \ref{exstring} for some examples on string manipulation See Page~\pageref{pm} for an explanation about patterns,
and Section~\ref{exstring} for some examples on string manipulation
in Lua. in Lua.
\subsubsection*{{\tt strfind (str, substr, [init, [end]])}} \subsubsection*{\ff{\tt strfind (str, pattern [, init [, plain]])}}
\Deffunc{strfind} \Deffunc{strfind}
Receives two string arguments, This function looks for the first {\em match} of
and returns a number. \verb-pattern- in \verb-str-.
This number indicates the first position where the second argument appears If it finds one, it returns the indexes on \verb-str-
in the first argument. where this occurence starts and ends;
If the second argument is not a substring of the first one, otherwise, it returns \nil.
then \verb'strfind' returns \nil. If the pattern specifies captures,
A third optional numerical argument specifies where to start the search. the captured strings are returned as extra results.
Another optional numerical argument specifies where to stop it. A third optional numerical argument specifies where to start the search;
its default value is 1.
A value of 1 as a forth optional argument
turns off the pattern matching facilities,
so the function does a plain ``find substring'' operation.
\subsubsection*{{\tt strlen (s)}}\Deffunc{strlen} \subsubsection*{\ff{\tt strlen (s)}}\Deffunc{strlen}
Receives a string and returns its length. Receives a string and returns its length.
\subsubsection*{{\tt strsub (s, i, [j])}}\Deffunc{strsub} \subsubsection*{\ff{\tt strsub (s, i [, j])}}\Deffunc{strsub}
Returns another string, which is a substring of \verb's', Returns another string, which is a substring of \verb's',
starting at \verb'i' and runing until \verb'j'. starting at \verb'i' and runing until \verb'j'.
If \verb'j' is absent, If \verb'j' is absent,
@ -1271,21 +1280,25 @@ with length \verb'j',
whereas the call \verb'strsub(s,i)' returns a suffix of \verb's', whereas the call \verb'strsub(s,i)' returns a suffix of \verb's',
starting at \verb'i'. starting at \verb'i'.
\subsubsection*{{\tt strlower (s)}}\Deffunc{strlower} \subsubsection*{\ff{\tt strlower (s)}}\Deffunc{strlower}
Receives a string and returns a copy of that string with all Receives a string and returns a copy of that string with all
upper case letters changed to lower case. upper case letters changed to lower case.
All other characters are left unchanged. All other characters are left unchanged.
\subsubsection*{{\tt strupper (s)}}\Deffunc{strupper} \subsubsection*{\ff{\tt strupper (s)}}\Deffunc{strupper}
Receives a string and returns a copy of that string with all Receives a string and returns a copy of that string with all
lower case letters changed to upper case. lower case letters changed to upper case.
All other characters are left unchanged. All other characters are left unchanged.
\subsubsection*{{\tt ascii (s, [i])}}\Deffunc{ascii} \subsubsection*{\ff{\tt strrep (s, n)}}\Deffunc{strrep}
Returns a string which is the concatenation of \verb-n- copies of
the string \verb-s-.
\subsubsection*{\ff{\tt ascii (s [, i])}}\Deffunc{ascii}
Returns the ascii code of the character \verb's[i]'. Returns the ascii code of the character \verb's[i]'.
If \verb'i' is absent, then it is assumed to be 1. If \verb'i' is absent, then it is assumed to be 1.
\subsubsection*{{\tt format (formatstring, e1, e2, \ldots)}}\Deffunc{format} \subsubsection*{\ff{\tt format (formatstring, e1, e2, \ldots)}}\Deffunc{format}
\label{format} \label{format}
This function returns a formated version of its variable number of arguments This function returns a formated version of its variable number of arguments
following the description given in its first argument (which must be a string). following the description given in its first argument (which must be a string).
@ -1300,12 +1313,120 @@ back by the Lua interpreter.
The string is written between double quotes, The string is written between double quotes,
and all double quotes, returns and backslashes in the string and all double quotes, returns and backslashes in the string
are correctly escaped when written. are correctly escaped when written.
For instance, the call
\begin{verbatim}
format('%q', 'a string with "quotes" and \n new line')
\end{verbatim}
will produce the string:
\begin{verbatim}
"a string with \"quotes\" and \
new line"
\end{verbatim}
The options \verb'c', \verb'd', \verb'E', \verb'e', \verb'f', The options \verb'c', \verb'd', \verb'E', \verb'e', \verb'f',
\verb'g' \verb'i', \verb'o', \verb'u', \verb'X', and \verb'x' all \verb'g' \verb'i', \verb'o', \verb'u', \verb'X', and \verb'x' all
expect a number argument, expect a number as argument,
whereas \verb'q' and \verb's' expect a string. whereas \verb'q' and \verb's' expect a string.
\subsubsection*{\ff{\tt gsub (s, from, to [, n])}}\Deffunc{gsub}
Returns a copy of \verb-s-,
where all ocurrences of the pattern \verb-from- have been
replaced by a replacement string specified by \verb-to-.
This function also returns, as a second value,
the total number of substitutions made.
If \verb-to- is a string, its value is used for replacement.
Any sequence in \verb-to- of the form \verb-%n- with \verb-n- between 1 and 9
stands for the value of the n-th captured substring.
If \verb-to- is a function, this function is called every time a
match occurs, with all captured substrings as parameters.
If the value returned by this function is a string,
it is used as the replacement string;
otherwise, the replacement string is the empty string.
An optional parameter \verb-n- limits
the maximum number of substitutions to occur.
For instance, when \verb-n- is 1 only the first ocurrence of
\verb-from- is replaced.
As an example, in the following expression each ocurrence of the form
\verb-$name$- calls the function \verb|getenv|,
passing \verb|name| as argument
(because only this part of the pattern is captured).
The value returned by \verb|getenv| will replace the pattern.
Therefore, the whole expression:
\begin{verbatim}
gsub('home = $HOME$, user = $USER$', "$(%w%w*)$", getenv)
\end{verbatim}
may return the string:
\begin{verbatim}
home = /home/roberto, user = roberto
\end{verbatim}
\subsubsection*{Patterns} \label{pm}
A \Def{character class} is used to represent a set of characters.
The following combinations are allowed in describing a character class:
\begin{description}
\item[{\em x}] (where {\em x} is any character not in the list \verb'()%.[*?')
--- represents the character {\em x} itself.
\item[{\tt .}] --- represents all characters.
\item[{\tt \%a}] --- represents all letters.
\item[{\tt \%A}] --- represents all non letter characters.
\item[{\tt \%d}] --- represents all digits.
\item[{\tt \%D}] --- represents all non digits.
\item[{\tt \%l}] --- represents all lower case letters.
\item[{\tt \%L}] --- represents all non lower case letter characters.
\item[{\tt \%s}] --- represents all space characters.
\item[{\tt \%S}] --- represents all non space characters.
\item[{\tt \%u}] --- represents all upper case letters.
\item[{\tt \%U}] --- represents all non upper case letter characters.
\item[{\tt \%w}] --- represents all alphanumeric characters.
\item[{\tt \%W}] --- represents all non alphanumeric characters.
\item[{\tt \%\em x}] (where {\em x} is any non alphanumeric character) ---
represents the character {\em x}.
\item[{\tt [char-set]}] ---
Represents the class which is the union of all
characters in char-set.
To include a \verb']' in char-set, it must be the first character.
A range of characters may be specified by
separating the end characters of the range with a \verb'-';
e.g., \verb'A-Z' specifies the upper case characters.
If \verb'-' appears as the first or last character of char-set,
then it represents itself.
All classes \verb'%'{\em x} described above can also be used as
components in a char-set.
All other characters in char-set represent themselves.
\item[{\tt [\^{ }char-set]}] ---
represents the complement of char-set,
where char-set is interpreted as above.
\end{description}
A \Def{pattern item} may be a single character class,
or a character class followed by \verb'*' or by \verb'?'.
A single character class matches any single character in the class.
A character class followed by \verb'*' matches 0 or more repetitions
of characters in the class.
A character class followed by \verb'?' matches 0 or one ocurrence
of a character in the class.
A pattern item may also has the form \verb'%n',
for \verb-n- between 1 and 9.
Such item matches a sub-string equal to the n-th captured string.
A \Def{pattern} is a sequence of pattern items.
Any repetition item (\verb'*') inside a pattern will always
match the longest possible sequence.
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.
A pattern may contain sub-patterns enclosed in parentheses,
that describe \Def{captures}.
When a match succeeds, the sub-strings of the subject string
that match captures are {\em captured} for future use.
Captures are numbered according to their left delimiter.
\subsection{Mathematical Functions} \label{mathlib} \subsection{Mathematical Functions} \label{mathlib}
@ -1333,8 +1454,6 @@ value of its numeric arguments.
Similarly, \verb'min' computes the minimum. Similarly, \verb'min' computes the minimum.
Both can be used with an unlimited number of arguments. Both can be used with an unlimited number of arguments.
The function \verb'mod' is equivalent to the \verb'%' operator in C.
The functions \verb'random' and \verb'randomseed' are interfaces to The functions \verb'random' and \verb'randomseed' are interfaces to
the simple random generator functions \verb'rand' and \verb'srand', the simple random generator functions \verb'rand' and \verb'srand',
provided by ANSI C. provided by ANSI C.
@ -1350,129 +1469,127 @@ Initially, the current input file is \verb'stdin',
and the current output file is \verb'stdout'. and the current output file is \verb'stdout'.
Unless otherwise stated, Unless otherwise stated,
all I/O functions return 1 on success and \nil\ on failure. all I/O functions return \nil\ on failure and
some value different from \nil\ on success.
\subsubsection*{{\tt readfrom (filename)}}\Deffunc{readfrom} \subsubsection*{\ff{\tt readfrom (filename)}}\Deffunc{readfrom}
This function opens a file named \verb'filename' and sets it as the This function may be called in three ways.
{\em current} input file. When called with a file name,
it opens the named file,
sets it as the {\em current} input file,
and returns a {\em handle} to the file
(this handle is a user data containing the file stream \verb|FILE *|).
When called with a file handle, returned by a previous call,
it restores the file as the current input.
When called without parameters, When called without parameters,
this function closes the current input file, it closes the current input file,
and restores \verb'stdin' as the current input file. and restores \verb'stdin' as the current input file.
If this function fails, it returns \nil.
{\em System dependent:} if \verb'filename' starts with a \verb'|', {\em System dependent:} if \verb'filename' starts with a \verb'|',
then a \Index{piped input} is open, via function \IndexVerb{popen}. then a \Index{piped input} is open, via function \IndexVerb{popen}.
\subsubsection*{{\tt writeto (filename)}}\Deffunc{writeto} \subsubsection*{\ff{\tt writeto (filename)}}\Deffunc{writeto}
This function opens a file named \verb'filename' and sets it as the This function may be called in three ways.
{\em current} output file. When called with a file name,
it opens the named file,
sets it as the {\em current} output file,
and returns a {\em handle} to the file
(this handle is a user data containing the file stream \verb|FILE *|).
Notice that, if the file already exists, Notice that, if the file already exists,
it will be {\em completely erased} with this operation. it will be {\em completely erased} with this operation.
When called with a file handle, returned by a previous call,
it restores the file as the current output.
When called without parameters, When called without parameters,
this function closes the current output file, this function closes the current output file,
and restores \verb'stdout' as the current output file. and restores \verb'stdout' as the current output file.
\index{closing a file} \index{closing a file}
If this function fails, it returns \nil.
{\em System dependent:} if \verb'filename' starts with a \verb'|', {\em System dependent:} if \verb'filename' starts with a \verb'|',
then a \Index{piped output} is open, via function \IndexVerb{popen}. then a \Index{piped output} is open, via function \IndexVerb{popen}.
\subsubsection*{{\tt appendto (filename)}}\Deffunc{appendto} \subsubsection*{\ff{\tt appendto (filename)}}\Deffunc{appendto}
This function opens a file named \verb'filename' and sets it as the This function opens a file named \verb'filename' and sets it as the
{\em current} output file. {\em current} output file.
It returns the file handle,
or \nil\ in case of error.
Unlike the \verb'writeto' operation, Unlike the \verb'writeto' operation,
this function does not erase any previous content of the file. this function does not erase any previous content of the file.
\subsubsection*{{\tt remove (filename)}}\Deffunc{remove} \subsubsection*{\ff{\tt remove (filename)}}\Deffunc{remove}
This function deletes the file with the given name. This function deletes the file with the given name.
\subsubsection*{{\tt rename (name1, name2)}}\Deffunc{rename} \subsubsection*{\ff{\tt rename (name1, name2)}}\Deffunc{rename}
This function renames file \verb'name1' to \verb'name2'. This function renames file \verb'name1' to \verb'name2'.
\subsubsection*{{\tt tmpname ()}}\Deffunc{tmpname} \subsubsection*{\ff{\tt tmpname ()}}\Deffunc{tmpname}
This function returns a string with a file name that can safely This function returns a string with a file name that can safely
be used for a temporary file. be used for a temporary file.
\subsubsection*{{\tt read ([format])}}\Deffunc{read} \subsubsection*{\ff{\tt read ([readpattern])}}\Deffunc{read}
This function returns a value read from the current input. This function reads the current input
An optional string argument specifies the way the input is interpreted. according to a read pattern, that specifies how much to read;
characters are read from the current input file until
the read pattern fails or ends.
The function \verb|read| returns a string with the characters read,
or \nil\ if the result string would be empty {\em and\/}
the read pattern fails.
When called without parameters,
it uses a default pattern that reads the next line
(see below).
Without a format argument, {\tt read} first skips blanks, tabs and newlines. A \Def{read pattern} is a sequence of read pattern items.
Then it checks whether the current character is \verb'"' or \verb-'-. An item may be a single character class
If so, it reads a string up to the ending quotation mark, or a character class followed by \verb'?' or by \verb'*'.
and returns this string, without the quotation marks. A single character class reads the next character from the input
Otherwise it reads up to a blank, tab or newline. if it belongs to the class, otherwise it fails.
A character class followed by \verb'?' reads the next character
from the input if it belongs to the class;
it never fails.
A character class followed by \verb'*' reads until a character that
does not belong to the class, or end of file;
it never fails.%
\footnote{
Notice that this behaviour is different from regular pattern matching,
where a \verb'*' expands to the maximum length {\em such that}
the rest of the pattern does not fail.}
The format string can have the following format: A pattern item may contain sub-patterns enclosed in curly brackets,
\begin{verbatim} that describe \Def{skips}.
?[n] Characters matching a skip are read,
\end{verbatim} but are not included in the resulting string.
where \verb'?' can be:
\begin{description}
\item['s' or 'S'] to read a string;
\item['f' or 'F'] to read a real number;
\item['i' or 'I'] to read an integer.
\end{description}
The optional \verb'n' is a number which specifies how many characters
must be read to compose the input value.
Particularly, the format \verb'"s1"' reads a single character.
\subsubsection*{{\tt readuntil (char)}}\Deffunc{readuntil} Following are some examples of read patterns and their meanings:
Reads the current input until the first ocurrence of the given character.
When called with no parameters,
reads until the end of the current input file.
Returns the string read.
The character itself is not read.
\subsubsection*{{\tt write (value, [format])}}\Deffunc{write}
This function writes the value of its first argument to the current output.
An optional second argument specifies the format to be used.
This format is given as a string, composed of four parts.
The first part is the only one not optional, and must be one of the
following characters:
\begin{description}
\item['s' or 'S'] to write strings;
\item['f' or 'F'] to write floats;
\item['i' or 'I'] to write integers;
\item['q' or 'Q'] to write quoted strings.
This format writes the 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.
\end{description}
These characters can be followed by
\begin{verbatim}
[?][m][.n]
\end{verbatim}
where:
\begin{description}
\item[\verb'?'] indicates justification inside the field.
\begin{itemize} \begin{itemize}
\item['\verb'<''] right justification (default); \item \verb|"."| returns the next character, or \nil\ on end of file.
\item['\verb'>''] left justification; \item \verb|".*"| reads the whole file.
\item['\verb'|''] center justification. \item \verb|"[^\n]*{\n}"| returns the next line
(skipping the end of line), or \nil\ on end of file.
This is the default pattern.
\item \verb|"{%s*}%S%S*"| returns the next word
(maximal sequence of non white-space characters),
or \nil\ on end of file.
\item \verb|"{%s*}[+-]?%d%d*"| returns the next integer
or \nil\ if the next characters do not conform to an integer format.
\end{itemize} \end{itemize}
\item[\verb'm'] Indicates the field size in characters.
\item[\verb'.n'] For reals, indicates the number of digital places.
For integers, it is the minimum number of digits.
This option has no meaning for strings.
\end{description}
When called without a format string, \subsubsection*{\ff{\tt write (value1, ...)}}\Deffunc{write}
this function writes numbers using the \verb'%g' format
and strings with \verb'%s'.
For better format facilities,
the function \verb'format' should be used (\see{format}).
\subsubsection*{{\tt date ([format])}}\Deffunc{date} This function writes the value of each of its arguments to the
current output file.
The arguments must be strings or numbers.
\subsubsection*{\ff{\tt date ([format])}}\Deffunc{date}
This function returns a string containing date and time This function returns a string containing date and time
formatted according to the given string \verb'format', formatted according to the given string \verb'format',
@ -1480,15 +1597,23 @@ following the same rules of the ANSI C function \verb'strftime'.
When called without arguments, When called without arguments,
it returns a reasonable date and time representation. it returns a reasonable date and time representation.
This function replaces functions \verb'date' and \verb'time' from \subsubsection*{\ff{\tt exit ([code])}}\Deffunc{exit}
previous Lua versions.
\subsubsection*{{\tt exit ([code])}}\Deffunc{exit}
This function calls the C function \verb-exit-, This function calls the C function \verb-exit-,
with an optional \verb-code-, with an optional \verb-code-,
to terminate the program. to terminate the program.
\subsubsection*{\ff{\tt getenv (varname)}}\Deffunc{getenv}
Returns the value of the environment variable \verb|varname|,
or \nil\ if the variable is not defined.
\subsubsection*{\ff{\tt execute (command)}}\Deffunc{execute}
This function is equivalent to the C function \verb|system|.
It passes \verb|command| to be executed by an Operating System Shell.
It returns an error code, which is implementation-defined.
\section{The Debugger Interface} \label{debugI} \section{The Debugger Interface} \label{debugI}
@ -1496,7 +1621,7 @@ Lua has no built-in debugger facilities.
Instead, it offers a special interface, Instead, it offers a special interface,
by means of functions and {\em hooks}, by means of functions and {\em hooks},
which allows the construction of different which allows the construction of different
kinds of debugers, profilers, and other tools kinds of debuggers, profilers, and other tools
that need ``inside information'' from the interpreter. that need ``inside information'' from the interpreter.
This interface is declared in the header file \verb'luadebug.h'. This interface is declared in the header file \verb'luadebug.h'.
@ -1699,32 +1824,21 @@ end
\subsection{String Manipulation} \label{exstring} \subsection{String Manipulation} \label{exstring}
The first example is a function to trim extra blanks at the beginning The first example is a function to trim extra white-spaces at the beginning
and end of a string. and end of a string.
\begin{verbatim} \begin{verbatim}
function trim(s) function trim(s)
local l = 1 local _, i = strfind(s, '^ *')
while strsub(s,l,l) == ' ' do local f, __ = strfind(s, ' *$')
l = l+1 return strsub(s, i+1, f-1)
end
local r = strlen(s)
while strsub(s,r,r) == ' ' do
r = r-1
end
return strsub(s,l,r)
end end
\end{verbatim} \end{verbatim}
The second example shows a function that eliminates all blanks The second example shows a function that eliminates all spaces
of a string. of a string.
\begin{verbatim} \begin{verbatim}
function remove_blanks (s) function remove_blanks (s)
local b = strfind(s, ' ') return gsub(s, "%s%s*", "")
while b do
s = strsub(s, 1, b-1) .. strsub(s, b+1)
b = strfind(s, ' ')
end
return s
end end
\end{verbatim} \end{verbatim}
@ -2058,6 +2172,46 @@ void remove_blanks (char *s)
\end{verbatim} \end{verbatim}
\section{\Index{Lua Stand-alone}}
Although Lua has been designed as an extension language,
the language can also be used as a stand-alone interpreter.
An implementation of such an interpreter,
called simply \verb|lua|,
is provided with the standard distribution.
This program can be called with any sequence of the following arguments:
\begin{description}
\item[{\tt -v}] prints version information.
\item[{\tt -}] runs interactively, accepting commands from standard input
until an \verb|EOF|.
\item[{\tt -e stat}] executes \verb|stat| as a Lua chunck.
\item[{\tt var=exp}] executes \verb|var=exp| as a Lua chunck.
\item[{\tt filename}] executes file \verb|filename| as a Lua chunck.
\end{description}
All arguments are handle in order.
For instance, an invocation like
\begin{verbatim}
$ lua - a=1 prog.lua
\end{verbatim}
will first interact with the user until an \verb|EOF|,
then will set \verb'a' to 1,
and finally will run file \verb'prog.lua'.
Please notice that the interaction with the shell may lead to
unintended results.
For instance, a call like
\begin{verbatim}
$ lua a="name" prog.lua
\end{verbatim}
will {\em not} set \verb|a| to the string \verb|"name"|.
Instead, the quotes will be handled by the shell,
lua will get only \verb'a=name' to run,
and \verb'a' will finish with \nil.
Instead, one should write
\begin{verbatim}
$ lua 'a="name"' prog.lua
\end{verbatim}
\section*{Acknowledgments} \section*{Acknowledgments}
The authors would like to thank CENPES/PETROBR\'AS which, The authors would like to thank CENPES/PETROBR\'AS which,
@ -2076,7 +2230,27 @@ Lua means {\em moon} in Portuguese.
Although great care has been taken to avoid incompatibilities with Although great care has been taken to avoid incompatibilities with
the previous public versions of Lua, the previous public versions of Lua,
some differences had to be introduced. some differences had to be introduced.
Here is a list of all these differences. Here is a list of all these incompatibilities.
\subsection*{Incompatibilities with \Index{version 2.4}}
The whole I/O facilities have been rewritten.
We strongly encourage programmers to addapt their code
to this new version.
However, we are keeping the old version of the libraries
in the distribution,
to allow a smooth transition.
The incompatibilities between the new and the old libraries are:
\begin{itemize}
\item The format facility of function \verb'write' has been supersed by
function \verb'format';
therefore this facility has been dropped.
\item Function \verb'read' now uses {\em read patterns} to specify
what to read;
this is incompatible with the old format options.
\item Function \verb'strfind' now accepts patterns,
so it may have a different behavior when the pattern includes
special characteres.
\end{itemize}
\subsection*{Incompatibilities with \Index{version 2.2}} \subsection*{Incompatibilities with \Index{version 2.2}}
\begin{itemize} \begin{itemize}