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

VERSION

Version 0.0.1, August 2011

SUMMARY

The keyval2e package provides lightweight and robust facilities for
creating and managing keys. Its machinery isn't as extensive as
that of, eg, ltxkeys package, but it is equally robust. Ease of
use and speed of processing are the two main motives of this package.
Some, indeed many, applications of the key-value syntax (while they
call for robustness) don't require the full armor of key-value
processing as found in, eg, the ltxkeys package.

Ordinary, boolean, and choice keys can be created using only
one command (\kve@definekeys). Keys can be initialized (with
the command \kve@setdefaults) as soon as they are created. And
in any run the default values of keys can be used to set keys that
have no current values. The latter task is accomplished by the
command \kve@setafterdefaults, meaning 'set keys with the current
values after those without current values have been initialized/set
with their default values'. Normally, keys are set with the
re-entrant command \kve@setkeys.

LICENSE

Copyright (c) 2011 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.

RELATED PACKAGES

keyval.sty, xkeyval.sty, ltxkeys

AUTHOR

Ahmed Musa (amusa22@gmail.com)

USER COMMANDS

\kve@definekeys[<pref>]{<fam>}{<key-1>/<defa-1>/<callback-1>,...,
  <key-n>/<defa-n>/<callback-n>}

\kve@setkeys[<pref>]{<fam>}[na]{<keyval pairs>}

\kve@setdefaults[<pref>]{<fam>}[<na>]

\kve@setafterdefaults[<pref>]{<fam>}[<na>]{<curr-keyval>}

Here, <pref> is the optional key prefix, <fam> is the
mandatory family, and [<na>] is a comma-separated list
of keys that should be ignored, ie, not set in the current
run. Undefined keys are reported as undefined and are not
saved as 'remaining keys'. There are no 'undefined key
handlers' and no 'handled keys' (see the ltxkeys package
for these facilities).

You can use #1 in <callback> to access the value of the current
key. Also the macros \currpref, \currfam, \currkey, \currval,
and \currkeyval are always available.

The following macros are utilities:

\kve@checkchoice{<teststring>}{<nominations>}{<nomatch>}

The <nominations> have the syntax

<nom-1>:<callback-1>,...,<nom-n>:<callback-n>

Here, <callback-i> will be executed if <nom-i> matches <teststring>.
The first match found takes priority over subsequent matches.

The action <nomatch> will be executed if <teststring> doesn't
match any of the <nom>'s.

\kve@checkbool{<val>}{<true>}{<false>}

This checks if <val> is an admissible value of a boolean,
namely, if it is in the set {true | false}. The text <true> will
be executed if <val> is valid; otherwise <false> will be executed.

\kve@keyvalerr

This is a parameterless command that uses \currkey and
\currval internally. It simply generates an error to indicate
that the current value of a key is invalid. It will indicate the
key name and the truncated version of the value that is invalid.

EXAMPLES

\kve@definekeys[KV]{fam}{%
  % keya and keyb are boolean keys:
  keya/true/\kve@checkbool{#1}{\def\result{OK}}\kve@keyvalerr,
  keyb/false/\kve@checkbool{#1}{\usename{@tempswa#1}}\kve@keyvalerr,
  % keyc is a choice key:
  keyc/left/\kve@checkchoice{#1}{left:\let\x\flushleft,
    right:\let\x\flushright}\kve@keyvalerr,
  keyone/+/\csn@def{mp@keyone}{#1},
  keytwo/+/\csn@def{mp@keytwo}{#1},
  keythree/+/\csn@def{mp@keythree}{#1},
  keyfour/+/\csn@def{mp@keyfour}{#1}
}

Now that the keys have been defined, set them with their default
values:

\kve@setdefaults[KV]{fam}

The following command says 'the current keys will be set with
the current values, after the defaults have been set up'. 
Keys with current values will not be set with their default values:

\def\mysetkeys#1{%
  \ifblankTF{#1}{}
  {\kve@setafterdefaults[KV]{fam}{#1}}%
}
\mysetkeys{keyone=+,keytwo=abc,keythree=+,keyfour=+}