% Copyright 2008 by Till Tantau
%
% This file may be distributed and/or modified
%
% 1. under the LaTeX Project Public License and/or
% 2. under the GNU Free Documentation License.
%
% See the file doc/generic/pgf/licenses/LICENSE for more details.


\section{Parser Module}
\label{section-module-parser}

\begin{pgfmodule}{parser}
    This module defines some commands for creating a simple letter-by-letter
    parser.
\end{pgfmodule}

This module provides commands for defining a parser that scans some given text
letter-by-letter. For each letter, some code is executed and, possibly a
state-switch occurs. The parsing process ends when a final state has been
reached.

\begin{command}{\pgfparserparse\marg{parser name}\meta{text}}
    This command is used to parse the \meta{text} using the (previously
    defined) parser named \meta{parser name}.

    The \meta{text} is not contained in curly braces, rather it is all the text
    that follows. The end of the text is determined implicitly, namely when the
    final state of the parser has been reached.

    The parser works as follows: At any moment, it is in a certain
    \emph{state}, initially this state is called |initial|. Then, the first
    letter of the \meta{text} is examined (using the |\futurlet| command). For
    each possible state and each possible letter, some action code is stored in
    the parser in a table. This code is then executed. This code may, but need
    not, trigger a \emph{state switch}, causing a new state to be set. The
    parser then moves on to the next character of the text and repeats the
    whole procedure, unless it is in the state |final|, which causes the
    parsing process to stop immediately.

    In the following example, the parser counts the number of |a|'s in the
    \text{text}, ignoring any |b|'s. The \meta{text} ends with the first~|c|.
    %
\begin{codeexample}[]
\newcount\mycount
\pgfparserdef{myparser}{initial}{the letter a}
{\advance\mycount by 1\relax}
\pgfparserdef{myparser}{initial}{the letter b}
{} % do nothing
\pgfparserdef{myparser}{initial}{the letter c}
{\pgfparserswitch{final}}% done!

\pgfparserparse{myparser}aabaabababbbbbabaabcccc
There are \the\mycount\ a's.
\end{codeexample}
    %
\end{command}

\begin{command}{\pgfparserdef\marg{parser name}\marg{state}\marg{symbol meaning}\marg{action}}
    This command should be used repeatedly to define a parser named
    \meta{parser name}. With a call to this command you specify that the
    \meta{parser name} should do the following: When it is in state
    \meta{state} and reads the letter \meta{symbol meaning}, perform the code
    stored in \meta{action}.

    The \meta{symbol meaning} must be the text that results from applying the
    \TeX\ command |\meaning| to the given character. For instance, |\meaning a|
    yields |the letter a|, while |\meaning 1| yields |the character 1|. A space
    yields |blank space|.

    Inside the \meta{action} you can perform almost any kind of code. This code
    will not be surrounded by a scope, so its effect persists after the parsing
    is done. However, each time after the \meta{action} is executed, control
    goes back to the parser. You should not launch a parser inside the
    \meta{action} code, unless you put it in a scope.

    When you set the \meta{state} to |all|, the state \meta{action} is
    performed in all states as a fallback, whenever \meta{symbol meaning} is
    encountered. This means that when you do not specify anything explicitly
    for a state and a letter, but you do specify something for |all| and this
    letter, then the specified \meta{action} will be used.

    When the parser encounters a letter for which nothing is specified in the
    current state (neither directly nor indirectly via |all|), an error occurs.
\end{command}

\begin{command}{\pgfparserswitch\marg{state}}
  This command can be called inside the action code of a parser to cause a
  state switch to \meta{state}.
\end{command}
