diff options
author | Norbert Preining <norbert@preining.info> | 2023-01-16 03:03:27 +0000 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2023-01-16 03:03:27 +0000 |
commit | 6f9e1680085e7bb4d258f6f8116369d122e196e1 (patch) | |
tree | 9ac0ecb239240d1d672b188f29c1479de215074b /graphics/pgf/base/doc/text-en/pgfmanual-en-pgfkeysfiltered.tex | |
parent | b8345f39630408bb198e7636381ce4240154ca9b (diff) |
CTAN sync 202301160303
Diffstat (limited to 'graphics/pgf/base/doc/text-en/pgfmanual-en-pgfkeysfiltered.tex')
-rw-r--r-- | graphics/pgf/base/doc/text-en/pgfmanual-en-pgfkeysfiltered.tex | 579 |
1 files changed, 0 insertions, 579 deletions
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-pgfkeysfiltered.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-pgfkeysfiltered.tex deleted file mode 100644 index f0891afd7b..0000000000 --- a/graphics/pgf/base/doc/text-en/pgfmanual-en-pgfkeysfiltered.tex +++ /dev/null @@ -1,579 +0,0 @@ - -\subsection{Key Filtering} -\begingroup - -{\small \emph{An extension by Christian Feuersänger}} -\vspace{0.4cm}% - -\noindent Normally, a call to |\pgfkeys| sets all keys provided in its argument -list. This is usually what users expect it to do. However, implementations of -different packages or \pgfname-libraries may need more control over the key -setting procedure: library~A may want to set its options directly and -communicate all remaining ones to library~B. - -This section describes key filtering methods of \pgfname, including options for -family groupings. If you merely want to use \pgfname\ (or its libraries), you -can skip this section. It is addressed to package (or library) authors. - - -\subsubsection{Starting With An Example} -\label{section-key-filter-example} - -Users of |xkeyval| are familiar with the concept of key families: keys belong -to groups and those keys can be `filtered' out of other options. \pgfname\ -supports family groupings and more abstract key selection mechanism with -|\pgfkeysfiltered|, a variant of |\pgfkeys|. Suppose we have the example key -grouping - -\begin{codeexample}[setup code,hidden] -\pgfkeys{ - /my group/A1/.code=(A1:#1), - /my group/A2/.code=(A2:#1), - /my group/A3/.code=(A3:#1), - /my group/B/.code=(B:#1), - /my group/C/.code=(B:#1), - /my group/A/.is family, - /my group/A1/.belongs to family=/my group/A, - /my group/A2/.belongs to family=/my group/A, - /my group/A3/.belongs to family=/my group/A, - /pgf/key filters/active families/.install key filter, - /my group/A/.activate family, -} -\end{codeexample} -% -\begin{codeexample}[code only] -\pgfkeys{ - /my group/A1/.code=(A1:#1), - /my group/A2/.code=(A2:#1), - /my group/A3/.code=(A3:#1), - /my group/B/.code=(B:#1), - /my group/C/.code=(B:#1), -} -\end{codeexample} - -\noindent and we want to set options |A1|, |A2| and |A3| only. A call to -|\pgfkeys| yields -% -\begin{codeexample}[] -\pgfkeys{/my group/A1=a1, /my group/A2=a2, /my group/B=b, /my group/C=c} -\end{codeexample} -% -\noindent because all those command option are processed consecutively. - -Now, let's define a family named |A| which contains |A1|, |A2| and |A3| and set -only family members of |A|. We prepare our key settings with -% -\begin{codeexample}[code only] -\pgfkeys{ - /my group/A/.is family, - /my group/A1/.belongs to family=/my group/A, - /my group/A2/.belongs to family=/my group/A, - /my group/A3/.belongs to family=/my group/A, -} -\end{codeexample} -% -\noindent and -% -\begin{codeexample}[code only] -\pgfkeys{/pgf/key filters/active families/.install key filter} -\end{codeexample} -% -\noindent After this preparation, we can use |\pgfkeysfiltered| with -% -\begin{codeexample}[] -\pgfkeys{/my group/A/.activate family} -\pgfkeysfiltered{/my group/A1=a1, /my group/A2=a2, - /my group/B=b, /my group/C=c} -\end{codeexample} -% -\noindent or -% -\begin{codeexample}[] -\pgfkeys{/my group/A/.activate family} -\pgfkeysfiltered{/my group/A1=a1, /my group/A2=a2, - /my group/B=b, /my group/C=c, /tikz/color=blue, /my group/A3=a3} -\end{codeexample} -% -\noindent to set only keys which belong to an `active' family -- in our case, -only family~|A| was active, so the remaining options have not been processed. -The family processing is quite fast and allows an arbitrary number of active -key families. - -Unprocessed options can be collected into a macro (similar to |xkeyval|'s -|\xkv@rm|), discarded or handled manually. The details of key selection and -family declaration are described in the following sections. - - -\subsubsection{Setting Filters} - -The command |\pgfkeysfiltered| is the main tool to process only selected -options. It works as follows. -% -\begin{command}{\pgfkeysfiltered\marg{key--value-list}} - Processes all options in exactly the same way as - |\pgfkeys|\marg{key--value-list}, but a key filter is considered as soon as - key identification is complete. - - The key filter tells |\pgfkeysfiltered| whether it should continue to apply - the current option (return value is `true') or whether something different - shall be done (filter returns `false'). - - There is exactly one key filter in effect, and it is installed by the - |.install key filter| handler or by |\pgfkeysinstallkeyfilter|. - - If the key filter returns `false', a unique key filter handler gets - control. This handler is installed by the |.install key filter handler| - method and has access to the key's full name, value and (possibly) path. - - Key filtering applies to any (possibly nested) call to |\pgfkeys|, - |\pgfkeysalso|, |\pgfqkeys| and |\pgfqkeysalso| during the evaluation of - \marg{key--value-list}. It does \emph{not} apply to routines like - |\pgfkeyssetvalue| or |\pgfkeysgetvalue|. Furthermore, keys belonging to - |/errors| are always processed. Key filtering routines can't be nested: you - can't combine different key filters automatically. -\end{command} - -\begin{command}{\pgfqkeysfiltered\marg{default-path}\marg{key--value-list}} - A variant of |\pgfkeysfiltered| which uses the `quick' search path setting. - It is the |\pgfqkeys| variant of |\pgfkeysfiltered|, see the documentation - for |\pgfqkeys| for more details. -\end{command} - -\begin{command}{\pgfkeysalsofrom\marg{macro}} - A variant of |\pgfkeysalso| which loads its key list from \marg{macro}. - - It is useful in conjunction with the - |/pgf/key filter handlers/append filtered to=|\meta{macro} handler. - - The following example uses the same settings as in the intro - section~\ref{section-key-filter-example}. - % -\begin{codeexample}[] -\pgfkeys{/pgf/key filter handlers/append filtered to/.install key filter handler=\remainingoptions} -\def\remainingoptions{} -\pgfkeysfiltered{/my group/A1=a1, /my group/A2=a2, - /my group/B=b, /my group/C=c, /tikz/color=blue, /my group/A3=a3} - -Remaining: `\remainingoptions'. -\pgfkeysalsofrom{\remainingoptions} -\end{codeexample} - % -\end{command} - -\begin{command}{\pgfkeysalsofiltered\marg{key--value-list}} - This command works as |\pgfkeysfiltered|, but it does not change the - current default path. See the documentation of |\pgfkeysalso| for more - details. -\end{command} - -\begin{command}{\pgfkeysalsofilteredfrom\marg{macro}} - A variant of |\pgfkeysalsofiltered| which loads its key list from - \marg{macro}. -\end{command} - -\begin{handler}{{.install key filter}|=|\meta{optional arguments}} - This handler installs a key filter. A key filter is a command key which - sets the \TeX-boolean |\ifpgfkeysfiltercontinue|, that means a key with - existing `|/.@cmd|' suffix. A simple example is a key filter which returns - always true: - % -\begin{codeexample}[code only] -\pgfkeys{/foo/bar/true key filter/.code={\pgfkeysfiltercontinuetrue}} -\pgfkeys{/foo/bar/true key filter/.install key filter} -\end{codeexample} - % - If key filters require arguments, they are installed by - |.install key filter| as well. An example is the |/pgf/key filters/equals| - handler: - % -\begin{codeexample}[] -\pgfkeys{/pgf/key filters/equals/.install key filter={/my group/A1}} -\pgfkeysfiltered{/my group/A1=a1, /my group/A2=a2, -/my group/B=b, /my group/C=c, /tikz/color=blue, /my group/A3=a3} -\end{codeexample} - % - If a key filter requires more than one argument, you need to provide the - complete argument list in braces like |{{first}{second}}|. - - You can also use |\pgfkeysinstallkeyfilter|\meta{full key}\meta{optional - arguments}, it has the same effect. - - See section~\ref{section-key-writing-filters} for how to write key filters. -\end{handler} - -\begin{handler}{{.install key filter handler}|=|\meta{optional arguments}} - This handler installs the routine which will be invoked for every - \emph{unprocessed} option, that means any option for which the key filter - returned `false'. - - The |.install key filter handler| is used in the same way as - |.install key filter|. There exists a macro version, - |\pgfkeysinstallkeyfilterhandler|\meta{full key}\meta{optional arguments}, - which has the same effect. - - See section~\ref{section-key-writing-filters} for how to write key filter - handlers. -\end{handler} - - -\subsubsection{Handlers For Unprocessed Keys} - -Each option for which key filters decided to skip them is handed over to a `key -filter handler'. There are several predefined key filter handlers. - -\begin{key}{/pgf/key filter handlers/append filtered to=\marg{macro}} - Install this filter handler to append any unprocessed options to macro - \marg{macro}. - % -\begin{codeexample}[] -\pgfkeys{/pgf/key filter handlers/append filtered to/.install key filter handler=\remainingoptions} -\def\remainingoptions{} -\pgfkeysfiltered{/my group/A1=a1, /my group/A2=a2, - /my group/B=b, /my group/C=c, /tikz/color=blue} - -Remaining options: `\remainingoptions'. -\end{codeexample} - % - This example uses the same keys as defined in the intro - section~\ref{section-key-filter-example}. -\end{key} - -\begin{key}{/pgf/key filter handlers/ignore} - Install this filter handler if you simply want to ignore any unprocessed - option. This is the default. -\end{key} - -\begin{key}{/pgf/key filter handlers/log} - This key filter handler writes messages for any unprocessed option to your - logfile (and terminal). -\end{key} - - -\subsubsection{Family Support} - -\pgfname{} supports a family concept: every option can be associated with (at -most) one family. Families form loose key groups which are independent of the -key hierarchy. For example, |/my tree/key1| can belong to family |/tikz|. - -It is possible to `activate' or `deactivate' single families. Furthermore, it -is possible to set only keys which belong to active families using appropriate -key filter handlers. - -The family support is fast: if there are $N$ options in a key--value-list and -there are $K$ active families, the runtime for |\pgfkeysfiltered| is $O(N+K)$ -(activate every family $O(K)$, check every option $O(N)$, deactivate every -family $O(K)$). - -\begin{handler}{{.is family}} - Defines a new family. This option has already been described in - section~\ref{section-is family-handler} on page~\pageref{section-is - family-handler}. -\end{handler} - -\begin{handler}{{.activate family}} - Activates a family. The family needs to be defined, otherwise - |/errors/family unknown| will be raised. - - Activation means a \TeX-boolean will be set to |true|, indicating that a - family should be processed. - - You can also use |\pgfkeysactivatefamily|\meta{full path} to get the same - effect. Furthermore, you can use |\pgfkeysactivatefamilies|\meta{list of - families}\meta{macro name for de-activation} to activate a list of families - (see section~\ref{section-key-filter-api}). -\end{handler} - -\begin{handler}{{.deactivate family}} - Deactivates a family. The family needs to be defined, otherwise - |/errors/family unknown| will be raised. - - You can also use |\pgfkeysdeactivatefamily|\meta{full path} to get the same - effect. -\end{handler} - -\begin{handler}{{.belongs to family}|=|\marg{family name}} - Associates the current option with \marg{family name}, which is expected to - be a full path of a family. - % -\begin{codeexample}[code only] -\pgfkeys{/foo/bar/.is family} -\pgfkeys{ - /foo/a/.belongs to family=/foo/bar, - /foo/b/.belongs to family=/foo/bar -} -\end{codeexample} - % - Each option can have up to one family, |.belongs to family| overwrites any - old setting. -\end{handler} - -\begin{key}{/pgf/key filters/active families} - Install this key filter if |\pgfkeysfiltered| should only process activated - families. If a key does not belong to any family, it is not processed. If a - key is completely unknown within the default path, the normal `unknown' - handlers of |\pgfkeys| are invoked. -\end{key} - -\begin{key}{/pgf/key filters/active families or no family=\marg{key filter 1}\marg{key filter 2}} - This key filter configures |\pgfkeysfiltered| to work as follows. - % - \begin{enumerate} - \item If the current key belongs to a family, set - |\ifpgfkeysfiltercontinue| to true if and only if its family is - active. - \item If the current key does \emph{not} belong to a family, assign - |\ifpgfkeysfiltercontinue| as result of \marg{key filter 1}. - \item If the current key is unknown within the default path, assign - |\ifpgfkeysfiltercontinue| as result of \marg{key filter 2}. - \end{enumerate} - % - The arguments \marg{key filter 1} and \marg{key filter 2} are other key - filters (possibly with options) and allow fine-grained control over the - filtering process. - % -\begin{codeexample}[code only] - \pgfkeysinstallkeyfilter - {/pgf/key filters/active families or no family} - {{/pgf/key filters/is descendant of=/tikz}% for keys without family - {/pgf/key filters/false}% for unknown keys - }% -\end{codeexample} - % - This key filter will return true for any option with active family. If an - option has no family, the return value is true if and only if it belongs to - |/tikz|. If the option is unknown, the return value is |false| and unknown - handlers won't be called. -\end{key} - -\begin{key}{/pgf/key filters/active families or no family DEBUG=\marg{key filter 1}\marg{key filter 2}} - A variant of |active families or no family| which protocols each action on - your terminal (log-file). -\end{key} - -\begin{key}{/pgf/key filters/active families and known} - A fast alias for - - |/pgf/key filters/active families or no family=|\par - \noindent\hskip10pt|{/pgf/keys filters/false}|\par - \noindent\hskip10pt|{/pgf/keys filters/false}|. -\end{key} -% -\begin{key}{/pgf/key filters/active families or descendants of=\marg{path prefix}} - A fast alias for - - |/pgf/key filters/active families or no family=|\par - \noindent\hskip10pt|{/pgf/keys filters/is descendant of=|\marg{path prefix}|}|\par - \noindent\hskip10pt|{/pgf/keys filters/false}|. -\end{key} - -\begin{command}{\pgfkeysactivatefamiliesandfilteroptions\marg{family list}\marg{key--value-list}} - A simple shortcut macro which activates any family in the comma separated - \marg{family list}, invokes |\pgfkeysfiltered|\meta{key--value-list} and - deactivates the families afterwards. - - Please note that you will need to install a family key filter, otherwise - family activation has no effect. -\end{command} -% -\begin{command}{\pgfqkeysactivatefamiliesandfilteroptions\marg{family list}\marg{default path}\marg{key--value-list}} - The `quick' default path variant of |\pgfkeysactivatefamiliesandfilteroptions|. -\end{command} - -\begin{command}{\pgfkeysactivatesinglefamilyandfilteroptions\marg{family name}\marg{key--value-list}} - A shortcut macro which activates a single family and invokes |\pgfkeysfiltered|. - - Please note that you will need to install a family key filter, otherwise - family activation has no effect. -\end{command} -% -\begin{command}{\pgfqkeysactivatesinglefamilyandfilteroptions\marg{family name}\marg{default path}\marg{key--value-list}}% - The `quick' default path variant of |\pgfkeysactivatesinglefamilyandfilteroptions|. -\end{command} - - -\subsubsection{Other Key Filters} - -There are some more key filters which have nothing to do with family handling. -% -\begin{key}{/pgf/key filters/is descendant of=\marg{path}} - Install this key filter to process only options belonging to the key tree - \meta{path}. It returns true for every key whose key path is equal to - \meta{path}. It also returns true for any unknown key, that means unknown - keys are processed using the standard unknown handlers of \pgfname. - % -\begin{codeexample}[] -\pgfkeys{ -/group 1/A/.code={(A:#1)}, -/group 1/foo/bar/B/.code={(B:#1)}, -/group 2/C/.code={(C:#1)}, -/pgf/key filters/is descendant of/.install key filter=/group 1} -\pgfkeysfiltered{/group 1/A=a,/group 1/foo/bar/B=b,/group 2/C=c} -\end{codeexample} - % -\end{key} - -\begin{key}{/pgf/key filters/equals=\marg{full key}} - Install this key filter to process only the fully qualified option - \marg{full key}. The filter returns true for any unknown key or if the key - equals \marg{full key}. - % -\begin{codeexample}[] -\pgfkeys{ -/group 1/A/.code={(A:#1)}, -/group 1/B/.code={(B:#1)}, -/pgf/key filters/equals/.install key filter=/group 1/A} -\pgfqkeysfiltered{/group 1}{A=a,B=b} -\end{codeexample} - % -\end{key} - -\begin{key}{/pgf/key filters/not=\marg{key filter}} - This key filter logically inverts the result of \marg{key filter}. - % -\begin{codeexample}[] -\pgfkeys{ -/group 1/A/.code={(A:#1)}, -/group 1/foo/bar/B/.code={(B:#1)}, -/group 2/C/.code={(C:#1)}, -/pgf/key filters/not/.install key filter= - {/pgf/key filters/is descendant of=/group 1}} -\pgfkeysfiltered{/group 1/A=a,/group 1/foo/bar/B=b,/group 2/C=c} -\end{codeexample} - % - Please note that unknown keys will be handed to the usual unknown handlers. -\end{key} - -\begin{key}{/pgf/key filters/and=\marg{key filter 1}\marg{key filter 2}} - This key filter returns true if and only if both, \marg{key filter 1} and - \marg{key filter 2} return true. -\end{key} - -\begin{key}{/pgf/key filters/or=\marg{key filter 1}\marg{key filter 2}} - This key filter returns true if one of \marg{key filter 1} and \marg{key - filter 2} returns true. -\end{key} - -\begin{key}{/pgf/key filters/true} - This key filter returns always true. -\end{key} - -\begin{key}{/pgf/key filters/false} - This key filter returns always false (including unknown keys). -\end{key} - -\begin{key}{/pgf/key filters/defined} - This key filter returns false if the current key is unknown, which avoids - calling the unknown handlers. -\end{key} - - -\subsubsection{Programmer Interface} -\label{section-key-filter-api} - -\begin{plainenvironment}{{pgfkeysinterruptkeyfilter}} - Temporarily disables key filtering inside the environment. If key filtering - is not active, this has no effect at all. - - Please note that no \TeX-group is introduced. -\end{plainenvironment} - -\begin{command}{\pgfkeyssavekeyfilterstateto\marg{macro}} - Creates \marg{macro} which contains commands to re-activate the current key - filter and key filter handler. It can be used to temporarily switch the key - filter. -\end{command} - -\begin{command}{\pgfkeysinstallkeyfilter\marg{full key}\marg{optional arguments}} - The command - |\pgfkeysinstallkeyfilter{|\meta{full key}|}{|\meta{optional arguments}|}| - has the same effect as - |\pgfkeys{|\meta{full key}|/.install key filter={|\meta{optional arguments}|}}|. -\end{command} - -\begin{command}{\pgfkeysinstallkeyfilterhandler\marg{full key}\marg{optional arguments}} - The command - |\pgfkeysinstallkeyfilterhandler{|\meta{full key}|}{|\meta{optional arguments}|}| - has the same effect as - |\pgfkeys{|\meta{full key}|/.install key filter handler={|\meta{optional arguments}|}}|. -\end{command} - -\begin{command}{\pgfkeysactivatefamily\marg{family name}} - Equivalent to |\pgfkeys{|\meta{family name}|/.activate family}|. -\end{command} - -\begin{command}{\pgfkeysdeactivatefamily\marg{family name}} - Equivalent to |\pgfkeys{|\meta{family name}|/.deactivate family}|. -\end{command} - -\begin{command}{\pgfkeysactivatefamilies\marg{family list}\marg{deactivate macro name}} - Activates each family in \meta{family list} and creates a macro - \meta{deactivate macro name} which deactivates each family in \meta{family - list}. - % -\begin{codeexample}[code only] -\pgfkeysactivatefamilies{/family 1,/family 2,/family 3}{\deactivatename} -\pgfkeysfiltered{foo,bar} -\deactivatename -\end{codeexample} - % -\end{command} - -\begin{command}{\pgfkeysiffamilydefined\marg{family}\marg{true case}\marg{false case}}% - Checks whether the full key \meta{family} is a family and executes either - \meta{true case} or \meta{false case}. -\end{command} - -\begin{command}{\pgfkeysisfamilyactive\marg{family}} - Sets the \TeX-boolean |\ifpgfkeysfiltercontinue| to whether \meta{family} - is active or not. -\end{command} - -\begin{command}{\pgfkeysgetfamily\marg{full key}\marg{resultmacro}} - Returns the family associated to a \meta{full key} into macro - \meta{resultmacro}. -\end{command} - -\begin{command}{\pgfkeyssetfamily\marg{full key}\marg{family}} - The command |\pgfkeyssetfamily|\marg{full key}\marg{family} has the same - effect as |\pgfkeys{|\meta{full key}|/.belongs to family=|\marg{family}|}|. -\end{command} - - -\subsubsection{Defining Own Filters Or Filter Handlers} -\label{section-key-writing-filters} - -During |\pgfkeysfiltered|, the key filter code will be invoked. At this time, -the full key path including key name is available as |\pgfkeyscurrentkey|, the -key name before default paths have been considered as |\pgfkeyscurrentkeyRAW| -and the values as |\pgfkeyscurrentvalue|. - -Furthermore, the macro |\pgfkeyscasenumber| contains the current key's type as -an integer: -% -\begin{itemize} - \item[\meta{1}] The key is a command key (i.e.\ |.../.@cmd| exists). - \item[\meta{2}] The key contains its value directly. - \item[\meta{3}] The key is handled (for example it is |.code| or |.cd|). - - In this case, the macros |\pgfkeyscurrentname| and - |\pgfkeyscurrentpath| are set to the handlers name and path, - respectively. Invoke |\pgfkeyssplitpath{}| to extract these values for - non-handled keys. - \item[\meta{0}] The key is unknown. -\end{itemize} -% -Any key filter or key filter handler can access these variables. Key filters -are expected to set the \TeX-boolean |\ifpgfkeysfiltercontinue| to whether the -current key shall be processed or not. - -\begin{command}{\pgfkeysevalkeyfilterwith\marg{full key}=\marg{filter arguments}} - Evaluates a fully qualified key filter \meta{full key} with argument(s) - \meta{filter arguments}. - % -\begin{codeexample}[code only] -\pgfkeysevalkeyfilterwith{/pgf/key filters/equals=/tikz} -\end{codeexample} - % -\end{command} - -\endgroup |