ConTeXt: How do you create your own commands?

There seems to be a Current and Standard way to define new (core) commands in ConTeXt. For example, an e-mail by Wolfgang states:

Many of the \define... and \setup... commands are now auto generated from \installcommandhandler which generates only one setup-command which can be used for global (i.e. \setup…[..,..=..,..]) and local (i.e. \setup...[...][..,..=..,..]) settings. For backward compatibility you can find things like this: \let\setupnotes\setupnote

I cannot wrap my head around the source code, and I cannot find any documentation on the commands involved.

For example, the code that creates \startnarrower and \setupnarrower, from spac-hor.mkiv:

\installcorenamespace{narrower}
\installcorenamespace{narrowermethod}

% ... (some code skipped)
\installcommandhandler \??narrower {narrower} \??narrower

\appendtoks
%% this means: \def\startmynarrower{\spac_narrower_start{mynarrower}}
\setuevalue{\e!start\currentnarrower}{\spac_narrower_start%
{\currentnarrower}}%
%% this means: \def\startmynarrower{\spac_narrower_stop}
\setuevalue{\e!stop \currentnarrower}{\spac_narrower_stop}%
\to \everydefinenarrower

% \??narrowermethod is the narrowermethod corenamespace?
\unexpanded\def\installnarrowermethod#1#2%
{\setvalue{\??narrowermethod#1}{#2}}

% ...

\narrowerparameter\c!left  \relax}
\narrowerparameter\c!middle\relax}


So, what do these commands do/mean?

• \installcorenamespace
• \??...
• \installcommandhandler, and possibly its buddies defined in mult-aux.mkiv and elsewhere: \installswitchcommandhandler, \installautocommandhandler, \installsimplecommandhandler, \installframedautocommandhandler, etc.
• \setuevalue
• Wrt. namespaces you might want to have a look at mult-aux.mkiv: installcorenamespace is reserved for Hans, use installnamespace or definenamespace instead. There’s also a section on the wiki dedicated to module namespacing. Also look at syst-aux.mkiv for the constants \c!..., \v!.... – Philipp Gesang Jun 5 '12 at 15:14
• Thank you for those links. By the way, I am equally interested in deciphering existing command definitions as in writing my own, so e.g. \installcorenamespace is also interesting even though I can't use it; especially because it is not user-facing and therefore less documented. – Esteis Jun 5 '12 at 15:33
• Small self-answer: \csname...\endcsname expands its contents, sticks a backslash in front, and TeX then pretends that that was what you wrote. See this SE answer. It's used inside \setuevalue, for example, to piece together \e!start\currentnarrower into \startnarrower, or \startmynarrower, or \demarrecompoetroite". – Esteis Jun 6 '12 at 10:32
• See, especially, the TeXbook, page 40. – Philipp Gesang Jun 7 '12 at 15:07

Creating a name space

To create a namespace the command \installnamespace is used in contrast to \installcorenamespace, which is reserved for command in the core. They basically do the same. \installnamespace{whatever} creates a new control sequence \????whatever, which expands to something random, say 345>. The command \installcorenamespace creates a command with just two question marks. You never need this value, since it's only accessed via the control sequence.

Creating a command handler

The command \installcommandhandler is called like this:

\installcommandhandler \????whatever {whatever} \????whatever


It creates several commands that are used in ConTeXts user interface:

\definewhatever [myA]
\setupwhatever  [key=value]
\setupwhatever  [myA] [key=value]


It creates bunch of other command handlers as well, like the \everydefine… token lists.

Also an interesting read: The higher level command \definenamespace (see Module Namespaces):

After

\installcommandhandler \????whatever {whatever} \????whatever


and

\setupwhatever  [foo=globalbar]
\definewhatever [mywhatever]
\setupwhatever  [mywhatever] [key=value, foo=localbar]


the values can be accessed by

\whateverparameter{foo}                  % ⇒ globalbar (*not* localbar!)
\namedwhateverparameter{mywhatever}{key} % ⇒ value
\namedwhateverparameter{mywhatever}{foo} % ⇒ globalbar (inherits from \setupwhatever)


after \def\currentwhatever{mywhatever}

\whateverparameter{foo} % ⇒ localbar


Altering the values

With \set…parameter{key}{value} one can change or set values. If \current… is empty, then the global key is changed, if \current… is set, then the change applies locally.

\installnamespace{whatever}
\installcommandhandler \????whatever {whatever} \????whatever

\setupwhatever  [foo=globalbar]
\definewhatever [mywhatever]
\setupwhatever  [mywhatever] [key=value, foo=localbar]

\setwhateverparameter{foo}{newvalueglobal} % alters global foo
\whateverparameter{foo}

\def\currentwhatever{mywhatever}
\setwhateverparameter{foo}{newvaluelocal} % alters local foo

\whateverparameter{foo} % local foo changed

\let\currentwhatever\empty
\whateverparameter{foo} % global foo unchanged


Conventions

The following information is taken from the Context wiki - System Macros

\s!: These are macros holding system constants, ie. values that never change
\c!: These are macros holding constant keys in key-value pairs.
The actual definitions depend on the multi-lingual interface that is
currently being used.
\v!: These are macros holding names of variable values in key-value pairs.
The actual definitions depend on the multi-lingual interface that is
currently being used.
\??: These are multi-lingual interface constant calls.
\@@: These are results of a multi-lingual interface constant expansion.


\setuevalue is defined as follows

\def\setuevalue#1{\normalprotected\expandafter\edef\csname#1\endcsname}


So it basically acts as an \edef.

• Further to what \setuevalue does: I've worked out what the ue means. Looking at the source, the \set*value commands are for assignments using \csname, which is the multilingual-friendly technique; the e stands for \edef; and the u macros all have \normalprotected, so I think it stands for 'user(-facing)'. – Esteis Jun 6 '12 at 10:18
• \csname has nothing to do with the multilingual interface. It enables passing an arbitrary string, which would fail otherwise due to catcode issues. Eg. \setvalue{3&_}{foo} and \getvalue{3&_} – Marco Jun 6 '12 at 10:40
• Yes, sorry, that was unclear: I meant "assigning things using \csname" is a multilingual-friendly technique, because instead of mentioning the command you're defining you can use \csname to piece it together from language-independent placeholders. E.g. \expandafter\def\csname\e!start\currentnarrower\endcsname{...} is flexible, while \def\demarreMonNarrower` is set in stone. ---- On top of the useful ability to paste comes the useful property of catcode-independence, as you say. – Esteis Jun 6 '12 at 11:01