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