mirrors/lua
1
0
Fork 0
mirror of https://github.com/lua/lua synced 2024-12-25 03:46:50 +03:00
Code Issues Packages Projects Releases Wiki Activity

lots of new stuff from 3.2

Browse Source
This commit is contained in:
Roberto Ierusalimschy 1999-02-05 10:15:07 -02:00
parent 028ec00ab9
commit 8fdd06ba3c
1 changed files with 138 additions and 69 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

207
manual.tex
View File

@ -1,4 +1,4 @@
% $Id: manual.tex,v 1.20 1998/11/13 16:48:48 roberto Exp roberto $
% $Id: manual.tex,v 1.21 1998/11/20 15:41:43 roberto Exp roberto $
\documentclass[11pt]{article}
\usepackage{fullpage,bnf}
@ -41,7 +41,7 @@ Waldemar Celes
\tecgraf\ --- Computer Science Department --- PUC-Rio
}
%\date{\small \verb$Date: 1998/11/13 16:48:48 $}
%\date{\small \verb$Date: 1998/11/20 15:41:43 $}
\maketitle
@ -410,11 +410,7 @@ Lua provides some automatic conversions between values at run time.
Any arithmetic operation applied to a string tries to convert
that string to a number, following the usual rules.
Conversely, whenever a number is used when a string is expected,
that number is converted to a string, according to the following rule:
if the number is an integer, it is written without exponent or decimal point;
otherwise, it is formatted following the \verb|%g|
conversion specification of the \verb|printf| function in the
standard C library.
that number is converted to a string, in a reasonable format.
For complete control on how numbers are converted to strings,
use the \verb|format| function \see{format}.
@ -523,9 +519,9 @@ only \nil\ is considered false.
\begin{Produc}
\produc{stat}{\rwd{while} exp1 \rwd{do} block \rwd{end} \OrNL
\rwd{repeat} block \rwd{until} exp1 \OrNL
\rwd{if} exp1 \rwd{then} block \rep{elseif}
\rwd{if} exp1 \rwd{then} block
\rep{\rwd{elseif} exp1 \rwd{then} block}
\opt{\rwd{else} block} \rwd{end}}
\produc{elseif}{\rwd{elseif} exp1 \rwd{then} block}
\end{Produc}
A \T{return} is used to return values from a function or from a chunk.
@ -688,6 +684,24 @@ All binary operators are left associative,
except for \verb|^| (exponentiation),
which is right associative.
\subsubsection{If Expressions}
\begin{Produc}
\produc{exp}{\rwd{if} exp1 \rwd{then} exp1
\rep{\rwd{elseif} exp1 \rwd{then} exp1}
\opt{\rwd{else} exp1} \rwd{end}}
\end{Produc}%
An \Index{if expression} chooses an expression to evaluate
according to its condition.
Its final value is the value of the chosen expression.
An absent else-part is equivalent to \verb|else nil|.
\subsubsection{Assignment Expressions}
\begin{Produc}
\produc{exp}{\ter{(} var \ter{=} exp1 \ter{)}}
\end{Produc}%
An \Index{assignment expression} executes a regular assignment,
and results in the final value of its right hand expression.
\subsubsection{Table Constructors} \label{tableconstructor}
Table \Index{constructors} are expressions that create tables;
every time a constructor is evaluated, a new table is created.
@ -1978,8 +1992,9 @@ field not present in a table or a field with value \nil.
Therefore, the function only considers fields with non \nil\ values.
The order in which the indices are enumerated is not specified,
\emph{even for numeric indices}
(to traverse a table in numeric order, use a counter).
If the table is modified in any way during a traversal,
(to traverse a table in numeric order,
use a counter or function \verb|foreachi|).
If the table indices are modified in any way during a traversal,
the semantics of \verb|next| is undefined.
This function cannot be written with the standard API.
@ -1992,7 +2007,7 @@ or \nil\ to get a first name.
Similarly to \verb|next|, it returns the name of another variable
and its value,
or \nil\ if there are no more variables.
There can be no assignments to global variables during the traversal;
There can be no creation of new global variables during the traversal;
otherwise the semantics of \verb|nextvar| is undefined.
This function cannot be written with the standard API.
@ -2150,14 +2165,13 @@ value in the table.
This function could be defined in Lua:
\begin{verbatim}
function getn (t)
if type(t.n) == 'number' then return floor(t.n) end
local i = next(t, nil)
if type(t.n) == 'number' then return t.n end
local i = nil
local max = 0
while i do
while (i=next(t, i)) do
if type(i) == 'number' and i>max then max=i end
i = next(t, i)
end
return floor(max)
return max
end
\end{verbatim}
@ -2198,11 +2212,10 @@ as the final value of \verb|foreachi|.
This function could be defined in Lua:
\begin{verbatim}
function foreachi (t, f)
local i, n = 1, getn(t)
while i<=n do
local i, n = 0, getn(t)
while (i=i+1)<=n do
local res = f(i, t[i])
if res then return res end
i = i+1
end
end
\end{verbatim}
@ -2227,50 +2240,80 @@ This function could be defined in Lua:
end
\end{verbatim}
\subsubsection*{\ff \T{tinsert (table [, pos] , value)}}\Deffunc{tinsert}
Inserts element \verb|value| at table position \verb|pos|,
shifting other elements to open space.
The default value for \verb|pos| is \verb|n+1|
(where \verb|n| is the result of \verb|getn(table)| \see{getn})
so that a call \verb|tinsert(t,x)| inserts \verb|x| at the end
of table \verb|t|.
This function also sets or increments the field \verb|n| of the table,
to \verb|n+1|.
This function is equivalent to the following Lua function,
except that the table accesses are all raw (that is, without tag methods):
\begin{verbatim}
function tinsert (t, ...)
local pos, value
local n = getn(t)
if arg.n == 1 then
pos = n+1; value = arg[1]
else
pos = arg[1]; value = arg[2]
end
t.n = n+1; n=n+1
while (n=n-1)>=pos do
t[n+1] = t[n]
end
t[pos] = value
end
\end{verbatim}
\subsubsection*{\ff \T{tremove (table [, pos])}}\Deffunc{tremove}
Removes from \verb|table| the element at position \verb|pos|,
shifting other elements to close the space.
Returns the value of the removed element.
The default value for \verb|pos| is \verb|n|
(where \verb|n| is the result of \verb|getn(table)| \see{getn}),
so that a call \verb|tremove(t)| removes the last element
of table \verb|t|.
This function also sets or decrements the field \verb|n| of the table,
to \verb|n-1|.
This function is equivalent to the following Lua function,
except that the table accesses are all raw (that is, without tag methods):
\begin{verbatim}
function tremove (t, pos)
local n = getn(t)
pos = pos or n
local value = t[pos]
if n<=0 then return end
t.n = n-1
pos = pos-1
while (pos=pos+1)<n do
t[pos] = t[pos+1]
end
return value
end
\end{verbatim}
\subsubsection*{\ff \T{sort (table [, comp])}}\Deffunc{sort}
Sorts table elements in ascending order, \emph{in-place},
Sorts table elements in a given order, \emph{in-place},
from \verb|table[1]| to \verb|table[n]|,
where \verb|n| is the result of \verb|getn(table)| \see{getn}.
If \verb|comp| is given,
it must be a function that compares two table elements,
it must be a function that receives two table elements,
and returns true when the first is less than the second
(that is, \verb|not comp(a[i+1], a[i])| will be true after the sort).
(so that \verb|not comp(a[i+1], a[i])| will be true after the sort).
If \verb|comp| is not given,
the standard \verb|<| Lua operator is used instead.
Function \verb|sort| returns the (sorted) table.
This function could be defined in Lua:
\begin{verbatim}
function aux_qsort (a, l, u, leq)
if l < u then
local m = floor((l+u)/2) -- choose middle element as pivot
a[l], a[m] = a[m], a[l] -- swap pivot to first position
local t = a[l] -- pivot value
m = l
local i = l+1
while i <= u do
-- invariant: a[l+1..m] < t <= a[m+1..i-1]
if leq(a[i], t) then
m = m+1
a[m], a[i] = a[i], a[m] -- swap
end
i = i+1
end
a[l], a[m] = a[m], a[l] -- swap pivot to a valid place
-- a[l+1..m-1] < a[m] <= a[m+1..u]
aux_qsort(a, l, m-1, leq)
aux_qsort(a, m+1, u, leq)
end
return a -- return the table
end
function sort (a, f)
f = f or function (a,b) return a<b end
return aux_qsort(a, 1, getn(a), f)
end
\end{verbatim}
\subsection{String Manipulation}
This library provides generic functions for string manipulation,
@ -2364,9 +2407,8 @@ The only differences are that the options/modifiers
and \verb|h| are not supported,
and there is an extra option, \verb|q|.
This option formats a string in a form suitable to be safely read
back by the Lua interpreter;
that is,
the string is written between double quotes,
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
@ -2393,7 +2435,7 @@ 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.
Note that the \verb|*| modifier can be simulated by building
The \verb|*| modifier can be simulated by building
the appropriate format string.
For example, \verb|"%*g"| can be simulated with
\verb|"%"..width.."g"|.
@ -2464,17 +2506,15 @@ The following combinations are allowed in describing a character class:
--- represents the character \emph{x} itself.
\item[\T{.}] --- (a dot) represents all characters.
\item[\T{\%a}] --- represents all letters.
\item[\T{\%A}] --- represents all non letter characters.
\item[\T{\%c}] --- represents all control characters.
\item[\T{\%d}] --- represents all digits.
\item[\T{\%D}] --- represents all non digits.
\item[\T{\%l}] --- represents all lower case letters.
\item[\T{\%L}] --- represents all non lower case letter characters.
\item[\T{\%p}] --- represents all punctuation characters.
\item[\T{\%s}] --- represents all space characters.
\item[\T{\%S}] --- represents all non space characters.
\item[\T{\%u}] --- represents all upper case letters.
\item[\T{\%U}] --- represents all non upper case letter characters.
\item[\T{\%w}] --- represents all alphanumeric characters.
\item[\T{\%W}] --- represents all non alphanumeric characters.
\item[\T{\%x}] --- represents all hexa-decimal digits.
\item[\T{\%z}] --- represents the character with representation 0.
\item[\T{\%\M{x}}] (where \M{x} is any non alphanumeric character) ---
represents the character \M{x}.
This is the standard way to escape the magic characters \verb|()%.[*-?|.
@ -2495,6 +2535,9 @@ E.g., assuming an \emph{ascii} character set,
represents the complement of char-set,
where char-set is interpreted as above.
\end{description}
For all classes represented by single letters (\verb|%a|, \verb|%c|, \ldots),
the correspondent upper-case letter represents the complement of the class.
For instance, \verb|%S| represents all non-space characters.
The definitions of letter, space, etc. depend on the current locale.
In particular, the class \verb|[a-z]| may not be equivalent to \verb|%l|.
@ -2591,6 +2634,8 @@ The function \verb|random|, when called without arguments,
returns a pseudo-random real number in the range \Math{[0,1)}.
When called with a number \Math{n},
\verb|random| returns a pseudo-random integer in the range \Math{[1,n]}.
When called with two arguments, \Math{l} and \Math{u},
\verb|random| returns a pseudo-random integer in the range \Math{[l,u]}.
\subsection{I/O Facilities} \label{libio}
@ -2891,10 +2936,18 @@ then \verb|linedefined| is \Math{-1}, and \verb|filename| is \verb|"(C)"|.
The function \verb|lua_currentline| gives the current line where
a given function is executing.
It only works if the function has been compiled with debug
information \see{pragma}.
information.
When no line information is available,
\verb|lua_currentline| returns \Math{-1}.
The generation of debug information is controled by an internal flag,
which can be switched with
\begin{verbatim}
int lua_setdebug (int debug);
\end{verbatim}
This function sets the flag and returns its previous value.
This flag can also be set from Lua~\see{pragma}.
Function \verb|lua_getobjname| tries to find a reasonable name for
a given function.
Because functions in Lua are first class values,
@ -2918,6 +2971,8 @@ The following functions allow the manipulation of the
local variables of a given activation record.
They only work if the function has been compiled with debug
information \see{pragma}.
Moreover, for these functions, a local variable becomes
visible in the line after its definition.
\begin{verbatim}
lua_Object lua_getlocal (lua_Function func, int local_number, char **name);
int lua_setlocal (lua_Function func, int local_number);
@ -2947,17 +3002,17 @@ then this function fails and returns 0.
The Lua interpreter offers two hooks for debugging purposes:
\begin{verbatim}
typedef void (*lua_CHFunction) (lua_Function func, char *file, int line);
extern lua_CHFunction lua_callhook;
lua_CHFunction lua_setcallhook (lua_CHFunction func);
typedef void (*lua_LHFunction) (int line);
extern lua_LHFunction lua_linehook;
lua_LHFunction lua_setlinehook (lua_LHFunction func);
\end{verbatim}
The first one is called whenever the interpreter enters or leaves a
function.
When entering a function,
its parameters are a handle to the function activation record,
plus the file and the line where the function is defined (the same
information which is provided by \verb|lua_funcinfo|);
plus the file and the line where the function is defined
(the same information which is provided by \verb|lua_funcinfo|);
when leaving a function, \verb|func| is \verb|LUA_NOOBJECT|,
\verb|file| is \verb|"(return)"|, and \verb|line| is 0.
@ -2971,6 +3026,8 @@ has been compiled with debug information \see{pragma}.
A hook is disabled when its value is \verb|NULL|,
which is the initial value of both hooks.
Both \verb|lua_setcallhook| and \verb|lua_setlinehook|
set their corresponding hooks and return their previous values.
@ -3040,6 +3097,18 @@ the previous public versions of Lua,
some differences had to be introduced.
Here is a list of all these incompatibilities.
\subsection*{Incompatibilities with \Index{version 3.1}}
\begin{itemize}
\item
In the debug API, the old variables \verb|lua_debug|,
\verb|lua_callhook| and \verb|lua_linehook| now live inside \verb|lua_state|.
Therefore, they are no more directly accessible, and must be
manipulated through the new functions \verb|lua_setdebug|,
\verb|lua_setcallhook| and \verb|lua_setlinehook|.
\item Old pre-compiled code is obsolete, and must be re-compiled.
\end{itemize}
\subsection*{Incompatibilities with \Index{version 3.0}}
\begin{itemize}