1 files changed, 96 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-module-parser.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-module-parser.tex
new file mode 100644
index 00000000000..8668d69ad24
--- /dev/null
+++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-module-parser.tex
@@ -0,0 +1,96 @@
+% 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, possible, 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
+  persist 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}