1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
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}
|