summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/keys3/keys3-test.tex
blob: a3a2c5c3e26bb1af20e042f98139c15109994205 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
% !TEX program  = pdflatex
% 
% This is a test file demonstrating the keys3 experimental LaTeX3 
% package. This file illustrates the methods made available by keys3
% for managing key-value input. It also acts as a check, as almost all
% of the keys3 methods are used (with known output) and because a number
% of errors are deliberately raised.

\documentclass{article}
\usepackage{keys3,xparse}
\usepackage[parfill]{parskip}

% The document commands for using keys is very simple.

\ExplSyntaxOn
\DeclareDocumentCommand \SetModuleKeys { m } {
  \keys_set:nn { module } {#1}
}
\ExplSyntaxOff

\begin{document}

% Each test starts with a short piece of text explaining the property
% being used. Under this, the expected output is given, followed
% if relevant by the text of any error messages expected.

% Test one: Simply creating a key with one argument and then using it.
% Notice that the text length determines the limits of the argument: 
% spaces at either end are ignored. Literal spaces between text are 
% counted, as are those enclosed in braces.
% ----------------------------------------------------------------------
%   You said: `Hello World'
%   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 = Hello World ,
  key = { Hello World },
  key 
}

% Test two: Creating a multiple-argument key. Here, the arguments
% given need to be at least as many as those required by the code!
% ----------------------------------------------------------------------
%   You said: `A', `B', `C', D'.
%   You said: `AAA', `BBB', `CCC', ` DDD'.
% ----------------------------------------------------------------------
\ExplSyntaxOn
\keys_define:nn { module } {
  key .code:Nn = 4 {You said:~`#1',~`#2',~`#3',~`#4'.\\},
}
\ExplSyntaxOff

\SetModuleKeys{
  key = ABCD,
  key = {AAA}{BBB} {CCC} { DDD}
}

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

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

% Now the :Nx version
% ----------------------------------------------------------------------
%   Arguments: A, B. Temp holds: ABC
%   Arguments: 1, 2. Temp hold: 123
% ----------------------------------------------------------------------
\renewcommand*{\temp}{123}

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

% Test four: Values can be required and forbidden with the 
% .value_required: and .value_forbidden: properties.
% ----------------------------------------------------------------------
%   All okay
%   All okay
% ----------------------------------------------------------------------
% The key `module/key-one' cannot taken a value:
% the given input `Not allowed' is being ignored.
% 
% 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-one,
  key-one = Not allowed,
  key-two = All okay,
  key-two
}

% 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
%   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-one,
  key-one = Real,
  key-two,
  key-two = Real,
  key-three,
  key-three = Real
}

% 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
% ----------------------------------------------------------------------
\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-one = Some~content
}
\l_temp_tl\\
\endgroup
\l_temp_tl\\

\begingroup
\SetModuleKeys{
  key-two = Some~content
}
\g_temp_tl\\
\endgroup
\g_temp_tl\\
\ExplSyntaxOff

% Test seven: An expanded version of .set:N is available.
% ----------------------------------------------------------------------
%   Unexpanded
%   Expanded
% ----------------------------------------------------------------------
\ExplSyntaxOn
\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,
}

\SetModuleKeys{
  key-one = \l_temp_tl,
  key-two = \l_temp_tl,
}
\tl_set:Nn \l_temp_tl {Unxpanded}
\l_tempa_tl\\
\l_tempb_tl\\

\ExplSyntaxOff

% 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.
% ----------------------------------------------------------------------
% Choice `a' is number 1
% Choice `b' is number 2
% Choice `c' is number 3
% An extra choice
% ----------------------------------------------------------------------
% 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 = a,
  key = b,
  key = c,
  key = d,
  key = e
}

% Test nine: A completely unknown key should cause an error.
% ----------------------------------------------------------------------
% The key `module/unknown key' is unknown and is being ignored.
% ----------------------------------------------------------------------
\SetModuleKeys{
  unknown key = some value
}

% Test ten: If the special `unknown' key has been set up, however,
% unknown input can be re-directed.
% ----------------------------------------------------------------------
% You tried to set key `unknown key' to `some value'
% ----------------------------------------------------------------------
\ExplSyntaxOn
\keys_define:nn { module } {
   unknown .code:n = You~tried~to~set~key~`\l_keys_key_tl'~to~`#1'
}
\ExplSyntaxOff

\SetModuleKeys{
  unknown key = some~value
}


\end{document}