% 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}