[NTG-context] defining macros

[NTG-context] defining macros

[Henning Hraban Ramm]

Hi, I just recognized that I’m not sure how to define a macro with 
optional and mandatory arguments the best way.

E.g. (oldfashioned)

\def\doMyMacro[#1]#2%
{Do something ... \iffirstargument #1\fi #2}

\def\MyMacro%
{\dosingleargument\doMyMacro}


Is this still the way to do it?
Does it also work with \define?

I have more questions like that:

 From Wolfgang’s presentation (article in progress…) I know all the cool 
stuff for modules (namespaces, setup helpers…), I also know the Lua way 
of interface.implement, but how to combine those?

When should I use brackets or other characters in a definition, when not?

Which docs should I read?


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

maillist : ntg-context@ntg.nl / https://mailman.ntg.nl/mailman3/lists/ntg-context.ntg.nl
webpage  : https://www.pragma-ade.nl / https://context.aanhet.net (mirror)
archive  : https://github.com/contextgarden/context
wiki     : https://wiki.contextgarden.net
___________________________________________________________________________________

[NTG-context] Re: defining macros

[Hans Hagen via ntg-context]

On 1/10/2025 12:55 PM, Henning Hraban Ramm wrote:
> Hi, I just recognized that I’m not sure how to define a macro with 
> optional and mandatory arguments the best way.
> 
> E.g. (oldfashioned)
> 
> \def\doMyMacro[#1]#2%
> {Do something ... \iffirstargument #1\fi #2}
> 
> \def\MyMacro%
> {\dosingleargument\doMyMacro}

\tolerant\def\MyMacro[#1]#:#2%
   {\ifparameter#1\or
      (#1)
    \fi
    /#2/}

\MyMacro[one]{two}

\MyMacro{two}

> Is this still the way to do it?
> Does it also work with \define?
> 
> I have more questions like that:
> 
>  From Wolfgang’s presentation (article in progress…) I know all the cool 
> stuff for modules (namespaces, setup helpers…), I also know the Lua way 
> of interface.implement, but how to combine those?
> 
> When should I use brackets or other characters in a definition, when not?

optionals normally have []

> Which docs should I read?

how about lowlevel-macros .. but haven't you read all of them by now ?

Hans

-----------------------------------------------------------------
                                           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 / https://mailman.ntg.nl/mailman3/lists/ntg-context.ntg.nl
webpage  : https://www.pragma-ade.nl / https://context.aanhet.net (mirror)
archive  : https://github.com/contextgarden/context
wiki     : https://wiki.contextgarden.net
___________________________________________________________________________________

[NTG-context] Re: defining macros

[Henning Hraban Ramm]

Am 10.01.25 um 19:45 schrieb Hans Hagen:
> \tolerant\def\MyMacro[#1]#:#2%
>    {\ifparameter#1\or
>       (#1)
>     \fi
>     /#2/}
> 
> \MyMacro[one]{two}
> 
> \MyMacro{two}

Oops, another variant that I didn’t know.
I must unlearn my remaining MkII stuff…

>> When should I use brackets or other characters in a definition, when not?
> optionals normally have []

Yes, of course, but I’m often surprised by funny characters like #:

>> Which docs should I read?
> 
> how about lowlevel-macros .. but haven't you read all of them by now ?

Apparently not diligently enough.
If at all. Can’t remember any more.

I’m not competent enough to rewrite e.g.
https://wiki.contextgarden.net/System_Macros/Handling_Arguments

Sigh.

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

maillist : ntg-context@ntg.nl / https://mailman.ntg.nl/mailman3/lists/ntg-context.ntg.nl
webpage  : https://www.pragma-ade.nl / https://context.aanhet.net (mirror)
archive  : https://github.com/contextgarden/context
wiki     : https://wiki.contextgarden.net
___________________________________________________________________________________

[NTG-context] Re: defining macros

[Hans Hagen]

On 1/10/2025 11:04 PM, Henning Hraban Ramm wrote:
> Am 10.01.25 um 19:45 schrieb Hans Hagen:
>> \tolerant\def\MyMacro[#1]#:#2%
>>    {\ifparameter#1\or
>>       (#1)
>>     \fi
>>     /#2/}
>>
>> \MyMacro[one]{two}
>>
>> \MyMacro{two}
> 
> Oops, another variant that I didn’t know.
> I must unlearn my remaining MkII stuff…
> 
>>> When should I use brackets or other characters in a definition, when 
>>> not?
>> optionals normally have []
> 
> Yes, of course, but I’m often surprised by funny characters like #:

Well, there are reasons: It has to fit in the #1 .. #9 approach because
these things are stored into tokens, so single character. Then one has 
to decide on what characters. There's also a performance issue because 
we don't want to sacrifice too much and these preamble tokens are 
"parsed" every time a macro is called so they better can be efficient.

In the end only a few users (mostly developers) will see the obscure 
ones (and understand why some are there). The \optional prefix enables 
these extensions. It's a bit like: I want to grab arguments with mandate 
{} and there is something so let's look it up. Or, I bet that one can 
grab \par's so lets the manual for that.

Did you know that we can have #A..#E as well. So 15 parameters instead 
of 9? I still need to use that more (deep down).

>>> Which docs should I read?
>>
>> how about lowlevel-macros .. but haven't you read all of them by now ?
> 
> Apparently not diligently enough.
> If at all. Can’t remember any more.

Don't worry, you don't want to know what I forget.

> I’m not competent enough to rewrite e.g.
> https://wiki.contextgarden.net/System_Macros/Handling_Arguments

> Sigh.

So you haven't reached Wolfgang level yet, and by the time you have, he 
bumped the scale up again, so don't sigh too much ... won't help, 
actually your upcoming manual will cover plenty, so more of a hurray.

Hans

-----------------------------------------------------------------
                                           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 / https://mailman.ntg.nl/mailman3/lists/ntg-context.ntg.nl
webpage  : https://www.pragma-ade.nl / https://context.aanhet.net (mirror)
archive  : https://github.com/contextgarden/context
wiki     : https://wiki.contextgarden.net
___________________________________________________________________________________

[NTG-context] Re: defining macros

[Henning Hraban Ramm]

Am 11.01.25 um 00:19 schrieb Hans Hagen:
>> Yes, of course, but I’m often surprised by funny characters like #:
> 
> Well, there are reasons: It has to fit in the #1 .. #9 approach because
> these things are stored into tokens, so single character. Then one has 
> to decide on what characters. There's also a performance issue because 
> we don't want to sacrifice too much and these preamble tokens are 
> "parsed" every time a macro is called so they better can be efficient.
> 
> In the end only a few users (mostly developers) will see the obscure 
> ones (and understand why some are there). The \optional prefix enables 
> these extensions. It's a bit like: I want to grab arguments with mandate 
> {} and there is something so let's look it up. Or, I bet that one can 
> grab \par's so lets the manual for that.

Thank you for the explanation!
I guess you meant \tolerant instead of \optional?


> Did you know that we can have #A..#E as well. So 15 parameters instead 
> of 9? I still need to use that more (deep down).

That I knew. At least in mkvi/mklx mode.
If I use even 4 params I lose count of them.

> Don't worry, you don't want to know what I forget.

Sure.
I’m proud to have found several features that you forgot about ;)

>> I’m not competent enough to rewrite e.g.
>> https://wiki.contextgarden.net/System_Macros/Handling_Arguments
> 
>> Sigh.
> 
> So you haven't reached Wolfgang level yet, and by the time you have, he 
> bumped the scale up again, so don't sigh too much ... won't help, 
> actually your upcoming manual will cover plenty, so more of a hurray.

I’m always aiming for the stars. ;)
But my manual can’t be better than me, and I want it to be up to date 
and helpful – mostly for myself ;-P

Yes, I need to read the lowlevel manuals. But after taxes… (Also sigh.)

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

maillist : ntg-context@ntg.nl / https://mailman.ntg.nl/mailman3/lists/ntg-context.ntg.nl
webpage  : https://www.pragma-ade.nl / https://context.aanhet.net (mirror)
archive  : https://github.com/contextgarden/context
wiki     : https://wiki.contextgarden.net
___________________________________________________________________________________

[NTG-context] Re: defining macros

[Hans Hagen via ntg-context]

On 1/11/2025 10:21 AM, Henning Hraban Ramm wrote:
> Am 11.01.25 um 00:19 schrieb Hans Hagen:
>>> Yes, of course, but I’m often surprised by funny characters like #:
>>
>> Well, there are reasons: It has to fit in the #1 .. #9 approach because
>> these things are stored into tokens, so single character. Then one has 
>> to decide on what characters. There's also a performance issue because 
>> we don't want to sacrifice too much and these preamble tokens are 
>> "parsed" every time a macro is called so they better can be efficient.
>>
>> In the end only a few users (mostly developers) will see the obscure 
>> ones (and understand why some are there). The \optional prefix enables 
>> these extensions. It's a bit like: I want to grab arguments with 
>> mandate {} and there is something so let's look it up. Or, I bet that 
>> one can grab \par's so lets the manual for that.
> 
> Thank you for the explanation!
> I guess you meant \tolerant instead of \optional?

yes, (i sometimes localy uise that as aliasm, sorry) .. consider that 
you just past the examn

>> Did you know that we can have #A..#E as well. So 15 parameters instead 
>> of 9? I still need to use that more (deep down).
> 
> That I knew. At least in mkvi/mklx mode.
> If I use even 4 params I lose count of them.
> 
>> Don't worry, you don't want to know what I forget.

\tolerant\def\MyMacro[#1]#:#2%
   {\parameterdef\ikeepforgettingone1
    \parameterdef\ikeepforgettingtwo2
    \ifparameter#1\or % maybe here too
      (\ikeepforgettingone)
    \fi
    /\ikeepforgettingtwo/}

\MyMacro[one]{two}

\MyMacro{two}

seems that i also need to let \ifparameter handle these defs ... so now 
you contributed to development (and i can delegate documentation of low 
levels to you)

> Sure.
> I’m proud to have found several features that you forgot about ;)

ah, so you now make a nice certificate that you can put behind you when 
we chat

>>> I’m not competent enough to rewrite e.g.
>>> https://wiki.contextgarden.net/System_Macros/Handling_Arguments
>>
>>> Sigh.
>>
>> So you haven't reached Wolfgang level yet, and by the time you have, 
>> he bumped the scale up again, so don't sigh too much ... won't help, 
>> actually your upcoming manual will cover plenty, so more of a hurray.
> 
> I’m always aiming for the stars. ;)
> But my manual can’t be better than me, and I want it to be up to date 
> and helpful – mostly for myself ;-P
> 
> Yes, I need to read the lowlevel manuals. But after taxes… (Also sigh.)
> 
> Hraban
> ___________________________________________________________________________________
> If your question is of interest to others as well, please add an entry 
> to the Wiki!
> 
> maillist : ntg-context@ntg.nl / https://mailman.ntg.nl/mailman3/lists/ 
> ntg-context.ntg.nl
> webpage  : https://www.pragma-ade.nl / https://context.aanhet.net (mirror)
> archive  : https://github.com/contextgarden/context
> wiki     : https://wiki.contextgarden.net
> ___________________________________________________________________________________


-- 

-----------------------------------------------------------------
                                           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 / https://mailman.ntg.nl/mailman3/lists/ntg-context.ntg.nl
webpage  : https://www.pragma-ade.nl / https://context.aanhet.net (mirror)
archive  : https://github.com/contextgarden/context
wiki     : https://wiki.contextgarden.net
___________________________________________________________________________________

[NTG-context] Re: defining macros

[Henning Hraban Ramm]

Am 11.01.25 um 12:30 schrieb Hans Hagen via ntg-context:
>> Sure.
>> I’m proud to have found several features that you forgot about ;)
> 
> ah, so you now make a nice certificate that you can put behind you when 
> we chat

Will do ;)
Do you also give out cheques? ;)

Back to macros (I read lowlevel-macros, at least tried to…):

While I liked \define, it looks like it just doesn’t make sense anymore 
if I need (\tolerant)\def for anything advanced anyway?

You stress how costly named macros are – then we should forget about 
MkLX mode?

Did I understand correctly, that bracketed = optional parameters is just 
a convention, i.e. only the handling of arguments makes them optional, 
not their definition/fencing?

With \tolerant, we can not only forget about the last dodos (and even 
single dos), but also about \dosingleargument & friends, right?
Are there cases where the MkIV way still makes sense with LMTX?

When does it make sense to define macros in Lua (interfaces.implement)?
Obviously, if I need calculations or I/O operations that are easier to 
do in Lua. Are there disadvantages of Lua-defined vs. TeX-defined  macros?

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

maillist : ntg-context@ntg.nl / https://mailman.ntg.nl/mailman3/lists/ntg-context.ntg.nl
webpage  : https://www.pragma-ade.nl / https://context.aanhet.net (mirror)
archive  : https://github.com/contextgarden/context
wiki     : https://wiki.contextgarden.net
___________________________________________________________________________________

[NTG-context] Re: defining macros

[Hans Hagen]

On 1/14/2025 6:50 PM, Henning Hraban Ramm wrote:
> Am 11.01.25 um 12:30 schrieb Hans Hagen via ntg-context:
>>> Sure.
>>> I’m proud to have found several features that you forgot about ;)
>>
>> ah, so you now make a nice certificate that you can put behind you 
>> when we chat
> 
> Will do ;)
> Do you also give out cheques? ;)

we might if we got them

> Back to macros (I read lowlevel-macros, at least tried to…):
> 
> While I liked \define, it looks like it just doesn’t make sense anymore 
> if I need (\tolerant)\def for anything advanced anyway?

\starttexdefinition

supports this

> You stress how costly named macros are – then we should forget about 
> MkLX mode?

i meant 'if supported by the engine' but mklx are only named when you 
define them adnm internalized as #1 ...

> Did I understand correctly, that bracketed = optional parameters is just 
> a convention, i.e. only the handling of arguments makes them optional, 
> not their definition/fencing?

indeed, you could also do

\tolerant\def\foo(#1){...}

> With \tolerant, we can not only forget about the last dodos (and even 
> single dos), but also about \dosingleargument & friends, right?
> Are there cases where the MkIV way still makes sense with LMTX?

only a few places (where we were too lazy to redo it) but eventually all 
will use the modern way ... if you see one and are annoyed you can tell 
me (HH & WS)

> When does it make sense to define macros in Lua (interfaces.implement)?
> Obviously, if I need calculations or I/O operations that are easier to 
> do in Lua. Are there disadvantages of Lua-defined vs. TeX-defined  macros?

it depends but i doubt if you will notice (often the performance hits 
are not where you think they are so one can occasionaly run into curious 
assumptions)

timing tex is kind of tricky because in a loop that does simple things 
cpu caching speeds up things contrary to doing things all over memory 
and code; anyway one avoids some tokenization when used right

if one noticed a bottleneck we can look into but as we don't get 
complaints i guess performance is ok

Hans

-----------------------------------------------------------------
                                           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 / https://mailman.ntg.nl/mailman3/lists/ntg-context.ntg.nl
webpage  : https://www.pragma-ade.nl / https://context.aanhet.net (mirror)
archive  : https://github.com/contextgarden/context
wiki     : https://wiki.contextgarden.net
___________________________________________________________________________________