The program interface definition schema details

This page gives a detailed view of the program interface definition schema nodes. For a complete view, read the full schema <<file ns/xsd/program/2.0/program.xsd>>

To validate a XML file against the XSD schema, you can use xmllint (part of the Gnome XML toolkit)

xmllint --noout --xinclude --schema ${NS_XML}/ns/xsd/program/2.0/program.xsd ${path-to-your-xml}

Namespace

The schema location of the <program /> schema is ##http://xsd.nore.fr/program##. The namespace ##prg## is generally used in XML documents.

<prg:program xmlns:prg="http://xsd.nore.fr/program" version="2.0" />

Shared nodes

Some nodes of the XML schema are used in various nodes.

documentation

A <documentation /> node can be added to most of element description nodes (<program />, <subcommand />, <switch />, <value />, ...). It may contains

<documentation>
  <abstract>A short description</abstract>
  <details>A less short description<endl />with more lines
    <block>An some nested block of text</block>
  </details>
</documentation>

databinding

Options (switch, argument, multiargument and group) and values (value and other) may defines a variable name representing the option's value when generating parser code through XSLT stylesheets. The final name of the variable depends on the generated language.

<databinding>
  <variable>var_name</variable>
</databinding>

names

All option nodes (except the special <group /> node) have at least one name. Option names are command line arguments starting with a single dash (ex. -h) for single-letter names and a double dash (ex. --help) for long names. Theses names are described in a names node and its sub nodes short and long.

<names>
  <short>h</short>
  <long>help</long>
  <long>mayday</long>
</names>

The names node can contain any number of different short and long names.

See also the Option name aliasing section of the specifications page.

ui

the parent node.

program

The <program /> node is the root of a full progrma XML document. It gives general informations about the program and its authors. The <program /> node may also contains:

<program>
  <name>my_program</program>
  <author>Thor</author>
  <copyright>Copyright © 1337 by Leet (anonymous@hack.me)</copyright>
  <license>Distributed under the terms of the DO-WHAT-YOU-WANT license</license>
  <documentation>
    <!-- ... -->
  </documentation>
  <ui>
    <!-- A more user friendly name to display in a GUI -->
    <label>My Program</label>
  </ui>
  <subcommands>
    <!-- ... -->
  </subcommands>
  <options>
    <!-- ... -->
  </options>
  <values>
    <!-- ... -->
  </values>
</program>

subcommands

A program may have a set of subcommands. The subcommand layout is commonly used in VCS system such as Mercurial

hg add -S file1 file2

The <subcommands /> node accepts a list of <subcommand /> node

<subcommands>
  <subcommand />
  <subcommand />
  <!-- ... -->
<subcommands/>

subcommand

The <subcommand /> node describes a program subcommand. It must contains at least a <name /> node whose value is the main name of the subcommand. It also accept

<subcommand>
  <name>commit</name>
  <aliases>
    <alias>ci</alias>
    <alias>store</alias>
  </aliases>
  <options>
    <!-- ... -->
  </options>
  <values> 
    <!-- ... -->
  </values>
<subcommand/>

options

Contains a set of option nodes

<options>
  <switch>
    <!-- ... -->
  </switch>
  <argument>
    <!-- ... -->
  </argument>
</options>

The <options /> node can be used as a root node of an XML document to create a library of common options.

switch

Describes an option without argument.

<switch id="optional_id">
  <databinding>
    <variable>hasSwitch</variable>
  </databinding>
  <documentation>
    <abstract>Simple switch</abstract>
    <details>A simple switch option (true/false)</details>
  </documentation>
  <names>
    <short>s</short>
    <long>simpleswitch</long>
  </names>
  <ui mode="default">
    <label>GUI Switch label</label>
  </ui>
</switch>

If the option is present on the command line, the value of the bound variable will be true. Otherwise, false.

The <ui /> node may specify the way the switch is displayed by specifying the mode attribute

argument

Describes an option with a single parameter.

<argument>
  <databinding>
    <variable>dgarg</variable>
  </databinding>
  <documentation>
    <abstract>Single argument option</abstract>
  </documentation>
  <names>
    <long>argument-option</long>
    <short>a</short>
  </names>
  <default>Default value</default>
  <ui mode="hidden">
    <label>GUI friendly label</label>
    <value>Value for GUI frontend</value>
  </ui>
</argument>

The value of the bound variable will be

The <ui /> node may specify a specific value to use when the option mode is "hidden".

Option value restrictions

A (non-)restrictive list of value can be set with the <select /> node.

<select restrict="true">
  <option>Value A</option>
  <option>2nd value</option>
  <option>Yet another possible value</option>
</select>

The @restrict attribute can be set to true to limit possible values to those described in the <option /> nodes. Otherwise, the <select /> node will only be used as a hint.

Option value types

The type of argument expected by the option may also be described using the <type /> subnode

<argument>
  <!-- ... -->
  <type>
    <number min="1.0" max="10.0" decimal="2" />
  </type>
</argument>
number
path

The <path /> node has two optional attributes.

<path access="rw" exists="true" />

The @access attribute will filter file path by permissions. @access value have to be a combination of the characters 'r', 'w' and 'x'

The @exist attribute specify that the path must exists. The only accepted value for this attribute is true.

The kind of file system item expected is defined with the sub node <kinds />

<path>
  <kinds>
    <folder />
    <file />
    <socket />
    <symlink />
  </kinds>
</path>

A set of name patterns rules can be set using the <patterns /> subnode

<path>
  <patterns>
    <pattern>
      <name>XML-based files</name>
      <rules>
        <rule>
          <endWith>.xml</endWith>
        </rule>
        <rule>
          <endWith>.xsl</endWith>
        </rule>
      </rules>
    </pattern>
    <pattern>
      <name>Linux System configuration path</name>
      <rules>
        <rule>
          <startWith>/etc</startWith>
        </rule>
      </rules>
    </pattern>
  </patterns>
</path>

multiargument

Describes an option which will accept one or more parameters. The <multiargument/> node has the same sub nodes as the <argument /> minus the <default /> one and add optional @min and @max attributes to set the minimum and maximum number of parameters accepted.

group

Describes a sub group of options.

<group type="exclusive">
  <options>
    <!-- ... Sub options -->
    <switch>
      <names><short>a</short></names>
    </switch>
    <switch>
      <names><short>b</short></names>
    </switch>
  </options>
</group>

The optional @type attribute with a value set to exclusive specify that only one option of the group can be present on the same command line. In the example above, writing program -a -b will not be allowed.

If @type is not present, the <group /> will not have any particular incidence on the command line parsing. However, it will affect how the options are displayed in a XUL frontend.

Required option

The <argument />, <multiargument /> and <group /> nodes accept the attribute @required="true". This attribute specifies that the option is mandatory and must appear on the command line at least once

<prg:argument required="true" id="prg.unittest.option.required.rargumentA">
  <prg:databinding>
    <prg:variable>rargumentA</prg:variable>
  </prg:databinding>
  <prg:documentation>
    <prg:abstract>This option is mandatory</prg:abstract>
  </prg:documentation>
  <prg:names>
    <prg:long>argument-A</prg:long>
    <prg:short>A</prg:short>
  </prg:names>
</prg:argument>

When the required option O is part of an exclusive group G (directly or not), this rule will apply only if one of the options of the exclusive group is present and if this option is O or an ancestor of O

<prg:group type="exclusive" id="prg.unittest.option.groupT">
  <prg:databinding>
    <prg:variable>groupT</prg:variable>
  </prg:databinding>
  <prg:options>
    <prg:group id="prg.unittest.option.groupTa">
      <prg:options>
        <prg:switch id="prg.unittest.option.switchD">
          <prg:databinding>
            <prg:variable>switchB</prg:variable>
          </prg:databinding>
          <prg:documentation>
            <prg:abstract>This one is NOT required</prg:abstract>
          </prg:documentation>
          <prg:names>
            <prg:long>switch-d</prg:long>
            <prg:short>d</prg:short>
          </prg:names>
        </prg:switch>
        <prg:argument id="prg.unittest.option.argumentE">
          <prg:databinding>
            <prg:variable>argumentE</prg:variable>
          </prg:databinding>
          <prg:names>
            <prg:short>e</prg:short>
          </prg:names>
        </prg:argument>
      </prg:options>
    </prg:group>
    <prg:argument required="true" id="prg.unittest.option.rargumentF">
      <prg:databinding>
        <prg:variable>rargumentF</prg:variable>
      </prg:databinding>
      <prg:documentation>
        <prg:abstract>The @required attribute will be ignored if the exclusive group
          was 'activated' by another option (--switch-d or -e), or not activated at all</prg:abstract>
      </prg:documentation>
      <prg:names>
        <prg:long>argument-F</prg:long>
        <prg:short>F</prg:short>
      </prg:names>
    </prg:argument>
  </prg:options>
</prg:group>

values

Describes particular meanings of positional arguments (non-option). 

																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																																					mv -f from to

In the mv command, from and to are not options nor options arguments. from is the first positional argument and to the second.

<program>
  <values>
    <value>
      <!-- First positional argument description -->
    </value>
    <value>
      <!-- Second positional argument description -->
    </value>
    <other>
      <!-- Other positional arguments description -->
    </other>
  </values>
  <subcommands>
    <subcommand>
      <name>...</name>
      <values>
        <!-- positional arguments meaning in the subcommand context -->
        <value />
        <other />
      </values>
    </subcommand>
  </subcommands>
</program>

Values can't be bound to a specific variable using <databinding/> node. They are generally represented as an indexed array variable (ex: parser_values[*] in the shell, or result.values in Python)

If no <values/> node is present in a program or a subcommand description, this program (or subcommand) will treat any non-recognized command line argument as an error. If no <other /> node is set, the n+1th value and the following will be treated as errors (where n is the number of <value /> nodes)

value

Describes one positional argument meaning. The <value /> accepts the same nodes as the <argument /> node except <databinding /> and <default />

other

Describes all other possible positional arguments after zero or more specifically defined ones using <value/>. The <other/> node accepts the same nodes as the <multiargument /> node except <databinding />

The program interface definition framework