summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/skeyval/README
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/skeyval/README')
-rw-r--r--Master/texmf-dist/doc/latex/skeyval/README200
1 files changed, 165 insertions, 35 deletions
diff --git a/Master/texmf-dist/doc/latex/skeyval/README b/Master/texmf-dist/doc/latex/skeyval/README
index fe6e31d7d37..5a43e018146 100644
--- a/Master/texmf-dist/doc/latex/skeyval/README
+++ b/Master/texmf-dist/doc/latex/skeyval/README
@@ -6,7 +6,7 @@ Ahmed Musa
VERSION
-Version 1.1, October 2012.
+Version 1.1a, October 16, 2012.
LOCATION ON CTAN
@@ -47,8 +47,8 @@ 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.
+Users of pre-version-1.0 of skeyval package can access the former
+version 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.
@@ -84,11 +84,11 @@ 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
+** 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
+** 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}}
@@ -112,12 +112,44 @@ of the functionality of skeyval package are
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:
+** Handlers
+
+ The skeyval package has many handlers. The handlers of
+ start with a dot (.), as in pgfkeys package.
+
+ Unlike in pgfkeys package, when 'expand' or 'expanded'
+ is found in a handler, the expansion will invariably be done
+ when the key is set, not when it's being defined.
+
+
+** Subject-observer keys (called 'style keys' in pgfkeys) can be readily
+ introduced.
+
+ \skvappendstyles[KV]{fam}{key1,key2}{keya=.expanded{\vala},keyb=valb}
+ [defaultof 1&2]{\def\y##1{#1*##1}}
+
+ Here the subjects are key1 and key2, while the observers are keya and
+ keyb. For now, the only thing the subject does is to set the given values
+ of the observers on the current path. In the future, we intend to extend
+ the subject-observer functionality to include more features of the
+ observer pattern found in other programming paradigms. We foresee that
+ subjects will be able to publish their services, and observer keys will be
+ able to subscribe for notification from subjects. And rather than 'notify
+ messages' simply setting observer keys with prior prescribed observer
+ values, as is currently the obtainable, observers may be able to do more
+ with such messages (such as change observer state patterns).
+
+** The parameters/arguments of callbacks of keys can be easily changed
+ by calling \skvdefinekeys, \skvmakekeys, \skvassignargs or \directkeys.
+
+ \skvordkeys[KV1]{fam2}{keya,keyb}[default-a]{\def\x##1{#1*##1}}
+ \skvassignargs[KV1,KV2]{fam1,fam2}[x1]{keya,keyb}{#1/#2}
+ \skvsetkeys[KV1]{fam2}{keya=vala/valb}
+
+ 'x1' here means expand argument once at setting keys.
\directkeys{%
- .exec=\def\avalue{a+b},
+ .exec code=\def\avalue{a+b},
.prefixes={KV1,KV2},
.families={fam1,fam2},
.holder prefix=mp@,
@@ -134,12 +166,18 @@ of the functionality of skeyval package are
.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:
+
+** Nested \directkeys. The current path is put on stack
+ and restored later, so that the nest is independent
+ of its surrounding topology (prefix and family). But
+ the default prefix survives outside \directkeys.
+
\directkeys{
- .path=KV3/fam3,
+ .default prefix=KV,
+ % The prefix for 'famx' will be 'KV'.
+ .paths={KV3/fam3,famx},
.new keys={
+ .initialize keys after define=false,
.ord/keya/defa/\def\ya##1{#1*##1*#2},
.arg/keya/#1+#2,
.choice/keyc/center/{right,left,center,justified},
@@ -150,9 +188,9 @@ of the functionality of skeyval package are
},
.try set keys={
.paths={KV1/fam1,KV3/fam3},
- .try=2, .goal=1
- }{
- keyc=left,keyd=false
+ .try=2,
+ .goal=1,
+ .kv list={keyc=left,keyd=false},
},
.ignore path=KV1/fam1,
.exec=\def\cvalue{center},
@@ -160,8 +198,7 @@ of the functionality of skeyval package are
.add prefix=KV3,
.add families={fam3,fam4},
.max attempts=4, .goal=2,
- }{
- keyc=.expand once{\cvalue}
+ .kv list={keyc=.expand once{\cvalue}},
},
.append values={
keya=\def\y##1{#1+##1},
@@ -182,14 +219,24 @@ of the functionality of skeyval package are
},
}
- 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.
+** Prepending and appending to key names and callbacks at
+ definition time:
+
+ \directkeys*{
+ .path=claudio/color,
+ .hp=claudio@col@,
+ .define keys={
+ .prepend to every key name=X@,
+ .append to every key name=@Y,
+ .prepend to every callback=\def\X##1{#1*##1},
+ .append to every callback=\def\Y##1{##1**#1},
+ .ord/{1,2,3,4,5,6}/red,
+ }
+ }
+ \skvusekeys[.path=claudio/color]{X@1@Y,X@2@Y}
- The handlers of skeyval package start with a dot (.),
- as in pgfkeys package.
-4. Several new features are introduced by the skeyval package. For
+** 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:
@@ -200,23 +247,79 @@ of the functionality of skeyval package are
.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},
+ .allowed values expanded=keye/{
+ center.do=\def\curralign##1{\hfil##1\hfil},
+ right.do=\def\curralign##1{\hfill##1},
+ left.do=\def\curralign##1{##1\hfill},
+ justified.do=\let\curralign\@iden
+ },
+ }
+
+** Bipolar boolean keys
+
+ \skvbiboolkeys[KV]{fam}[mp@]{.forbid value{keya},keyb}[true]{%
+ \ifmp@keya\def\xa##1{##1}\fi
+ }{%
+ \ifmp@keyb\def\xb##1{##1}\fi
+ }%
+ \skvsetkeys[KV]{fam}{keya}
+
+ The value of keya is frozen as 'true'. Hence whenever keya is called,
+ the value 'true' will be used for it. Since keya and keyb are bipolar,
+ the value of keyb will be 'false' whenever keya is called.
+
+ \skvbiboolkeys+[KV]{fam}[mp@]{keya,keyb}[true]{%
+ \ifmp@keya\def\xa##1{##1}\fi
+ }{%
+ \ifmp@keyb\def\xb##1{##1}\fi
+ }{%
+ \skv@warn{Value '#1' is invalid}%
}
+ \skvsetkeys[KV]{fam}{keya=xtrue}
-5. The concepts of 'trying' to set a key with 'goals' is introduced.
+
+** 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.
+ but applied to setting a key. See an example above. Then there
+ is 'search also' set keys.
+
+** 'Quick keys' are a new concept. They're quite fast to define and set,
+ but they can't carry pointers.
+
+ \quickkeys.define{<family>}[<holder.prefix>]{<list>}
+ \quickkeys.set{<family>}[<na>]{<kvlist>}
+
+ When defining keys, the syntax of <list> is:
+
+ {<keya-1,...,keya-n>}/{<default>}/{<callback>}/{<nominations>}/{<arg>}
+ ;...;
+ {<keyx-1,...,keyx-n>}/{<default>}/{<callback>}/{<nominations>}/{<arg>}
+
+ Example:
+
+ \quickkeys.define{fam}[mp@]{%
+ keya/true/\def\x##1{#1*##1}/true,false;
+ keyb;
+ keyc,keyd/aaa+bbb/\def\y##1{#1*##1*#2}/.na/#1+#2;
+ }
-6. 'Quick keys' are a new concept. They're quite fast to define and set.
+ '.na' means a missing entry that isn't empty but should be ignored.
-7. Keys can be 'made', as in
+ <nominations> can be used to restrict the user-values of the key
+ or keys.
+
+ <arg> means the argument pattern for the key or keys.
+
+
+** 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}/,
+ .ord/{keya,keyb}/{default-a},
+ .arg/keyb/{#1+#2},
+ .cmd/{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},
@@ -228,7 +331,7 @@ of the functionality of skeyval package are
without spaces in their names, while maintaining key names with
spaces.
-8. Keys can be set using \skvsetkeys, \directkeys (with the handlers
+** Keys can be set using \skvsetkeys, \directkeys (with the handlers
.set keys, .try, etc.), or \skvusekeys:
\krdusekeys[
@@ -240,14 +343,41 @@ of the functionality of skeyval package are
keya,keyb
}
-9. Keys defined in families can be viewed in files using the package
+ \directkeys*{
+ .path=user/color,
+ .hp=user-col-,
+ .define keys={
+ .cmd/{1,2,3,4,5,6}/red
+ }
+ }
+ \newcommand*\setcolorlist[1]{\skvusekeys[.path=user/color]{#1}}
+ \setcolorlist{1=red,2=blue,3=cyan,4=green,5=magenta,6=purple}
+ \newcommand*\usecolor[1]{%
+ \skvifcsname user-col-#1\then
+ \csname user-col-#1\endcsname
+ \else
+ black%
+ \fi
+ }
+ \newcommand*\drawcoloredarrows[1]{%
+ \foreacfox {#1}{%
+ \draw[\usecolor{##1},-stealth] (0,-##1)--(2,-##1);
+ }
+ }
+ \begin{document}
+ \begin{tikzpicture}
+ \drawcoloredarrows{1,...,4}
+ \end{tikzpicture}
+ \end{document}
+
+** 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
+** 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
+** 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