%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% Copyright 2007/2008 by Christian Feuersaenger.
%
% This program is free software: you can redistribute it and/or modify
% it under the terms of the GNU General Public License as published by
% the Free Software Foundation, either version 3 of the License, or
% (at your option) any later version.
% 
% This program is distributed in the hope that it will be useful,
% but WITHOUT ANY WARRANTY; without even the implied warranty of
% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
% GNU General Public License for more details.
% 
% You should have received a copy of the GNU General Public License
% along with this program.  If not, see <http://www.gnu.org/licenses/>.
%
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\pdfminorversion=5 % to allow compression
\pdfobjcompresslevel=2
\documentclass[a4paper]{ltxdoc}
\input{pgfplots.preamble.tex}

\usepackage{array}
\usepackage{colortbl}
\usepackage{booktabs}
\usepackage{eurosym}

\long\def\codeexamplenl{\noexpand\par}%
\pgfqkeys{/codeexample}{%
	every codeexample/.style={
		width=4cm,
		/pgfplots/every axis/.append style={legend style={fill=graphicbackground}}
	},
	narrow/.style={width=7cm},
	tabsize=4,
	%pre={\begin{minipage}{\linewidth}\begingroup},
	%post={\endgroup\end{minipage}},
	vbox,
	newline=\codeexamplenl,
}

\def\API{\textsc{Api}}%

\title{Notes On Programming in \TeX}%\\and Library Functions from \PGF\ and \PGFPlots}

\begin{document}
\maketitle
\begin{abstract}%
	This document contains notes which are intended for those who are interested in \TeX\ programming. It is valuable for beginners as a first start with a lot of examples, and it is also valuable for experienced \TeX nicians who are interested in details about \TeX\ programming. However, it is neither a complete reference, nor a complete manual of \TeX.
\end{abstract}
\tableofcontents
\section{Introduction}
This document is intended to provide a direct start with \TeX\ programming (not necessarily \TeX\ typesetting). The addressed audience consists of people interested in package or library writing.

At the time of this writing, this document is far from complete. Nevertheless, it might be a good starting point for interested readers. Consult the literature given below for more details.

\section{Programming in \TeX}
\subsection{Variables in Registers}
\TeX\ provides several different variables and associated registers which can be manipulated freely.

\label{sec:variables}
\begin{command}{\count\meta{num}}
	There are 256 Integer registers which provide 32 Bit Integer arithmetics. The registers can be used for example with |\count0=42 | or |\count7=\macro | where |\macro| expands to a number.

	The value of a register can be typeset using |\the|\meta{register}.
\begin{codeexample}[]
\count0=42
The value is now `\the\count0'. 
\def\macro{-123456}
\count0=\macro 
The value is now `\the\count0'.
\end{codeexample}
	
	The `|=|' sign is optional and can be omitted. One thing is common among the registers: an assignment of the form |\count0=|\meta{$\cdots$} expands everything which follows until the expansion doesn't need more numbers -- even more than one following macro.
\begin{codeexample}[]
\def\firstmacro{123}
\def\secondmacro{456}
\def\thirdmacro{789}
\count0=\firstmacro\secondmacro\thirdmacro
The value is now `\the\count0'.
\end{codeexample}
 The precise rules can be found in~\cite{texbook}, but it should be kept in mind that care needs to be taken here. More than once, my code failed to produce the expected result because \TeX\ kept expanding macros and the registers got unexpected results. Here is the correct method:
\begin{codeexample}[]
1. \count0=42 % a white space after the number aborts the reading process. It is discarded.
The value is now `\the\count0'.
2. The following code will absorb the `3' of '3.':
\def\macro{1234}
\count0=\macro % a white space after a macro will be absorbed by TeX, so this is wrong.
3. The value is now `\the\count0'.
4. Use \textbackslash relax after an assignment to end scanning:
\count0=\macro\relax
5. The value is now `\the\count0'.
\end{codeexample}
	The command |\relax| tells \TeX\ to ``relax'': it stops scanning for tokens, but |\relax| doesn't expand to anything.
	\index{relax@\texttt{\textbackslash relax}}%
\end{command}

\begin{command}{\dimen\meta{num}}
	There are also 255 registers for fixed point numbers which are used pretty much in the same way as the |\count| registers -- but |\dimen| register assignments require a unit like `|cm|' or `|pt|'.

	String access with `|\the|' works in exactly the same way as for |\count| registers.
\begin{codeexample}[]
\dimen0=1pt
The value is now \the\dimen0.
\dimen0=0.0001pt
The value is now \the\dimen0.
\def\macro{1234.5678}
\dimen0=\macro pt
The value is now \the\dimen0.
\end{codeexample}
	The same rules with expansion of macros after assignments apply here as well.

	The |\dimen| registers perform their arithmetics internally with 32 bit scaled integers, so called `scaled point' with unit `|sp|'. It holds |1pt=65536sp|=$2^{16}$|sp|. One of the 32 bits is used as sign. The total number range in |pt| is $[-(2^{30}-1)/2^{16}, (2^{30}-1)/2^{16} ] = [-16383.9998,+16383.9998]$\footnote{Please note that this does not cover the complete range of a 32 bit integer, I do not know why.}.
\end{command}

\begin{command}{\toks\meta{number}}
\label{cmd:toks}
	There are also 255 token registers which can be thought of as special string variables. Of course, every macro assignment |\def\macro|\marg{content} is also some kind of string variable, but token registers are special: their contents won't be expanded when used with |\the\toks|\meta{number}. This can be used for fine grained expansion control, see Section~\ref{sec:expansion:control} below.

\begin{codeexample}[]
\toks0={abc}%
\toks1={DEF}%
The value is now \the\toks0 \the\toks1.
\end{codeexample}
	Note the white space after |\the\toks0|: its purpose is to stop the number parsing when \TeX\ scans for |0|. The white space is discarded.

	Token registers can also contain the special token |#| which would typically have a special meaning inside of macros:
\begin{codeexample}[]
\toks0={#1}%
\message{Meaning is \the\toks0}%
\end{codeexample}
	This outputs ``\texttt{Meaning is \#\#1}'' in your log file.

	Token registers are mainly useful when it comes to fine grained expansion control and are discussed in more depth in Section~\ref{sec:expansion:control}.
\end{command}

\subsubsection{Allocating Registers}
There is a very limited number of registers. Consequently, one has to think carefully how to allocate them. Typical use--cases for registers are temporary variables (like some intermediate result) and long--living resources which are to be accumulated while the document or some part of it is to be generated.

It is clearly a bad idea to carelessly overwrite a register.

\TeX\ comes with a single way to ``allocate'' registers:
\begin{commandlist}{\newdimen\meta{\textbackslash macroname},\newcount\meta{\textbackslash macroname},\newtoks\meta{\textbackslash macroname}}
	These macros allocate a new register which is then accessable as \meta{\textbackslash macroname}.
\begin{codeexample}[]
\newdimen\variable

\variable=42pt

The value is now \the\variable.
\end{codeexample}

	The resulting \meta{\textbackslash macroname} can now be used in the same way as if you used the register directly. In fact, it is often simpler because you do not need to worry about the register's number.

	The allocation relies on some global integer variable which is increased for each allocation. This ensures that variables stored in such allocated variables do not accidentally overwrite the contents of some other variable.

	Note that deallocation is impossible.
\end{commandlist}
	
While it is perfectly reasonable to allocate long--living variables, one should avoid the allocation of a new variable just because one needs a ``new'' temporary variable.

It makes sense to allocate a couple of named variables like |\tempa|, |\tempb|, or something like that and reuse these values for every temporary evaluation. Clearly, care needs to be taken to avoid unintended overwrites.

It is also possible to use token registers as explained above. However, the usage should be protected by means of groups:
\begin{codeexample}[]
\toks3={Value outside of group}

\begingroup
\toks3={Value inside of group}
toks3 inside of group: \the\toks3
\endgroup

toks3 outside of group: \the\toks3
\end{codeexample}
	Groups constitute \TeX's concept of ``scope'' and are explained somewhere else in this document.

\subsubsection{Using More than 256 Registers}
\TeX\ on its own is restricted to 256 registers. However, you can manually activate ``extended \TeX\ mode'' by using
\begin{codeexample}[code only]
\usepackage{etex}	
\end{codeexample}
early in your preamble. This is actually a very good idea: it allows access to 65536 registers. Today's documents which involve lots of packages actually need |etex|.

Note that even |etex| does not justify wild and uncontrolled allocated of registers just to store temporary variables.

If you want almost unlimited temporary variables, you should store the temporaries in macros. This, of course, involves conversion from numbers to string, but it is the only save way which avoids the limited number of registers.

\subsection{Arithmetics in \TeX}
\begin{command}{\advance\meta{register}\texttt{ by}\meta{quantity}}
\begin{codeexample}[]
\count0=42
\advance\count0 by 10
The value is now \the\count0.
\end{codeexample}

\begin{codeexample}[]
\dimen0=1pt
\advance\dimen0 by 10pt
The value is now \the\dimen0.
\end{codeexample}
\end{command}

\begin{command}{\multiply\meta{register}\texttt{ by}\meta{integer}}
\begin{codeexample}[]
\count0=42
\multiply\count0 by -10
The value is now \the\count0.
\end{codeexample}

\begin{codeexample}[]
\dimen0=0.5pt
\multiply\dimen0 by 20
The value is now \the\dimen0.
\end{codeexample}
\end{command}

\begin{command}{\divide\meta{register}\texttt{ by}\meta{integer}}
	This allows integer division by \meta{integer} with truncation.
\begin{codeexample}[]
\count0=5
\divide\count0 by 2
The value is now \the\count0.
\end{codeexample}

	Scaling of |\dimen| registers:
\begin{codeexample}[]
\dimen0=10pt
\divide\dimen0 by 20
The value is now \the\dimen0.
\end{codeexample}

	It is impossible to divide by some non--integer number.
\end{command}

\begin{command}{\dimen\meta{number}\texttt{=}\meta{fixed point number without unit}\textbackslash dimen\meta{number}}
	This allows fixed point multiplication in |\dimen| registers.
\begin{codeexample}[]
\dimen1=50pt
\dimen0=0.6\dimen1
The value is now \the\dimen0.
\end{codeexample}
\end{command}

This is actually all that \TeX\ allows. One needs powerful macro packages like \PGF\ with its |\pgfmathparse|\marg{expression} to do some ``real'' arithmetics.

Note that the limited number range of these registers also applies to the result of any numerical operation.


\subsection{Expansion Control}
\label{sec:expansion:control}
Expansion is what \TeX\ does all the time. Thus, expansion control is a key concept for understanding how to program in \TeX.

The first thing to know is: \TeX\ deals the input as a long, long sequence of ``tokens''. A token is the smallest unit which is understood by \TeX. Each character becomes a token the first time it is seen by \TeX. Every macro becomes a (single!) token the first time it is seen by \TeX.

The second thing to know is what characters are \emph{before} \TeX\ has seen them. Although this knowledge is rarely needed in every day's life, it is nevertheless important. The characters which are in the input document are nothing but characters at first. Even the characters known to have a special meaning like `|%|', `|\|' or the braces `|{}|' are \emph{not} special -- until they have been converted to a token. This happens when \TeX\ encounters them the first time during its linear processing of the character stream. A token stays a token - and it will remain the same token forever. If you manage to tell \TeX\ that `|\|' is a normal character and \TeX\ sees just one backslash, this backslash will be a normal character token -- even if the meaning of all following backslashes is again special.

Now, we are given a very long list of tokens \meta{token1}\meta{token2}\meta{token3}\meta{token4}\meta{token5}$\cdots$. \TeX\ processes these tokens one-by-one in linear sequence. If \meta{token1} is a character token like `|a|', it is typeset. This is not what I want to write about here now; my main point is how to program in \TeX\footnote{Of course, typesetting is an art in itself and there is a lot to read about it. Just not here in these notes.}. So, the interesting thing in these notes is when \meta{token1} is a macro.

\subsubsection{Macros}
We have already seen some applications of macros above. Actually, most users who are willing to read notes about \TeX\ programming will have seen macros and may have written some on their own -- for example using |\newcommand| (|\newcommand| is a ``more high--level'' version of |\def| used only in \LaTeX).

A macro has a name and is treated as an elementary token in \TeX\ (even if the name is very long). A macro has replacement text. As soon as \TeX\ encounters a macro, it replaces its occurrence with the replacement text. Furthermore, a macro can consume one or more of the following tokens as arguments.
\begin{codeexample}[]
\def\macro{This here is actually the replacement text.}
Executing it: `\macro'.
\end{codeexample}
\begin{codeexample}[]
\def\macro#1{replacement with first argument=#1}
Invoking it: \macro{hello!}.
\end{codeexample}
This here is not really a surprise. What might come as a surprise is that the accepted arguments can be pretty much anything.
\begin{codeexample}[]
\def\macro#1-#2.{replacement with arguments: `#1' and `#2'.}
Invoking it: \macro a-sign.
\end{codeexample}
\noindent The last example |\macro| runs through the token list which follows the occurrence of |\macro|. This token list is ``|a-sign.|''. Macro expansion is greedy, that means the first matching pattern is used. Now, our |\macro| expected something, then a minus sign `|-|', then another (possibly long) argument, then a period `|.|'. The argument between |\macro| and the minus sign is available as |#1| and the tokens between the minus sign and the period as |#2|.

\begin{codeexample}[]
\def\macro(#1,#2,#3){I found arguments `#1', `#2' and `#3'.}
\macro(42,43,44)
\end{codeexample}

As we have seen, macros can be used to manipulate the input tokens by expansion: they take some input arguments (maybe none) away and insert other tokens into the input token list. These tokens will be the next to process. We will soon learn more about that.

There is a command which helps to understand what \TeX\ does here:

\begin{command}{\meaning\meta{macro}}
	This command expands to the contents of \meta{macro} as it is seen by \TeX.
\begin{codeexample}[]
\def\macro{Replacement \textmacro text  \count0=42 \the\count0.}
\message{Debug message: '\meaning\macro'}
\end{codeexample}
As result, the log file and terminal output will contain

|Debug message: 'macro:->Replacement \textmacro text \count 0=42 \the \count 0.'|
\end{command}

The last example already shows something about |\def|: the replacement text can still contain other macros.

\begin{command}{\def\meta{\textbackslash macroname}\meta{argument pattern}\marg{replacement text}}
	 A new macro named \meta{macroname} will be defined (or re-defined). The \marg{replacement text} is the macro body, whenever the macro is executed, it expands to \marg{replacement text}. The \marg{replacement text} is a token list which can contain other macros. On the time of the definition, \TeX\ does \emph{not} process (expand) the \marg{replacement text}.

	 The \marg{replacement text} will only be expanded if the macro is executed. This does also apply to any macros which are inside of \marg{replacement text}.
\begin{codeexample}[]
\def\macroone{This is macro one}
\def\macrotwo{Macro two contains \macroone.}
Now, I execute it: \macrotwo.
\def\macroone{Redefined macroone}
Now, I execute the second macro again: \macrotwo.
\end{codeexample}

	Macros can be defined almost everywhere in a \TeX\ document. They can also be invoked almost everywhere.

	The \meta{argument pattern} is a token list which can contain simple strings or macro parameters `|#|\meta{number}' or other macro tokens. The \meta{number} of the first parameter is always 1, the second must have 2 and so on up to at most 9. Valid argument patterns are `|#1#2#3|', `|(#1,#2,#3)|' or `|---\relax|'. If \TeX\ executes a macro, it searches for \meta{argument pattern} in the input token list until the first match is found. If no match can be found, it aborts with a (more or less helpful) error message.
\begin{codeexample}[]
\def\macroone abc{\macrotwo}
\def\macrotwo def{\macrothree}
\def\macrothree#1{Got `#1'}
\macroone abcdefg
\end{codeexample}
	The last example contains three macro definitions. Then, \TeX\ encounters |\macroone|. The input token list is now
	
	`|\macroone abcdefg|'.

	The space(s) following |\macroone| are ignored by \TeX, they delimit the \meta{\textbackslash macroname}. Now, \TeX\ attempts to find matches for \meta{argument pattern}. It expects `|abc|' -- and it finds `|abc|'. These three tokens are \emph{removed} from the input token list, and \TeX\ inserts the replacement text of |\macroone| which is |\macrotwo|. At that time, the input token list is

	`|\macrotwo defg|'.

	Now, the same game continues with |\macrotwo|: \TeX\ searches for the expected \marg{argument pattern} which is `|def|', erases these tokens from the input token list and inserts the replacement text of |\macrotwo| instead. This yields

	`|\macrothree g|'.

	Finally, |\macrothree| expects one parameter token (or a token list enclosed in parenthesis). The next token is `|g|', which is consumed from the input token list and the replacement text is inserted -- and `|#1|' is replaced by `|g|'. Then, the token list is

	`|Got `g'|'.

	This text is finally typeset (because it doesn't expand further).
\end{command}

What we have seen now is how \TeX\ macros can be used to modify the token list. It should be noted explicitly that macro expansion does is in no way limited to those tokens provided inside of \marg{replacement text} -- if the last argument in \marg{replacement text} is a macro which requires arguments, these arguments will be taken from the following tokens. Using nested macros, one can even process a complete part of the token list, in a manner of loops (but we don't know yet how to influence macro expansion conditionally, that comes later).

Let's try to solve the following task. Suppose you have a macro named |\point| with \meta{argument pattern} `|(#1,#2)|', i.e.

|\def\point(#1,#2){we do something with #1 and #2}|.

\noindent
Suppose furthermore that you want to invoke |\point| with the contents which is stored in another macro. After all, macros are some kind of string variables -- it makes sense to accumulate or generate string variables which will then be used as input for other macros. Let's assume we have |\temp| and |\temp| contains `|(42,1234)|'. A first choice to invoke |\point| would be to use |\point\temp|. But: |\point| searches for an argument pattern which starts with `|(|', not with |\temp|! The invocation fails.

\begin{command}{\expandafter\meta{token}\meta{next token}}
	The |\expandafter| command is an -- at first sight confusing -- method to alter the input token list. But: it solves our problem with |\point\temp|!
\begin{codeexample}[]
\def\point(#1,#2){we do something with #1 and #2}
\def\temp{(42,1234)}
\expandafter\point\temp
\end{codeexample}
	Why did that work!? The command |\expandafter| scans for the token after |\expandafter| in the input token list. This is |\point| in our case. Then, it scans for the next token which is |\temp| in our case (remember: macros are considered to be elementary tokens, just like characters `|a|' or so). The two scanned arguments are removed from the input token list. Then, |\expandafter| \emph{expands} the \meta{next token} one time. In our case, \meta{next token} is |\temp|. The first level of expansion of |\temp| is `|(42,1234)|'.  Then, |\expansion| inserts the (unexpanded) \meta{token} followed by the (expanded) contents of \meta{next token} back into the input token list. In single steps:

	\begin{enumerate}
		\item |\expandafter\point\temp|
		\item Expand |\expandafter|: next two tokens are `|\point\temp|'.
		\item Use |\point| as \meta{token} and |\temp| as \meta{next token}.
		\item Expand |\temp| once, which leads to the tokens `|(42,1234)|'.
		\item re-insert \meta{token} and the expansion of \meta{next token} back into the input token list. The list is then
			
			`|\point(42,1234)|'.
		\item Expand |\point| as next token.
	\end{enumerate}

	A further example: suppose we want to invoke |\theimportantmacro|\marg{argument}. However, \marg{argument} is contained in another macro! Furthermore, |\theimportantmacro| is defined to take exactly one parameter and our desired argument may have more than one token (which means we need to surround it with braces). This can be solved by the listing below.
\begin{codeexample}[]
\def\theimportantmacro#1{I got the pre-assembled argument `#1' here.}
\def\temp{xyz}
\expandafter\theimportantmacro\expandafter{\temp}
\end{codeexample}
	Now, what happens here? Let's apply the rules step by step again:
	\begin{enumerate}
		\item After the initial definitions, the token list is |\expandafter\theimportantmacro\expandafter{\temp}|.
		\item \TeX\ expands |\expandafter|, using |\theimportantmacro| as \meta{token} and the second |\expandafter| as \meta{next token}.
		\item According to the rules, \TeX\ expands \meta{next token} once. But: \meta{next token} is again a macro, namely |\expandafter|! Does that make a difference? No:
			\begin{enumerate}
				\item The token list after the second |\expandafter| is `|{\temp}|' (3 tokens).
				\item The \meta{token} is thus `|{|' and \meta{next token} is `|\temp|'.
				\item The expansion of \meta{next token} is `|xyz|'.
				\item The second |\expandafter| re-inserts its \meta{token} and expanded \meta{next token}, which is
					
					`|{xyz|'.

					Note that the closing brace `|}|' has not been touched at all, \TeX\ hasn't even seen it so far.
			\end{enumerate}
			We come back from the recursion. Remember: \meta{token} is |\theimportantmacro| and the top-level expansion of \meta{next token} is -- as we have seen above -- `|{xyz|'.
		\item \TeX\ re-inserts \meta{token} and the expansion of \meta{next token} to the input token list, which leads to

			`|\theimportantmacro{xyz}|'.

			The closing brace `|}|' has not been touched, it simply resides in the input token list.
		\item \TeX\ expands |\theimportantmacro|.
	\end{enumerate}

	The \meta{next token} is expanded exactly once. We have already seen that if \meta{next token} is a macro which does substitutions on its own, these substitutions will be performed recursively. But what means `once' exactly? We will need to use |\meaning| to check that (or the |\tracingmacros| tools) because we need to see what \TeX\ does.
\begin{codeexample}[]
\def\macroone{This is macro one \macrotwo}
\def\macrotwo{--2--}
\def\macrothree#1{\def\macrofour{4[#1]}}
\expandafter\macrothree\expandafter{\macroone}%
So far, nothing has been typeset. But now: \macrofour.
\message{We have macrofour = \meaning\macrofour}%
\end{codeexample}
	The logfile (and terminal) will now contain

	`|We have macrofour = macro:->4[This is macro one \macrotwo ]|'.

	What happened? We can proceed as in the last example. After the two |\expandafter| expansions, \TeX\ finds the input token list

	`|\macrothree{This is macro one \macrotwo}|'

	which, after execution, defines |\macrofour| to be `|This is macro one \macrotwo|'. The top-level expansion of |\macroone| has not expanded the nested call to |\macrotwo|.


	So, |\expandafter| is a normal macro which can be expanded -- and it is even possible to expand an |\expandafter| by another |\expandafter|.
\end{command}

What we have seen so far is
\begin{enumerate}
	\item the |\def| command which stores \emph{unexpanded} arguments in a macro variable and
	\item the |\expandafter| which allows control over top-level expansion of macros (it expands one time).
\end{enumerate}
\TeX\ provides two more features for expansion control: the |\edef| macro and token registers.

\begin{command}{\edef\meta{\textbackslash macroname}\meta{argument pattern}\marg{replacement text}}
	The |\edef| command is the same as |\def| insofar as it defines a new macro. However, it expands \marg{replacement text} until only unexpandable tokens remain (|\edef| $=$ expanded definition).
\begin{codeexample}[]
\def\a{3}
\def\b{2\a}
\def\c{1\b}
\def\d{value=\c}
\message{Macro `d' is defined to be `\meaning\d'}
\edef\d{value=\c}
\message{Macro `d' is e-defined to be `\meaning\d'}
\expandafter\def\expandafter\d\expandafter{\c}
\message{Macro `d' is defined to be `\meaning\d' using expandafter}
\end{codeexample}
	This listing results in the log-file output

	|Macro `d' is defined to be `macro:->value=\c '|

	|Macro `d' is e-defined to be `macro:->value=123'|

	|Macro `d' is defined to be `macro:->1\b ' using expandafter|

	\noindent So, |\def| does not expand at all, |\edef| expands until it can't expand any further and the |\expandafter| construction expands |\c| one time and defines |\d| to be the result of this expansion.

	Although possible, it might not occur too often to specify \meta{argument pattern} for an |\edef| because the expansion is immediate in contrast to |\def|. But it works in the same way: the positional arguments |#1|, |#2|$,\dotsc,$ |#9| will be replaced with their arguments.

	The expansion of \marg{replacement text} happens in the same way as the expansion the main token list of \TeX.

	Now, what exactly does ``expands until only unexpandable tokens remain'' mean? Our example indicates that the three tokens |1|, |2| and |3| are not expandable while the macros |\c|, |\b| and |\a| could be expanded. There is one large class of \TeX\ commands which can't be expanded: any assignment operation. The example
\begin{codeexample}[]
\edef\d{\count0=42}
\message{Macro `d' is defined to be `\meaning\d'}
\def\a{1234}
\edef\d{\advance\count0 by\a}
\message{Macro `d' is defined to be `\meaning\d'}
\end{codeexample}
\noindent yields the log-messages 

|Macro `d' is defined to be `macro:->\count 0=42'| and

|Macro `d' is defined to be `macro:->\advance \count 0 by1234'|.

So, assignment and arithmetics operations are \emph{not} expandable, they remain as executable tokens in the newly defined macro. This does also hold for |\let| and other assignment operations.

	Interestingly, conditional expressions using |\if| $\dotsb$ |\fi| \emph{are} expandable, but we will come to that later.

	There is also a method to convert a macro temporarily into an unexpandable token: the |\noexpand| macro.
\end{command}

\begin{command}{\noexpand\meta{expandable token}}
	The |\noexpand| command is only useful inside of the \marg{replacement text} of an |\edef| command. As soon as |\edef| encounters the |\noexpand|, the |\noexpand| will be removed and the \meta{expandable token} will be converted into an unexpandable token. Thus, the code
\begin{codeexample}[]
\edef\d{Invoke \noexpand\a another macro}
\message{Macro `d' is defined to be `\meaning\d'}
\end{codeexample}
\noindent yields the terminal output

|Macro `d' is defined to be `macro:->Invoke \a another macro'|

because |\noexpand\a| yields the token `|\a|' (unexpanded)\footnote{The \texttt{\textbackslash noexpand} key is actually used to implement the \LaTeX\ command \texttt{\textbackslash protect}: \LaTeX's concept of moveable arguments is implemented with \texttt{\textbackslash edef}.}.
\end{command}

\subsubsection{Token Registers}
Now, we turn to token registers. As we have already seen in Section~\ref{cmd:toks}, a token register stores a token list. A macro does also store a token list in its \marg{replacement text}, so where is the difference? There are two differences:
\begin{enumerate}
	\item Token registers are faster.
	\item The contents of token registers will \emph{never} be expanded.
\end{enumerate}
I can't give numbers for the first point -- I have just read it in~\cite{texbook}. But the second point allows expansion control. While |\edef| allows ``infinite'' expansion, token registers allow only top--level expansion, just like |\expandafter|. But they can be used in a more flexible (and often more efficient) way than |\expandafter|.

The following examples demonstrates the second point.
\begin{codeexample}[]
\toks0={A \token list \a \b \count0=42 will never be expanded}
\edef\d{\the\toks0 }% the space token is important!
\message{Macro `d' is defined to be `\meaning\d'}
\end{codeexample}
\noindent Executing this code fragment yields the log output

|Macro `d' is defined to be `macro:->A \token list \a \b \count 0=42 will never be expanded'|.

So, the contents of |\toks0| has been copied unexpanded into |\d|, although we have just |\edef|. Note that the space token after |\the\toks0| is indeed important! \TeX\ uses it to delimit the integer |0|. Without the space token, it would have continued scanning, even beyond the boundaries of the replacement text of |\edef| (see Section~\ref{sec:variables} for details about this scanning).

The example is very simple, and we could have done the same with |\expandafter| as before. But let's try something more difficult: we want to assemble a new macro which consists of different pieces. Each piece is stored in a macro, and for whatever reason, we only want top-level expansion of the single pieces. And: the pieces won't be adjacent to each other. We can assemble the target macro using the following example listing.

\begin{codeexample}[]
\def\piecea{\a{xyz}}
\def\pieceb{\count0=42 }
\def\piecec{string \b}
\toks0=\expandafter{\piecea}
\toks1=\expandafter{\pieceb}
\toks2=\expandafter{\piecec}
\edef\d{I have \the\toks0 and \the\toks1 and \the\toks2}
\message{Macro `d' is defined to be `\meaning\d'}
\end{codeexample}

The first three lines define our pieces. Each of the macros |\piecea|, |\pieceb| and |\piecec| contains tokens which should not be expanded during the definition of |\d|. The three following lines assign the top-level expansion of our pieces into token registers. Since |\toks0={\piecea}| would have stored `|\piecea|' into the token register, we need to use |\expandafter| here\footnote{We could have eliminated the \texttt{\textbackslash piece*} macros by writing everything into token registers directly. But I think this example is more realistic.}. Then, we use |\the\toks|\meta{number} to insert the contents of a token list somewhere -- in our case, into the expanded replacement text of our macro |\d|. Thus, the complete example yields the log--output

|Macro `d' is defined to be `macro:->I have \a {xyz}and \count 0=42 and string \b '|.

\noindent It \emph{is} possible to get exactly the same result using (a lot of) |\expandafter|s. Don't try it.


\subsubsection{Summary of macro definition commands}
Besides |\def| and |\edef|, there are some more commands which allow to define macros (although the main functionality is covered by |\def| and |\edef|). Here are the remaining definition commands.
\begin{command}{\def\meta{\textbackslash macroname}\meta{argument pattern}\marg{replacement text}}
	Defines a new macro named |\macroname| without expanding \marg{replacement text}, see above.	
\end{command}
\begin{command}{\edef\meta{\textbackslash macroname}\meta{argument pattern}\marg{replacement text}}
	Defines a new macro named |\macroname|, expanding \marg{replacement text} completely (see above).
\end{command}
\begin{command}{\let\meta{\textbackslash newmacro}=\meta{token}}
	Defines or redefines |\newmacro| to be an equivalent to \meta{token}. For example, |\let\a=\b| will create a new copy of macro |\b|. The copy is named |\a|, and it will have exactly the same \marg{replacement text} and \meta{argument pattern} as |\b|.

	It is also possible that \meta{token} is something different than a macro, for example a named register or a single character.
\end{command}

\begin{command}{\gdef\meta{\textbackslash macroname}\meta{argument pattern}\marg{replacement text}}
	A shortcut for |\global\def|. It defines |\macroname| globally, independent of the current scope.

	You should avoid macros which exist in both, the global namespace and a local scope, with different meanings. Section~\ref{sec:scopes} explains more about scoping.
\end{command}
\begin{command}{\xdef\meta{\textbackslash macroname}\meta{argument pattern}\marg{replacement text}}
	A shortcut for |\global\edef|. It defines |\macroname| globally, independent of the current scope.

	You should avoid macros which exist in both, the global namespace and a local scope, with different meanings. Section~\ref{sec:scopes} explains more about scoping.
\end{command}

\begin{command}{\csname\meta{expandable tokens}\textbackslash endcsname}
	This command is not a macro definition, it is a definition of a macro's \emph{name}. The ``cs'' means ``control sequence''. The |\csname|, |\endcsname| pair defines a control sequence name (a macro name) using \meta{expandable tokens}. The control sequence character `|\|' will be prepended automatically by |\csname|.\footnote{In fact, the contents of \texttt{\textbackslash escapechar} will be used here. If its value is -1, no character will be prepended. The same holds for any occurrence where a backslash would be inserted by \TeX\ commands.}
\begin{codeexample}[]
\def\macro{Content}
This here is normal usage: `\macro'.
This here uses csname: `\csname macro\endcsname'.
\end{codeexample}
	\noindent The example demonstrates that |\csname|\meta{expandable tokens}|\endcsname| is actually the same as if you had written |\|\meta{expandable tokens} directly -- but the |\csname| construction allows much more tokens inside of macro names:
\begin{codeexample}[]
\expandafter\def\csname a01macro with.strange.chars\endcsname{Content}
I use a strange macro. Here is it: `\csname a01macro with.strange.chars\endcsname'.
\end{codeexample}
	\noindent The example uses |\expandafter| to expand |\csname| one time. The top--level expansion of |\csname| is a single token, namely the control sequence name. Then, |\def| is used to define a macro with the prepared macro name.

	When |\csname| is expanded, it parses all tokens up to the next |\endcsname|. Those tokens will be expanded until only unexpandable tokens remain (as in |\edef|). The resulting string will be used to define a macro name (with the control sequence character `|\|' prepended). The fact that \meta{expandable tokens} is expanded allows to use ``indirect'' macro names:
\begin{codeexample}[]
\def\macro{onetwothree}
\expandafter\def\csname macro\macro\endcsname{Content}
I have just defined \expandafter\string\csname macro\macro\endcsname
with replacement text `\csname macro\macro\endcsname'.
\end{codeexample}
	\noindent I suppose the example is self-explaining, up to the |\string| command which is described below.

	Due do this flexibility, |\csname| is used to implement all (?) of the available key--value packages in \TeX.
\end{command}

\begin{command}{\string\meta{\textbackslash macro}}
	This command does not define a macro. Instead, it returns a macro's name as a sequence of separate tokens, including the control sequence token `|\|'.
\begin{codeexample}[]
\def\macro{Content}
I have just defined `\string\macro' using `\string\def'.
\end{codeexample}

	You can also use |\string| on other tokens -- for example characters. That doesn't hurt, the character will be returned as-is.
\end{command}

\subsubsection{Debugging Tools -- Understanding and Tracing What \TeX\ Does}
\begin{command}{\message\marg{tokens}}
\end{command}
\begin{command}{\meaning\meta{\textbackslash macro}}
\end{command}
\begin{command}{\tracingmacros=2}
\end{command}
\begin{command}{\tracingcommands=2}
\end{command}
\begin{command}{\tracingrestores=1}
\end{command}

\subsection{The Scope of a Variable}
\label{sec:scopes}
Each programming language knows the concept of a scope: they limit the effect of variables or routines. However, \TeX's scoping mechanisms have not been designed for programming -- \TeX\ is a typesetting language. Many programming languages like |C|, |C++|, |java| or a lot of scripting languages define the scope of a variable using the place where the variable has been defined. For example, the |C| fragment
\begin{codeexample}[code only]
int i = 42;

{
	++i;
	int i = 5;
}
\end{codeexample}
\noindent changes the value of the outer |i| to |43|. The inner |i| is |5|, but it will be deleted as soon as the closing brace is encountered. It may even be possible to access both, the value of the inner |i| variable and the value of the outer |i| variable, at the same time.

In \TeX, braces are also used for scopes. But: while \TeX\ will also destroy any variables (macros) defined inside of a scope at the end of that scope, it will \emph{also} undo any change which has been applied inside of that scope.
\begin{codeexample}[]
\def\i{42}
{
	\def\i{43}
	\def\b{2}
}
The value of \textbackslash i is now \i.
\end{codeexample}
\noindent The listing above defines |\i|, enters a local scope (a \TeX\ ``group'') and changes |\i|. However, due to \TeX's scoping rules, the old program state will be restored \emph{completely} after returning from the local group! Neither the change to |\i| nor the definition of |\b| will survive. The same holds for register changes or other assignments.

\TeX\ groups can be created in one of three ways: using curly braces\footnote{Or other tokens with the correct category code, compare~\cite{texbook}.}, using |\begingroup| or using |\bgroup|. Curly braces are seldom used to delimit \TeX\ groups because the other commands are more flexible. If one uses curly braces, they need to match up -- it is forbidden to have unmatched curly braces.
\begin{command}{\begingroup}
	Starts a new \TeX\ group (a local scope). The scope will be active until it will be closed by |\endgroup|. The |\endgroup| command can occur later in the main token list.
\end{command}
\begin{command}{\endgroup}
	Ends a \TeX\ group which has been opened with |\begingroup|.
\end{command}
\begin{command}{\bgroup}
	A special variant of |\begingroup| which can also be used to delimit arguments to |\hbox| or |\vbox| (i.e. it avoids the necessity to provide matched curly braces in this context).

	The |\bgroup| macro is also useful to test whether the next following character is an opening brace (see |\futurelet|).

	If one just needs to open a \TeX\ group, one should prefer |\begingroup|.
\end{command}
\begin{command}{\egroup}
	Closes a preceding |\bgroup|.
\end{command}

\TeX\ does not know how to write into macros of an outer scope -- except for the topmost (global) scope. This restriction is quite heavy if one needs to write complex structures: local variables should be declared inside of local groups, but changes to the structure should be written to the outer group. There is no direct possibility to do such a thing (except global variables).

\subsubsection{Global Variables}
\TeX\ knows only ``global'' variables and ``local'' variables. A local variable will be deleted at the end of the group in which it has been declared. All values assigned locally will also be restored to their old value at the end of the group.

A global variable, on the other hand, maintains the same value throughout \emph{every} scope. Usually, the topmost scope is the same as the one used for global variables: if you define anything in your \TeX\ document, you add commands on global scope. It is also possible to explicitly make assignments or definitions in the global scope.

\begin{command}{\global\meta{definition or assignment}}
	The definition which follows |\global| immediately will be done globally.
\begin{codeexample}[code only]
{
	\global\def\a{123}
	\global\advance\count0 by3
	\global\toks0={34}
}
\end{codeexample}
\end{command}

\begin{command}{\globaldefs=\mchoice{-1,0,1} (initially 0)}
	I cite from~\cite{texbook}: ``If the |\globaldefs| parameter is positive at the time of an assignment, a prefix of |\global| is automatically implied; but if |\globaldefs| is negative at the time of the assignment, a prefix of |\global| is ignored. If |\globaldefs| is zero (which it usually is), the appearance of nonappearance of |\global| determines whether or not a global assignment is made.''
\end{command}


\subsubsection{Transporting Changes to an Outer Group}
There are a couple of methods to ``transport'' changes to an outer scope. Some are copy operations, some require to redo the changes again after the end of the scope. All of them can be realized using expansion control.

Let's start with macro definitions which should be carried over the end of the group. I see the following methods:
\begin{itemize}
	\item Copy the macro into a global, temporary variable (or even token register) and get that value after the scope.
\begin{codeexample}[code only]
\def\initialvalue{0}
{
	% do something:
	\def\initialvalue{42}
	\global\let\myglobaltemporary=\initialvalue
}
\let\initialvalue=\myglobaltemporary
\end{codeexample}
	The idea is that |\myglobaltemporary| is only used temporary; its value is always undefined and can be overwritten at any time. This allows to use a local variable |\initialvalue|.

	Please note that you should not use variables both globally and locally. This confuses \TeX\ and results in a slow-down at runtime.

	\item ``Smuggle'' the result outside of the current group. I know this idea from the implementation of~\cite{tikz} written by Mark Wibrow and Till Tantau. The idea is to use several |\expandafter|s and a |\def| to redefine the macro directly after the end of the group:
\begin{codeexample}[code only]
\def\smuggle#1\endgroup{%
	\expandafter\endgroup\expandafter\def\expandafter#1\expandafter{#1}%
}

\begingroup
	\def\variable{12}
	\edef\variable{\variable34}
	\edef\variable{\variable56}
	\smuggle\variable
\endgroup
\end{codeexample}
	The technique relies on groups started with |\begingroup| and ended with |\endgroup| because unmatched braces are not possible with |\def|. The effect is that after all those |\expandafter|s, \TeX\ encounters the token list

	|\endgroup\def\variable{123456}|

	at the end of the group.

	\item Use the aftergroup stack. \TeX\ has a special token stack of limited size which can be used to re-insert tokens after the end of a group. However, this does only work efficiently if the number of tokens which need to be transported is small and constant (say, at most three). It works by prefixing every token with |\aftergroup|, compare~\cite{texbook} for details.
\end{itemize}

Sometimes one needs to copy other variables outside of a scope. The trick with a temporary global variable works always, of course. But it is also possible to define a macro which contains commands to apply any required changes and transport that macro out of the scope.

\subsection{Branching}
\label{sec:branching}

Here we discuss some of the available branching constructions of \TeX, with emphasis on conditions involving numbers and tokens.

\begin{command}{ifnum\meta{count/integer number}=\meta{count/integer number}\meta{true-block}\textbackslash else\meta{false-block}\textbackslash fi}
|\ifnum| compare integer numbers or integer registers (|\count| registers) and contains two branches, one is executed in the true case, the other in the case of false:
\begin{codeexample}[]
\ifnum1=2 % this space is important.
This is shown if above were true.
\else
This is shown if above results to false.
\fi
\end{codeexample}

	Note that the |\else| with its \meta{false-block} is optional.
\end{command}

\begin{command}{ifdim\meta{dimen/fixed point number}=\meta{dimen/fixed point number}\meta{true-block}\textbackslash else\meta{false-block}\textbackslash fi}
	Similar to |\ifnum|, |\ifdim| compares two fixed point numbers or |\dimen| registers. The numbers must have a unit.
\begin{codeexample}[]
\ifdim1pt=2pt % this space is important.
This is shown if above were true.
\else
This is shown if above results to false.
\fi
\end{codeexample}
\end{command}

\begin{command}{ifx\meta{token1}\meta{token2}\meta{true-block}\textbackslash else\meta{false-block}\textbackslash fi}
|\ifx| is a bit more complex: It compares two \emph{tokens} up to their first-level expansion.
\begin{codeexample}[]
\def\empty{\empty}
\ifx\empty\empty %
This is shown if the two tokens have equal expansion.
\else
This is shown if the two tokens expand to something different.
\fi
\end{codeexample}

Here, we have defined a token |\empty| to be a replacement for |\empty| and subsequently have compared whether these two tokens are equal in first-level expansion. Note that the definition is actually nonsense. If \TeX{} ever were to go through the whole expansion -- i.e. we would put |\empty| somewhere else -- it would do so indefinitely. However, with |\ifx| only first-level expansion is done and compared. Hence, the statement evaluates to true.

Have a look at the following example:
\begin{codeexample}[]
\def\empty{\relax}
\ifx\empty\relax %
This is shown if the two tokens have equal expansion.
\else
This is shown if the two tokens expand to something different.
\fi
\end{codeexample}

On first glance, this should evaluate to true: |\empty| is defined as a replacement for |\relax|. But it does not. Why? 

|\empty| is expanded to |\relax|, however |\relax| expanded has a different meaning, namely stop scanning and not |\relax| anymore. Hence, they are different and the statement is false! If the expansion in |\ifx| were to be taken till maximum, both would be equal but not in the case of a comparison on first-level expansion only.
\end{command}

\begin{command}{if\meta{token1}\meta{token2}\meta{true-block}\textbackslash else\meta{false-block}\textbackslash fi}
	The |\if| comparison is closely related to the |\ifx| conditional, with one major exception: it expands tokens until it finds the next two unexpandable tokens. If these two tokens are the same, it expands to the \meta{true-block}, otherwise to the \meta{false-block}.

	The |\if| conditional should be handled with care as it might produce undesirable effects. Use it only if you know what you do.

	A useful example is if you \emph{know} that a macro contains at most one character, and you want to test for a particular one:
\begin{codeexample}[]
\def\choice{a}
\if b\choice
  This is shown for the `b' choice.
\else
  This is shown for all other choices.
\fi
\end{codeexample}
\end{command}

\begin{command}{iftrue\meta{true-block}\textbackslash else\meta{false-block}\textbackslash fi}
	A ``conditional'' which always invokes the \meta{true-block}.
\end{command}
\begin{command}{iffalse\meta{true-block}\textbackslash else\meta{false-block}\textbackslash fi}
	A ``conditional'' which always invokes the \meta{false-block}.
\end{command}

\subsubsection{Boolean Variables}
\begin{command}{\newif\meta{if-name}}
	You can declare a new ``boolean variable `|\ifsupermanmode| by means of |\newif\ifsupermanmode|. Afterwards, you can use the |\supermanmodetrue| and |\supermanmodefalse| switches to assign the boolean and |\ifsupermanmode| to check it.

	The \meta{if-name} has to start with |\if| (to support scans for nested |\if...\fi| pairs, see below).
\end{command}

\subsubsection{Special Cases for Conditionals}
Whenever you work with |\if|\ldots\ and friends, you should know the following features:
\begin{enumerate}
	\item |\if...\else...\fi| is expandable (including each of the single macros |\if...|, |\else| and |\fi|), which means you can even use it inside of |\edef|:
\begin{codeexample}[]
\def\choice{a}
\edef\temp{The choice is \if a\choice `a'\else not `a'\fi}
We have now \texttt{\string temp=\meaning\temp}.
\end{codeexample}

\begin{codeexample}[]
\def\shownexttoken#1{The next token is `\texttt{\string#1}'.}
\def\mymacro{%
 	\ifnum1=1 %
 		\expandafter\shownexttoken%
 	\fi%
}%
\mymacro 23
\end{codeexample}
	This example is tricky. What would have happened without the |\expandafter|!? Well, |\shownexttoken| would be invoked with |#1=\fi|. This would lead to an error because the |\fi| would be missing, and it would spoil the effect since we do not want the |\fi| to be seen -- we expected |#1=2|. The |\expandafter| first expands |\fi| (which simply removes the |\fi| without further effect) such that |\shownexttoken| will see the |2| token in our example above. This would also have worked if there was an |\else| branch instead of |\fi|.
	
	\item You should generally make sure that the matching |\else| or |\fi| tokens are ``directly reachable'', i.e.\ without token expansion.

	The background here is that \TeX\ works on a token--based level: Whenever it encounters an |\if|\ldots\ statement, it evaluates it and scans tokens to find the matching end part (either an |\else| or an |\fi| token). But it will not expand tokens during this scan, although it will count nested |\if...\fi| pairs! Thus, if you are careless, it might become confused and your conditional will go awry.
\end{enumerate}

\subsection{Loops}
\label{sec:loops}
As you have seen, in \TeX{} we have a very specific control over token expansion. This makes it possible to construct even loops via means of recursion. In essence, a loop consist of the following parts:
\begin{itemize}
 \item counter or, more generally, list of items
 \item incrementor, or more generally, a next item picker
 \item threshold or, more generally, an end list marker
 \item a check of the threshold or end marker, respectively
\end{itemize}

Leafing through the sections above, we realize that all of this is actually in place: We do know about counters, we do know about branching. Only the specifics of how to create these loops is still to be made clear. We will show both cases, the counting loop and the loop over a list of items in the following in detail.

In general, for a loop done via a recursion we need two definitions: One for the loop start and another for the loop step.

\subsubsection{Counting loops}
\label{sec:counting:loops}
For a counting loop, we need a counter |\count0|, an incrementor |\advance|, a threshold |3| and a check |\ifnum\count=10| if the threshold has been reached.


\begin{codeexample}[]
\long\def\countingloop#1 in #2:#3#4{%
	#1=#2 %
	\loopcounter{#1}{#3}{#4}%
}

\long\def\loopcounter#1#2#3{%
	#3%
	\ifnum#1=#2 %
	\else%
		\advance#1 by1 %
		\loopcounter{#1}{#2}{#3}%
	\fi%
}
\countingloop{\count0} in 0:{3}{%
	The current value is `\the\count0'\par
}
\end{codeexample}

There are some subtleties to the above example:
\begin{itemize}
 \item We put a lot of \% in the example. Why? Note that whenever \TeX{} scans for a number -- e.\,g. as in the case of |#1=#2| -- it will continue scanning token by token, that is digit by digit, till he is sure that the number has ended, even over white space, and even expanding macros in case they themselves might not represent numbers again. Hence, \% tells \TeX{} to stop scanning. It is generally good practice to place \% to tell \TeX{} to stop scanning for more digits. However, there are some exceptions to it as well: In case of |\advance#1 by1| one should keep a white space in between, as well as in the case of |\ifnum#1=#2|.
 \item We placed the threshold |3| in |\countingloop{\count0} in 0:{3}| in curly brackets. Why? \TeX{} otherwise will recognize only the token |1| if a threshold of e\,g. |10| is given and stumble over the now remnant `extra' argument |0|. That is because a single letter represents a token to \TeX{}. Hence, two letters are two tokens and -- ungrouped -- become two arguments. Here, we have to group the threshold to make clear what we mean.
 \item One last thing becomes clear first when debugging is activated: As loops are done by recursion, i.\,e. by expansion followed by expansion till some threshold is reached, we will end with a lot of |\fi|s in the above case. If we place |\tracingmacros=2 \tracingcommands=2| before the |\countingloop| call and inspect the log file this will become apparent. This is bad because \TeX{} will keep a stack frame open for each |\if|\ldots|\fi| sequence. If we now have a loop over 10.000 items \ldots
 \item It is not good practice to use one of the system counters, here |\count0|, because one can never be sure that is not used for something else or changed somewhere else. E.\,g. when the page is full, \TeX{} will interrupt the current sequence of tokens to deal with creating a new page and finishing the old one, in this course changing |\count0|. Hence, we should also create our own counter.
\end{itemize}

Hence, we modify the example as follows:
\begin{codeexample}[]
\long\def\countingloop#1 in #2:#3#4{%
	#1=#2 %
	\loopcounter{#1}{#3}{#4}%
}

\long\def\loopcounter#1#2#3{%
	#3%
	\ifnum#1=#2 %
		\let\next=\relax%
	\else
		\advance#1 by1 %
		\def\next{\loopcounter{#1}{#2}{#3}}%
	\fi
	\next
}
\newcount\ourcounter

\countingloop{\ourcounter} in 0:{3}{%
	The current value is `\the\ourcounter'\par
}
\end{codeexample}

Principally, nothing has changed in terms of the output. However, notice that we have introduced the macro |\next| which either recurses into the next level -- but after the |\fi| statement has been given -- or ends the recursion by simply containing |\relax|. Also, we have declared a new counter called |\ourcounter| that is safe from harm.

Finally, let us briefly summarize what happens in detail:
\begin{enumerate}
 \item |\countingloop|\ldots is expanded to an assignment |#1=#2| and another macro |\loopcounter|\ldots.
 \item The assignment is done: |\ourcounter| is set to the starting value |0|.
 \item\label{countingloop:loopstart} The actual loop macro is expanded to the command block -- printing the current value -- and an if statement.
 \item The current value is printed.
 \item |\ourcounter| is compared to the threshold |3| and \ldots
 \begin{itemize}
	 \item False, i.\,e. the if statement is expanded to an |\advance| statement followed by defining |\next| to be another call of the same macro loop.
	 \item True, i.\,e. |\next| is set to be just |\relax|.
 \end{itemize}
 \item The statement is still false: |\advance| will increase |\ourcounter| by one, it is now |1|. |\next| is set to the loop macro.
 \item The loop macro is again expanded, go to step~\ref{countingloop:loopstart}. |\ourcounter| is \ldots |2| \ldots |\ourcounter| is |3|.
 \item Now the statement is true: |\next| is expanded to |\relax| and nothing happens.
\end{enumerate}

\subsubsection{Loops over list of items}
\label{sec:loops:over:list:of:items}
Looping over a list of items is very similar, only we will need |\ifx| in place of |\ifnum| and we need some end marker instead of the threshold value. However, how do we specify the list itself? Let's make some comma-separated list, e.\,g. |{a,b,c,d}| and call the end marker |\listingloopENDMARKER|.

\begin{codeexample}[]
\def\listingloopENDMARKER{\par \listingloopENDMARKER}
\long\def\listingloop#1in#2#3{%
	\looppicker{#1}{#3}#2,\listingloopENDMARKER,%
}%
\long\def\looppicker#1#2#3,{%
	\def\tempitem{#3}%
	\ifx\tempitem\listingloopENDMARKER
		\let\next=\relax%
	\else
		\def#1{#3}%
		#2%
		\def\next{\looppicker{#1}{#2}}%
	\fi
	\next
}%
\listingloop\x in{a,b,c,,d,e}{%
	The current item is `\x'
}
\end{codeexample}

Again, we make clear the subtleties contained therein:
\begin{itemize}
 \item We have defined |\listingloopENDMARKER| to replace itself. This is possible because |\ifx| will only compare first-level expansion, see Section~\ref{sec:branching}.
 \item We seem to miss a white space in \ldots|#1in#2|\ldots. However, tokens are always ending with an additional white space as |\xin| is not equal to |\x in|. Hence, none is needed here and more than one white space would probably get gobbled.
 \item The definition |\looppicker#1#2#3,|\ldots has three arguments but the recursive call |\looppicker{#1}{#2}| only gives two arguments!? This is the actual magic making this type of list possible! \TeX{} is actually scanning beyond the scope of the given token to obtain the third argument. In effect, we are biting off piece by piece, list item by list item off the given list. All because we have stated an additional |,| -- comma being the item separator -- in the definition of the |\looppicker| macro. The expansion of the loop macro will always pick up one more item from the list concatenated to its end until it has reached the |\ENDMARKER|. This is added to the list's very end on the loop's start, and there it stops.
\end{itemize}

\subsection{More On \TeX}
This document is far from complete. I recommend reading about conditional expressions in \cite{schwartz} (German, online version) or \cite{texbook} (bounded book). Hints about loops can be found in the manual of \PGFPlots, \cite{pgfplots} and the manual of \PGF, \cite{tikz}. Moreover, \PGFPlots\ and \PGF\ come with a whole lot of utility functions which are documented in the source |.code.tex| files.

\section{Survey of Key--Value Handling using \PGF Keys}

One of the most important things for every \TeX\ package is key--value input. There is a good overview and survey over different key--value packages, among them |xkeyval| and |pgfkeys|, in~\cite{keyvalintro}. 

In addition to the paper mentioned above and the extensive reference manual for |pdfkeys| in~\cite{tikz}, I give a brief survey over |pgfkeys| here. The addressed audience is primarily package writers or macro programmers. This section should allow you to define your own user interfaces and styles for \PGFPlots\ and for \PGF. It should also improve the understanding of |pgfkeys| and how it is to be used. I also address the topic of key filtering which is mainly useful for package writers.

The package |pgfkeys| is available as stand--alone package |\usepackage{pgfkeys}|. However, I believe that you never need to load it explicitly as \PGF\ will be loaded anyway and \PGF\ always loads |pgfkeys|.

It comes with two user interfaces. I believe that it is a best--practice to use the best of both worlds; although it might be sufficient to use just one of them. Consequently, I discuss both of them and propose a best--practices afterwards.

\subsection{The Low--Level (Direct) \API\ of \PGF Keys}
Let us start with the low--level \API\ of \PGF Keys. It consists of a couple of macros which allow to define keys, assign values, and get their values back.

\begin{command}{\pgfkeyssetvalue\marg{/key path/key name}\marg{value}}
	This macro (re)defines a key. 
	
	It is (almost) equivalent to a macro definition of sorts

|\expandafter\def\csname key@|\meta{/key path/key name}|\endcsname|\marg{value};

	i.e.\ it stores \meta{value} into a new macro such that the key can be looked up in constant time in \TeX's hash map. 
	Note that in contrast to other key--value packages like |xkeyval|, the low--level macro name which is used to store the value is \emph{not} part of the \PGF Keys \API\footnote{Note that \texttt{key@} is unrelated to \PGF Keys.} -- use |\pgfkeysgetvalue| and its friends to access the value.

	The only limit for the number of possible keys is the size of \TeX's hash map (which is very large).

	You may have wondered what the slash `|/|' means. Users which are accustomed to \PGF/\PGFPlots\ know that there exists some kind of ``key path'' which qualifies \meta{key name}. The \meta{key path} has the purpose of providing a name space such that many many keys with the same name can exist piecefully without ever touching another -- provided the correct \meta{key path} has been used. It can be seen as a (unix) file path: you can have many files with the same name, provided the files reside in different directories (i.e.\ have different paths).

	You should \emph{always} provide a key path, and it is highly recommended to use a different key path than just `|/|'.

	The \meta{value} can be anything; it is just stored. It can even contain |#|.
\end{command}

\begin{command}{\pgfkeysgetvalue\marg{/key path/key name}\marg{\textbackslash macro}}
	As you might have guessed, this macro allows to retrieve the value for some key and store it into \meta{\textbackslash macro}.

	Now that we have read about |\pgfkeyssetvalue| and |\pgfkeysgetvalue|, we can also provide an example:
\begin{codeexample}[]
\pgfkeyssetvalue{/notes/key}{abc}

\pgfkeysgetvalue{/notes/key}\temp 

The value of key \texttt{/notes/key} is `\temp'.
\end{codeexample}

	There is few magic around these two keys; it is just like a hashmap access with some special naming convention for the keys (due to the key path). Note that since ``hashmap access'' is what \TeX\ does all the time when it handles macros, we could have replaced the pair |\pgfkeyssetvalue|/|\pgfkeysgetvalue| by |\def| and suitable |\let| commands, perhaps combined with |\csname...\endcsname|. The advantage of \PGF Keys comes into play as soon as we inspect the high--level user interface in the next section.

	Note that since |\pgfkeyssetvalue| is essentially the same as a suitable |\def|, the assignment is local to the current \TeX\ group. In other words: the assignment will be undone by the next closing curly brace, or the next |\endgroup|, or the next |\end|\marg{environment}.
\end{command}

\begin{command}{\pgfkeyslet\marg{/key path/key name}\marg{\textbackslash macro}}
	This is essentially the same as |\pgfkeyssetvalue|, except that the key's value is already available inside of \meta{\textbackslash macro}:

\begin{codeexample}[]
\def\something{abc}
\pgfkeyslet{/notes/key}{\something}

\pgfkeysgetvalue{/notes/key}\temp 

The value of key \texttt{/notes/key} is `\temp'.
\end{codeexample}
	
	Just like |\pgfkeyssetvalue| boils down to |\def|, |\pgfkeyslet| boils down to |\let|.
\end{command}

\begin{command}{\pgfkeysvalueof\marg{/key path/key name}}
	This is essentially the same as |\pgfkeysgetvalue|\marg{/key path/key name}\marg{\textbackslash macro} \meta{\textbackslash macro}; i.e.\ it expands to the value stored in a key.
\begin{codeexample}[]
\pgfkeyssetvalue{/notes/key}{abc}

The value of key \texttt{/notes/key} is `\pgfkeysvalueof{/notes/key}'.
\end{codeexample}
	
	However, this key has one major advantage: it can be used inside of an |\edef| (because it is fully expandable):
\begin{codeexample}[]
\pgfkeyssetvalue{/notes/key}{abc}

\edef\temp{--- \pgfkeysvalueof{/notes/key} ---}

The value of key \texttt{/notes/key} along with dashes is \temp.
\end{codeexample}
	
	It boils down to a suitable |\csname ... \endcsname|. Consequently, it expands to |\relax| if the key happens to be undefined (see |\pgfkeysifdefined| below).
\end{command}

\begin{command}{\pgfkeysdef\marg{/key path/key name}\marg{macro body}}
	This is a variant of |\pgfkeyssetvalue|. However, it has a substantial difference which appears to be unmotivated as long as we discuss the low--level \API. It defines a so--called code--key.

	Code--keys are executable macros. They take an argument, and they do something with it. ``Assigning values'' to such a key is equivalent to invoking \meta{macro body} in a ``suitable'' way.

	The result of this macro call is a new key named \meta{/key path/key name/}|.@cmd|. That key, in turn, is stored as executable macro. The macro is equivalent to the following definition (up to the name, of course):

	|\def\macro#1\pgfeov|\marg{macro body}.

	This macro is stored (using |\pgfkeyslet|) under \meta{/key path/key name/}|.@cmd|. 

	We can use |\pgfkeysgetvalue| and/or |\pgfkeysvalueof| to access this special key\footnote{Note that the suffix |/.@cmd| is part of the public \API\ of \PGF Keys, so it is no hackery to make use of it.}, even though its use becomes more apparent later in this document: 

\begin{codeexample}[]
\pgfkeysdef{/notes/code key}{Expansion with value #1---X.}%

We ``assign a value'' or ``execute the code key'' (which is equivalent): 
\pgfkeysvalueof{/notes/code key/.@cmd}abc\pgfeov
\end{codeexample}
	Note that in this case, we \emph{have} to use |\pgfeov| to terminate the argument list. We could have placed our argument into curly braces, but we have to provide |\pgfeov|; just as we had to add the suffix |/.@cmd|. 

\end{command}

\begin{commandlist}{%
	\pgfkeysifdefined\marg{/key path/key name}\marg{true case}\marg{false case},
	\pgfkeysifassignable\marg{/key path/key name}\marg{true case}\marg{false case}}
	These keys provide conditionals based on existance or type of a key. Please refer to the reference manual in~\cite{tikz} for details.
\end{commandlist}

\subsection{The Standard \API\ of \PGF Keys}
\begingroup
\pgfkeys{
	/codeexample/newline=,
}
Now that we have seen how things defined by \PGF Keys can be accessed at a rather low level of abstraction, we will repeat the same using a higher level. This section explains the standard \API\ of \PGF Keys; this is how Keys can be defined and maintained easily, and it is also the end user interface.

\PGF Keys addresses a couple of use--cases with its standard API:
\begin{enumerate}
	\item simple key--value storage (i.e.\ put and get),
	\item code--keys which can do some (complex) operation whenever the key is used,
	\item configuration and modification of the key--value tool.
\end{enumerate}
All of these items are possible with the same macro:

\begin{command}{\pgfkeys\marg{comma--separated key--value pairs}}
	This key constitutes the public \API\ of \PGF Keys. It accepts any number of key--value pairs, separated by commas.
\end{command}

We start with an example:
\begin{codeexample}[]
% key definition:
\pgfkeys{
	/notes/key/.initial=abc,
}

The value of key \texttt{/notes/key} is `\pgfkeysvalueof{/notes/key}'.

% key usage:
\pgfkeys{
	/notes/key =  efg  ,
}

The value of key \texttt{/notes/key} is `\pgfkeysvalueof{/notes/key}'.
\end{codeexample}

There are some items which appear to be clear, and I will briefly confirm that it really is clear: white spaces before and after the key name and before and after the value are stripped away. Furthermore, trailing commas are ignored. Note that trailing commas are a best--practice: always insert trailing commas. This simplifies the addition of further keys significantly (I can't remember how often I added a key and wondered why it was not properly recognised until I found the missing comma). Just add the trailing comma as a habit. Another good practice is to indent code properly, i.e.\ to insert a tab stop for every new line. It is also a good idea to provide one key per line, although all that stuff is optional.

The first thing which is strange when inspecting the actual code is the suffix `|/.initial|'. This is, in fact, a consistent new system of \PGF Keys: these suffixes allow to configure and modify the keys to which them apply. They are called ``key handlers''. Whenever you encounter \meta{key path/key name} followed by `|/.|\meta{handler}', you can safely assume that \meta{key path/key name} is about to be reconfigured or modified.

Knowledge of key handlers means control over \PGF Keys. In the following, I will briefly discuss the most important handlers. 

\begin{handler}{{.initial}=\marg{value}}
	The key handler |/.initial| defines a new \meta{key} and assigns its initial \meta{value}.

	As such, it is equivalent to |\pgfkeyssetvalue|\marg{key}\marg{value}.

	That a key which has been defined by means of |/.initial| can be set at any time later using a simple value assignment (see the example above).

	Consequently, the first definition needs the suffix, all following assignments need to assignment to set the value.
\end{handler}

\begin{handler}{{.code}=\marg{body}}
	This key handler defines a new code--key \meta{key} with \meta{body} as result.
\begin{codeexample}[]
\pgfkeys{
	/notes/code key/.code={Expansion with value #1---X.},
}%

Execute the key using the simple API:
\pgfkeysvalueof{/notes/code key/.@cmd}abc\pgfeov

... execute the key using assignment in the standard API:
\pgfkeys{/notes/code key=abc}
\end{codeexample}
	We see that assignment of a code key means to executing \meta{body} where |#1| is set to the value assigned in the \API.

	A key defined by means of |/.code| is equivalent to one defined by means of |\pgfkeysdef|.

	Note that the argument \meta{body} can be surrounded by curly braces, but it does not need to be:
\begin{codeexample}[code only]
\pgfkeys{
	/notes/code key/.code={Expansion with value #1---X.},
	/notes/code key/.code=Expansion with value #1---X.,
}%
\end{codeexample}
	This is a common feature of \PGF Keys: any kind of value assignment can use braces, but it does not need to. You only need to use curly braces if the assigned argument (in our \meta{body}) contains control characters of \PGF Keys (i.e.\ |=| or |,|).
\end{handler}

\begin{handler}{{.style}=\marg{option list}}
	This key handler defines a new code--key \meta{key} which sets all options in \meta{option list} whenever it is assigned (used).

	Styles are defined in a simple way: they simply invoke |\pgfkeys| with \meta{option list} (well, almost -- see below). However, they are very expressive in any kind of application.

\begin{codeexample}[]
\pgfkeys{
	/notes/A/.initial=,
	/notes/B/.initial=,
	/notes/my style/.style={
		/notes/A={#1},
		/notes/B={#1},
	},
}%

Definition has been done. Assigning the style: 
\pgfkeys{
	/notes/my style=42
}
OK. Value of A=\pgfkeysvalueof{/notes/A}, value of B=\pgfkeysvalueof{/notes/B}.
\end{codeexample}
	Our example is a very simple application of a style: it sets a bunch of other options.

	Note that \meta{option list} can depend on |#1|. 

	So far, this document did always provide fully qualified key paths. However |/.style| explicitly supports the notion of a ``current key path'': if a ``current key path'' is in effect, \meta{option list} will be set in a context which also makes use of the same current key path. Technically, this means that |/.style| uses |\pgfkeysalso| to set \meta{option list}, i.e. it does not use |\pgfkeys| as claimed above.

\end{handler}

\begin{command}{\pgfkeysalso\marg{comma--separated key--value pairs}}
	This macro is \emph{almost} the same as |\pgfkeys|\marg{comma--separated key--value pairs}. In fact, if any assignments in its argument use fully--qualified paths (as we did so far in this document), both invocations are equivalent.

	The difference is how they treat keys which are \emph{relative} to some current key path, a concept which will be explained in the next subsection.

	Here is the difference between the macros: |\pgfkeys| resets the current key path to |/| before processing its argument whereas |\pgfkeysalso| does not change the current key path. Consequently, |\pgfkeysalso| is only useful inside of the body of some code--key (like |/.style|).
\end{command}

\subsubsection{The Current Key Path}
tbd

\subsubsection{Key Filtering}
tbd

\endgroup


%\subsection{Conditional Expressions}

%\subsection{Loops}

%\subsection{The Problem of Macro--Append Runtime}

%\section{Utility Functions of \PGF}

%\section{Utility Function of \PGFPlots}

\section{Special Tricks}

\subsection{Handling \# in Arguments}
More than once, I encountered the following difficulty: I wanted to collect an argument which contains the hash sign, `|#|'. That's not particularly difficult, but it can lead to a lot of strange error messages when the resulting argument shall be processed! Consider 
\begin{codeexample}[code only]
\def\collectargument#1{%
	\def\collectedcontent{#1}%
	\ifx\collectedcontent\empty
		It is empty.
	\else
		It is not empty, executing it: #1.
	\fi
}%

\collectargument{}% works

\collectargument{something}% works

\collectargument{% does not work!
	\def\something#1{which depends on #1}
}%
\end{codeexample}
The code in this example is relatively simple: the |\collectargument| macro expects one argument and checks if it is empty (using |\ifx|, which is a common and reliable check for emptiness). It is is not empty, it executes it. The |\collectargument| macro works in most circumstances. More precisely: it works as long as there is \emph{no} hash sign in its argument! In our example, the third call fails with ``Illegal parameter number in definition of |\collectedcontent|.'' which occurs during the |\def\collectedcontent{#1}| line (and \TeX\ has reasons for this message due to the special meaning of the parameter expansion).

The cure: redefine the |\collectargument| macro using
\begin{codeexample}[code only]
\def\collectargument#1{%
	\toks0={#1}%
	\edef\collectedcontent{\the\toks0}%
	\ifx\collectedcontent\empty
		It is empty.
	\else
		It is not empty, executing it: #1.
	\fi
}%

\end{codeexample}
\noindent (you may want to allocate a temporary token register for this task). What is the difference? Well, the |\toks0={#1}| assignment introduces no special meaning for the hash sign |#|, and |\the\toks0| neither. Note, however, that this requires |\edef\collectedcontent| instead of |\def\collectedcontent| since the |\the| statement needs to be expanded. Everything works as expected.

\printindex

\bibliographystyle{abbrv} %gerapali} %gerabbrv} %gerunsrt.bst} %gerabbrv}% gerplain}
\nocite{schwartz}
\nocite{pgfplots}
\bibliography{pgfplots}
\end{document}
