Commands in a Modular Vocabulary

1 Introduction

The content of a mv:match or mv:default element is a list of commands and data to control or add to the intermediate XML infoset. See Modes for more information and Writing Modular Vocabulary files for a general overview on writing and usig modular vocabularies. This page concentrates only on the basic commands. The full list of commands is given and documented in the modularvocab DTD.

2 mv:document, mv:document-fragment, mv:dtd

These commands creat a root node of the intermediate infoset indicating whether to the DOM in memory represents a document, a document fragment or a dtd, respectively. mv:document takes attributes xmldecl="include" (to include <?xml version="..." ... >, anything else to omit it), version="..." (default "1.0") encoding="..." and standalone="...". mv:document-fragment and mv:dtd take these all these attributes except standalone.

3 mv:element and mv:attribute

The mv:element command adds an XML element to the current infoset. There are two optional attributes: name="..." and ns="..". Here, name is the full qualified name of the element. (The default value is the full qualified name of the current token.) ns is a namespace uri. The contents of the mv:element command defines the contents of the element.

The mv:attribute command adds an attribute node to the current element. It also takes two optional attributes name="..." and ns="..", with the same meaning. The text value of the contents of the element is the value of the attribute.

4 mv:return and mv:abort

These commands finish the current mode. The difference between the two is that mv:abort will resture the input token stream to the time just before the current token was read, so that it (or the characters it comprises of) may be re-read. Neither command takes attrubutes and both have no content.

5 mv:process-tokens

This command takes a manditory attribute mode="..." (which is interpolated). It calls the mode with that name which accepts and processes tokens until finished, when control is returned to the point after mv:process-tokens.

6 Example: trivelt.mv

The MV trivelt.mv is a simple example MV file that reads a structured list of elements and outputs an XML document-fragment. It has two modes: main, to make the root mv:document-fragment node of the output; and elt,to make the child elements. It is run with the command gloss -mv trivelt.mv, and on input

apple orange
  pear
  banana
    kumquat
    clementine
  satsuma
lemon

it produces

<apple>
  <orange/>
  <pear/>
  <banana>
    <kumquat/>
    <clementine/>
  </banana>
  <satsuma/>
</apple>
<lemon/>

(Indentation of output added here for clarity.)

Mode "main" takes an empty punctuation string and can only run once because of the mv:return command. Mode "elts" is finished when a token not matching type "elt" is read or if the indentation of the token read wrong.

mv:process-tokens takes a complex range of attributes for fine control over the glossing process. These include:

use-indentation="...", to set indentatation checking on ("true") or off ("false"), the default is "true";
children="...", to set the maximum number of child tokens (as if ths were set in the mode);
parent="inherit|this" to specify the parent mode as being this mode (i.e. the mode containing the mv:process-tokens, this is the default or all tokens except empty punctuation) or this mode's parent (parent="inherit", the default for the punc token ""); and
parameters="[no]share" to specify whether a clone of the parameter space should be made for the new mode (parameters="noshare", the default) or whether the new mode should share the existing space.

These options are complex, but provide a lot of necessary control. For example, parameters="share" is useful to pass parameter values from a child mode to its parent. The notion of parent is used for boht indentation checking and the alternative method of passig parameter values, the mv:export-parameter command.

7 Example: testchildren.mv

The MV testchildren.mv is a modification of trivelt.mv to test the children features available in MV files. It defines element one to have at most one child normally, two to have at most two children, any child one-more to be in addition to the normal number of children, one-less to reduce the normal number of children by 1, child at-most-one to force the parent to have at most one child, and child two-left to force the parent to have at most two children remaining. It is run with the command gloss -mv testchildren.mv, and on input

one
  two
    apple
    pear
    orange
  one
    one-more
    one-more
    kumquat
  two
    one-less
    banana
    peach
  two
    at-most-one
    pineapple
  two
    pineapple
    two-left
    grape
    quince
    strawberry

it produces

<one>
  <two>
    <apple/>
    <pear/>
  </two>
</one>
<orange/>
<one>
  <one-more/>
  <one-more/>
  <kumquat/>
</one>
<two>
  <one-less/>
</two>
<banana/>
<peach/>
<two>
  <at-most-one/>
</two>
<pineapple/>
<two>
  <pineapple/>
  <two-left/>
  <grape/>
  <quince/>
</two>
<strawberry/>

(Indentation of output added here for clarity, as before.)