Main Site
Tutorial
Documentation
Downloads
JCommando Tag Reference

JCommando Tag Reference

This is a reference of the tags that can appear in a JCommand XML configuration file.  It specifies the syntax of the tags, as well as what attributes are available (or required) for each tag.  If you're looking for the JavaDoc, it's here.

<jcommando>

The <jcommando> tag is the primary (outter-most) tag in a JCommando configuration file.

Attribute name
Required
Attribute definition
none
n/a
n/a

Valid child elements: <option>, <command>, <commandless>, <usage>

<option>

The <option> tag is used to define a specific option.  One or both of the 'short' and 'long' must be specified.

Attribute name
Required
Attribute definition
id
Yes
A unique identifier for this option.  Must follow valid Java identifier naming conventions.
short
No
The "short form" of the option.  Specifying short="x" means that -x is a valid option on the command-line.
long
No
The "long form" of the option.  This is recommended, but not required.  Specifying long="expand-file" means that --expand-file is a valid option on the commmand-line.
type
No
This is a valid Java type, and one of: String, long, double.

Valid child element: <description>

Example:

<option id="fooBar" short="f" long="foobar" type="String">
   <description>Specified the type of foobar to process.</description>
</option>


<command>

The <command> specifies the syntax of a 'command' and the options that are allowed to be used with it.  A 'command' is a command-line parameter that is not associated with an option, and does not begin with a single or double hyphen.  An example of a command-line with a command is:

cvs -r label checkout

In this case, '-r' is an option, 'label' is a parameter to the '-r' option, and 'checkout' is the command.  When JCommando encounters a known command on the command-line, it invokes the associated method on the user's implementing class.

Attribute name
Required
Attribute definition
id
Yes
A unique identifier for this option.  Must follow valid Java identifier naming conventions.
allow-optionless
No


Valid child element: one of <and>, <or>, <xor>, <not>

Example:

<command id="checkout" allow-optionless="true">
   <or>
      <option-ref id="fooBar"/>
      <option-ref id="bazFaz"/>
   </or>
</command>


<option-ref>

The <option-ref> tag is used to bind an option to a 'command'.  Multiple 'commands' can reference the same option definition.

Attribute name
Required
Attribute definition
id
Yes
A unique identifier that equals an id specified by an <option>

Valid child elements: none

Example: see example for <command>

<commandless>

The <commandless> tag is ...

Attribute name
Required
Attribute definition
id
Yes
A unique identifier for this option.  Must follow valid Java identifier naming conventions.
allow-optionless
No


Valid child element: one of <and>, <or>, <xor>, <not>

Example:

<commandless id="execute" allow-optionless="true">
   <xor>
      <option-ref id="fooBar"/>
      <option-ref id="help"/>
   </xor>
</commandless>


<and>

The <and> tag is one of the logical grouping operators available in JCommando.  The logical grouping operators are in some ways the heart of JCommando's ability to parse complex option requirements.  In order for parsing to be considered successful, the logical operators must evaluate to true; meaning their constraints must be satisfied.  Let's look at a complex scenario:

<and>
   <or>
      <option-ref id="foo"/>
      <option-ref id="bar"/>
   </or>
   <or>
      <option-ref id="help"/>
   </or>
</and>


In this case, the <and> will only be satisfied (i.e. true), if both <or> conditions are true.  The <and> means that "or condition 1" AND "or condition 2" must be true.  So, to satisfy this constraint, one of "--foo" OR "--bar" (or both!) must be specified, AND "--help" must be specified.  The above semantic is equivalent to:

<and>
   <or>
      <option-ref id="foo"/>
      <option-ref id="bar"/>
   </or>
   <option-ref id="help"/>
</and>


Because the second <or> was redundant.

Attribute name
Required
Attribute definition
none
n/a
n/a

Valid child elements: <option-ref>, <and>, <or>, <xor>, <not>

Example:

<and>
   <option-ref id="recurse">
   <xor>
      <or>
         <option-ref id="foo"/>
         <option-ref id="bar"/>
      </or>
         <option-ref id="help"/>
   </xor>
</and>


<or>

The <or> tag provides a logical OR with respect to it's child elements.  It will evaluate to true if any one of it's sub-elements evaluates to true.  It will evaluate to false if none of it's sub-elements evaluates to true.  See the <and> tag for a more detailed explanation of logical operators.

Attribute name
Required
Attribute definition
none
n/a
n/a

Valid child elements: <option-ref>, <and>, <or>, <xor>, <not>

<xor>

The <xor> tag provides a logical "mutually exclusive" OR with respect to it's child elements.  It will evaluate to true if exactly one of it's sub-elements evaluates to true.  It will evaluate to false if multiple or none of it's sub-elements evaluates to true.  See the <and> tag for a more detailed explanation of logical operators.

Attribute name
Required
Attribute definition
none
n/a
n/a

Valid child elements: <option-ref>, <and>, <or>, <xor>, <not>

<not>

The <not> tag provides a logical NOT with respect to it's child elements.  It will evaluate to true if none of it's sub-elements evaluates to true.  It will evaluate to false if any of it's sub-elements evaluates to true.  See the <and> tag for a more detailed explanation of logical operators.

Attribute name
Required
Attribute definition
none
n/a
n/a

Valid child elements: <option-ref>, <and>, <or>, <xor>, <not>

<description>

The <description> tag is ...

Attribute name
Required
Attribute definition
tnon
n/a
n/a

Valid child element: <none>