path: root/Master/texmf-dist/doc/latex/pgfplots/TeX-programming-notes.tex

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

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

\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 valueable for beginners as a first start with a lot of examples, and it is also valueable 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.
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 |1sp=65536pt|=$2^{16}$|pt|. 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.
\end{command}

\subsubsection{Allocating Registers}

\subsubsection{Using More than 256 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}
\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}


\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 itsself 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 occurance 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 occurance 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 exectute 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 enclosen 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, independant 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, independant 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 occurance 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 unmatches 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 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{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.

%\subsection{Conditional Expressions}

%\subsection{Loops}

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

%\section{Utility Functions of \PGF}

%\section{Utility Function of \PGFPlots}

\printindex

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