| 1 |
% Copyright 2018 by Christian Feuersaenger |
| 2 |
% |
| 3 |
% This file may be distributed and/or modified |
| 4 |
% |
| 5 |
% 1. under the LaTeX Project Public License and/or |
| 6 |
% 2. under the GNU Free Documentation License. |
| 7 |
% |
| 8 |
% See the file doc/generic/pgf/licenses/LICENSE for more details. |
| 9 |
|
| 10 |
|
| 11 |
\section{Adding libraries to \pgfname: temporary registers} |
| 12 |
\label{section-internal-registers} |
| 13 |
|
| 14 |
This section is intended for those who like to write libraries to extend |
| 15 |
\pgfname. Of course, this requires a good deal of knowledge about |
| 16 |
\TeX-programming and the structure of the \pgfname\ basic layer. Besides, one |
| 17 |
will encounter the need of temporary variables and, especially, temporary \TeX\ |
| 18 |
registers. This section describes how to use a set of pre-allocated temporary |
| 19 |
registers of the basic layer without needing to allocate more of them. |
| 20 |
|
| 21 |
A part of these internals are already mentioned in |
| 22 |
section~\ref{section-internal-pointcmds}, but the basic layer provides more |
| 23 |
temporaries than |\pgf@x| and |\pgf@y|. |
| 24 |
|
| 25 |
\begin{internallist}[dimen register]{\pgf@x,\pgf@y} |
| 26 |
These registers are used to process point coordinates in the basic layer of |
| 27 |
\pgfname, see section~\ref{section-internal-pointcmds}. After a |
| 28 |
|\pgfpoint|$\dotsc$ command, they contain the final $x$ and $y$ coordinate, |
| 29 |
respectively. |
| 30 |
|
| 31 |
The values of |\pgf@x| and |\pgf@y| are set \emph{globally} in contrast to |
| 32 |
other available \pgfname\ registers. You should never assume anything about |
| 33 |
their value unless the context defines them explicitly. |
| 34 |
|
| 35 |
Please prefer the |\pgf@xa|, |\pgf@xb|, $\dotsc$ registers for temporary |
| 36 |
dimen registers unless you are writing point coordinate commands. |
| 37 |
\end{internallist} |
| 38 |
|
| 39 |
\begin{internallist}[dimen register]{ |
| 40 |
\pgf@xa, |
| 41 |
\pgf@xb, |
| 42 |
\pgf@xc, |
| 43 |
\pgf@ya, |
| 44 |
\pgf@yb, |
| 45 |
\pgf@yc% |
| 46 |
} |
| 47 |
Temporary registers for \TeX\ dimensions which can be modified freely. Just |
| 48 |
make sure changes occur only within \TeX\ groups. |
| 49 |
|
| 50 |
\paragraph{Attention:} |
| 51 |
% |
| 52 |
\pgfname\ uses these registers to perform path operations. For reasons of |
| 53 |
efficiency, path commands do not always guard them. As a consequence, the |
| 54 |
code |
| 55 |
% |
| 56 |
\begin{codeexample}[code only] |
| 57 |
\pgfpointadd{\pgfpoint{\pgf@xa}{\pgf@ya}}{\pgfpoint{\pgf@xb}{\pgf@yb}} |
| 58 |
\end{codeexample} |
| 59 |
% |
| 60 |
\noindent may fail: Inside |\pgfpointadd|, the |\pgf@xa| and friend |
| 61 |
registers might be modified. In particular, it might happen that |\pgf@xb| |
| 62 |
is changed before |\pgfpoint{\pgf@xb}{\pgf@yb}| is evaluated. The right |
| 63 |
thing to do would be to first expand everything using |\edef| and process |
| 64 |
the values afterwards, resulting in unnecessary expensive operations. Of |
| 65 |
course, one can avoid this by simply looking into the source code of |
| 66 |
|\pgfpointadd| to see which registers are used. |
| 67 |
\end{internallist} |
| 68 |
|
| 69 |
\begin{internallist}[dimen register]{\pgfutil@tempdima,\pgfutil@tempdimb} |
| 70 |
Further multi-purpose temporary dimen registers. For \LaTeX, these |
| 71 |
registers are already allocated as |\@tempdima| and |\@tempdimb| and are |
| 72 |
simply |\let| to the |\pgfutil@|$\dotsc$ names. |
| 73 |
\end{internallist} |
| 74 |
|
| 75 |
\begin{internallist}[count register]{ |
| 76 |
\c@pgf@counta, |
| 77 |
\c@pgf@countb, |
| 78 |
\c@pgf@countc, |
| 79 |
\c@pgf@countd% |
| 80 |
} |
| 81 |
These multiple-purpose count registers are used throughout \pgfname\ to |
| 82 |
perform integer computations. Feel free to use them as well, just make sure |
| 83 |
changes are scoped by local \TeX\ groups. |
| 84 |
\end{internallist} |
| 85 |
|
| 86 |
\begin{internallist}[openout handle]{\w@pgf@writea} |
| 87 |
An |\openout| handle which is used to generate complete output files within |
| 88 |
locally scoped parts of \pgfname\ (for example, to interact with |
| 89 |
|gnuplot|). You should always use |\immediate| in front of output |
| 90 |
operations involving |\w@pgf@writea| and you should always close the file |
| 91 |
before returning from your code. |
| 92 |
% |
| 93 |
\begin{codeexample}[code only] |
| 94 |
\immediate\openout\w@pgf@writea=myfile.dat |
| 95 |
\immediate\write\w@pgf@writea{...}% |
| 96 |
\immediate\write\w@pgf@writea{...}% |
| 97 |
\immediate\closeout\w@pgf@writea% |
| 98 |
\end{codeexample} |
| 99 |
% |
| 100 |
\end{internallist} |
| 101 |
|
| 102 |
\begin{internallist}[openin handle]{\r@pgf@reada} |
| 103 |
An |\openin| handle which is used to read files within locally scoped parts |
| 104 |
of \pgfname, for example to check if a file exists or to read data files. |
| 105 |
You should always use |\immediate| in front of output operations involving |
| 106 |
|\r@pgf@writea| and you should always close the file before returning from |
| 107 |
your code. |
| 108 |
% |
| 109 |
\begin{codeexample}[code only] |
| 110 |
\immediate\openin\r@pgf@reada=myfile.dat |
| 111 |
% do something with \macro |
| 112 |
\ifeof\r@pgf@reada |
| 113 |
% end of file or it doesn't exist |
| 114 |
\else |
| 115 |
% loop or whatever |
| 116 |
\immediate\read\r@pgf@reada to\macro |
| 117 |
... |
| 118 |
\fi |
| 119 |
\immediate\closein\r@pgf@reada |
| 120 |
\end{codeexample} |
| 121 |
% |
| 122 |
\end{internallist} |
| 123 |
|
| 124 |
\begin{internallist}[box]{\pgfutil@tempboxa} |
| 125 |
A box for temporary use inside of local \TeX\ scopes. For \LaTeX, this box |
| 126 |
is the same as the already pre-allocated |\@tempboxa|. |
| 127 |
\end{internallist} |