Debian Codegraph @

texmf-dist/doc/generic/pgf/pgfmanual-en-base-internalregisters.tex

raw
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}