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

<abstract /> whose content is a short inline description of the element
<details /> whose content is a more precise description. The content is a mix between text and some simple text formatting nodes
- <br /> or <endl /> for line breaks
- <block>details sub content</block>

<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

<ui /> nodes add special behaviors and informations for graphical frontend. The content of the <ui /> node depends of 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:

a <subcommands /> node, to describes the program subcommands and their options.
a <options /> node, to describes the program global options.
a <values /> node, to desccribes positional arguments meanings.

<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

one or more <alias /> names in a <aliases /> node
one <options /> node
one <values /> node

<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

default (the default): The option will be visible as a checkbox or a radiobutton.
hidden: The switch will allways be set to true and will be hidden in the GUI.
disabled: The option will not be available in the GUI and will not be set.

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 string given by the following positional argument, if the option is present on the command line,
the content of the <default /> node
An empty string otherwise

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>

<select /> is used in various way:

by the bash completion generator to suggest more accurate items to the user
by the parser generators to automatically check arguments values and raise errors if needed
by the XUL frontend generator to select which input control to display

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>

<type /> is used in various way:

by the bash completion generator to suggest more accurate items to the user
by the parser generators to automatically check arguments values and raise errors if needed
by the XUL frontend generator to select which input control to display

<type /> may contain one of the following nodes

<existingcommand /> An executable available in the user path
<hostname /> A host name
<mixed /> May contain anything (alias of <string />)
<number /> A numeric value
<path /> A file system path
<string /> May contain anything

number

<number /> may specify

@min to set a minimal accepted value (v >= @min)
@min to set a maximal accepted value (v <= @max)
@decimal to set the number of decimal to use for a floating point 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'

'r': Readable file
'w': Writable file
'x': Executable file

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.

<group /> accepts the following sub nodes described above.

<documentation />
<databinding />
<options />

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.

<values /> can appear under <program /> or <subcommand /> nodes and accept

zero or more <value /> node
then, zero or one <other /> node

<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

Wiki

ns-xml / program / Schema