5

I am trying to understand the interface3 documentation.

The LaTeX Interface 3 documentation v. May 20, 2014 and March 1, 2015 refer to Defining new functions using the signature in section 3.3. I am wondering what it means when it states that:

Within the code, the number of parameters is detected automatically from the function signature.

(It probably should read: "Within the code, the number of parameters is detected automatically by the function's signature.)

Example function using LaTeX 3 expl3 syntax:

\cs_new:Nn <function> {<code>}

Where are the parameters in that in contrast to:

\cs_new:Npn <function> <parameters> {<code>}
Community
  • 1
Jonathan Komar
  • 13,297
  • 1
    In computer science, a function's signature is the return type and the type of the arguments. –  May 15 '15 at 14:01
  • 2
    The signature are the chars behind the colon: \your_special_function:Nnn has three arguments (N, n, n). – Ulrike Fischer May 15 '15 at 14:09
  • @UlrikeFischer Sounds like an answer to me :-) – Joseph Wright May 15 '15 at 14:11
  • 1
    That sentence doesn't refer that a function \foo:nn knows how many arguments it has itself; it means that \cs_new:Nn will calculate the number of arguments from the signature it sees. That is, with \cs_new:Nn \foo:NNnn the \cs_new:Nn will extract the NNnn (the signature, after the colon) and counting it will se thath \foo:NNnn should have 4 arguments, so it will expand, somehow, to \cs_new:Npn \foo:NNnn #1 #2 #3 #4 and then will define a macro (traditionally that would be \def\foowhatever#1#2#3#4. I think that's the part you misunderstood, but I might be wrong. – Manuel May 15 '15 at 15:24

2 Answers2

8

A function name should be of the form

\<prefix>_<name>:<signature>

where <prefix> is a string of letters, possibly preceded by __, and <name> is a string of letters and underscores that should remind the function's role.

The <signature> is a string of letters among NnTFcofxVvwp, that should reflect the number of arguments the function has.

However, a function defined with 

\cs_new:Nn
\cs_new_protected:Nn
\cs_new_nopar:Nn
\cs_new_protected_nopar:Nn

or the \cs_set analogs, should only have a signature consisting of characters among NnTF. Actually T and F are essentially the same as n and should be used only for functions doing conditional business.

If you say

\cs_new:Nn \my_function:nn { <replacement text> }

you can use #1 and #2 in the replacement text just as if you had said

\cs_new:Npn \my_function:nn #1 #2 { <replacement text> }

because \cs_new:Nn examines its first argument and is able to figure out how many arguments to supply in the parameter text.

The signature of \tl_set:Nx is Nx meaning that it has two arguments, the first of which is a token (the name of the variable to set); the second argument is a normal braced argument, which is subject to full expansion before the value assignment is performed; the protected bit is because a value assignment is involved. However you can't define it as

\cs_new_protected:Nn \tl_set:Nx { <replacement text> }

but you must do

\cs_new_protected:Nn \tl_set:Nn { <replacement text> }
\cs_generate_variant:Nn \tl_set:Nn { Nx }

Note that you can define function with no signature in their name, but in this case the “long form”

\cs_new:Npn
\cs_new_protected:Npn
\cs_new_nopar:Npn
\cs_new_protected_nopar:Npn

should be used, with the parameter text fully spelled out. The same if you want to define functions with w in the signature.

egreg
  • 1,121,712
2

The signature are the chars behind the colon: \your_special_function:Nnn has three arguments (N, n, n).

Ulrike Fischer
  • 327,261