Skip to content
Permalink
Browse files

requested changes from review

  • Loading branch information...
Skillmon committed Apr 11, 2019
1 parent 9a0c7d6 commit c16f8e6be081a70181bc367d2f11d8cdf5765853
@@ -9,21 +9,21 @@
% See the file doc/generic/pgf/licenses/LICENSE for more details.


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

\begin{pgfmodule}{parser}
\begin{pgfmodule}{parser}%
This module defines some commands for creating a simple letter-by-letter
parser.
\end{pgfmodule}
\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 code for each letter might take mandatory or optional
arguments. The parsing process ends when a final state has been reached, and
optionally some code is executed afterwards.

\begin{command}{\pgfparserparse\marg{parser name}\meta{text}}
\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}.

@@ -47,27 +47,27 @@ \section{Parser Module}
%
\begin{codeexample}[]
\newcount\mycount
\pgfparserdef{myparser}{initial}{the letter a}
{\advance\mycount by 1\relax}
\pgfparserdef{myparser}{initial}{the letter b}
\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}
\pgfparserdef{myparser}{initial}{the letter c}%
{\pgfparserswitch{final}}% done!

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

\begin{command}
\begin{command}%
{%
\pgfparserdef\marg{parser name}\marg{state}\meta{symbol meaning}%
\oarg{arguments}\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}
\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}.

@@ -95,26 +95,26 @@ \section{Parser Module}
\parbox[t]{\dimexpr\linewidth-1.5em\relax}{#2}%
\endgroup
}%
\argdesc{m}
{a normal mandatory argument}
\argdesc{r\meta{delim}}
{a mandatory argument which is read up to the \meta{delim}}
\argdesc{o}
{an optional argument in |[]| defaulting to a special mark}
\argdesc{O\marg{default}}
{like |o| but defaulting to \meta{default}}
\argdesc{d\meta{delim1}\meta{delim2}}
\argdesc{m}%
{a normal mandatory argument}%
\argdesc{r\meta{delim}}%
{a mandatory argument which is read up to the \meta{delim}}%
\argdesc{o}%
{an optional argument in |[]| defaulting to a special mark}%
\argdesc{O\marg{default}}%
{like |o| but defaulting to \meta{default}}%
\argdesc{d\meta{delim1}\meta{delim2}}%
{%
an optional argument in \meta{delim1} and \meta{delim2} defaulting to a
special mark%
}
\argdesc{D\meta{delim1}\meta{delim2}\marg{default}}
{like |d| but defaulting to \meta{default}}
\argdesc{t\meta{token}}
}%
\argdesc{D\meta{delim1}\meta{delim2}\marg{default}}%
{like |d| but defaulting to \meta{default}}%
\argdesc{t\meta{token}}%
{%
tests whether the next letter is \meta{token}, if so gobbles it and
the argument is set to a special mark.%
}
}%
\endgroup

So if you want to define an \meta{action} that takes two mandatory arguments
@@ -147,105 +147,105 @@ \section{Parser Module}
current state (neither directly nor indirectly via |all|), an error occurs.
Additionally you can specify an action that is executed after the error is
thrown using |\pgfparserdefunknown|.
\end{command}
\end{command}%

\begin{command}
\begin{command}%
{%
\pgfparserlet
\marg{parser name 1}\marg{state 1}\meta{symbol meaning 1}%
\oarg{opt 1}\oarg{opt 2}\meta{symbol meaning 2}%
}
}%
If none of of the optional arguments are given in the following \meta{parser
name 2} and \meta{state 2} are the same as \meta{parser name 1} and
\meta{state 1}. If only the first is given \meta{state 2} equals
\meta{opt 1}. If both are given \meta{parser name 2} equals \meta{opt 1} and
\meta{state 2} equals \meta{opt 2}.

Defines an action for \meta{parser name 1} in \meta{state 1} for the
\meta{symbol meaning 1} to do the same as the action of \meta{parser name 2}
in \meta{state 2} for the \meta{symbol meaning 2}. For \meta{symbol meaning 1}
\meta{symbol meaning 1} to do the same as the action of \meta{parser name 2}%
in \meta{state 2} for the \meta{symbol meaning 2}. For \meta{symbol meaning 1}%
and \meta{symbol meaning 2} the same parsing rules apply as for \meta{symbol
meaning} in |\pgfparserdef| so you either give the meaning in braces or just
the symbol.
\end{command}
\end{command}%

\begin{command}{\pgfparserdefunknown\marg{parser name}\marg{state}\marg{action}}
With this macro you can define an \meta{action} for the \meta{parser name}
\begin{command}{\pgfparserdefunknown\marg{parser name}\marg{state}\marg{action}}%
With this macro you can define an \meta{action} for the \meta{parser name}%
parser in \meta{state} if the letter which was encountered was undefined.
\end{command}
\end{command}%

\begin{command}{\pgfparserdeffinal\marg{parser name}\marg{action}}
\begin{command}{\pgfparserdeffinal\marg{parser name}\marg{action}}%
Every parser can call a final \meta{action} after the state was switched to
|final|. This \meta{action} is executed after everything else, so you can use
something that grabs more arguments if you want to.
\end{command}
\end{command}%

\begin{command}{\pgfparserswitch\marg{state}}
\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}
\end{command}%

\begin{command}{\pgfparserifmark\marg{arg}\marg{true}\marg{false}}
\begin{command}{\pgfparserifmark\marg{arg}\marg{true}\marg{false}}%
Remember that some of the optional argument types set special marks? With
|\pgfparserifmark| you can test whether \meta{arg} is such a mark. So if
there was no optional argument for the argument types |o| and |d| the
\meta{true} branch will be executed, else the \meta{false} branch. For the |t|
type argument the \meta{true} branch is executed if the token was encountered.
\end{command}
\end{command}%

\begin{command}{\pgfparserreinsert}
\begin{command}{\pgfparserreinsert}%
You can use this as the final macro in an action of |\pgfparserdef| or
|\pgfparserdefunknown|. This has the effect that the letter which was parsed
in this action will be parsed again after this action (and after any arguments
were read).
\end{command}
\end{command}%

\begin{command}{\pgfparserstate}
\begin{command}{\pgfparserstate}%
Expands to the current state of the parser.
\end{command}
\end{command}%

\begin{command}{\pgfparsertoken}
\begin{command}{\pgfparsertoken}%
This is the macro which is let to the following token with |\futurelet|. You
can use it inside an action code.
\end{command}
\end{command}%

\begin{command}{\pgfparserletter}
\begin{command}{\pgfparserletter}%
This macro stores the letter to which |\pgfparsertoken| was let. So if
you'd use |\pgfparserparse{foo}a| this macro would be defined with
|\def\pgfparserletter{a}|. This definition is done before any action code is
executed. There are two special cases: If |{| or |}| would be the next letter
for the parser, this macro is defined to expand to |\bgroup| or |\egroup|.
\end{command}
\end{command}%

\begin{command}{\pgfparserset\marg{key list}}
\begin{command}{\pgfparserset\marg{key list}}%
The |pgfparser| module has a few keys you can access through this macro. It
is just a shortcut for |\pgfset{/pgfparser/.cd,#1}|. The available keys are
listed in subsection~\ref{sec:parser:keys}.
\end{command}
\end{command}%

\subsection{Keys of the Parser Module}\label{sec:parser:keys}
\begin{key}{/pgfparser/silent=\meta{boolean} (initially false)}
\subsection{Keys of the Parser Module}\label{sec:parser:keys}%
\begin{key}{/pgfparser/silent=\meta{boolean} (initially false)}%
If |true| then no error will be thrown when a letter is parsed for which no
action is specified, silently ignoring it. This holds true for every parser.
\end{key}
\end{key}%

\begin{key}{/pgfparser/status=\meta{boolean} (initially false)}
\begin{key}{/pgfparser/status=\meta{boolean} (initially false)}%
If |true| every parser prints a status message for every action executed. This
might help in debugging and understanding what the parser does.
\end{key}
\end{key}%

Additionally to those keys for every \meta{parser name} for which
|\pgfparserdef|, |\pgfparserdefunknown| or |\pgfparserlet| was run at least once
the following will be defined:

\begin{key}
{/pgfparser/\meta{parser name}/silent=\meta{boolean} (initially false)}
\begin{key}%
{/pgfparser/\meta{parser name}/silent=\meta{boolean} (initially false)}%
If |true| the parser \meta{parser name} will silently ignore undefined
letters. This is an individual equivalent of |/pgfparser/silent| for each
defined parser.
\end{key}
\end{key}%

\subsection{Examples}
\subsection{Examples}%
The following example counts the different letters appearing in a more or less
random string of letters. Every letter is counted only once, this is achieved by
defining a new action for every encountered unknown letter that does nothing. We
@@ -254,28 +254,28 @@ \subsection{Examples}
\begin{codeexample}[]
\mycount=0
% using the shortcut syntax of just placing ; after the state
\pgfparserdef{different letters}{all};{\pgfparserswitch{final}}
\pgfparserdefunknown{different letters}{all}
{\pgfparserdef{different letters}{all}\pgfparsertoken{}\advance\mycount1}
\pgfparserdeffinal{different letters}
{\the\mycount\ different letters found}
\pgfparserdef{different letters}{all};{\pgfparserswitch{final}}%
\pgfparserdefunknown{different letters}{all}%
{\pgfparserdef{different letters}{all}\pgfparsertoken{}\advance\mycount1}%
\pgfparserdeffinal{different letters}%
{\the\mycount\ different letters found}%
% don't throw errors for unknown letters
\pgfparserset{different letters/silent=true}
\pgfparserset{different letters/silent=true}%

\pgfparserparse{different letters}udiaternxqlchudiea;
\end{codeexample}
\end{codeexample}%

Next we want to try something that uses some of the different argument types
available.
\begin{codeexample}[]
% using the same syntax as \pgfparserdef
\pgfparserdef{arguments}{initial}{the letter a}[d()]
{\pgfparserifmark{#1}{\textcolor{red}{\textit{use}}}{\textbf{#1}} }
{\pgfparserifmark{#1}{\textcolor{red}{\textit{use}}}{\textbf{#1}} }%
% using the shortcut syntax
\pgfparserdef{arguments}{initial}t[m]{\texttt{#1} }
\pgfparserdef{arguments}{initial}t[m]{\texttt{#1} }%
\pgfparserdef{arguments}{initial}c[t*O{blue}m]
{\pgfparserifmark{#1}{#3}{\textcolor{#2}{#3}}}
\pgfparserdef{arguments}{all};{\pgfparserswitch{final}}
{\pgfparserifmark{#1}{#3}{\textcolor{#2}{#3}}}%
\pgfparserdef{arguments}{all};{\pgfparserswitch{final}}%

\pgfparserparse{arguments}t{nobody}a(will)ac[green]{P}c*{arse}c{r};
\end{codeexample}
\end{codeexample}%
Oops, something went wrong.

0 comments on commit c16f8e6

Please sign in to comment.
You can’t perform that action at this time.