diff options
author | Karl Berry <karl@freefriends.org> | 2009-06-14 18:00:54 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2009-06-14 18:00:54 +0000 |
commit | d88fd922cc82efa8efbbc59d5dfc3830567abb9b (patch) | |
tree | 6f455fe1f9b19d923c5a70ba81c1c14f4662fe75 /Master/texmf-dist/doc | |
parent | b9d7958e66727425075266e52ba598759a3edecc (diff) |
keys3 110 (12jun09)
git-svn-id: svn://tug.org/texlive/trunk@13738 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc')
-rw-r--r-- | Master/texmf-dist/doc/latex/keys3/README | 26 | ||||
-rw-r--r-- | Master/texmf-dist/doc/latex/keys3/keys3-test.tex | 378 | ||||
-rw-r--r-- | Master/texmf-dist/doc/latex/keys3/keys3.pdf | bin | 444041 -> 476644 bytes | |||
-rw-r--r-- | Master/texmf-dist/doc/latex/keys3/keys3opts2.pdf | bin | 313237 -> 313237 bytes |
4 files changed, 145 insertions, 259 deletions
diff --git a/Master/texmf-dist/doc/latex/keys3/README b/Master/texmf-dist/doc/latex/keys3/README index b79a089d7dc..02413bf1c9e 100644 --- a/Master/texmf-dist/doc/latex/keys3/README +++ b/Master/texmf-dist/doc/latex/keys3/README @@ -9,27 +9,25 @@ See http://www.latex-project.org/lppl.txt The keys3 package is an experimental implementation of key management for LaTeX3. The entire package is written in expl3 code rather than in traditional TeX/LaTeX. The key -module used by keys3 is based on that introduced by the -pgfkeys package from the pgf/TiKZ bundle. Keys are thus -addressed in a path-like manner, and are controlled by key -properties: +model used by keys3 is based on the idea that keys are created +by setting key properties: -/module/key/.code:n = <code>, -/module/key/.value_required:, -/module/key = <value> + \keys_define:nn { module } { + key .code:n = Hello #1, + key .value_required: + } The keys3 package is intended as a method for testing how key management might be implemented in LaTeX3. Both the methods used inside the package and the interface provided are intended to be discussed. Feedback is welcomed either by e-mail -(joseph.wright@morningstar2.co.uk) or at the package website -(http://keys3.berlios.de). +(joseph.wright@morningstar2.co.uk) or to the LaTeX-L mailing +list. -The experimental nature of keys3 and the underlying expl3 -system means that it should not be used in production -documents. However, programmers testing expl3, or keen to work -on improved key management systems, are encouraged to try the -package and provide feedback. +The experimental nature of keys3 means that it should not be +used in production documents. However, programmers testing +expl3, or keen to work on improved key management systems, +are encouraged to try the package and provide feedback. keys3 is *not* an official LaTeX3 team package. Whether any of the ideas explored here will be taken up by the team is 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} diff --git a/Master/texmf-dist/doc/latex/keys3/keys3.pdf b/Master/texmf-dist/doc/latex/keys3/keys3.pdf Binary files differindex 3d26fd7fdfe..3c1831ca5e8 100644 --- a/Master/texmf-dist/doc/latex/keys3/keys3.pdf +++ b/Master/texmf-dist/doc/latex/keys3/keys3.pdf diff --git a/Master/texmf-dist/doc/latex/keys3/keys3opts2.pdf b/Master/texmf-dist/doc/latex/keys3/keys3opts2.pdf Binary files differindex cdc4783125a..a0cc876d6b6 100644 --- a/Master/texmf-dist/doc/latex/keys3/keys3opts2.pdf +++ b/Master/texmf-dist/doc/latex/keys3/keys3opts2.pdf |