Defining new functions using parameter text and using the signature

Question

Have been reading the expl3 document interfaces3.pdf to understand how to declare and use functions. Although I have understood that there are three main methods (new, set, gset) where each method has specific use cases and restrictions upon parameter arguments.

Have also covered quite well the protected from expansion variants in certain contexts.

I would like some explanation about the difference between defining new functions using parameter text and defining new functions using the signature as covered in sections 4.3.2 and 4.3.3.

Answer 1

The code examples below are either from Joseph Wright or derived from code from Joseph Wright in answer to my (much) earlier question.

In standard cases, the difference is just one of how you prefer to specify the function. In the parametised case you specify the function's parameters explicitly:

\cs_new_protected_nopar:Npn \__chronos_set_minoryearformat:n #1
{
  \tl_set:Nn \l__chronos_minoryearformat_tl { #1 }
  \tl_replace_all:Nnn \l__chronos_minoryearformat_tl { ~ } { \c_space_token }
}

That is, the #1 tells LateX the function takes a single argument, just as \def\formatyear#1{ ... } does.

In the non-parametised case, LaTeX infers the parameters from the new function's signature:

\cs_new_protected_nopar:Nn \__chronos_set_minoryearformat:n 
{
  \tl_set:Nn \l__chronos_minoryearformat_tl { #1 }
  \tl_replace_all:Nnn \l__chronos_minoryearformat_tl { ~ } { \c_space_token }
}

That is the n tells LaTeX the function takes a single argument, just as the 1 does in \newcommand*\formatyear[1]{ ... } or m does in \NewDocumentCommand\formatyear{m}{ ... }.

But in some cases, you want the parametised version because you want to handle the arguments passed to the function specially.

\cs_new_protected_nopar:Npn \__chronos_set_date_aux_ce:w #1 - #2 - #3 - #4 @#5 \q_stop
{
    \__chronos_set_date:nnnn {#1} {#2} {#3} {#5}
}

So this function doesn't expect some mixture of tokens and braced lists of tokens. It expects something with a non-standard syntactical form.

This makes it possible to parse user input of dates which differ in how much information they provide. Basically, the user can say

date={1066-08-09}

or

date=1066

or

date={1066-03}

The package then adds to the user-specified input

<user-specified date>-01-01-0@start \q_stop

and the code will pass the appropriate information on. If the user only specified a year, a month and day will be added. If the user specified only a year and month, a day will be added. If the user specified a full date, nothing will be added except start which is used to create variable names.

This is why w. w is for 'weird'.

This is basically like similar definitions at the TeX level.

\def\mydateparser@aux#1-#2-#3-#4@#5\@nil{ ... }

would work similarly (except this isn't protected and there is no check to ensure the definition isn't obliterating some crucial thing).