Defining command with optional and mandatory arguments

Defining command with optional and mandatory arguments

[Christoph Reller]

On Wed, 23 May 2018 16:01:05 +0200, Hans Hagen <j.hagen@xs4all.nl> wrote:
>
> On 5/23/2018 3:39 PM, Christoph Reller wrote:
>> Hi,
>>
>> What is the right way to define a command with both mandatory and
>> optional arguments, e.g:
>>
>> \MyCommand[optional][mandatory]
>>
>> Consider the following MWE:
>>
>> \unexpanded\def\MyCommand[#1]{
>>    \dosingleempty{\doMyCommand[#1]}}
>> \def\doMyCommand[#1][#2]{
>>    \doifsomething{#1}{number 1: #1\par}
>>    \doifsomething{#2}{number 2: #2}\blank[big]}
>> \starttext
>> \MyCommand[A][B]
>> \MyCommand[A]
>> \stoptext
>>
>> In last year's versions of ConTeXt the output was
>>
>> number 1: A
>> number 2: B
>> number 1: A
>>
>> In the latest version of ConTeXt the output is
>>
>> number 1: A
>> number 2: B
>> number 2: A
>>
>> Is this behavior intended? How can I make a definition whose behavior
>> does not change in new versions of ConTeXt?
> i'm not sure wht happens at your end but this is the best way:
>
> \unexpanded\def\MyCommand
>    {\dodoubleempty\doMyCommand}
>
> \def\doMyCommand[#1][#2]%
>    {\iffirstargument
>       number 1: #1%
>       \par
>     \fi
>     \ifsecondargument
>       number 2: #2%
>     \fi
>     \blank[big]}
>
> \starttext
>      \MyCommand[A][B]
>      \MyCommand[A]
> \stoptext

Thank you Hans for this information. My question is rather about error
handling. I want:

\MyCommand[A][B] % <- succeeds with #1->A, #2->B
\MyCommand[A] % <- succeeds with #1->A
\MyCommand % <- fails with "! Use of \MyCommand doesn't match its definition"

I just wanted to ask whether there is a standard way to achieve this
with \do<whatever>empty. If not, then this is also okay.

Cheers,
Christoph
___________________________________________________________________________________
If your question is of interest to others as well, please add an entry to the Wiki!

maillist : ntg-context@ntg.nl / http://www.ntg.nl/mailman/listinfo/ntg-context
webpage  : http://www.pragma-ade.nl / http://context.aanhet.net
archive  : https://bitbucket.org/phg/context-mirror/commits/
wiki     : http://contextgarden.net
___________________________________________________________________________________

Re: Defining command with optional and mandatory arguments

[Hans Hagen]

On 5/24/2018 11:21 AM, Christoph Reller wrote:
> On Wed, 23 May 2018 16:01:05 +0200, Hans Hagen <j.hagen@xs4all.nl> wrote:
>>
>> On 5/23/2018 3:39 PM, Christoph Reller wrote:
>>> Hi,
>>>
>>> What is the right way to define a command with both mandatory and
>>> optional arguments, e.g:
>>>
>>> \MyCommand[optional][mandatory]
>>>
>>> Consider the following MWE:
>>>
>>> \unexpanded\def\MyCommand[#1]{
>>>     \dosingleempty{\doMyCommand[#1]}}
>>> \def\doMyCommand[#1][#2]{
>>>     \doifsomething{#1}{number 1: #1\par}
>>>     \doifsomething{#2}{number 2: #2}\blank[big]}
>>> \starttext
>>> \MyCommand[A][B]
>>> \MyCommand[A]
>>> \stoptext
>>>
>>> In last year's versions of ConTeXt the output was
>>>
>>> number 1: A
>>> number 2: B
>>> number 1: A
>>>
>>> In the latest version of ConTeXt the output is
>>>
>>> number 1: A
>>> number 2: B
>>> number 2: A
>>>
>>> Is this behavior intended? How can I make a definition whose behavior
>>> does not change in new versions of ConTeXt?
>> i'm not sure wht happens at your end but this is the best way:
>>
>> \unexpanded\def\MyCommand
>>     {\dodoubleempty\doMyCommand}
>>
>> \def\doMyCommand[#1][#2]%
>>     {\iffirstargument
>>        number 1: #1%
>>        \par
>>      \fi
>>      \ifsecondargument
>>        number 2: #2%
>>      \fi
>>      \blank[big]}
>>
>> \starttext
>>       \MyCommand[A][B]
>>       \MyCommand[A]
>> \stoptext
> 
> Thank you Hans for this information. My question is rather about error
> handling. I want:
> 
> \MyCommand[A][B] % <- succeeds with #1->A, #2->B
> \MyCommand[A] % <- succeeds with #1->A
> \MyCommand % <- fails with "! Use of \MyCommand doesn't match its definition"
> 
> I just wanted to ask whether there is a standard way to achieve this
> with \do<whatever>empty. If not, then this is also okay.
just use \dodoubleempty instead



-----------------------------------------------------------------
                                           Hans Hagen | PRAGMA ADE
               Ridderstraat 27 | 8061 GH Hasselt | The Netherlands
        tel: 038 477 53 69 | www.pragma-ade.nl | www.pragma-pod.nl
-----------------------------------------------------------------
___________________________________________________________________________________
If your question is of interest to others as well, please add an entry to the Wiki!

maillist : ntg-context@ntg.nl / http://www.ntg.nl/mailman/listinfo/ntg-context
webpage  : http://www.pragma-ade.nl / http://context.aanhet.net
archive  : https://bitbucket.org/phg/context-mirror/commits/
wiki     : http://contextgarden.net
___________________________________________________________________________________

Re: Defining command with optional and mandatory arguments

[Christoph Reller]

On Thu, 24 May 2018 14:50:36 +0200, Hans Hagen <j.hagen@xs4all.nl> wrote:
> On 5/24/2018 11:21 AM, Christoph Reller wrote:
>> On Wed, 23 May 2018 16:01:05 +0200, Hans Hagen <j.hagen@xs4all.nl> wrote:
>>> On 5/23/2018 3:39 PM, Christoph Reller wrote:
>>>>
>>>> What is the right way to define a command with both mandatory and
>>>> optional arguments, e.g:
>>>>
>>>> \MyCommand[optional][mandatory]
>>>>
>>>> Consider the following MWE:
>>>>
>>>> \unexpanded\def\MyCommand[#1]{
>>>>     \dosingleempty{\doMyCommand[#1]}}
>>>> \def\doMyCommand[#1][#2]{
>>>>     \doifsomething{#1}{number 1: #1\par}
>>>>     \doifsomething{#2}{number 2: #2}\blank[big]}
>>>> \starttext
>>>> \MyCommand[A][B]
>>>> \MyCommand[A]
>>>> \stoptext
>>>>
>>>> In last year's versions of ConTeXt the output was
>>>>
>>>> number 1: A
>>>> number 2: B
>>>> number 1: A
>>>>
>>>> In the latest version of ConTeXt the output is
>>>>
>>>> number 1: A
>>>> number 2: B
>>>> number 2: A
>>>>
>>>> Is this behavior intended? How can I make a definition whose behavior
>>>> does not change in new versions of ConTeXt?
>>> i'm not sure wht happens at your end but this is the best way:
>>>
>>> \unexpanded\def\MyCommand
>>>     {\dodoubleempty\doMyCommand}
>>>
>>> \def\doMyCommand[#1][#2]%
>>>     {\iffirstargument
>>>        number 1: #1%
>>>        \par
>>>      \fi
>>>      \ifsecondargument
>>>        number 2: #2%
>>>      \fi
>>>      \blank[big]}
>>>
>>> \starttext
>>>       \MyCommand[A][B]
>>>       \MyCommand[A]
>>> \stoptext
>>
>> Thank you Hans for this information. My question is rather about error
>> handling. I want:
>>
>> \MyCommand[A][B] % <- succeeds with #1->A, #2->B
>> \MyCommand[A] % <- succeeds with #1->A
>> \MyCommand % <- fails with "! Use of \MyCommand doesn't match its definition"
>>
>> I just wanted to ask whether there is a standard way to achieve this
>> with \do<whatever>empty. If not, then this is also okay.
> just use \dodoubleempty instead

Thank you for your hint, Hans. \dodoubleempty renders both arguments
optional and hence the command can be used without any argument, which
is not what I intended. Of course I can still test in the command's
definition whether at least one argument is given and generate an
error myself.

In i-context.pdf, many arguments are documented as being optional and
I assume that all the others are mandatory. A quick test has, however,
shown that when omitting mandatory arguments, either no error is
generated (e.g., nothing is setup or defined) or an obscure error
emerges other than "! Use of \<command> doesn't match its definition".

So I take it as a design decision that reporting missing mandatory
arguments as errors is not part of the interface implementation, and
that is a perfectly acceptable decision for me. It is just good to
know.

Thank you all for your highly valued feedback!

Cheers,

Christoph
___________________________________________________________________________________
If your question is of interest to others as well, please add an entry to the Wiki!

maillist : ntg-context@ntg.nl / http://www.ntg.nl/mailman/listinfo/ntg-context
webpage  : http://www.pragma-ade.nl / http://context.aanhet.net
archive  : https://bitbucket.org/phg/context-mirror/commits/
wiki     : http://contextgarden.net
___________________________________________________________________________________

Re: Defining command with optional and mandatory arguments

[Christoph Reller]

On Wed, 23 May 2018 17:54:39 +0200, Henning Hraban Ramm <texml@fiee.net> wrote:
> Date: Wed, 23 May 2018 17:54:39 +0200
> From: Henning Hraban Ramm <texml@fiee.net>
> To: mailing list for ConTeXt users <ntg-context@ntg.nl>
> Subject: Re: [NTG-context] Defining command with optional and
>         mandatory       arguments
> Message-ID: <A21D40D2-E607-47A4-BAB0-C437DC9150DA@fiee.net>
> Content-Type: text/plain; charset=windows-1252
>
> Am 2018-05-23 um 16:01 schrieb Hans Hagen <j.hagen@xs4all.nl>:
>
>> On 5/23/2018 3:39 PM, Christoph Reller wrote:
>>> Hi,
>>> What is the right way to define a command with both mandatory and
>>> optional arguments, e.g:
>> i'm not sure wht happens at your end but this is the best way:
>
> Also, there’s documentation at
> http://wiki.contextgarden.net/Commands_with_optional_arguments
>
> If there’s something wrong, please fix it yourself or come back to this list ;)
>

Thank you Hraban for pointing me to the wiki. I was aware of this page
but it contains only the case of mandatory arguments in curly braces
{} not in brackets [].

Cheers,

Christoph
___________________________________________________________________________________
If your question is of interest to others as well, please add an entry to the Wiki!

maillist : ntg-context@ntg.nl / http://www.ntg.nl/mailman/listinfo/ntg-context
webpage  : http://www.pragma-ade.nl / http://context.aanhet.net
archive  : https://bitbucket.org/phg/context-mirror/commits/
wiki     : http://contextgarden.net
___________________________________________________________________________________

Re: Defining command with optional and mandatory arguments

[Henning Hraban Ramm]

Am 2018-05-24 um 11:24 schrieb Christoph Reller <christoph.reller@gmail.com>:

> On Wed, 23 May 2018 17:54:39 +0200, Henning Hraban Ramm <texml@fiee.net> wrote:
>>>> What is the right way to define a command with both mandatory and
>>>> optional arguments, e.g:
>>> i'm not sure wht happens at your end but this is the best way:
>> 
>> Also, there’s documentation at
>> http://wiki.contextgarden.net/Commands_with_optional_arguments
>> If there’s something wrong, please fix it yourself or come back to this list ;)
> 
> Thank you Hraban for pointing me to the wiki. I was aware of this page
> but it contains only the case of mandatory arguments in curly braces
> {} not in brackets [].

Arguments in brackets are always optional (if I don’t misunderstand), depending on your own logic (\if*argument, \ifempty etc.)

see also
http://wiki.contextgarden.net/System_Macros :
http://wiki.contextgarden.net/System_Macros/Handling_Arguments
http://wiki.contextgarden.net/System_Macros/Branches_and_Decisions
etc.
I need to read these more often myself...

Greetlings, Hraban
---
https://www.fiee.net
http://wiki.contextgarden.net
https://www.dreiviertelhaus.de
GPG Key ID 1C9B22FD

___________________________________________________________________________________
If your question is of interest to others as well, please add an entry to the Wiki!

maillist : ntg-context@ntg.nl / http://www.ntg.nl/mailman/listinfo/ntg-context
webpage  : http://www.pragma-ade.nl / http://context.aanhet.net
archive  : https://bitbucket.org/phg/context-mirror/commits/
wiki     : http://contextgarden.net
___________________________________________________________________________________

Re: Defining command with optional and mandatory arguments

[Taco Hoekwater]

Hi,

> Arguments in brackets are always optional (if I don’t misunderstand), depending on your own logic (\if*argument, \ifempty etc.)

The original intent was for user-level commands to have square brackets
for arguments setting things up, and curly braces for arguments that
are actually typeset. That is where commands like \in come from, where
the braced part is optional and the bracketed part required.

Internal low-level commands tended to use braces more often because
of efficiency considerations. (also, at the primitive level, TeX syntax
is inconsistent anyway, with various primitives having quite different
syntactical conventions). Nowadays, this is less relevant, with lots
of stuff handled by lua instead.

Best wishes,
Taco



___________________________________________________________________________________
If your question is of interest to others as well, please add an entry to the Wiki!

maillist : ntg-context@ntg.nl / http://www.ntg.nl/mailman/listinfo/ntg-context
webpage  : http://www.pragma-ade.nl / http://context.aanhet.net
archive  : https://bitbucket.org/phg/context-mirror/commits/
wiki     : http://contextgarden.net
___________________________________________________________________________________

Re: Defining command with optional and mandatory arguments

[Alan Braslau]

On Thu, 24 May 2018 11:24:34 +0200
Christoph Reller <christoph.reller@gmail.com> wrote:

> Thank you Hraban for pointing me to the wiki. I was aware of this page
> but it contains only the case of mandatory arguments in curly braces
> {} not in brackets [].

One must *not* confuse with the LaTeX convention where "mandatory"
arguments are contained in curly braces and brackets indicate
"optional" arguments.

As Taco states below, curly braces not only give grouping but generally
are used for objects to be typeset, as for \in{Figure}{a} [fig:ref].

For new users, it is worth repeating here that arguments within braces
can be either a comma-separated list of words OR a comma-separated
list of keyword=value pairs, BUT NOT A MIXTURE OF BOTH. Generally, a
keyword=value exists for all words, for example \cite[authoryear][ref]
and \cite[alternative=authoryear,reference=ref]

values can be grouped using curly braces, as in
\cite[alternative=authoryear,lefttext={{see },}][ref1,ref2] where the
lefttext is associated with the first cite reference (and none with the
second). This can be tricky but is in fact rather straight-forward.

Alan

P.S. The wiki is only as good as users make it; some pages have not
been changed since mkii...


On Thu, 24 May 2018 15:43:27 +0200
Taco Hoekwater <taco@elvenkind.com> wrote:

> The original intent was for user-level commands to have square
> brackets for arguments setting things up, and curly braces for
> arguments that are actually typeset. That is where commands like \in
> come from, where the braced part is optional and the bracketed part
> required.

___________________________________________________________________________________
If your question is of interest to others as well, please add an entry to the Wiki!

maillist : ntg-context@ntg.nl / http://www.ntg.nl/mailman/listinfo/ntg-context
webpage  : http://www.pragma-ade.nl / http://context.aanhet.net
archive  : https://bitbucket.org/phg/context-mirror/commits/
wiki     : http://contextgarden.net
___________________________________________________________________________________

Defining command with optional and mandatory arguments

[Christoph Reller]

Hi,

What is the right way to define a command with both mandatory and
optional arguments, e.g:

\MyCommand[optional][mandatory]

Consider the following MWE:

\unexpanded\def\MyCommand[#1]{
  \dosingleempty{\doMyCommand[#1]}}
\def\doMyCommand[#1][#2]{
  \doifsomething{#1}{number 1: #1\par}
  \doifsomething{#2}{number 2: #2}\blank[big]}
\starttext
\MyCommand[A][B]
\MyCommand[A]
\stoptext

In last year's versions of ConTeXt the output was

number 1: A
number 2: B
number 1: A

In the latest version of ConTeXt the output is

number 1: A
number 2: B
number 2: A

Is this behavior intended? How can I make a definition whose behavior
does not change in new versions of ConTeXt?

Cheers,

Christoph
___________________________________________________________________________________
If your question is of interest to others as well, please add an entry to the Wiki!

maillist : ntg-context@ntg.nl / http://www.ntg.nl/mailman/listinfo/ntg-context
webpage  : http://www.pragma-ade.nl / http://context.aanhet.net
archive  : https://bitbucket.org/phg/context-mirror/commits/
wiki     : http://contextgarden.net
___________________________________________________________________________________

Re: Defining command with optional and mandatory arguments

[Hans Hagen]

On 5/23/2018 3:39 PM, Christoph Reller wrote:
> Hi,
> 
> What is the right way to define a command with both mandatory and
> optional arguments, e.g:
> 
> \MyCommand[optional][mandatory]
> 
> Consider the following MWE:
> 
> \unexpanded\def\MyCommand[#1]{
>    \dosingleempty{\doMyCommand[#1]}}
> \def\doMyCommand[#1][#2]{
>    \doifsomething{#1}{number 1: #1\par}
>    \doifsomething{#2}{number 2: #2}\blank[big]}
> \starttext
> \MyCommand[A][B]
> \MyCommand[A]
> \stoptext
> 
> In last year's versions of ConTeXt the output was
> 
> number 1: A
> number 2: B
> number 1: A
> 
> In the latest version of ConTeXt the output is
> 
> number 1: A
> number 2: B
> number 2: A
> 
> Is this behavior intended? How can I make a definition whose behavior
> does not change in new versions of ConTeXt?
i'm not sure wht happens at your end but this is the best way:

\unexpanded\def\MyCommand
   {\dodoubleempty\doMyCommand}

\def\doMyCommand[#1][#2]%
   {\iffirstargument
      number 1: #1%
      \par
    \fi
    \ifsecondargument
      number 2: #2%
    \fi
    \blank[big]}

\starttext
     \MyCommand[A][B]
     \MyCommand[A]
\stoptext


-----------------------------------------------------------------
                                           Hans Hagen | PRAGMA ADE
               Ridderstraat 27 | 8061 GH Hasselt | The Netherlands
        tel: 038 477 53 69 | www.pragma-ade.nl | www.pragma-pod.nl
-----------------------------------------------------------------
___________________________________________________________________________________
If your question is of interest to others as well, please add an entry to the Wiki!

maillist : ntg-context@ntg.nl / http://www.ntg.nl/mailman/listinfo/ntg-context
webpage  : http://www.pragma-ade.nl / http://context.aanhet.net
archive  : https://bitbucket.org/phg/context-mirror/commits/
wiki     : http://contextgarden.net
___________________________________________________________________________________

Re: Defining command with optional and mandatory arguments

[Henning Hraban Ramm]

Am 2018-05-23 um 16:01 schrieb Hans Hagen <j.hagen@xs4all.nl>:

> On 5/23/2018 3:39 PM, Christoph Reller wrote:
>> Hi,
>> What is the right way to define a command with both mandatory and
>> optional arguments, e.g:
> i'm not sure wht happens at your end but this is the best way:

Also, there’s documentation at
http://wiki.contextgarden.net/Commands_with_optional_arguments

If there’s something wrong, please fix it yourself or come back to this list ;)


Greetlings, Hraban
---
https://www.fiee.net
http://wiki.contextgarden.net
https://www.dreiviertelhaus.de
GPG Key ID 1C9B22FD

___________________________________________________________________________________
If your question is of interest to others as well, please add an entry to the Wiki!

maillist : ntg-context@ntg.nl / http://www.ntg.nl/mailman/listinfo/ntg-context
webpage  : http://www.pragma-ade.nl / http://context.aanhet.net
archive  : https://bitbucket.org/phg/context-mirror/commits/
wiki     : http://contextgarden.net
___________________________________________________________________________________