diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/keys3/keys3-test.tex')
-rw-r--r-- | Master/texmf-dist/doc/latex/keys3/keys3-test.tex | 378 |
1 files changed, 133 insertions, 245 deletions
diff --git a/Master/texmf-dist/doc/latex/keys3/keys3-test.tex b/Master/texmf-dist/doc/latex/keys3/keys3-test.tex index 2715d0f8a91..a3a2c5c3e26 100644 --- a/Master/texmf-dist/doc/latex/keys3/keys3-test.tex +++ b/Master/texmf-dist/doc/latex/keys3/keys3-test.tex @@ -10,21 +10,12 @@ \usepackage{keys3,xparse} \usepackage[parfill]{parskip} -% The document commands for creating keys is very simple. A generic -% one is created to set any modules keys, and one specific to the module -% used here. -\ExplSyntaxOn - -\DeclareDocumentCommand{\SetModuleKeys}{m}{ - \keys_manage:n{ - module~name/.cd:, - #1} -} +% The document commands for using keys is very simple. -\DeclareDocumentCommand{\SetKeys}{m}{ - \keys_manage:n{#1} +\ExplSyntaxOn +\DeclareDocumentCommand \SetModuleKeys { m } { + \keys_set:nn { module } {#1} } - \ExplSyntaxOff \begin{document} @@ -42,8 +33,17 @@ % You said: ` Hello World ' % You said: `' % ---------------------------------------------------------------------- +\ExplSyntaxOn +\keys_show:nn { module } {unknown} +\keys_set:nn { module } { + clive = india +} +\keys_define:nn { module } { + key .code:n = {You~said:~`#1'\\} +} +\ExplSyntaxOff + \SetModuleKeys{ - key/.code:n = {You said: `#1'\\}, key = Hello World , key = { Hello World }, key @@ -54,254 +54,178 @@ % ---------------------------------------------------------------------- % You said: `A', `B', `C', D'. % You said: `AAA', `BBB', `CCC', ` DDD'. -% You said: `', `', `', `'. % ---------------------------------------------------------------------- -\SetModuleKeys{ - key/.code:Nn = 4 {You said: `#1', `#2', `#3', `#4'.\\}, - key = ABCD, - key = {AAA}{BBB} {CCC} { DDD}, - key =, +\ExplSyntaxOn +\keys_define:nn { module } { + key .code:Nn = 4 {You said:~`#1',~`#2',~`#3',~`#4'.\\}, } +\ExplSyntaxOff -% Test three: The ability to change the key path is available with the -% .cd: property. The following moves from the key root to two separate -% paths, creating keys with the same names. -% ---------------------------------------------------------------------- -% A key in path one -% A key in path two -% A key in path two -% A key in path one -% ---------------------------------------------------------------------- -\SetKeys{ - /path one/.cd:, - key/.code:n = A key in path one\\, - /path two/.cd:, - key/.code:n = A key in path two\\, - /path one/key, - /path two/key, - key, - /path one/.cd:, - key +\SetModuleKeys{ + key = ABCD, + key = {AAA}{BBB} {CCC} { DDD} } -% Test four: Variants of .code:n and .code:Nn exist which carry out a +% Test three: Variants of .code:n and .code:Nn exist which carry out a % full expansion on code definition. First the :x variant is tested. % ---------------------------------------------------------------------- % Temp holds: ABC % Temp hold: 123 % ---------------------------------------------------------------------- \newcommand*{\temp}{123} -\SetModuleKeys{ - key one/.code:n = Temp holds: \temp\\, - key two/.code:x = Temp holds: \temp, + +\ExplSyntaxOn +\keys_define:nn { module } { + key-one .code:n = Temp~holds:~\temp\\, + key-two .code:x = Temp~holds:~\temp, } +\ExplSyntaxOff + \renewcommand*{\temp}{ABC} + \SetModuleKeys{ - key one, - key two + key-one, + key-two } + % Now the :Nx version % ---------------------------------------------------------------------- % Arguments: A, B. Temp holds: ABC % Arguments: 1, 2. Temp hold: 123 % ---------------------------------------------------------------------- \renewcommand*{\temp}{123} -\SetModuleKeys{ - key one/.code:Nn = 2 {Arguments: #1, #2. Temp holds: \temp\\}, - key two/.code:Nx = 2 {Arguments: #1, #2. Temp holds: \temp}, + +\ExplSyntaxOn +\keys_define:nn { module } { + key-one .code:Nn = 2 {Arguments:~#1,~#2.~Temp~holds:~\temp\\}, + key-two .code:Nx = 2 {Arguments:~#1,~#2.~Temp~holds:~\temp}, } +\ExplSyntaxOff \renewcommand*{\temp}{ABC} \SetModuleKeys{ - key one = {A} {B}, - key two = {1} {2} + key-one = {A} {B}, + key-two = {1} {2} } -% Test five: Values can be required and forbidden with the +% Test four: Values can be required and forbidden with the % .value_required: and .value_forbidden: properties. % ---------------------------------------------------------------------- % All okay % All okay % ---------------------------------------------------------------------- -% The key `/module name/key' cannot taken a value: +% The key `module/key-one' cannot taken a value: % the given input `Not allowed' is being ignored. % -% The key `/module name/key' requires a value +% The key `module/key-two' requires a value % and is being ignored. % ---------------------------------------------------------------------- +\ExplSyntaxOn +\keys_define:nn { module } { + key-one .code:n = All okay\\, + key-one .value_forbidden:, + key-two .code:n = #1, + key-two .value_required: +} +\ExplSyntaxOff + \SetModuleKeys{ - key/.code:n = {All okay\\}, - key/.value_forbidden:, - key, - key = Not allowed, - key/.code:n = #1, - key/.value_required:, - key = {All okay}, - key + key-one, + key-one = Not allowed, + key-two = All okay, + key-two } -% Test six: Keys can be given a default value, to be used if nothing is -% specified by the user. +% Test five: Keys can be given a default value, to be used if nothing is +% specified by the user. This can be done by name or by value. % ---------------------------------------------------------------------- % Default % Real -% Default +% Stuff +% Real +% Literal +% Real % ---------------------------------------------------------------------- +\ExplSyntaxOn +\renewcommand*{\temp}{Stuff} +\keys_define:nn { module } { + key-one .code:n = #1\\, + key-one .default:n = \temp, + key-two .code:n = #1\\, + key-two .default:V = \temp, + key-three .code:n = #1\\, + key-three .default:n = Literal, +} +\ExplSyntaxOff +\renewcommand*{\temp}{Default} + \SetModuleKeys{ - key/.code:n = {#1\\}, - key/.default:n = Default, - key, - key = Real, - key + key-one, + key-one = Real, + key-two, + key-two = Real, + key-three, + key-three = Real } -% Test seven: Keys can be created to store data tl variable both -% locally and globally. +% Test six: Keys can be created to store data both locally and +% globally. This is illustrated using token list variables. % ---------------------------------------------------------------------- % Some content % Outside % Some content % Some content % ---------------------------------------------------------------------- -\renewcommand*{\temp}{Outside} -\SetModuleKeys{ - key one/.tl_set:N = \temp, +\ExplSyntaxOn +\tl_new:Nn \l_temp_tl {Outside} +\tl_new:Nn \g_temp_tl {Outside} +\keys_define:nn { module } { + key-one .set:N = \l_temp_tl, + key-two .set:N = \g_temp_tl, } + \begingroup \SetModuleKeys{ - key = Some content + key-one = Some~content } -\temp\\ +\l_temp_tl\\ \endgroup -\temp\\ -\SetModuleKeys{ - key/.tl_gset:N = \temp -} +\l_temp_tl\\ + \begingroup \SetModuleKeys{ - key = Some content + key-two = Some~content } -\temp\\ +\g_temp_tl\\ \endgroup -\temp\\ +\g_temp_tl\\ +\ExplSyntaxOff -% Test eight: An expanded version of .tkp_set:N is available. +% Test seven: An expanded version of .set:N is available. % ---------------------------------------------------------------------- % Unexpanded % Expanded % ---------------------------------------------------------------------- -\renewcommand*{\temp}{Expanded} -\newcommand*{\tempa}{} -\newcommand*{\tempb}{} -\SetModuleKeys{ - key one/.tl_set:N = \tempa, - key two/.tl_set_x:N = \tempb, - key one = \temp, - key two = \temp, -} -\renewcommand*{\temp}{Unexpanded} -\tempa\\ -\tempb\\ - -% Test nine: Storage functions for int, skip and toks variables are also -% available. Both local and global setting is possible, although there -% are no "x" versions. -% ---------------------------------------------------------------------- -% 12345 -% 10.00002pt -% abc -% ---------------------------------------------------------------------- -\newcount\tempint -\newskip\tempskip -\newtoks\temptoks -\SetModuleKeys{ - key/.int_set:N = \tempint, - key = 12345, - key/.skip_set:N = \tempskip, - key = 1 em, - key/.toks_set:N = \temptoks, - key = abc -} -\the\tempint\\ -\the\tempskip\\ -\the\temptoks - -% Test ten: Variables can be identified only by the unique part of their -% name, provided that /keys/current_module:n has been set with the -% appropriate information. Both local and global names can be used in -% this way. -% ---------------------------------------------------------------------- -% Local -% Global -% ---------------------------------------------------------------------- \ExplSyntaxOn -\tl_new:N \l_module_local_tl -\tl_new:N \g_module_global_tl -\ExplSyntaxOff -\SetModuleKeys{ - /keys/current_module:n = module, - key one/.tl_set:n = local, - key two/.tl_gset:n = global, - key one = Local, - key two = Global +\tl_set:Nn \l_temp_tl {Expanded} +\tl_new:N \l_tempa_tl +\tl_new:N \l_tempb_tl +\keys_define:nn { module } { + key-one .set:N = \l_tempa_tl, + key-two .set_x:N = \l_tempb_tl, } -\ExplSyntaxOn -\l_module_local_tl \\ -\g_module_global_tl -\ExplSyntaxOff -% Test eleven: Boolean keys are created in the same way as other storage -% keys. However, the key will then only accept "true" and "false" as -% input. The key name can be given alone, resulting in the switch being -% set "true". -% ---------------------------------------------------------------------- -% Local switch true -% Global switch true -% ---------------------------------------------------------------------- -% Key `/module name/key one' takes the Boolean values -% `true' and `false' only. -% The given value `rubbish' is being ignored. -% ---------------------------------------------------------------------- -\ExplSyntaxOn -\bool_new:N \localbool -\bool_new:N \g_module_global_bool -\ExplSyntaxOff \SetModuleKeys{ - /keys/current_module:n = module, - key one/.bool_set:N = \localbool, - key two/.bool_gset:n = global, - key one = true, - key two = false, - key two, - key one = rubbish + key-one = \l_temp_tl, + key-two = \l_temp_tl, } -\ExplSyntaxOn -\bool_if:NTF \localbool { Local~switch~true } { Local~switch~false } \\ -\bool_if:NTF \g_module_global_bool - { Global~switch~true } { Global~switch~false } -\ExplSyntaxOff +\tl_set:Nn \l_temp_tl {Unxpanded} +\l_tempa_tl\\ +\l_tempb_tl\\ -% Test twelve: The logic for Boolean keys can be reversed using the -% .bool_set_inverse:N and related properties. This can be used with -% in concert with .bool_set:N to create complementary keys. -% ---------------------------------------------------------------------- -% Hello World -% Hello User -% ---------------------------------------------------------------------- -\SetModuleKeys{ - /keys/current_module:n = module, - key one/.bool_set_inverse:N = \localbool, - key two/.bool_gset_inverse:n = global, - key one, - key two = true, -} -\ExplSyntaxOn -\bool_if:NTF \localbool { Local~switch~true } { Local~switch~false } \\ -\bool_if:NTF \g_module_global_bool - { Global~switch~true } { Global~switch~false } \ExplSyntaxOff -% Test thirteen: Choices can be created either from a list of options or +% Test eight: Choices can be created either from a list of options or % one by one. Both are tested here by creating a list then adding to it % with an extra key. Unknown choices lead to an error message. % ---------------------------------------------------------------------- @@ -310,14 +234,19 @@ % Choice `c' is number 3 % An extra choice % ---------------------------------------------------------------------- -% Choice `e' unknown for key `/module name/key/e': +% Choice `e' unknown for key `module/key': % the key is being ignored. % ---------------------------------------------------------------------- +\ExplSyntaxOn +\keys_define:nn { module } { + key .generate_choices:nn = {a,b,c} { + Choice~`\l_keys_choice_tl'~is~number~\int_use:N \l_keys_choice_int\\ + }, + key/d .code:n = An~extra~choice \\ +} +\ExplSyntaxOff + \SetModuleKeys{ - key/.create_choices:nn = {a,b,c} - {Choice `\csname l_keys_current_choice_tl\endcsname' is number - \the\csname l_keys_current_choice_int\endcsname \\}, - key/d/.code:n = {An extra choice \\}, key = a, key = b, key = c, @@ -325,70 +254,29 @@ key = e } -% Test fourteen: Keys can be used to set other keys. One or more -% arguments can be accepted when this happens, allowing complex key -% setting to be carried out easily. There are expanded versions of these -% properties, which work similarly. +% Test nine: A completely unknown key should cause an error. % ---------------------------------------------------------------------- -% Hello Fred. -% How are you, Fred? -% Hello Fred. -% How are you, Ginger? +% The key `module/unknown key' is unknown and is being ignored. % ---------------------------------------------------------------------- \SetModuleKeys{ - key one/.code:n = {Hello #1.\\}, - key two/.code:n = {How are you, #1?\\}, - key three/.use_keys:n = { key one = #1, key two = #1}, - key three = Fred, - key three/.use_keys:Nn = 2 { key one = #1, key two = #2}, - key three = {Fred} {Ginger} + unknown key = some value } -% Test fifteen: The .try:w and .retry:w properties attempt to set a key -% only if it exists. The .try:w property does this for every key it -% is given, whereas .retry: only works if the previous .try:w failed. +% Test ten: If the special `unknown' key has been set up, however, +% unknown input can be re-directed. % ---------------------------------------------------------------------- -% Hello -% World -% Seen +% You tried to set key `unknown key' to `some value' % ---------------------------------------------------------------------- -\SetModuleKeys{ - key one/.code:n = {#1\\}, - key two/.code:n = {#1\\}, - key one/.try:n = Hello, - key ten/.try:n = Rubbish, - key two/.try:n = World, - key two/.retry:n = Not seen, - key ten/.try:n = Rubbish, - key two/.retry:n = Seen, +\ExplSyntaxOn +\keys_define:nn { module } { + unknown .code:n = You~tried~to~set~key~`\l_keys_key_tl'~to~`#1' } +\ExplSyntaxOff -% Test sixteen: Two programmers tools, .show_code: and .show_key:, do -% pretty much what might be expected. .show_key: is mainly useful for -% internal keys. -% ---------------------------------------------------------------------- -% a or b -% ---------------------------------------------------------------------- -% > \keys-root/module name/key one/._cmd:w=\long macro: -% #1#2->#1 or #2. -% -% > \keys-root/module name/key one/._num_args_tl=macro: -% ->2. -% ---------------------------------------------------------------------- \SetModuleKeys{ - key one/.code:Nn = 2 {#1 or #2}, - key one = ab, - key one/.show_code:, - key one/._num_args_tl/.show_key:, + unknown key = some~value } -% Test seventeen: A completely unknown key should cause an error. -% ---------------------------------------------------------------------- -% The key `/module name/unknown key' is unknown and is being ignored -% ---------------------------------------------------------------------- -\SetModuleKeys{ - unknown key = some value -} \end{document} |