Difference between revisions of "Commands with KeyVal arguments"
(formatting correction, no text change) |
(added texcode and cmd markup) |
||
| Line 1: | Line 1: | ||
< [[Inside ConTeXt]] | < [[Inside ConTeXt]] | ||
| − | |||
(a post on the mailing list by Taco Hoekwater from 2004-06-28:) | (a post on the mailing list by Taco Hoekwater from 2004-06-28:) | ||
The 'key' to the keyval functionality in ConTeXt are two macros called | The 'key' to the keyval functionality in ConTeXt are two macros called | ||
| − | < | + | <cmd>getparameters</cmd> and <cmd>processaction</cmd>. |
Here is a 'quickstart', assuming you want to define <tt>\MyZigzag</tt>: | Here is a 'quickstart', assuming you want to define <tt>\MyZigzag</tt>: | ||
| − | < | + | <texcode> |
\unprotect % enable exclamations in macro names | \unprotect % enable exclamations in macro names | ||
| Line 16: | Line 15: | ||
\getparameters[ZZ][Dir=,Linewidth=1pt,Color=Red,Width=3em,#2] | \getparameters[ZZ][Dir=,Linewidth=1pt,Color=Red,Width=3em,#2] | ||
| − | </ | + | </texcode> |
Now you have a set of new macros that all start with ZZ. | Now you have a set of new macros that all start with ZZ. | ||
| Line 23: | Line 22: | ||
Here's a usage example: | Here's a usage example: | ||
| − | < | + | <texcode> |
\edef\mywidth{\ZZWidth}% | \edef\mywidth{\ZZWidth}% | ||
| − | </ | + | </texcode> |
| − | If you want to use keyword values, then you also need to use < | + | If you want to use keyword values, then you also need to use <cmd>processaction</cmd>. |
Say you want "Dir" to be mandatory and that it accepts 4 directional keywords, as well as a direct angle specification. | Say you want "Dir" to be mandatory and that it accepts 4 directional keywords, as well as a direct angle specification. | ||
| Line 33: | Line 32: | ||
I've used all mixed case keywords, because otherwise you might run into conflicts with the multilingual interface | I've used all mixed case keywords, because otherwise you might run into conflicts with the multilingual interface | ||
| − | < | + | <texcode> |
\expandafter\processaction\expandafter[\ZZDir] | \expandafter\processaction\expandafter[\ZZDir] | ||
[Down =>\def\Dir{270}, | [Down =>\def\Dir{270}, | ||
| Line 42: | Line 41: | ||
\s!unknown =>\checkDir{\ZZDir}] | \s!unknown =>\checkDir{\ZZDir}] | ||
} % this brace belongs to \def! | } % this brace belongs to \def! | ||
| − | </ | + | </texcode> |
<tt>\s!default</tt> may be triggered because <tt>\ZZDir</tt>'s expansion is empty unless the user supplied something. | <tt>\s!default</tt> may be triggered because <tt>\ZZDir</tt>'s expansion is empty unless the user supplied something. | ||
| − | The first argument to | + | The first argument to <cmd>processaction</cmd> has to be expanded, so you need the <cmd>expandafter</cmd>s. |
for completeness, here is an example definition of <tt>\checkDir</tt> and <tt>\errorDir</tt>: | for completeness, here is an example definition of <tt>\checkDir</tt> and <tt>\errorDir</tt>: | ||
| − | < | + | <texcode> |
\def\errorDir{% | \def\errorDir{% | ||
\def\Dir{0}% error recovery | \def\Dir{0}% error recovery | ||
| Line 63: | Line 62: | ||
\protect % end of definitions | \protect % end of definitions | ||
| − | </ | + | </texcode> |
Revision as of 11:34, 2 September 2004
(a post on the mailing list by Taco Hoekwater from 2004-06-28:)
The 'key' to the keyval functionality in ConTeXt are two macros called \getparameters and \processaction.
Here is a 'quickstart', assuming you want to define \MyZigzag:
\unprotect % enable exclamations in macro names \def\MyZigzag#1[#2]{% % the #1 makes sure we allow a space before the bracket \getparameters[ZZ][Dir=,Linewidth=1pt,Color=Red,Width=3em,#2]
Now you have a set of new macros that all start with ZZ. At least there are \ZZDir,\ZZLinewidth, \ZZColor and \ZZWidth (these have default values) but possibly others as well, depending on user input.
Here's a usage example:
\edef\mywidth{\ZZWidth}%
If you want to use keyword values, then you also need to use \processaction.
Say you want "Dir" to be mandatory and that it accepts 4 directional keywords, as well as a direct angle specification.
I've used all mixed case keywords, because otherwise you might run into conflicts with the multilingual interface
\expandafter\processaction\expandafter[\ZZDir] [Down =>\def\Dir{270}, Left =>\def\Dir{180}, Up =>\def\Dir{90}, Right =>\def\Dir{0}, \s!default =>\errorDir, \s!unknown =>\checkDir{\ZZDir}] } % this brace belongs to \def!
\s!default may be triggered because \ZZDir's expansion is empty unless the user supplied something.
The first argument to \processaction has to be expanded, so you need the \expandafters.
for completeness, here is an example definition of \checkDir and \errorDir:
\def\errorDir{% \def\Dir{0}% error recovery \message{Please supply "Dir" argument}% } \def\checkDir#1{% \doifnumberelse {#1} {\def\Dir{#1}} {\message{Invalid "Dir" argument! (#1)}} } \protect % end of definitions
