summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/skeyval/README
blob: fe6e31d7d3770a76c98a28e44ce09ec516469163 (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
This is the README file for the 'skeyval' package.

AUTHOR

Ahmed Musa

VERSION

Version 1.1, October 2012.

LOCATION ON CTAN

macros/latex/contrib/skeyval

LICENSE

Copyright (c) 2010-2012 Ahmed Musa

This software is author-maintained. Permission is granted to copy,
distribute and/or modify this software under the terms of the
LaTeX Project Public License, version 1.3 or higher. This software
is provided 'as it is', without warranty of any kind, either
expressed or implied, including, but not limited to, the implied
warranties of merchantability and fitness for any particular purpose.


FILES

The following files constitute the skeyval bundle and must be
distributed as a whole:

  readme, skeyval.sty, skeyval-core.tex, skeyval-for.tex,
  skeyval-view.sty, skeyval-ltxpatch.sty, skeyval-ltxcmds.tex,
  skeyval-pstkey.sty, skeyval-pstkey.tex, skeyval-testclass.cls,
  and skeyval-testpkg.sty.

The skeyval package can be used by LaTeX and non-LaTeX users.
LaTeX users should load the package via

    \usepackage[<options>]{skeyval}

or, in class files and packages,

    \RequirePackage[<options>]{skeyval}

Plain TeX users can do

    \input skeyval-core

Users of pre-version-1.0  of skeyval package can access former
versions by entering the option 'compatibility' in <options> above.
This option will automatically load version 0.73 (the version
just before 1.0) of skeyval package. From version 1.0, the package
has changed radically.


SUMMARY

The 's' in skeyval means 'skeleton keys' or 'master keys'.

The skeyval package provides commands for compactly defining and
initializing all types of key (ordinary, command, boolean, style, choice,
etc). It attempts to combine the features of ltxkeys package (which has
the syntax of the xkeyval package) and pgfkeys package. One of the powers
of pgfkeys package lies in its use of handlers. But the way handlers
are used in pgfkeys package does add to computational complexity and
overheads. Family or key filtering in pgfkeys is particularly complex
and inefficient. Nesting of family or key filtering is, in particular,
not recommended.

In pgfkeys package, handlers come at the end of the key name, so that
if a key isn't defined, the system tests to find if the key has a
handler at its end. If a handler is found and defined, the handler's
callback (called 'code' by pgfkeys package) is executed on the
current path.

The skeyval package puts handlers at the beginning of the key
(or a set of keys) and uses the handler to process the key (or a set
of keys). This speeds up key processing and reduces the computational
complexity. Key processing, including filtering, can be nested
naturally and efficiently.

The skeyval package also maintains and, in fact, greatly extends the
functionality and syntaxes of the ltxkeys package. Very few examples
of the functionality of skeyval package are

1.  The callbacks of keys can be readily modified using commands
    like \skvaddtocallback, \skvprependtocallback, \skvappendtocallback,
    or the handlers .prepend code, .append code, .add code.

2.  Apart from the usual keys in xkeyval and ltxkeys packages, it is
    now possible to define a rather weird key like

    \skvpntkey[KV]{fam}{evaluate (?) as (?) using (?)}{\edef#2{#3}}

    The key name here is 'evaluate (?) as (?) by (?)'. It has three
    arguments, indicated by the closed parenthesis. The mark '?' can be
    replaced by any character or characters, and the key could have up
    to 9 arguments. This key can be set as

    \skvsetkeys[KV]{fam}{evaluate (\x) as (\y) using (\numexpr\x*2)}

    We can also define the same key with the default values specified:

    \skvpntkey[KV]{fam}{evaluate (?) as (?) using (?)}[\x\y{\numexpr\x*2}]{%
      \def\argone{#1}\def\argtwo{#2}\def\argthree{#3}%
    }

    and set it as follows (if pgfmath package is loaded):

    \skvsetkeys[KV]{fam}{%
      evaluate (\x) as (\pgfmathresult) using (\pgfmathparse{\x^10})
    }

3.  The parameters/arguments of callbacks of keys can be easily changed.
    For example, to change the argument of keya, one way is via
    the magical command \directkeys:

    \directkeys{%
      .exec=\def\avalue{a+b},
      .prefixes={KV1,KV2},
      .families={fam1,fam2},
      .holder prefix=mp@,
      .initialize keys after define,
      .define keys={
          .ord/keya/def-a/\def\xa##1{#1*##1*#2},
          .arg/keya/#1+#2,
          .cmd/.value required{keyb}/def-b/\def\cmdb##1{##1@#1},
        },
      .initial values={
          keya=ini-value,
        },
      .ignore family=fam2,
      .set keys={
          keya=.expanded{\avalue}
        },
      % Nested \directkeys. The current path is put on stack
      % and restored later, so that the nest is independent
      % of its surrounding topology:
      \directkeys{
          .path=KV3/fam3,
          .new keys={
            .ord/keya/defa/\def\ya##1{#1*##1*#2},
            .arg/keya/#1+#2,
            .choice/keyc/center/{right,left,center,justified},
            .arg expanded/keyc/#1,
            .bool/keyd/true,
            .cmd/.forbid value{keye}/defe/\def\ye##1{#1*##1},
          },
        },
      .try set keys={
          .paths={KV1/fam1,KV3/fam3},
          .try=2, .goal=1
        }{
          keyc=left,keyd=false
        },
      .ignore path=KV1/fam1,
      .exec=\def\cvalue{center},
      .search also set keys={
          .add prefix=KV3,
          .add families={fam3,fam4},
          .max attempts=4, .goal=2,
        }{
          keyc=.expand once{\cvalue}
        },
      .append values={
          keya=\def\y##1{#1+##1},
          keyb=\def\w##1{#1+##1},
        },
      .prepend code={
          keyb=\def\pre##1{#1+##1},
        },
      .styles{
          key1/keya=value1,
          key2/keyb=value2
        },
      .inherit code={
          key1/keyb, key2/keyd
        },
      .preset keys={
          key1,key2
        },
    }

    Unlike in pgfkeys package, when we use 'expand' or 'expanded'
    in a handler, the expansion will invariably be done when the
    key is set, not when it's being defined.

    The handlers of skeyval package start with a dot (.),
    as in pgfkeys package.

4.  Several new features are introduced by the skeyval package. For
    example, we now have 'style' and 'link' keys in the context of
    ltxkeys syntax. For example, to link keys via .link or .style
    handler:

    \directkeys{%
      .link={key1, key2}/keya,
      .link={key3, key4}/{keya, keyb},
      .append style expand twice={key3, key4}/keyf=\valuea,
      .prepend style expanded={key5, key6}/{keyc=#1, keyd=#1},
      .prepend style={key7, key8}/{keyd=#1, keye=#1},
    }

5.  The concepts of 'trying' to set a key with 'goals' is introduced.
    The handler '.goal' can be interpreted in the sense of \pagegoal,
    but applied to setting a key.
    See an example above. Then there is 'search also' set keys.

6.  'Quick keys' are a new concept. They're quite fast to define and set.

7.  Keys can be 'made', as in

    \skvmakekeys[
      .prefix=KVA, .families={fam1,fam2}, .holder prefix=mp@,
      .all are new, .define in all families, .initialize after define
    ]{%
      .ords/{keya,keyb}/{default-a},
      .cmds/{keyc,keyd}/,
      .zcmd/key e/\def\cmde##1{##1}/
        \edef\y{\detokenize\expandafter{\thp@keye}}\def\x##1{#1*key e*##1},
      .choice/keyf/center/{center.do=\def\x##1{#1*##1},left,right},
      .zbool/show center/true/\edef\cmd{\ifthp@showcenter Yes\else No\fi}
    }

    'z-keys' are keys whose names are zapped (ie, spaces are removed)
    internally. This is to allow holder/store macros to be used
    without spaces in their names, while maintaining key names with
    spaces.

8.  Keys can be set using \skvsetkeys, \directkeys (with the handlers
    .set keys, .try, etc.), or \skvusekeys:

    \krdusekeys[
      .prefix=KVA,
      .families={fam1,fam2},
      .set in all families,
      .save unknown keys
    ]{%
      keya,keyb
    }

9.  Keys defined in families can be viewed in files using the package
    'skeyval-view'. The functionality of 'skeyval-view' is greater than
    that of xkeyval-view package.

10. Files skeyval-pstkey.sty and skeyval-pstkey.tex are provided for
    PSTricks developers and users, as did xkeyval package.

11. Some new and versatile looping macros are introduced in the
    skeyval package. In fact, the powerful \newforeach list
    processor of the 'loops' package has its roots in the 'skeyval-for'
    module. It is a generalization of PGF's \foreach macro for
    arbitrary parsers and list separators, including active parsers.


% End of readme file