Skip to content
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}
\section{Parser Module}%

This module defines some commands for creating a simple letter-by-letter

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}
\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!

There are \the\mycount\ a's.

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

@@ -95,26 +95,26 @@ \section{Parser Module}
{a normal mandatory argument}
{a mandatory argument which is read up to the \meta{delim}}
{an optional argument in |[]| defaulting to a special mark}
{like |o| but defaulting to \meta{default}}
{a normal mandatory argument}%
{a mandatory argument which is read up to the \meta{delim}}%
{an optional argument in |[]| defaulting to a special mark}%
{like |o| but defaulting to \meta{default}}%
an optional argument in \meta{delim1} and \meta{delim2} defaulting to a
special mark%
{like |d| but defaulting to \meta{default}}
{like |d| but defaulting to \meta{default}}%
tests whether the next letter is \meta{token}, if so gobbles it and
the argument is set to a special mark.%

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|.

\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.

\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.

\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.

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

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.

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).

Expands to the current state of the parser.

This is the macro which is let to the following token with |\futurelet|. You
can use it inside an action code.

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|.

\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}.

\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.

\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.

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:

{/pgfparser/\meta{parser name}/silent=\meta{boolean} (initially false)}
{/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.

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

Next we want to try something that uses some of the different argument types
% 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} }%

Oops, something went wrong.

0 comments on commit c16f8e6

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