Parameters in the GLOSS system

1 Introduction

Parameters can be used to pass information from one part of a gloss parser to another, or to indicate finer information on the state of the parser. This page describes usage of parameters in the gloss system, especially when writing modular vocabulary (MV) files.

2 ParameterContainer

Parameters are contained in a parameter container class which contains a number of name="value" data. The name here is a non-null key or parameter name and value is a non-null string of unicode characters. The ParameterContainer class has a clone method which is used extensively for saving current values during recursion.

3 Parameter names

A parameter must have a non-null string as a name. It may have a name built from a-z A-Z 0-9 - _ . according to the usual rules (under review - TO DO) or else may have name "{URI}name" where "URI" may be any URI with balanced (or no) braces and name agrees with the above. The URI is used as a "namespace" for the name, and may be abbreviated by a "prefix" according to the interpolation rules following.

4 Interpolation

Almost everywhere in text or attribute values in the MV file, parameter values will be interpolated. For details of exactly when interpolation takes place see the documentation for the modularvocab DTD.

The interpolation rules follow.

If the input string is a literal "'...'", i.e., has length at least 2 and the first and last characters are "'" then its content, the part ... between the quotes, is returned verbatim without further interpolation.
Else the input string is resolved (once) against all prefixes known at that particular time. This replaces an input of the form "pref:localpart" with "{uri}localpart", where "uri" is the URI corresponding to prefix "pref:". A prefix must be formed from the characters a-z A-Z 0-9 . _ and -. Currently this is the only syntactical rule for "pref:localpart", in particular any order or characters is allowed but only the standard ASCII unicode letter characters are allowed. These rules may change (to something more in line with the syntax as that used by XML namespace-prefixes - TO DO). Note that no prefix interpolation takes place unless the input is "pref:localpart" and obeys the syntax rules for "prefix" and (any rules for) "localpart".
The result is scanned for $ symbols and any substring with $ present is replaced according to the following rules:
- ${name} The string "name" (which must have balanced braces) is interpolated once against further prefixes, according to the rule above, and then recursively according to these rules but without further use of the prefix rule. The result is interpreted if possible as the name of a parameter. If there is no such parameter, ${name} is replaced by the empty string. Otherwise the value of that parameter is obtained but not interpolated further and the result is substituted for ${name}.
- $ (when at end of string) replaced by $
- $$ replaced by a single $
- $: replaced by a single :
- $a replaced by the address of the ParameterContainer being used (a useful feature for debugging sometimes)
- $c replaced by the column number of the current token
- $d replaced by the full data for the current token
- $l replaced by the line number of the current token
- $m replaced by the current mode's name
- $f replaced by the current mode's parent's name
- $g replaced by the current mode's grandparent's name
- $n replaced by the local name of the current token
- $p replaced by the namespace prefix of the current token
- $q replaced by the full (qualified) name of the current token, equal to either $p:$n or $n
- $s replaced by the name of the current input document
- $t replaced by the type of the current token
- $v replaced by the value of the current token
- $x for any other character x, replaced by x
where if the "current token" tok or "current mode name" are not defined then the relevant interpolants are empty.

The rationale behind these rules are that parameter values themselves might be thought of as tainted and should not themselves be interpolated unless they are used (at a higher level) to build a parameter name. In other words, only prefixes that are explicitly given in the MV file should be resolved and parameter expressions in the input text file should never be interpolated.

5 Information on particular token types

The MV file tokentypes.mv reads a list of tokens and dumps the tokens to the screen, showing the effects of $d, $n, $p, $q, $t, $v on the different token types. The following summary may be found helpful.

Token types: elt pelt attr fp hex int uri pdef pref cref eref b64 char str pi ns uc eos punc

elt: syntax PREFIX:NAME or NAME where PREFIX and NAME are valid XML element names; value="", prefix="PREFIX" or "", localname="NAME", data="PREFIX:NAME" or "NAME", fullname="PREFIX:NAME" or "NAME"
pelt: syntax !PREFIX:NAME or !NAME where PREFIX and NAME are valid XML element names; value="", prefix="PREFIX" or "", localname="NAME", data="PREFIX:NAME" or "NAME", fullname="PREFIX:NAME" or "NAME"
attr: syntax @PREFIX:NAME or @NAME where PREFIX and NAME are valid XML element names; value="", prefix="PREFIX" or "", localname="NAME", data="PREFIX:NAME" or "NAME", fullname="PREFIX:NAME" or "NAME"
fp: syntax FPDATA where prefix and name are valid XML element names; value="FPDATA", data="FPDATA", prefix="", localname="", fullname=""
hex: syntax 0xHEXDATA; value="fp-0xHEXDATA", data="0xHEXDATA", prefix="", localname="", fullname=""
hex: syntax INTDATA; value="fp-INTDATA", data="INTDATA", prefix="", localname="", fullname=""
uri: syntax ~URI where URI is any contiguous string of safe characters; value="URI", data="URI", prefix="", localname="", fullname=""
pdef: syntax ${PREFIX:NAME}="VALUE" or ${NAME}="VALUE"where PREFIX and VALUE are as above; value="VALUE", prefix="PREFIX" or "", localname="NAME", data="PREFIX:NAME=VALUE" or "NAME=VALUE", fullname="PREFIX:NAME" or "NAME"
pref: syntax ${PREFIX:NAME} or ${NAME} where PREFIX and VALUE are as above; value="", prefix="PREFIX" or "", localname="NAME", data="PREFIX:NAME" or "NAME", fullname="PREFIX:NAME" or "NAME"
cref: syntax &#INTDATA; or &#xHEXDATA;; value=<the character>, prefix="" or "", localname="INTDATA" of "xHEXDATA", data="INTDATA" or "xHEXDATA", fullname="INTDATA" or "xHEXDATA"
eref: syntax &PREFIX:NAME; or &NAME;; value="", prefix="PREFIX" or "", localname="NAME", data="PREFIX:NAME" or "NAME", fullname="PREFIX:NAME" or "NAME"
b64: syntax =B64; value="B64", prefix="", localname="", data="B64", fullname=""
str: syntax "STRING"; value="STRING", prefix="", localname="", data="STRING", fullname=""
char: syntax 'C'; value="C", prefix="", localname="0xHEX", data="C", fullname="0xHEX"
pi: syntax ?[PREFIX:]NAME; value="", prefix="PREFIX" or "", localname="NAME", data="PREFIX:NAME" or "NAME", fullname="PREFIX:NAME" or "NAME"
uc: syntax C; value="C", prefix="", localname="0xHEX", data="C", fullname="0xHEX"
ns: syntax C; value="C", prefix="", localname="0xHEX", data="C", fullname="0xHEX"
punc: syntax STRING as in accept; value="STRING", prefix="", localname="", data="STRING", fullname=""
eos: syntax <end-of-stream>; value="", prefix="", localname="", data="", fullname=""

6 Modular vocabulary commands

MV files may use a number of commands and features that enable you to use parameters effectively. Only a few manipulate parameters directly. Many more use parameters via the interpolation mechanism. The main commands that use parameters include

 <mv:init-parameter name="..." value="..." />

 <mv:set-parameter name="..." value="..." />

 <mv:append-parameter name="..." value="..." />

 <mv:incr-parameter name="..." value="..." />

 <mv:declare-prefix prefix="..." uri="...">
      ...
 </mv:declare-prefix>

 <mv:... parameters="[no]share" > ...

 <mv:if [test="..."] [value="..."] >
      ...
 </mv:if>

 <mv:if-not [test="..."] [value="..."] >
      ...
 </mv:if-not>

 <mv:else>
      ...
 </mv:else>

See the documentation for the modularvocab DTD.

7 Exporting parameters, and `parameters="[no]share"`

Parameters are local to their current mode unless they explicitly share space with their parent mode or a parameter is exported to an ancestor mode. See the documentation for the modularvocab DTD.