diff options
Diffstat (limited to 'graphics/pgf/base/doc/text-en/pgfmanual-en-module-parser.tex')
-rw-r--r-- | graphics/pgf/base/doc/text-en/pgfmanual-en-module-parser.tex | 311 |
1 files changed, 0 insertions, 311 deletions
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-module-parser.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-module-parser.tex deleted file mode 100644 index 143bc16851..0000000000 --- a/graphics/pgf/base/doc/text-en/pgfmanual-en-module-parser.tex +++ /dev/null @@ -1,311 +0,0 @@ -% Copyright 2019 by Till Tantau -% Copyright 2019 by Jonathan P. Spratte -% -% 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} - -\begin{package}{pgfparser} - Because the parser module is almost independent of the rest of \pgfname, it - can also be used as a standalone package with minimal dependencies. -\end{package} - -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}}% - 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. If you defined a final action for - the parser using |\pgfparserdeffinal| it is executed now. - - 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 |\futurelet| 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}[preamble={\usepgfmodule{parser}}] -\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}\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} 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 |. Alternatively you can give the symbol you want without - surrounding it in braces. So both - |\pgfparserdef{myparser}{initial}{the letter a}{foo}| - and - |\pgfparserdef{myparser}{initial}a{foo}| - define an \meta{action} for |the letter a|. This short form works for most - tokens, but not for a space (in which case you can use - |\pgfparserdef{myparser}{initial}{blank space}{foo}|), and opening braces - (in which case you can use - |\pgfparserdef{myparser}{initial}{\meaning\bgroup}{foo}|, and one might prefer - to use |\pgfparserdef{myparser}{initial}{\meaning\egroup}{foo}| for closing - braces as well). You can as well define an action for a macro's meaning (note - that macros with different names can have the same meaning), so things like - |\pgfparserdef{myparser}{initial}\texttt{foo}| are possible as well. - - The \meta{action} might require arguments which you can specify in the - optional \meta{arguments} string. The argument string can contain up to nine - argument specifications of the following types: - - \begingroup - \def\argdesc#1#2% - {% - \par - \begingroup - \setbox0\hbox{\texttt #1}\makebox[1.5em][l]{\usebox0}% - \ifdim\wd0>1.5em\\\null\hspace{1.5em}\fi - \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}}% - {% - 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}}% - {% - 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 - you use |[mm]|, if it should take an optional star, one optional argument in - brackets that returns a marker if it's not used, one mandatory and finally an - optional argument in parentheses that defaults to |something| you use - |[t*omD(){something}]| as the argument string. If the argument should be - anything up to a semicolon, you use |[r;]|. Spaces before argument - specifications in the string are ignored. So |[r m]| will be one argument and - read anything up to an |m|. Also spaces before any argument in the parsed - letters are ignored, so if |a| was setup to take an optional argument the - argument would be detected in |a []|. Like with normal \LaTeXe\ optional - arguments you have to protect nested brackets: |[a[bc]d]| would be read as - |a[bc| with a trailing |d]|, \emph{not} as |a[bc]d|. You'd have to use - |[{a[bc]d}]| to get it correct. - - 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 use |all| as the \meta{state}, the \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. - Additionally you can specify an action that is executed after the error is - thrown using |\pgfparserdefunknown|. To suppress these errors (but not the - action specified with |\pgfparserdefunknown|) you can use the - |/pgfparser/silent| key or the |silent| key of the current \meta{parser name}. -\end{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 the optional arguments are given in the following explanation - \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} - 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}% - -\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 no action was defined for the letter which was - encountered. -\end{command}% - -\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}% - -\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}% - -\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}% - -\begin{command}{\pgfparserreinsert}% - You can use this as the final macro in an action of |\pgfparserdef| or - |\pgfparserdefunknown|. This has the effect that the contents of - |\pgfparserletter| will be parsed next. Without any redefinition the result - will be that the last token will be parsed again. You can change the - definition of |\pgfparserletter| just before |\pgfparserreinsert| as well to - parse some specific tokens next. -\end{command}% - -\begin{command}{\pgfparserstate}% - Expands to the current state of the parser. -\end{command}% - -\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}% - -\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 four special cases: If the next token is of category code - 1, 2, 6, or 10, so with standard category codes the tokens |{|, |}|, |#|, and - \textvisiblespace\ (a space), it would be treated differently. In those cases - this macro expands to |\bgroup|, |\egroup|, |##|, and \textvisiblespace\ for - the categories 1, 2, 6, and 10, respectively. -\end{command}% - -\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}% - - -\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}% - -\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}% - -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)}% - 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}% - - -\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 can define such rule without knowing which letter is used, because -|\pgfparsertoken| has the same meaning as that letter. -% -\begin{codeexample}[ - preamble={\usepgfmodule{parser}}, - pre={\newcount\mycount}, -] -\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}% -% don't throw errors for unknown letters -\pgfparserset{different letters/silent=true}% - -\pgfparserparse{different letters}udiaternxqlchudiea; -\end{codeexample}% - -Next we want to try something that uses some of the different argument types -available. -% -\begin{codeexample}[preamble={\usepgfmodule{parser}}] -% using the long syntax of \pgfparserdef -\pgfparserdef{arguments}{initial}{the letter a}[d()] - {\pgfparserifmark{#1}{\textcolor{red}{\textit{use}}}{\textbf{#1}} }% -% using the shortcut syntax -\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}}% - -\pgfparserparse{arguments}t{nobody}a(will)ac[green]{P}c*{arse}c{r}; -\end{codeexample}% |