ConTeXt: How do you create your own commands?

Question

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}}

% ...

\installnarrowermethod \v!left  {\global\advance\s_spac_narrower_left%
    \narrowerparameter\c!left  \relax}
\installnarrowermethod \v!middle{\global\advance\s_spac_narrower_mid%
    \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

Answer 1

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):

Access to the values

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.