| Main Site |
| Tutorial |
| Documentation |
| Downloads |
|
|
|
|
|
|
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.
Valid child elements: <option>, <command>, <commandless>, <usage>
| 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.
Valid child element: <description>
Example:
| 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.
Valid child elements: none
Example: see example for <command>
| 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 ...
Valid child element: one of <and>, <or>, <xor>, <not>
Example:
| 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:
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:
Because the second <or> was redundant.
Valid child elements: <option-ref>, <and>, <or>, <xor>, <not>
Example:
<and>
<or>
<option-ref id="foo"/>
<option-ref id="bar"/>
</or>
<or>
<option-ref id="help"/>
</or>
</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>
<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.
Valid child elements: <option-ref>, <and>, <or>, <xor>, <not>
| 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.
Valid child elements: <option-ref>, <and>, <or>, <xor>, <not>
| 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.
Valid child elements: <option-ref>, <and>, <or>, <xor>, <not>
| Attribute
name |
Required |
Attribute
definition |
|---|---|---|
| none |
n/a |
n/a |
Valid child elements: <option-ref>, <and>, <or>, <xor>, <not>
<description>
The <description> tag is ...
Valid child element: <none>
| Attribute
name |
Required |
Attribute
definition |
|---|---|---|
| tnon |
n/a |
n/a |
Valid child element: <none>