Difference between revisions of "Commands with KeyVal arguments"

From Wiki
Jump to navigation Jump to search
(replace [cmd]...[/cmd] with cmd:... wikilinks, as the showcommand Javascript doesn't work.)
(Make text more explanatory)
Line 6: Line 6:
 
[[cmd:getparameters|\getparameters]] and [[cmd:processaction|\processaction]].
 
[[cmd:getparameters|\getparameters]] and [[cmd:processaction|\processaction]].
  
Here is a 'quickstart', assuming you want to define <tt>\MyZigzag</tt>:
+
Here is a 'quickstart', assuming you want to define <tt>\MyZigzag</tt>. The code example is interrupted with explantory running text.
  
 
<texcode>
 
<texcode>
 
\unprotect % enable exclamations in macro names
 
\unprotect % enable exclamations in macro names
  
\def\MyZigzag#1[#2]{%  
+
\def\MyZigzag#1[#2]{% % This brace is closed below, after the \expandafter block
 
   % the #1 makes sure we allow a space before the bracket
 
   % the #1 makes sure we allow a space before the bracket
  
Line 18: Line 18:
  
 
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.
At least there are <tt>\ZZDir</tt>,<tt>\ZZLinewidth</tt>, <tt>\ZZColor</tt> and <tt>\ZZWidth</tt> (these have default values) but possibly others as well, depending on user input.
+
At least there are <tt>\ZZDir</tt>,<tt>\ZZLinewidth</tt>, <tt>\ZZColor</tt> and <tt>\ZZWidth</tt> (these have default values) but possibly others as well, depending on user input. In the next lines you make use of these variables, for example as follows:   
 
 
Here's a usage example:  
 
   
 
 
<texcode>
 
<texcode>
 
  \edef\mywidth{\ZZWidth}%
 
  \edef\mywidth{\ZZWidth}%
 
</texcode>
 
</texcode>
  
If you want to use keyword values, then you also need to use [[cmd:processaction|\processaction]].
+
If you want some of the variables to accept keyword values, then you also need to use [[cmd:processaction|\processaction]] on the ZZ variable in question to map the keywords onto actual values.
 
 
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
+
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:
  
 
<texcode>
 
<texcode>

Revision as of 11:22, 29 January 2012

< Inside ConTeXt

(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. The code example is interrupted with explantory running text.

\unprotect % enable exclamations in macro names

\def\MyZigzag#1[#2]{% % This brace is closed below, after the \expandafter block
  % 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. In the next lines you make use of these variables, for example as follows:

 \edef\mywidth{\ZZWidth}%

If you want some of the variables to accept keyword values, then you also need to use \processaction on the ZZ variable in question to map the keywords onto actual values.

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