diff --git a/manual.tex b/manual.tex index 6573c472..37b51ba0 100644 --- a/manual.tex +++ b/manual.tex @@ -1,8 +1,7 @@ -% $Id: manual.tex,v 2.8 1997/06/27 22:38:49 roberto Exp roberto $ +% $Id: manual.tex,v 2.9 1997/07/01 17:41:34 roberto Exp roberto $ \documentstyle[fullpage,11pt,bnf]{article} -\newcommand{\rw}[1]{{\bf #1}} \newcommand{\See}[1]{Section~\ref{#1}} \newcommand{\see}[1]{(see \See{#1})} \newcommand{\M}[1]{\emph{#1}} @@ -39,7 +38,7 @@ Waldemar Celes \tecgraf\ --- Computer Science Department --- PUC-Rio } -\date{\small \verb$Date: 1997/06/27 22:38:49 $} +\date{\small \verb$Date: 1997/07/01 17:41:34 $} \maketitle @@ -167,14 +166,14 @@ Before the first assignment, the value of a global variable is \nil; this default can be changed \see{tag-method}. The unit of execution of Lua is called a \Def{chunk}. -The syntax% -\footnote{As usual, \rep{\emph{a}} means 0 or more \emph{a}'s, -\opt{\emph{a}} means an optional \emph{a} and \oneormore{\emph{a}} means -one or more \emph{a}'s.} -for chunks is: +The syntax for chunks is: \begin{Produc} \produc{chunk}{\rep{stat \Or function} \opt{ret}} \end{Produc}% +(As usual, \rep{\emph{a}} means 0 or more \emph{a}'s, +\opt{\emph{a}} means an optional \emph{a} and \oneormore{\emph{a}} means +one or more \emph{a}'s.) + A chunk may contain statements and function definitions, and may be in a file or in a string inside the host program. A chunk may optionally end with a \verb|return| statement \see{return}. @@ -182,10 +181,10 @@ When a chunk is executed, first all its functions and statements are compiled, then the statements are executed in sequential order. All modifications a chunk effects on the global environment persist after its end. -Those include modifications to global variables and definitions -of new functions% -\footnote{Actually, a function definition is an -assignment to a global variable \see{TypesSec}.}. +Those include modifications to global variables +and definitions of new functions +(actually, a function definition is an +assignment to a global variable \see{TypesSec}). Chunks may be pre-compiled into binary form; see program \IndexVerb{luac} for details. @@ -207,7 +206,9 @@ There are six \Index{basic types} in Lua: \Def{nil}, \Def{number}, \emph{Nil} is the type of the value \nil, whose main property is to be different from any other value. \emph{Number} represents real (floating-point) numbers, -while \emph{string} has the usual meaning. +while \emph{string} has the usual meaning; +notice that Lua is \Index{eight-bit clean}, +so strings can have ISO characters. The function \verb|type| returns a string describing the type of a given value \see{pdf-type}. @@ -275,9 +276,11 @@ This section describes the lexis, the syntax and the semantics of Lua. \subsection{Lexical Conventions} \label{lexical} -Lua is a case-sensitive language. \Index{Identifiers} can be any string of letters, digits, and underscores, not beginning with a digit. +The definition of letter depends on the current locale: +Any character considered alphabetic by the current locale +can be used in an identifier. The following words are reserved, and cannot be used as identifiers: \index{reserved words} \begin{verbatim} @@ -286,6 +289,9 @@ The following words are reserved, and cannot be used as identifiers: nil not or repeat return then until while \end{verbatim} +Lua is a case-sensitive language: +\T{and} is a reserved word, but \T{And} and \T{\'and} +(if the locale permits) are two other different identifiers. The following strings denote other \Index{tokens}: \begin{verbatim} @@ -307,9 +313,9 @@ other quoted strings. \Index{Comments} start anywhere outside a string with a double hyphen (\verb|--|) and run until the end of the line. Moreover, -the first line of a chunk file is skipped if it starts with \verb|#|% -\footnote{This facility allows the use of Lua as a script interpreter -in Unix systems \see{lua-sa}.}. +the first line of a chunk file is skipped if it starts with \verb|#|. +This facility allows the use of Lua as a script interpreter +in Unix systems \see{lua-sa}. \Index{Numerical constants} may be written with an optional decimal part, and an optional decimal exponent. @@ -325,9 +331,9 @@ The \verb|$| can be followed by any of the following directives: \begin{description} \item[\T{debug}] --- turn on some debugging facilities \see{pragma}. \item[\T{nodebug}] --- turn off some debugging facilities \see{pragma}. -\item[{\tt if \M{cond}}] --- starts a conditional part. +\item[\T{if \M{cond}}] --- starts a conditional part. If \M{cond} is false, then this part is skipped by the lexical analyzer. -\item[{\tt ifnot \M{cond}}] --- starts a conditional part. +\item[\T{ifnot \M{cond}}] --- starts a conditional part. If \M{cond} is true, then this part is skipped by the lexical analyzer. \item[\T{end}] --- ends a conditional part. \item[\T{else}] --- starts an ``else'' conditional part, @@ -439,9 +445,9 @@ an assignment \verb|x = val|, where \verb|x| is a global variable, is equivalent to a call \verb|setglobal('x', val)|; an assignment \verb|t[i] = val| is equivalent to \verb|settable_event(t, i, val)|. -See \See{tag-method} for a description of these functions% -\footnote{Function \verb|setglobal| is pre-defined in Lua. -Function \T{settable\_event} is used only for explanatory purposes.}. +See \See{tag-method} for a description of these functions. +(Function \verb|setglobal| is pre-defined in Lua. +Function \T{settable\_event} is used only for explanatory purposes.) The syntax \verb|var.NAME| is just syntactic sugar for \verb|var["NAME"]|: @@ -515,9 +521,9 @@ An access to a global variable \verb|x| is equivalent to a call \verb|getglobal('x')|; an access to an indexed variable \verb|t[i]| is equivalent to a call \verb|gettable_event(t, i)|. -See \See{tag-method} for a description of these functions% -\footnote{Function \verb|getglobal| is pre-defined in Lua. -Function \T{gettable\_event} is used only for explanatory purposes.}. +See \See{tag-method} for a description of these functions. +(Function \verb|getglobal| is pre-defined in Lua. +Function \T{gettable\_event} is used only for explanatory purposes.) The non-terminal \M{exp1} is used to indicate that the values returned by an expression must be adjusted to one single value: @@ -563,9 +569,6 @@ If both arguments are numbers, then they are compared as such. Otherwise, if both arguments are strings, their values are compared using lexicographical order. Otherwise, the ``order'' tag method is called \see{tag-method}. -%Note that the conversion rules of Section~\ref{coercion} -%do apply to order operators. -%Thus, \verb|"2">"12"| evaluates to true. \subsubsection{Logical Operators} Like control structures, all logical operators @@ -643,7 +646,7 @@ is essentially equivalent to: The form \emph{ffieldlist1} initializes other fields in a table: \begin{Produc} \produc{ffieldlist1}{ffield \rep{\ter{,} ffield} \opt{\ter{,}}} -\produc{ffield}{\ter{[} exp \ter{]} \ter {=} exp \Or name \ter{=} exp} +\produc{ffield}{\ter{[} exp \ter{]} \ter{=} exp \Or name \ter{=} exp} \end{Produc}% For example: \begin{verbatim} @@ -1322,7 +1325,7 @@ The use of explicit nested blocks is strongly encouraged. \subsection{Executing Lua Code} A host program can execute Lua chunks written in a file or in a string -using the following functions:% +using the following functions: \Deffunc{lua_dofile}\Deffunc{lua_dostring} \begin{verbatim} int lua_dofile (char *filename); @@ -1967,7 +1970,7 @@ The following combinations are allowed in describing a character class: \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[{\tt \%\M{x}}] (where \M{x} is any non alphanumeric character) --- +\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|()%.[*-?|. \item[\T{[char-set]}] --- @@ -1976,17 +1979,21 @@ 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. +e.g., \verb|A-Z| specifies the English upper case characters. If \verb|-| appears as the first or last character of char-set, then it represents itself. All classes \verb|%|\emph{x} described above can also be used as components in a char-set. All other characters in char-set represent themselves. -\item[{\tt [\^{ }char-set]}] --- +\item[\T{[\^{ }char-set]}] --- represents the complement of char-set, where char-set is interpreted as above. \end{description} +The definitions of letter, space, etc depend on the current locale. +In particular, the class \verb|[a-z]| may not be equivalent to \verb|%l|. +The second form should be preferred for more portable programs. + \paragraph{Pattern Item:} a \Def{pattern item} may be: \begin{itemize} @@ -2006,11 +2013,11 @@ these repetition items will always match the shortest possible sequence. a single character class followed by \verb|?|, which matches 0 or 1 occurrence of a character in the class; \item -{\tt \%\M{n}}, for \M{n} between 1 and 9; +\T{\%\M{n}}, for \M{n} between 1 and 9; such item matches a sub-string equal to the n-th captured string (see below); \item -{\tt \%b\M{xy}}, where \M{x} and \M{y} are two distinct characters; +\T{\%b\M{xy}}, where \M{x} and \M{y} are two distinct characters; such item matches strings that start with \M{x}, end with \M{y}, and where the \M{x} and \M{y} are \emph{balanced}. That means that, if one reads the string from left to write, @@ -2039,6 +2046,7 @@ stored as the first capture (and therefore has number 1); the character matching \verb|.| is captured with number 2, and the part matching \verb|%s*| has number 3. + \subsection{Mathematical Functions} \label{mathlib} This library is an interface to some functions of the standard C math library. @@ -2101,8 +2109,6 @@ When called with a file name, it opens the named file, sets its handle as the value of \verb|_INPUT|, and returns this value. It does not close the current input file. -%When called with a file handle returned by a previous call, -%it simply assigns it to \verb|_INPUT|. When called without parameters, it closes the \verb|_INPUT| file, and restores \verb|stdin| as the value of \verb|_INPUT|. @@ -2130,8 +2136,6 @@ and returns this value. It does not close the current output file. Notice that, if the file already exists, then it will be \emph{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, this function closes the \verb|_OUTPUT| file, and restores \verb|stdout| as the value of \verb|_OUTPUT|. @@ -2203,15 +2207,13 @@ from the input if it belongs to the class; it never fails. A character class followed by \verb|*| reads until a character that does not belong to the class, or end of file; -since it can match a sequence of zero characters, it never fails.% -\footnote{ +since it can match a sequence of zero characters, it never fails. Notice that the behavior of read patterns is different from the regular pattern matching behavior, where a \verb|*| expands to the maximum length \emph{such that} the rest of the pattern does not fail. With the read pattern behavior there is no need for backtracking the reading. -} A pattern item may contain sub-patterns enclosed in curly brackets, that describe \Def{skips}. @@ -2270,6 +2272,17 @@ This function is equivalent to the C function \verb|system|. It passes \verb|command| to be executed by an operating system shell. It returns an error code, which is system-dependent. +\subsubsection*{\ff \T{setlocale (locale [, category])}}\Deffunc{setlocale} + +This function is an interface to the ANSI C function \verb|setlocale|. +\verb|locale| is a string specifing a locale; +\verb|category| is a number describing which category to change: +0 is \verb|LC_ALL|, 1 is \verb|LC_COLLATE|, 2 is \verb|LC_CTYPE|, +3 is \verb|LC_MONETARY|, 4 is \verb|LC_NUMERIC|, and 5 is \verb|LC_TIME|; +the default category is \verb|LC_ALL|. +The function returns the name of the new locale, +or \nil\ if the request cannot be honored. + \section{The Debugger Interface} \label{debugI}