Debian Codegraph @

texmf-dist/doc/latex/pgfkeysearch/pgfkeysearch.tex

raw
1 %%%==============================================================================
2 % WinEdt pragmas
3 % !Mode:: "TeX:EN"
4 % Default Compile engines:
5 % !TEX program = pdflatex
6 % !PDFTeXify ext = --enable-etex --restrict-write18
7 % !PDFLaTeX ext = --enable-etex --restrict-write18
8 % !BIB program = none
9 %%%==============================================================================
10 %% Copyright 2023 by Alceu Frigeri
11 %%
12 %% This work may be distributed and/or modified under the conditions of
13 %%
14 %% * The [LaTeX Project Public License](http://www.latex-project.org/lppl.txt),
15 %% version 1.3c (or later), and/or
16 %% * The [GNU Affero General Public License](https://www.gnu.org/licenses/agpl-3.0.html),
17 %% version 3 (or later)
18 %%
19 %% This work has the LPPL maintenance status *maintained*.
20 %%
21 %% The Current Maintainer of this work is Alceu Frigeri
22 %%
23 %% This is version {1.5} {2025/11/06}
24 %%
25 %% The list of files that compose this work can be found in the README.md file at
26 %% https://ctan.org/pkg/pgfkeysearch
27 %%
28 %%%==============================================================================
29 \documentclass[10pt]{article}
30 \RequirePackage[verbose,a4paper,marginparwidth=27.5mm,top=2.5cm,bottom=1.5cm,hmargin={40mm,20mm},marginparsep=2.5mm,columnsep=10mm,asymmetric]{geometry}
31 \usepackage[T1]{fontenc}
32 \usepackage[utf8]{inputenc}
33 \usepackage{lmodern}
34 \usepackage[infograb]{codedescribe}
35 \usepackage[root search]{pgfkeysearch}
36 \RequirePackage[inline]{enumitem}
37 \SetEnumitemKey{miditemsep}{parsep=0ex,itemsep=0.4ex}
38
39 \RequirePackage{pgfkeys}
40
41
42 \RequirePackage[hidelinks,hypertexnames=false]{hyperref}
43 \begin{document}
44 \tstitle{
45 author={Alceu Frigeri\footnote{\tsverb{https://github.com/alceu-frigeri/pgfkeysearch}}},
46 date={\tsdate},
47 title={The pgfkeysearch Package\break A Search Extension for pgfkeys\break Version \PkgInfo{pgfkeysearch}{version}}
48 }
49
50 \begin{typesetabstract}
51
52 The command \tsobj{\pgfkeysvalueof}, unlike \tsobj{\pgfkeys} command, doesn't use the \tsobj[keys]{.unknown} handler or offers the option to search for a key in other paths, and raises an error if the key isn't defined in the given path.
53
54 The following commands will recursively search for a key in a collection of paths.
55 \end{typesetabstract}
56
57 \tableofcontents
58
59 \section{Package Options}\label{Pack-Options}
60 The default search behaviour assumes that all keys defined by a package or document are under a uniquely defined path, meaning, no root keys. For instance, given the path /A/B/C/D, the following commands will look, first, at /A/B/C/D/\tsobj[marg]{key}, then /A/B/C/\tsobj[marg]{key}, and so on, until /A/\tsobj[marg]{key}, stopping at the first hit. This can be changed with the \tsobj[option]{root search} package option.
61
62 By default, the value stored in a \tsobj[pkg]{pgfkey} key will be recovered, but, with the option \tsobj[option]{key=macro} a macro will be returned, such that, later changes to the searched key (with \tsobj[pkg]{pgfkey}) will be reflected by the recovered macro, the recovered macro will, effectively, be an alias for it.
63
64 Lastly, if a key isn't found, the returning macro will always be cleared up (\tsobj[option]{settings=new}), but, with \tsobj[option]{settings=old}, the \tsobj[pkg]{expl3} commands (see \ref{expl-ones}) won't clear up the returning macro (old/original behaviour of this package).
65 \begin{describelist*}{keys}
66 \describe{root search}{(default: false) If set, the \emph{path root} will also be included in the search, meaning it will look if /\tsobj[marg]{key}, as last resort, is defined.}
67 \describe{key}{(default: \tsobj[option]{value}. Possible values: \tsobj[option,sep=or]{value,macro}. As said, the default behaviour is to recover the value stored in a \tsobj[pkg]{pgfkey}. With \tsobj[option]{key=macro}, a macro ``pointing to'' the \tsobj[pkg]{pgfkey} will be recovered.}
68 \describe{settings}{(default: \tsobj[option]{new}). Possible values: \tsobj[option,sep=or]{old,new}. If set to \tsobj[option]{old}, this will revert to the original \tsobj[pkg]{expl3} behaviour, whereas if the key wasn't found, the returning variable won't be cleared up (no assignment taking place).}
69 \end{describelist*}
70 \begin{tsremark}
71 With \tsobj[option]{root search} set, the root key (/\tsobj[marg]{key}) will be look at for every path in the path list. For instance \tsobj[verb]{\pgfkeysearch{/A/B/C,/X/Y,/Z/T}{key}}, /\tsobj[marg]{key} (at the root) will be tried up to three times.
72 \end{tsremark}
73
74
75
76 \section{User Document Commands}\label{Doc-level}
77 Those commands are meant to be used at Document level. For packages, one is advised to use the ones defined at \ref{expl-ones}.
78
79 \begin{codedescribe}[code,new=2025/05/27]{\pgfkeysearchsettings}
80 \begin{codesyntax}%
81 \tsmacro{\pgfkeysearchsettings}{options}
82 \end{codesyntax}
83 To change the search behaviour, middle document. \tsobj[marg]{options} can be any package option (see \ref{Pack-Options}).
84 \end{codedescribe}
85
86
87
88 \begin{codedescribe}[code,new=2025/11/03]{\pgfkeygetvalueof,\pgfkeyget,\pgfkeygetvalueofTF,\pgfkeygetTF}
89 \begin{codesyntax}%
90 \tsmacro{\pgfkeygetvalueof}{single-path,key,macro}
91 \tsmacro{\pgfkeyget}{single-path,key,macro}
92 \tsmacro{\pgfkeygetvalueofTF}{single-path,key,macro,if-found,if-not}
93 \tsmacro{\pgfkeygetTF}{single-path,key,macro,if-found,if-not}
94 \end{codesyntax}
95 Those are ``non searching'' variants (faster than the searching variants), whereas \tsobj[marg]{single-path} is the single location/path to be looked at. \tsobj[marg]{key} is the desired key, and \tsobj[marg]{macro} is the macro/command that will receive (store) the key value (if one is found). \tsobj[marg]{macro} will be set with the found (if any) value.
96
97 \end{codedescribe}
98 \begin{tsremark}
99 If \tsobj[option]{key=value}, then the key value will be recovered. Otherwise, if \tsobj[option]{key=macro} then \tsobj[marg]{macro} will ``point to'' (\tsobj[pkg]{pgfkey}) key.
100 \end{tsremark}
101 \begin{tsremark}
102 \tsobj{\pgfkeykeg,\pgfkeygetvalueof} are aliases to each other. Same for \tsobj{\pgfkeygetTF,\pgfkeygetvalueofTF}
103 \end{tsremark}
104 \begin{tsremark}
105 Those commands aren't expandable, though, once retrieved, the returning macro can be used in an expandable context.
106 \end{tsremark}
107 \begin{tsremark}
108 If \tsobj[marg]{key} isn't found, \tsobj[marg]{macro} will be empty, no warning or error will be raised.
109 \end{tsremark}
110
111
112
113 \begin{codedescribe}[code,update=2024/01/11]{\pgfkeysearch,\pgfkeysearchvalueof,\pgfkeysearchTF,\pgfkeysearchvalueofTF}
114 \begin{codesyntax}%
115 \tsmacro{\pgfkeysearch}{path-list,key,macro}
116 \tsmacro{\pgfkeysearchvalueof}{path-list,key,macro}
117 \tsmacro{\pgfkeysearchTF}{path-list,key,macro,if-found,if-not}
118 \tsmacro{\pgfkeysearchvalueofTF}{path-list,key,macro,if-found,if-not}
119 \end{codesyntax}
120 \tsobj[marg]{path-list} is a comma separated list (clist) of paths (can be a single one). \tsobj[marg]{key} is the desired key, and \tsobj[marg]{macro} is the macro/command that will receive (store) the key value (if one is found).
121
122 \tsobj[marg]{key} will be searched for in the many paths from \tsobj[marg]{path-list} as described in \ref{Pack-Options}. \tsobj[marg]{macro} will be set with the found (if any) value.
123 The branch versions will also execute either \tsobj[marg,sep={or}]{if-found,if-not}.
124
125 \end{codedescribe}
126 \begin{tsremark}
127 If \tsobj[option]{key=value}, then the key value will be recovered. Otherwise, if \tsobj[option]{key=macro} then \tsobj[marg]{macro} will ``point to'' (\tsobj[pkg]{pgfkey}) key.
128 \end{tsremark}
129
130 \begin{tsremark}
131 \tsobj{\pgfkeysearch,\pgfkeysearchvalueof} are aliases to each other. Same with \tsobj{\pgfkeysearchvalueofTF,\pgfkeysearchTF}.
132 \end{tsremark}
133 \begin{tsremark}
134 Those commands aren't expandable, though, once retrieved, the returning macro can be used in an expandable context.
135 \end{tsremark}
136 \begin{tsremark}
137 If \tsobj[marg]{key} isn't found, \tsobj[marg]{macro} will be empty, no warning or error will be raised.
138 \end{tsremark}
139
140
141
142 \begin{codestore}[keyval.demo]
143 \pgfkeys{%
144 /tikz/A/.cd,
145 keyA/.initial={keyA at /tikz/A},
146 keyB/.initial={keyB at /tikz/A},
147 %
148 B/.cd,
149 keyA/.initial={keyA at /tikz/A/B},
150 keyC/.initial={keyC at /tikz/A/B},
151 %
152 C/.cd,
153 keyX/.initial={keyX at /tikz/A/B/C}
154 }
155 \end{codestore}
156
157 \begin{codestore}[keyval.demo]
158 \pgfkeysearch{/tikz/X,/tikz/A/B/C}{keyA}{\VALkeyA}
159 \pgfkeysearch{/tikz/X/Y,/tikz/A/B/C}{keyB}{\VALkeyB}
160 \pgfkeysearch{/tikz/X/Y,/tikz/Y/Y,/tikz/A/B/C}{keyC}{\VALkeyC}
161 \pgfkeysearch{/tikz/X/Y,/tikz/Y/Y,/tikz/A/B/C}{keyX}{\VALkeyX}
162 \end{codestore}
163
164
165 \begin{codestore}[keyval.demo]
166 I got for keyA: \textbf{\VALkeyA} \par
167 I got for keyB: \textbf{\VALkeyB} \par
168 I got for keyC: \textbf{\VALkeyC} \par
169 I got for keyX: \textbf{\VALkeyX} \par
170 \end{codestore}
171
172
173
174 \setnewcodekey{keydemo}{codeprefix={},resultprefix={},texcs2={pgfkeysearchvalueof,pgfkeysearch},keywd3={keyA,keyB,keyC,keyX},emph2={VALkeyA,VALkeyB,VALkeyC,VALkeyX}}
175
176
177 \subsection{Example}
178 Given the following pgfkeys:
179
180 \tscode*[keydemo]{keyval.demo}[1]
181 \tsexec{keyval.demo}[1]
182
183 \newpage
184 Key values can be retrieved and used as:
185
186 \tsexec{keyval.demo}[2]
187 \tscode*[keydemo]{keyval.demo}[2]
188
189
190 \tsdemo[keydemo]{keyval.demo}[3]
191
192
193 \section{Expl3 Commands}\label{expl-ones}
194
195
196 \begin{tsremark}[Deprecation:]
197 A warning will be raised if either \tsobj{\pgfkeysearch_keysearch:nnnTF} or \tsobj{\pgfkeysearch_multipath_keysearch:nnnTF} are used.
198 \end{tsremark}
199
200 \begin{codedescribe}[code,new=2025/05/27]{\pgfkeysearch_settings:n}
201 \begin{codesyntax}%
202 \tsmacro{\pgfkeysearch_settings:n}{options}
203 \end{codesyntax}
204 To change the search behaviour, middle document. \tsobj[marg]{options} can be any package option (see \ref{Pack-Options}).
205
206 \end{codedescribe}
207
208
209 \begin{codedescribe}[code,new=2025/11/03]{\pgfkeysearch_keyget:nnN,\pgfkeysearch_keyget:nnNTF}
210 \begin{codesyntax}%
211 \tsmacro{\pgfkeysearch_keyget:nnN}{single-path,key,tl-var}
212 \tsmacro{\pgfkeysearch_keyget:nnNTF}{single-path,key,tl-var,if-found,if-not}
213 \end{codesyntax}
214 \tsobj[marg]{key} is the desired key, and \tsobj[marg]{tl-var} is a token list variable that will receive the key value, if one is found.
215 \tsobj[marg]{key} will be looked at \tsobj[marg]{single-path} \textsl{only}.
216
217 \tsobj{\pgfkeysearch_keyget:} is faster than the search variants.
218 \end{codedescribe}
219
220 \begin{tsremark}
221 If \tsobj[marg]{key} isn't found \tsobj[marg]{tl-var} will be cleared up (new default). But, with option \tsobj[option]{settings=old} \tsobj[marg]{tl-var} will preserve whatever value it had, no assignment will be made. In both cases, no warning or error will be raised.
222 \end{tsremark}
223 \begin{tsremark}
224 If \tsobj[option]{key=value}, then the key value will be recovered. Otherwise, if \tsobj[option]{key=macro} then \tsobj[marg]{macro} will ``point to'' (\tsobj[pkg]{pgfkey}) key.
225 \end{tsremark}
226
227
228 \begin{codedescribe}[code,update=2025/05/26,update=2025/11/03]{\pgfkeysearch_keysearch:nnN,\pgfkeysearch_keysearch:nnNTF}
229 \begin{codesyntax}%
230 \tsmacro{\pgfkeysearch_keysearch:nnN}{single-path,key,tl-var}
231 \tsmacro{\pgfkeysearch_keysearch:nnNTF}{single-path,key,tl-var,if-found,if-not}
232 \end{codesyntax}
233 \tsobj[marg]{key} is the desired key, and \tsobj[marg]{tl-var} is a token list variable that will receive the key value, if one is found.
234 \tsobj[marg]{key} will be searched for in \tsobj[marg]{single-path} as described in \ref{Pack-Options}.
235
236 \tsobj{\pgfkeysearch_keysearch:nnNTF} is slightly faster than the more generic multi-path version.
237 \end{codedescribe}
238
239 \begin{tsremark}
240 If \tsobj[marg]{key} isn't found \tsobj[marg]{tl-var} will be cleared up (new default). But, with option \tsobj[option]{settings=old} \tsobj[marg]{tl-var} will preserve whatever value it had, no assignment will be made. In both cases, no warning or error will be raised.
241 \end{tsremark}
242 \begin{tsremark}
243 If \tsobj[option]{key=value}, then the key value will be recovered. Otherwise, if \tsobj[option]{key=macro} then \tsobj[marg]{macro} will ``point to'' (\tsobj[pkg]{pgfkey}) key.
244 \end{tsremark}
245
246
247 \begin{codedescribe}[code,update=2025/05/26,update=2025/11/03]{\pgfkeysearch_multipath_keysearch:nnN,\pgfkeysearch_multipath_keysearch:nnNTF}
248 \begin{codesyntax}%
249 \tsmacro{\pgfkeysearch_multipath_keysearch:nnN}{path-list,key,tl-var}
250 \tsmacro{\pgfkeysearch_multipath_keysearch:nnNTF}{path-list,key,tl-var,if-found,if-not}
251 \end{codesyntax}
252 Given a comma separated \tsobj[marg]{path-list}, this will call \tsobj{\pgfkeysearch_keysearch:nnNTF} for each path in \tsobj[marg]{path-list}, until \tsobj[marg]{key} is found.
253 \end{codedescribe}
254
255 \begin{tsremark}
256 If \tsobj[marg]{key} isn't found \tsobj[marg]{tl-var} will be cleared up (new default). But, with option \tsobj[option]{settings=old} \tsobj[marg]{tl-var} will preserve whatever value it had, no assignment will be made. In both cases, no warning or error will be raised.
257 \end{tsremark}
258 \begin{tsremark}
259 The document level commands (in \ref{Doc-level}) are just wrappers to this command.
260 \end{tsremark}
261 \begin{tsremark}
262 If \tsobj[option]{key=value}, then the key value will be recovered. Otherwise, if \tsobj[option]{key=macro} then \tsobj[marg]{macro} will ``point to'' (\tsobj[pkg]{pgfkey}) key.
263 \end{tsremark}
264
265 \end{document}