Schema

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)

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

• [The program interface definition schema details](#The program interface definition schema details)
  • Namespace
  • [Shared nodes](#Shared nodes)
    • documentation
    • databinding
    • names
    • ui
  • program
  • subcommands
    • subcommand
  • options
    • switch
    • argument
      • [Option value restrictions](#Option value restrictions)
      • [Option value types](#Option value types)
        • number
        • path
    • multiargument
    • group
  • values
    • value
    • other

Namespace

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

#!xml
<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>

  #!xml <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.

#!xml
<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.

#!xml
<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.

  #!xml <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

#!bash
hg add -S file1 file2 

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

#!xml
<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

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

options

Contains a set of option nodes

#!xml
<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.

#!xml
<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.

#!xml
<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.

#!xml
<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

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

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

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

#!xml
<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 />

#!xml
<path>
	<kinds>
		<folder />
		<file />
		<socket />
		<symlink />
	</kinds>
</path>

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

#!xml
<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.

#!xml
<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.

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

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.

• zero or more <value /> node

• then, zero or one <other /> node

  #!xml <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