CTAN Comprehensive TeX Archive Network

Directory macros/latex/contrib/skeyval

This is the README file for the 'skeyval' package.


Ahmed Musa


Version 1.3, 2013/05/15.




The package integrates the features of xkeyval and of pgfkeys by
introducing a new set of handlers. Style keys, links, changing
key callbacks and values on the fly, and other features of pgfkeys
are introduced in a new context.


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


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,
  skeyval-testpkg.sty, skeyval-pokayoke1.tex, skeyval-pokayoke2.tex,

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


or, in class files and packages,


Plain TeX users can do

    \input skeyval-core

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. Please accept my sincere apologies for making
changes to the implementation and command names without renaming
the package. I hate the practice of creating many forks of the same
package, irrespective of the fact that forking a package is rather
a standard practice in LaTeX.


The 's' in skeyval means 'skeleton' 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 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 required search overhead isn't insignificant.

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 xkeyval and ltxkeys packages.

Some of the features of skeyval vs. xkeyval are as follows. All the
features listed below could be incorporated in xkeyval package but
at a great expense.

* xkeyval's use of the rather expensive selective sanitization
   scheme of Uwe Kern;

* xkeyval strips three levels of outer braces in the values of keys;

* the impossibility of parsing unbalanced conditionals in key values
   while using xkeyval;

* xkeyval requires a large payload for defining many keys in the
   same family;

* when using xkeyval, existing keys could be easily overridden
   (there is nothing like \newcommand functionality);

* key macros, once defined by xkeyval, are difficult to modify/patch;

* key macros defined by xkeyval can't accept more than one argument;

* xkeyval provides no machinery for deploying style (subject/observer)

* xkeyval offers no direct tools for key-commands and key-environments;

* xkeyval can't be loaded before \documentclass (eg, in the past the
   fontspec package needed this feature);

* skeyval offers 'list processor keys' (called 'listkeys').

Very few examples of the functionality of skeyval package are given in
the following.

**  Ordinary, command/store, boolean, toggle, and choice keys can be
    defined and set. For example,

    \skvordkeys[KV]{fam}{key1,key2}[default value]{%


**  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}]{%

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

      evaluate (\x) as (\pgfmathresult) using (\pgfmathparse{\x^10})

**  Default prefix can be set by


    For a fixed prefix, this can be used to avoid repeated entry of the
    key prefix in many of the commands of the skeyval package. Note,
    however, that the first '[]' in

    \skvordkey[KV]{fam}{key1}[deafult value]{}

    still can't be used for any other thing than the key prefix.



    we can do


    and much later


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

**  Handlers

    The skeyval package has many handlers. The handlers of skeyval package
    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

     [default of key1&2]{\def\y##1{#1*##1}}

    Here the subjects/observable 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 having
    'notify messages' simply setting observer keys with prior prescribed
    observer values, which is what is currently 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.


** \directkeys command:

      .exec code=\def\avalue{a+b},
      .holder prefix=mp@,
      .initialize keys after define,
      .define keys={
          .cmd/.value required{keyb}/def-b/\def\cmdb##1{##1@#1},
      .initial values={
      .ignore family=fam2,
      .set keys={

**  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.

          .default prefix=KV,
          % The prefix for 'famx' will be 'KV'.
          .new keys={
            .initialize keys after define=false,
            .arg expanded/keyc/#1,
            .cmd/.forbid value{keye}/defe/\def\ye##1{#1*##1},
      .try set keys={
          .kv list={keyc=left,keyd=false},
      .ignore path=KV1/fam1,
      .search also set keys={
          .add prefix=KV3,
          .add families={fam3,fam4},
          .max attempts=4, .goal=2,
          .kv list={keyc=.expand once{\cvalue}},
      .append values={
      .prepend code={
      .inherit code={
          key1/keyb, key2/keyd
      .preset keys={

**  Handlers and letting handlers

    The skeyval has many handlers and many tools for creating handlers.
    A full listing of handlers and their meaning will be provided in
    the user manual.

    .define handlers, .define handler
    .new handlers, .new handler
    .new reserved handlers, .new reserved handler,
        .define reserved handlers, .define reserved handler
    .define narg handler,.define narg handlers
    .new narg handler,.new narg handlers
    .new reserved narg handler,.new reserved narg handlers,
        .define reserved narg handler,.define reserved narg handlers
    .handlers let, .handler let
    .handlers let*, .handler let*, .force handler let
    .handlers let reserved, .handler let reserved
    .reserve handlers

**  Prepending and appending to key names and callbacks at
    definition time:

      .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},

**  Several new features are introduced by the skeyval package. For
    example, we now have 'slot' and 'link' keys. For example, to link
    keys via .link or .slot handler, we can do:

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

**  Bipolar boolean keys

    \skvbiboolkeys[KV]{fam}[mp@]{.forbid value{keya},keyb}[true]{%

    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.

      \skv@warn{Value '#1' is invalid}%

**  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.

**  'Quick keys' are a new concept. They're quite fast to define and set,
    but they can't carry pointers.


    When defining keys, the syntax of <list> is:




    '.na' means a missing entry that isn't empty but should be ignored.

    <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

      .holder prefix=mp@,
      .all are new,
      .define in all families,
      .initialize after define
      .zcmd/key e/\def\cmde##1{##1}/
        \edef\y{\detokenize\expandafter{\thp@keye}}\def\x##1{#1*key e*##1},
      .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

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

      .set in all families,
      .save unknown keys

      .define keys={
      \skvifcsname user-col-#1\then
        \csname user-col-#1\endcsname
      \foreachfox {#1}{%
        \draw[\usecolor{##1},-stealth] (0,-##1)--(2,-##1);

**  Arguments of keys:

    Argument of keys can be prescribed

    1. Within the key's callback by using the pointers

        .arg, .arg unexpanded, .arg expand once, .arg expand twice,
        .arg expanded.


          Using \ifskvnovalue default\else user \fi value of `\skvcurrentkey'.
          Argument-2 of key: #2%
        % Test arguments given inside the callback:
          .arg expanded{#1/#2}%
        \def\aval{blue/Some stuff}

    2. By calling the command \skvassignargs.

    3. By using the following handlers within \directkeys or within

        .arg, .arg unexpanded, .arg expand once, .arg expand twice,
        .arg expanded

**  Listkeys

    List processor keys. The key's value is considered a csv list
    and each of its element is used as the argument of the key's callback.
    The user of a listkey doesn't have to define his own list processor,
    or define one key for each list item. The list separator can be
    arbitrary; it can be specified in the key's callback as the
    argument of the dummy commands \listsep and \listparser. The default
    list separator is comma (,).

          Using default value of `\skvcurrentkey':
          Using user value of `\skvcurrentkey':
      Processing item no. \skvlistcount: #2%

    % Use comma (,), the default list separator, as the list
    % separator for keya and keyb:
      % Process only four (4) items of the list/value for keya and keyb:

    % Use semicolon (;) as the list separator for keyc and keyd:
      % The next line gives error, as expected, since a list key
      % can't have an assigned argument that isn't simple.
      % .arg{#1,#2}%

    % No values for keya and keyb; use their default values:
    % Set keyc and keyd with their default values:

**  Make any key a listkeys at key-setting time

    You can use the pointers '.process list' on any key's value at
    key-setting time to temporarily turn that key into a listkey.
    Its current value will be processed as a list, ie, the key's
    callback will be applied to every element of the current value.
    This scheme is costlier than defining the key as a listkey,
    using \skvlistkey, but it is more versatile. This allows any
    key to accept and process a value that is a list, irrespective
    of its argument pattern.

    Example 1:

      key1=val1,key2=.process list{val2a,val2b}

    Example 2:

      .arg expanded{#1/#2}%
      % Because of '.arg expanded' in the key's callback, \aval
      % will be expanded at setting keys:
      % \bval will be expanded before its content is processed
      % as a list. Because of '.arg expanded' in the key's callback,
      % each element in \bval will be expanded at setting keys:
      key2=.expand once process list{\bval}

    Example 3:

      key1=.expand once process list{\aval},
      key1=.expand twice process list{\bval},
      key1=.expand process list{\cval}

**  Disabling keys:

    Message type to be issued when a disabled key is called:

    \skvmessagetypefordisabledkey{<message type>}

    <message type> can be 'warning', 'error', or 'nothing'. The default is

    The key(s) may be disabled long before \skvmessagetypefordisabledkey
    is called.

    Disabling keys locally:

    \skvdisablekeys[<pref>]{<fam>}{<key list>}

    Disabling keys globally:

    \skvgdisablekeys[<pref>]{<fam>}{<key list>}

**  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.

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

**  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.

**  For a package 'foobar', you can access its options by

    \csname opt@foobar.sty\endcsname

    To get the options that were actually found/defined and instantiated
    during the processing of options, the skeyval package offers
    \skvpackagelist and '.poxkeys' (processed options).

    If 'option1' and 'option2' (but not 'option3') are recognized
    options of foobar.sty, then after


    you can issue

    \show\skvpackagelist -> foobar.sty{option1,option2}

    \expandafter\show\csname foobar.sty.poxkeys\endcsname
        -> option1, option2

**  Key filtering

    The handlers for key filtering are

    .prefix, .change prefix, .family, .change family, .families,
    .change families, .add family, .add families, .ignore family,
    .ignore families, .restore family, .restore families, .paths,
    .change path, .change paths, .add paths, .ignore paths, .restore paths,
    .ignore keys, .restore keys

        \@@warning{\noexpand\storecontent is empty}%
      % Define keys in two families:
      .define ordinary keys={
          \@@warning{No token '\detokenize{#1}' in command \string\storecontent}
    \def\showfam{Family: \skvcurrentfamily\savpar}

      % Set keys in only family1:
      .set keys={
        store={\showfam first test\bigvskip},
        store={\showfam second test\bigvskip}
      .exec code=\usecontent{\color{red}\savpar\hrule\bigvskip},
      % Set keys in only family2:
      .set keys={
        remove={\showfam first test\bigvskip},
        remove={\showfam second test\bigvskip},
        store={\showfam third test\bigvskip},
        store={\showfam fourth test\bigvskip}
      .exec code=\usecontent

**  Inheritance of keys

    There are \skvkeyslet with the syntax

      <list> -> {<newkey1>,<newkey2>,...,<newkey-n>}={<oldkey>}

    and the handler .inherit.

      .define ordinary keys={

**  Defining and setting keys on fixed prefix and family


% End of readme file

Download the contents of this package in one zip archive (491.5k).

skeyval – Key-value parsing combining features of xkeyval and pgfkeys

The package integrates the features of xkeyval and of pgfkeys by introducing a new type of handlers. Style keys, links, changing key callbacks and values on the fly, and other features of pgfkeys are introduced in a new context.

LicensesThe Project Public License 1.3
Copyright2010–2012 Ahmed Musa
MaintainerAhmed Musa
Contained inTeX Live as skeyval
MiKTeX as skeyval
See alsoskeycommand
Guest Book Sitemap Contact Contact Author