Difference between revisions of "Module Namespaces"
(namespaces of the world, unite!) |
(→Namespace Configuration: Added info supplied by Wolfgang on the ML) |
||
Line 84: | Line 84: | ||
determine what commands will be available. | determine what commands will be available. | ||
At the time of this writing (2010-09-27), this is rather | At the time of this writing (2010-09-27), this is rather | ||
− | new stuff and so far | + | new stuff and so far not guaranteed to stay in context |
− | + | unmodified. | |
− | |||
− | |||
− | {|cellpadding="10" style="border:2px solid #addeff" | + | {|cellpadding="10" style="border:2px solid #addeff" rules="rows" |
− | ! style="background:#addeff;" | Option !! Parameters and their description | + | ! style="background:#addeff;" | Option !! Parameters and their description (''NS'' is a namespace dummy) |
|- | |- | ||
− | |<tt>name</tt> || ''string'': The identifier that will be used to reference setups and parameters. | + | |<tt>name</tt> || ''string'': The identifier that will be used to reference setups and parameters; e. g. a value of ''NS'' causes the macros <tt>\defineNS</tt> and <tt>\setupNS</tt> to be created. |
|- | |- | ||
− | |<tt>parent</tt> || ''string'': a namespace identifier. | + | |<tt>parent</tt> || ''string'': a namespace identifier. Should be the same as the identifier of the module’s namespace. |
|- | |- | ||
− | |<tt>type</tt> || <tt>module</tt>: | + | |<tt>type</tt> || <tt>module</tt>: creates the namespace prefixed with quadruple ''@''; other values are planned to be added in the future for internal purposes. |
|- | |- | ||
− | |<tt> | + | |<tt>setup</tt> || <tt>list</tt> or ''boolean'': initiates the creation of a setup according to the <tt>name</tt> argument, e. g. <tt>\setupNS</tt>. The specified value influences the behaviour of the setup: |
+ | {| | ||
+ | |<tt>yes</tt> || first argument of the setup accepts one parameter (<tt>\setupNS[one][..,..=..,..]</tt>); | ||
|- | |- | ||
− | |<tt>setup</tt> | + | |<tt>list</tt> || first argument of the setup accepts a comma separated list (<tt>\setupNS[one,two,three][..,..=..,..]</tt>). |
+ | |} | ||
+ | |- | ||
+ | |align="right" | <tt>command</tt> | ||
+ | |<tt>list</tt> or ''boolean'': creates auxiliary macros and the proper command to define further commands within the new namespace (<tt>\defineNS</tt>). | ||
+ | For a <tt>name</tt> parameter ''NS'', the values of the <tt>\setupNS</tt> command will be retrievable via <tt>\NSparameter{parametername}</tt>. Additionally, access is provided by <tt>\namedNSparameter</tt> and <tt>\detokenizedNSparameter</tt>. | ||
+ | The <tt>\defineNS[command][..,..=..,..]</tt> can be used to create instances of a generic macro with local setups. Works like ordinary Context <tt>\definesomething</tt> commands and allows for inheritance (<tt>\defineNS[command][othercommand]</tt>). Of course, if <tt>command</tt> is set to ''list'', the first argument of <tt>\defineNS</tt> will take comma separated values. | ||
|- | |- | ||
|<tt>comment</tt> || ''string'': non-functional information that will be stored along with the namespace?? | |<tt>comment</tt> || ''string'': non-functional information that will be stored along with the namespace?? | ||
|- | |- | ||
|<tt>version</tt> || ''number'': versioning information?? Functionality not yet known. | |<tt>version</tt> || ''number'': versioning information?? Functionality not yet known. | ||
− | + | |- | |
+ | |<tt>style</tt> || ''boolean'': enables special handling for text color and style attributes. | ||
+ | If set to ''yes'', a macro <tt>\dosetNSattributes</tt> will be created. It receives the values for the <tt>style</tt> and <tt>color</tt> arguments as supplied to the <tt>\setupNS</tt> macro which itself gets created via the <tt>setup</tt> key (see above). | ||
|+ Optional settings for module namespaces. | |+ Optional settings for module namespaces. | ||
|} | |} | ||
− | |||
=Further Information= | =Further Information= | ||
* [[source:mult-aux.mkiv|Definition of <tt>\definenamespace</tt>]]. | * [[source:mult-aux.mkiv|Definition of <tt>\definenamespace</tt>]]. | ||
* [[System Macros]]. | * [[System Macros]]. |
Revision as of 00:24, 18 November 2010
Contents
List of Module Namespaces
TODO: This list is under construction and will eventually contain all namespaces used in context modules. (See: To-Do List) |
To avoid clashes with existing and future commands, any module should adhere to the following rules:
- Namespaces should have more than two characters (at least yours [1]),
- the namespace should be registered here for others to know.
Namespace | Name | Main file | Description |
---|---|---|---|
fb | fancybreak | t-fancybreak | Inserting thought breaks (transitions). |
Generating a Namespace for Your Module
Context provides the user command \definenamespace that generates a valid namespace for variables and takes care of defining a setup command as well. Suppose you have a module called My Module (preferably in a file t-mymodule.mkiv) and want to reserve the namespace mymod. The following snippet will get you a setup command \setupMyMod.
\definenamespace[mymod] [ type=module, name=MyMod, setup=list, ]
Through \setupMyMod you can now set the variables that you are planning to use in your module – it is already a mature command that conforms to the overall context style and can take a parameter list, a list of key-value pairs or both as arguments. Any parameter defined that way can now be retrieved via another command that got auto-generated, \MyModparameter.
% setting a parameter within the namespace \setupMyMod[ yamp=Yet another module parameter, ] % command sequence that does something with the parameter \def\blueparameter{\setupcolors[state=start]\colored[blue]\MyModparameter{yamp}} % deploying the new user command \starttext \blueparameter \stoptext
Wondering why your namespace, albeit defined as mymod initially, is always referred to as MyMod, i.e. the value of the parameter name as given in the definition? Internally the namespaces are represented as ordinary command sequences with a prefix. This prefix is composed from first the usual four @-signs, second the namespace identifier, and third the key id from the argument list. In the example this results in a macro \@@@@ + mymod + yamp. Thus, \MyModparameter{yamp} would be equivalent to calling:
\unprotect \@@@@mymodyamp \protect
Namespace Configuration
\definenamespace accepts a number of options that determine what commands will be available. At the time of this writing (2010-09-27), this is rather new stuff and so far not guaranteed to stay in context unmodified.
Option | Parameters and their description (NS is a namespace dummy) | ||||
---|---|---|---|---|---|
name | string: The identifier that will be used to reference setups and parameters; e. g. a value of NS causes the macros \defineNS and \setupNS to be created. | ||||
parent | string: a namespace identifier. Should be the same as the identifier of the module’s namespace. | ||||
type | module: creates the namespace prefixed with quadruple @; other values are planned to be added in the future for internal purposes. | ||||
setup | list or boolean: initiates the creation of a setup according to the name argument, e. g. \setupNS. The specified value influences the behaviour of the setup:
| ||||
command | list or boolean: creates auxiliary macros and the proper command to define further commands within the new namespace (\defineNS).
For a name parameter NS, the values of the \setupNS command will be retrievable via \NSparameter{parametername}. Additionally, access is provided by \namedNSparameter and \detokenizedNSparameter. The \defineNS[command][..,..=..,..] can be used to create instances of a generic macro with local setups. Works like ordinary Context \definesomething commands and allows for inheritance (\defineNS[command][othercommand]). Of course, if command is set to list, the first argument of \defineNS will take comma separated values. | ||||
comment | string: non-functional information that will be stored along with the namespace?? | ||||
version | number: versioning information?? Functionality not yet known. | ||||
style | boolean: enables special handling for text color and style attributes.
If set to yes, a macro \dosetNSattributes will be created. It receives the values for the style and color arguments as supplied to the \setupNS macro which itself gets created via the setup key (see above). |