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