Difference between revisions of "Commands with optional arguments"

From Wiki
Jump to navigation Jump to search
(corrected order of arguments, edited description for clarity)
m
(24 intermediate revisions by 12 users not shown)
Line 1: Line 1:
In LaTeX you define a new command with an optional argument with "newcommand":
+
< [[Inside ConTeXt]] | [[Commands with KeyVal arguments]] >
  
  \newcommand{\MyCommand}[2][World]{{#2Hello #1!}}
+
In ConTeXt, the optional argument processing is handled as a two-step process. First, we write the command for the end-user as a wrapper command, which calls {{cmd|dosingleempty}}, {{cmd|dodoubleempty}}, {{cmd|dotripleempty}}, ... (from {{src|syst-aux.mkiv}} or {{src|syst-gen.mkii}}) to handle the arguments properly -- including the optional ones -- and then calls a "private" command that contains the internals of the macro.  Note that this function call does not explicitly refer to the arguments at all.
\MyCommand{\bfseries}
 
\MyCommand[Hans]{\scshape}
 
  
ConTeXt:
+
For a command with two optional arguments, we use:
 +
<texcode>
 +
\def\MyCommand{\dodoubleempty\doMyCommand}
 +
</texcode>
  
There is perhaps a way to do the same. Otherwise, the key value method is preferred, see [[Define Commands]].
+
We then create the "private" macro (<tt>\doMacroName</tt> is the traditional ConTeXt name for these), with all the arguments defined as nonoptional. Default values for the arguments need to be handled somewhat more explicitly than with LaTeX; macros such as {{cmd|ifsecondargument}} are used to determine whether the given argument was specified, as follows:
  
----
+
<texcode>
 +
\def\doMyCommand[#1][#2]{#1Hello
 +
    \ifsecondargument
 +
      #2%
 +
    \else
 +
      World%
 +
    \fi
 +
    !}
 +
</texcode>
  
<i>The following is my understanding of how to do thisIt's currently untested; someone please test this and integrate it with the above. --[[User:Brooks|Brooks]]</i>
+
Note that this makes both arguments optional -- something that is much more difficult to do in LaTeX ([http://www.tex.ac.uk/cgi-bin/texfaq2html?label=twooptarg but can be done])This also means that we should reverse the order of arguments, since if the user specifies only one argument it will be treated as the first argument.
  
In ConTeXt, the optional argument processing is handled as a two-step process.  First, we write the command for the end-user as a wrapper command, which calls <tt>\dodoubleempty</tt> (from <tt>syst-gen.tex</tt>) to handle the arguments properly -- including the optional ones -- and then calls a "private" command that contains the internals of the macro.  Note that this function call does not explicitly refer to the arguments at all.
+
(Also, note that <tt>\MyCommand</tt> without the second argument ends up gobbling the following spaces, so we need to explicitly include one with "<tt>\ </tt>".)
  
\def\MyCommand{\dodoubleempty\doMyCommand}
+
<texcode>
 +
\MyCommand[\bf]\ %
 +
\MyCommand[\sc][Hans]
 +
</texcode>
  
We then create the "private" macro (<tt>\doMacroName</tt> is the traditional ConTeXt name for these), with all the arguments defined as nonoptional.  Default values for the arguments need to be handled somewhat more explicitly than with LaTeX; macros such as <tt>\ifsecondargument</tt> are used to determine whether the given argument was specified, as follows:
+
<context>
 
+
\def\MyCommand{\dodoubleempty\doMyCommand}
\def\doMyCommand[#1][#2]{#1Hello
+
\def\doMyCommand[#1][#2]{#1Hello
 
     \ifsecondargument
 
     \ifsecondargument
 
       #2%
 
       #2%
Line 26: Line 38:
 
     \fi
 
     \fi
 
     !}
 
     !}
 +
\MyCommand[\bf]\ %
 +
\MyCommand[\sc][Hans]
 +
</context>
 +
 +
If you ''don't'' want any optional arguments, but still want your arguments enclosed in <tt>[]</tt> with appropriate handling for spaces (or line breaks) between the square brackets, use {{cmd|dodoubleargument}} instead of {{cmd|dodoubleempty}}.  There are of course versions for other numbers of arguments, found by replacing <tt>double</tt> with <tt>single</tt> through <tt>seventuple</tt>; see {{src|syst-aux.mkiv}} for the exact names.
 +
 +
=== Examples ===
 +
 +
To define <code>\mycommand[#1]{#2}</code> with one optional argument and one mandatory argument, do the following
 +
<context source="yes">
 +
\def\mynewcommand{\dosingleempty\doMyNewCommand}
 +
\def\doMyNewCommand[#1]#2{%
 +
\iffirstargument
 +
  There is an optional parameter: {\bf #1}\par%
 +
\else
 +
  No optional parameter\par%
 +
\fi
 +
  This is the mandatory text: {\em #2}%
 +
}
 +
 +
\starttext
 +
\mynewcommand[opt]{Hello People}
 +
\blank
 +
\mynewcommand{Hello People}
 +
\stoptext
 +
</context>
 +
 +
 +
To define <code>\mycommand[#1][#2]{#3}</code> with two optional arguments and one mandatory argument, do
 +
 +
<texcode>
 +
\def\mycommand{\dodoubleempty\doMycommand}
 +
\def\doMycommand[#1][#2]#3{whatever}
 +
</texcode>
 +
 +
=== Pitfalls ===
 +
 +
Please keep in mind that <code>\iffirstargument</code> will always return true if you put before it a command which itself has an argument. See the following example:
 +
 +
<context source="yes" text="produces">
 +
\def\mynewcommand{\dosingleempty\doMyNewCommand}
 +
\def\doMyNewCommand[#1]#2{%
 +
\startalignment[center]
 +
\iffirstargument
 +
  There is an optional parameter: {\bf #1}\par%
 +
\else
 +
  No optional parameter\par%
 +
\fi
 +
  This is the mandatory text: {\em #2}%
 +
\stopalignment
 +
}
 +
\starttext
 +
\mynewcommand[opt]{Hello People}
 +
\blank
 +
\mynewcommand{Hello People}
 +
\stoptext
 +
</context>
 +
 +
Use <code>\doifsomethingelse</code> instead:
 +
 +
<context source="yes" text="this time is correct:">
 +
\def\mynewcommand{\dosingleempty\doMyNewCommand}
 +
\def\doMyNewCommand[#1]#2{%
 +
\startalignment[center]%
 +
\doifsomethingelse{#1}
 +
  {There is an optional parameter: {\bf #1}\par}
 +
  {No optional parameter\par}
 +
  This is the mandatory text: {\em #2}
 +
\stopalignment%
 +
}
 +
\starttext
 +
\mynewcommand[opt]{Hello People}
 +
\blank
 +
\mynewcommand{Hello People}
 +
\stoptext
 +
</context>
 +
  
Note that this makes both arguments optional -- something that is much more difficult to do in LaTeX.  This also means that we should reverse the order of arguments, since if the user specifies only one argument it will be treated as the first argument.
+
On a final note, for comparative purposes: in LaTeX, a new command with an optional argument is defined with <code>\newcommand</code>.
  
If you don't want any optional arguments, but still want your arguments enclosed in <tt>[]</tt> with appropriate handling for spaces (or line breaks) between the square brackets, use <tt>\dodoublearguments</tt> instead of <tt>\dodoubleempty</tt>.  There are of course versions for other numbers of arguments, found by replacing <tt>double</tt> with <tt>single</tt> through <tt>seventuple</tt>; see <tt>syst-gen.tex</tt> for the exact names.
+
<texcode>
 +
\newcommand{\MyCommand}[2][World]{{#2Hello #1!}}
 +
\MyCommand{\bfseries}
 +
\MyCommand[Hans]{\scshape}
 +
</texcode>
  
----
+
Reference:
 +
http://archive.contextgarden.net/message/20101215.225603.cc903e62.en.html
  
Also, does someone know how to define \mycommand[.1.][.2.]{.3.}?  E.g., with curly braces around a non-optional third argument?  I think this just involves adding a second, non-delimited argument to <tt>\doMyCommand</tt>, but I'm not sure.  Also, can someone test to see if <tt>\dosingleempty</tt> and <tt>\dosingleargument</tt> can be chained, to get only one optional square-bracketed argument?
+
[[Category:Programming and Databases]]
 +
[[Category:Tools]]

Revision as of 17:04, 8 June 2020

< Inside ConTeXt | Commands with KeyVal arguments >

In ConTeXt, the optional argument processing is handled as a two-step process. First, we write the command for the end-user as a wrapper command, which calls \dosingleempty, \dodoubleempty, \dotripleempty, ... (from syst-aux.mkiv or syst-gen.mkii) to handle the arguments properly -- including the optional ones -- and then calls a "private" command that contains the internals of the macro. Note that this function call does not explicitly refer to the arguments at all.

For a command with two optional arguments, we use:

\def\MyCommand{\dodoubleempty\doMyCommand}

We then create the "private" macro (\doMacroName is the traditional ConTeXt name for these), with all the arguments defined as nonoptional. Default values for the arguments need to be handled somewhat more explicitly than with LaTeX; macros such as \ifsecondargument are used to determine whether the given argument was specified, as follows:

 \def\doMyCommand[#1][#2]{#1Hello
    \ifsecondargument
       #2%
    \else
       World%
    \fi
    !}

Note that this makes both arguments optional -- something that is much more difficult to do in LaTeX (but can be done). This also means that we should reverse the order of arguments, since if the user specifies only one argument it will be treated as the first argument.

(Also, note that \MyCommand without the second argument ends up gobbling the following spaces, so we need to explicitly include one with "\ ".)

\MyCommand[\bf]\ %
\MyCommand[\sc][Hans]

If you don't want any optional arguments, but still want your arguments enclosed in [] with appropriate handling for spaces (or line breaks) between the square brackets, use \dodoubleargument instead of \dodoubleempty. There are of course versions for other numbers of arguments, found by replacing double with single through seventuple; see syst-aux.mkiv for the exact names.

Examples

To define \mycommand[#1]{#2} with one optional argument and one mandatory argument, do the following

\def\mynewcommand{\dosingleempty\doMyNewCommand}
\def\doMyNewCommand[#1]#2{%
 \iffirstargument
  There is an optional parameter: {\bf #1}\par%
 \else
  No optional parameter\par%
 \fi
  This is the mandatory text: {\em #2}%
}

\starttext
\mynewcommand[opt]{Hello People}
\blank
\mynewcommand{Hello People}
\stoptext


To define \mycommand[#1][#2]{#3} with two optional arguments and one mandatory argument, do

\def\mycommand{\dodoubleempty\doMycommand}
\def\doMycommand[#1][#2]#3{whatever}

Pitfalls

Please keep in mind that \iffirstargument will always return true if you put before it a command which itself has an argument. See the following example:

\def\mynewcommand{\dosingleempty\doMyNewCommand}
\def\doMyNewCommand[#1]#2{%
 \startalignment[center]
 \iffirstargument
  There is an optional parameter: {\bf #1}\par%
 \else
  No optional parameter\par%
 \fi
  This is the mandatory text: {\em #2}%
 \stopalignment
}
\starttext
\mynewcommand[opt]{Hello People}
\blank
\mynewcommand{Hello People}
\stoptext

produces

Use \doifsomethingelse instead:

\def\mynewcommand{\dosingleempty\doMyNewCommand}
\def\doMyNewCommand[#1]#2{%
 \startalignment[center]%
 \doifsomethingelse{#1}
   {There is an optional parameter: {\bf #1}\par}
   {No optional parameter\par}
  This is the mandatory text: {\em #2}
 \stopalignment%
}
\starttext
\mynewcommand[opt]{Hello People}
\blank
\mynewcommand{Hello People}
\stoptext

this time is correct:


On a final note, for comparative purposes: in LaTeX, a new command with an optional argument is defined with \newcommand.

\newcommand{\MyCommand}[2][World]{{#2Hello #1!}}
\MyCommand{\bfseries}
\MyCommand[Hans]{\scshape}

Reference: http://archive.contextgarden.net/message/20101215.225603.cc903e62.en.html