doc/manual/mlp-ref.tex

   1 \def\tableHeader{\begin{tabular}{|c|c|p{5cm}|}\hline
   2 \bf name & \bf type & \multicolumn{1}{c|}{\bf description} \\\hline}
   3 \def\entry#1#2#3{{#1} & {\tt#2} & {#3} \\\hline}
   4 \def\tableFooter{\hline\end{tabular}}
   5
   6 \section{{\tt mlp}, the metalua parser}
   7
   8 Metalua parser is built on top of \verb|gg|, and cannot be understood
   9 without some knowledge of it. Basically, \verb|gg| allows not only to
  10 build parsers, but to build {\em extensible} parsers. Depending on a
  11 parser's type (sequence, sequence set, list, expression\ldots),
  12 different extension methods are available, which are documented in
  13 \verb|gg| reference. The current section will give the information
  14 needed to extend Metalua syntax:
  15 \begin{itemize}
  16 \item what \verb|mlp| entries are accessible for extension;
  17 \item what do they parse;
  18 \item what is the underlying parser type (and therefore, what
  19   extension methods are supported)
  20 \end{itemize}
  21
  22 \vfill\pagebreak
  23
  24 \subsection{Parsing expressions}
  25 \tableHeader
  26
  27 \entry{mlp.expr}{gg.expr}{Top-level expression parser, and the main
  28   extension point for Metalua expression. Supports all of the methods
  29   defined by {\tt gg.expr}.}
  30
  31 \entry{mlp.func\_val}{gg.sequence}{Read a function definition,
  32   from the arguments' openning parenthesis to the final {\tt end}, but
  33   excluding the initial {\tt function} keyword, so that it can be used
  34   both for anonymous functions, for {\tt function some\_name(...) end}
  35   and for {\tt local function some\_name(...) end}.}
  36
  37 % \entry{mlp.func\_params\_content}{gg.list}{Read a potentially empty
  38 %   (``{\tt)}''- or ``{\tt|}''-terminated) list of function definition
  39 %   parameters, i.e. identifiers or ``{\tt ...}'' varargs. Surrounding
  40 %   parentheses are excluded. Don't get confused between parameters and
  41 %   arguments: parameters are the variable names used in a function
  42 %   definition; arguments are the values passed in a function call.}
  43
  44 % \entry{mlp.func\_args\_content}{gg.list}{Read a potentially emtpy list
  45 %   of function call arguments. Surrounding parentheses are excluded.}
  46
  47 % \entry{mlp.func\_args}{gg.sequence\_set}{Read function arguments: a
  48 %   list of expressions between parenthses, or a litteral table, or a
  49 %   litteral string.}
  50
  51 %\entry{mlp.func\_params}{}{}
  52 \entry{mlp.expr\_list}{}{}
  53
  54 %\entry{mlp.adt}{\rm custom function}{Read an algebraic datatype
  55 %  without its leading backquote.}
  56
  57 \entry{mlp.table\_content}{gg.list}{Read the content of a table,
  58   excluding the surrounding braces}
  59
  60 \entry{mlp.table}{gg.sequence}{Read  a litteral table,
  61   including the surrounding braces}
  62
  63 \entry{mlp.table\_field}{\rm custom function}{Read a table entry: {\tt
  64     [foo]=bar}, {\tt foo=bar} or {\tt bar}.}
  65
  66 \entry{mlp.opt\_id}{\rm custom function}{Try to read an identifier, or
  67   an identifier splice. On failure, returns false.}
  68
  69 \entry{mlp.id}{\rm custom function}{Read an identifier, or
  70   an identifier splice. Cause an error if there is no identifier.}
  71
  72 \tableFooter
  73
  74 \vfill\pagebreak
  75
  76 \subsection{Parsing statements}
  77 \tableHeader
  78 \entry{mlp.block}{gg.list}{Read a sequence of statements, optionally
  79   separated by semicolons. When introducing syntax extensions, it's
  80   often necessary to add block terminators with {\tt
  81   mlp.block.terminators:add().}}
  82 \entry{mlp.for\_header}{\rm custom function}{Read a {\tt for} header,
  83 from just after the ``{\tt for}'' to just before the ``{\tt do}''.}
  84 \entry{mlp.stat}{gg.multisequence}{Read a single statement.}
  85 \tableFooter
  86
  87 Actually, {\tt mlp.stat} is an extended version of a multisequence: it
  88 supports easy addition of new assignment operator. It has a field {\tt
  89 assignments}, whose keys are assignment keywords, and values are
  90 assignment builders taking left-hand-side and right-hand-side as
  91 parameters. for instance, C's ``+='' operator could be added as:
  92 \begin{verbatim}
  93 mlp.lexer:add "+="
  94 mlp.stat.assignments["+="] = function (lhs, rhs)
  95   assert(#lhs==1 and #rhs==1)
  96   local a, b = lhs[1], rhs[1]
  97   return +{stat: (-{a}) = -{a} + -{b} }
  98 end
  99 \end{verbatim}
 100
 101 \subsection{Other useful functions and variables}
 102
 103 \begin{itemize}
 104 \item{\tt mlp.gensym()} generates a unique identifier. The uniqueness
 105   is guaranteed, therefore this identifier cannot capture another
 106   variable; it is useful to write hygienic\footnote{Hygienic macros
 107     are macros which take care not to use names that might interfere
 108     with user-provided names. The typical non-hygienic macro in C
 109     is {\tt \#define SWAP( a, b) \{ int c=a; a=b; b=c; \}}: this macro
 110     will misearbly fail if you ever call it with a parameter named
 111     {\tt c}. There are well-known techniques to automatically make a
 112     macro hygienic. Without them, you'd have to generate a unique name
 113     for the temporary variable, if you had a {\tt gensym()} operator
 114     in C's preprocessor} macros.
 115 \end{itemize}