-\def\tableHeader{\begin{tabular}{|c|c|p{5cm}|}\hline\r
-\bf name & \bf type & \multicolumn{1}{c|}{\bf description} \\\hline}\r
-\def\entry#1#2#3{{#1} & {\tt#2} & {#3} \\\hline}\r
-\def\tableFooter{\hline\end{tabular}}\r
-\r
-\section{{\tt mlp}, the metalua parser}\r
-\r
-Metalua parser is built on top of \verb|gg|, and cannot be understood\r
-without some knowledge of it. Basically, \verb|gg| allows not only to\r
-build parsers, but to build {\em extensible} parsers. Depending on a\r
-parser's type (sequence, sequence set, list, expression\ldots),\r
-different extension methods are available, which are documented in\r
-\verb|gg| reference. The current section will give the information\r
-needed to extend Metalua syntax:\r
-\begin{itemize}\r
-\item what \verb|mlp| entries are accessible for extension;\r
-\item what do they parse;\r
-\item what is the underlying parser type (and therefore, what\r
- extension methods are supported)\r
-\end{itemize}\r
-\r
-\vfill\pagebreak\r
-\r
-\subsection{Parsing expressions}\r
-\tableHeader\r
-\r
-\entry{mlp.expr}{gg.expr}{Top-level expression parser, and the main\r
- extension point for Metalua expression. Supports all of the methods\r
- defined by {\tt gg.expr}.}\r
-\r
-\entry{mlp.func\_val}{gg.sequence}{Read a function definition,\r
- from the arguments' openning parenthesis to the final {\tt end}, but\r
- excluding the initial {\tt function} keyword, so that it can be used\r
- both for anonymous functions, for {\tt function some\_name(...) end}\r
- and for {\tt local function some\_name(...) end}.}\r
-\r
-% \entry{mlp.func\_params\_content}{gg.list}{Read a potentially empty\r
-% (``{\tt)}''- or ``{\tt|}''-terminated) list of function definition\r
-% parameters, i.e. identifiers or ``{\tt ...}'' varargs. Surrounding\r
-% parentheses are excluded. Don't get confused between parameters and\r
-% arguments: parameters are the variable names used in a function\r
-% definition; arguments are the values passed in a function call.}\r
-\r
-% \entry{mlp.func\_args\_content}{gg.list}{Read a potentially emtpy list\r
-% of function call arguments. Surrounding parentheses are excluded.}\r
-\r
-% \entry{mlp.func\_args}{gg.sequence\_set}{Read function arguments: a\r
-% list of expressions between parenthses, or a litteral table, or a\r
-% litteral string.}\r
-\r
-%\entry{mlp.func\_params}{}{}\r
-\entry{mlp.expr\_list}{}{}\r
-\r
-%\entry{mlp.adt}{\rm custom function}{Read an algebraic datatype\r
-% without its leading backquote.}\r
-\r
-\entry{mlp.table\_content}{gg.list}{Read the content of a table,\r
- excluding the surrounding braces}\r
-\r
-\entry{mlp.table}{gg.sequence}{Read a litteral table,\r
- including the surrounding braces}\r
-\r
-\entry{mlp.table\_field}{\rm custom function}{Read a table entry: {\tt\r
- [foo]=bar}, {\tt foo=bar} or {\tt bar}.}\r
-\r
-\entry{mlp.opt\_id}{\rm custom function}{Try to read an identifier, or\r
- an identifier splice. On failure, returns false.}\r
-\r
-\entry{mlp.id}{\rm custom function}{Read an identifier, or\r
- an identifier splice. Cause an error if there is no identifier.}\r
-\r
-\tableFooter\r
-\r
-\vfill\pagebreak\r
-\r
-\subsection{Parsing statements}\r
-\tableHeader\r
-\entry{mlp.block}{gg.list}{Read a sequence of statements, optionally\r
- separated by semicolons. When introducing syntax extensions, it's\r
- often necessary to add block terminators with {\tt\r
- mlp.block.terminators:add().}}\r
-\entry{mlp.for\_header}{\rm custom function}{Read a {\tt for} header,\r
-from just after the ``{\tt for}'' to just before the ``{\tt do}''.}\r
-\entry{mlp.stat}{gg.multisequence}{Read a single statement.}\r
-\tableFooter\r
-\r
-Actually, {\tt mlp.stat} is an extended version of a multisequence: it\r
-supports easy addition of new assignment operator. It has a field {\tt\r
-assignments}, whose keys are assignment keywords, and values are\r
-assignment builders taking left-hand-side and right-hand-side as\r
-parameters. for instance, C's ``+='' operator could be added as:\r
-\begin{verbatim}\r
-mlp.lexer:add "+="\r
-mlp.stat.assignments["+="] = function (lhs, rhs)\r
- assert(#lhs==1 and #rhs==1)\r
- local a, b = lhs[1], rhs[1]\r
- return +{stat: (-{a}) = -{a} + -{b} }\r
-end \r
-\end{verbatim}\r
-\r
-\subsection{Other useful functions and variables}\r
-\r
-\begin{itemize}\r
-\item{\tt mlp.gensym()} generates a unique identifier. The uniqueness\r
- is guaranteed, therefore this identifier cannot capture another\r
- variable; it is useful to write hygienic\footnote{Hygienic macros\r
- are macros which take care not to use names that might interfere\r
- with user-provided names. The typical non-hygienic macro in C\r
- is {\tt \#define SWAP( a, b) \{ int c=a; a=b; b=c; \}}: this macro\r
- will misearbly fail if you ever call it with a parameter named\r
- {\tt c}. There are well-known techniques to automatically make a\r
- macro hygienic. Without them, you'd have to generate a unique name\r
- for the temporary variable, if you had a {\tt gensym()} operator\r
- in C's preprocessor} macros. \r
-\end{itemize}\r
+\def\tableHeader{\begin{tabular}{|c|c|p{5cm}|}\hline
+\bf name & \bf type & \multicolumn{1}{c|}{\bf description} \\\hline}
+\def\entry#1#2#3{{#1} & {\tt#2} & {#3} \\\hline}
+\def\tableFooter{\hline\end{tabular}}
+
+\section{{\tt mlp}, the metalua parser}
+
+Metalua parser is built on top of \verb|gg|, and cannot be understood
+without some knowledge of it. Basically, \verb|gg| allows not only to
+build parsers, but to build {\em extensible} parsers. Depending on a
+parser's type (sequence, sequence set, list, expression\ldots),
+different extension methods are available, which are documented in
+\verb|gg| reference. The current section will give the information
+needed to extend Metalua syntax:
+\begin{itemize}
+\item what \verb|mlp| entries are accessible for extension;
+\item what do they parse;
+\item what is the underlying parser type (and therefore, what
+ extension methods are supported)
+\end{itemize}
+
+\vfill\pagebreak
+
+\subsection{Parsing expressions}
+\tableHeader
+
+\entry{mlp.expr}{gg.expr}{Top-level expression parser, and the main
+ extension point for Metalua expression. Supports all of the methods
+ defined by {\tt gg.expr}.}
+
+\entry{mlp.func\_val}{gg.sequence}{Read a function definition,
+ from the arguments' openning parenthesis to the final {\tt end}, but
+ excluding the initial {\tt function} keyword, so that it can be used
+ both for anonymous functions, for {\tt function some\_name(...) end}
+ and for {\tt local function some\_name(...) end}.}
+
+% \entry{mlp.func\_params\_content}{gg.list}{Read a potentially empty
+% (``{\tt)}''- or ``{\tt|}''-terminated) list of function definition
+% parameters, i.e. identifiers or ``{\tt ...}'' varargs. Surrounding
+% parentheses are excluded. Don't get confused between parameters and
+% arguments: parameters are the variable names used in a function
+% definition; arguments are the values passed in a function call.}
+
+% \entry{mlp.func\_args\_content}{gg.list}{Read a potentially emtpy list
+% of function call arguments. Surrounding parentheses are excluded.}
+
+% \entry{mlp.func\_args}{gg.sequence\_set}{Read function arguments: a
+% list of expressions between parenthses, or a litteral table, or a
+% litteral string.}
+
+%\entry{mlp.func\_params}{}{}
+\entry{mlp.expr\_list}{}{}
+
+%\entry{mlp.adt}{\rm custom function}{Read an algebraic datatype
+% without its leading backquote.}
+
+\entry{mlp.table\_content}{gg.list}{Read the content of a table,
+ excluding the surrounding braces}
+
+\entry{mlp.table}{gg.sequence}{Read a litteral table,
+ including the surrounding braces}
+
+\entry{mlp.table\_field}{\rm custom function}{Read a table entry: {\tt
+ [foo]=bar}, {\tt foo=bar} or {\tt bar}.}
+
+\entry{mlp.opt\_id}{\rm custom function}{Try to read an identifier, or
+ an identifier splice. On failure, returns false.}
+
+\entry{mlp.id}{\rm custom function}{Read an identifier, or
+ an identifier splice. Cause an error if there is no identifier.}
+
+\tableFooter
+
+\vfill\pagebreak
+
+\subsection{Parsing statements}
+\tableHeader
+\entry{mlp.block}{gg.list}{Read a sequence of statements, optionally
+ separated by semicolons. When introducing syntax extensions, it's
+ often necessary to add block terminators with {\tt
+ mlp.block.terminators:add().}}
+\entry{mlp.for\_header}{\rm custom function}{Read a {\tt for} header,
+from just after the ``{\tt for}'' to just before the ``{\tt do}''.}
+\entry{mlp.stat}{gg.multisequence}{Read a single statement.}
+\tableFooter
+
+Actually, {\tt mlp.stat} is an extended version of a multisequence: it
+supports easy addition of new assignment operator. It has a field {\tt
+assignments}, whose keys are assignment keywords, and values are
+assignment builders taking left-hand-side and right-hand-side as
+parameters. for instance, C's ``+='' operator could be added as:
+\begin{verbatim}
+mlp.lexer:add "+="
+mlp.stat.assignments["+="] = function (lhs, rhs)
+ assert(#lhs==1 and #rhs==1)
+ local a, b = lhs[1], rhs[1]
+ return +{stat: (-{a}) = -{a} + -{b} }
+end
+\end{verbatim}
+
+\subsection{Other useful functions and variables}
+
+\begin{itemize}
+\item{\tt mlp.gensym()} generates a unique identifier. The uniqueness
+ is guaranteed, therefore this identifier cannot capture another
+ variable; it is useful to write hygienic\footnote{Hygienic macros
+ are macros which take care not to use names that might interfere
+ with user-provided names. The typical non-hygienic macro in C
+ is {\tt \#define SWAP( a, b) \{ int c=a; a=b; b=c; \}}: this macro
+ will misearbly fail if you ever call it with a parameter named
+ {\tt c}. There are well-known techniques to automatically make a
+ macro hygienic. Without them, you'd have to generate a unique name
+ for the temporary variable, if you had a {\tt gensym()} operator
+ in C's preprocessor} macros.
+\end{itemize}
projects / metalua.git / blobdiff