Difference between revisions of "System Macros/Definitions and Assignments"

From Wiki
Jump to navigation Jump to search
(Added the second part of Key_Val_Assignments, fit better here)
m (Basic navigation)
Line 1: Line 1:
[[System_Macros]]
+
< '''Prev:''' [[System Macros/Handling Arguments|Handling Arguments]] | '''Top:''' [[System Macros]] | '''Next:''' [[System Macros/Branches and Decisions|Branches & Decisions]] >
  
 
TeX's primitive <code>\csname</code> can be used to construct all kind of commands that cannot be defined with <code>\def</code> and <code>\let</code>. Every macro programmer sooner or later wants macros like these.
 
TeX's primitive <code>\csname</code> can be used to construct all kind of commands that cannot be defined with <code>\def</code> and <code>\let</code>. Every macro programmer sooner or later wants macros like these.
Line 198: Line 198:
  
 
Just as their <code>[]</code>, they also set the <code>\ifXXXXargument</code> switches.
 
Just as their <code>[]</code>, they also set the <code>\ifXXXXargument</code> switches.
 +
 +
< '''Prev:''' [[System Macros/Handling Arguments|Handling Arguments]] | '''Top:''' [[System Macros]] | '''Next:''' [[System Macros/Branches and Decisions|Branches & Decisions]] >
 +
 +
[[Category:System Macros]]
 +
[[Category:ConTeXt programming]]

Revision as of 01:22, 2 August 2006

< Prev: Handling Arguments | Top: System Macros | Next: Branches & Decisions >

TeX's primitive \csname can be used to construct all kind of commands that cannot be defined with \def and \let. Every macro programmer sooner or later wants macros like these.

\setvalue   {name}{...} = \def\name{...}
\setgvalue  {name}{...} = \gdef\name{...}
\setevalue  {name}{...} = \edef\name{...}
\setxvalue  {name}{...} = \xdef\name{...}
\letvalue   {name}=\... = \let\name=\...
\getvalue   {name}      = \name
\resetvalue {name}      = \def\name{}

As we will see, ConTeXt uses these commands many times, which is mainly due to its object oriented and parameter driven character.

The next macro can be very useful when using \csname like in:

\csname if\strippedcsname\something\endcsname

This expands to \ifsomething.

Setups can be optional. A command expecting a setup is prefixed by \complex, a command without one gets the prefix \simple. Commands like this can be defined by:

\complexorsimple\command

When \command is followed by a [setup], then

\complexcommand [setup]

executes, else we get

\simplecommand

An alternative for \complexorsimple is:

\complexorsimpleempty {command}

Depending on the presence of [setup], this one leads to one of:

\complexcommando [setup]
\complexcommando []

Many ConTeXt commands started as complex or simple ones, but changed into more versatile (more object oriented) ones using the \get...argument commands later in their existence.

The previous commands are used that often that we found it worthwile to offer two more alternatives.

These commands are called as:

\definecomplexorsimple\command

Of course, we must have available

\def\complexcommand[#1]{...}
\def\simplecommand {...}

Using this construction saves a few strings now and then.

We won't go into details here, but the general form of this using this command is:

\definestartstopcommand\somecommand\e!specifier{arg}{arg}%
  {do something with arg}

This expands to something like:

\def\somecommand arg \startspecifier arg \stopspecifier%
  {do something with arg}

The arguments can be anything reasonable, but double #'s are needed in the specification part, like:

\definestartstopcommand\somecommand\e!specifier{[##1][##2]}{##3}%
  {do #1 something #2 with #3 arg}

which becomes:

\def\somecommand[#1][#2]\startspecifier#3\stopspecifier%
  {do #1 something #2 with #3 arg}

Actually, this macro is never used in ConTeXt, but it used to be part of constructions like \placeformula.

When working with delimited arguments, spaces and lineendings can interfere. The next set of macros uses TeX' internal scanner for grabbing everything between arguments. Forgive me the funny names.

\dosingleargument\command     = \command[#1]
\dodoubleargument\command     = \command[#1][#2]
\dotripleargument\command     = \command[#1][#2][#3]
\doquadrupleargument\command  = \command[#1][#2][#3][#4]
\doquintupleargument\command  = \command[#1][#2][#3][#4][#5]
\dosixtupleargument\command   = \command[#1][#2][#3][#4][#5][#6]
\doseventupleargument\command = \command[#1][#2][#3][#4][#5][#6][#7]

These macros are used in the following way:

\def\docommand[#1][#2]%
  {... #1 ... #2 ...}

\def\command%
  {\dodoubleargument\docommand}

So \dodoubleargument leads to:

\docommand[#1][#2]
\docommand[#1][]
\docommand[][]

The macros above insure that the resulting call always has the correct number of bracket pairs, even if the user did not supply all of the options. In this case, a number of trailing bracket pairs are empty. A set of related \if booleans is initialized to give you access to the number of user supplied parameters.

These maybe too mysterious macros enable us to handle more than one setup at once.

\dosingleargumentwithset \command[#1]
\dodoubleargumentwithset \command[#1][#2]
\dotripleargumentwithset \command[#1][#2][#3]
\dodoubleemptywithset    \command[#1][#2]
\dotripleemptywithset    \command[#1][#2][#3]

The first macro calls \command[##1] for each string in the set #1. The second one calls for \commando[##1][#2] and the third, well one may guess. These commands support constructions like:

\def\dodefinesomething[#1][#2]%
  {\getparameters[\??xx#1][#2]}

\def\definesomething%
  {\dodoubleargumentwithset\dodefinesomething}

Which accepts calls like:

\definesomething[alfa,beta,...][variable=...,...]

Now a whole bunch of variables like \@@xxalfavariable and \@@xxbetavariable is defined.

We've already seen some commands that take care of optional arguments between [].

The next two commands handle the ones with {}. They are called as:

\dosinglegroupempty    \ineedONEargument
\dodoublegroupempty    \ineedTWOarguments
\dotriplegroupempty    \ineedTHREEarguments
\doquadruplegroupempty \ineedFOURarguments
\doquintuplegroupempty \ineedFIVEarguments

where \ineedONEargument takes one and the others two and three arguments, et cetera.

These macros were first needed in ppchTeX. At first glance, the functionality sounds trivial. But in fact, it is not. Consider this expanded input:

\def\test#1{\message{#1}}
\dosinglegroupempty\test {a}Text
\dosinglegroupempty\test Text

In the last line, #1 will not print the letter T, as would be 'normal' TeX behaviour. These macros can explictly take care of spaces, which means that the next definition and calls are valid:

\dotriplegroupempty\test {a} {b} {c}
\dotriplegroupempty\test {a} {b}
\dotriplegroupempty\test
{a}
{b}

And alike.

Just as their [], they also set the \ifXXXXargument switches.

< Prev: Handling Arguments | Top: System Macros | Next: Branches & Decisions >