Parsing

The command-line, entered by the user of your program, needs to be parsed by Argument. The result of parsing is that the arguments may have their values set according to the contents of the command-line. The CommandLineParser class handles this parsing.

But the command line is not the only input that Argument can handle. It can parse input from files as well, and in three different formats in those files: Command-line, XML, and Properties file.

CommandLineParser

The CommandLineParser expects the format of the input to be in the --command value format. Even if the input is from a file rather than a command-line.

The most used, default, simplest way to parse the command line. To do it this way you would need to be using the [injection of values] method. That is because the Argument instance is not saved. So it is not possible to [obtain the values] for the arguments otherwise.

CmdLine.create(
    "--type boolean --key upperCase --variable asUpperCase"
    ).parse(this, args);

This example assumes that the CommandLineParser is handling the input. The CommandLineParser can be explicitly specified as well. This produces the same as the previous convenience method call.

ICmdLine arguments = CmdLine.create(
    "--type boolean --key upperCase --variable asUpperCase"
    );
arguments.parse(
    CommandLineParser.getInstance(arguments.getCommandPrefix(), args),
    this);
~~~~~~

The input can also be from a file rather than the command-line.

ICmdLine arguments = CmdLine.create(
"--type boolean --key upperCase --variable asUpperCase"
);
File userInput = new File("myCommandFile.txt");
arguments.parse(
CommandLineParser.getInstance(arguments.getCommandPrefix(), userInput),
this);

<b>XmlParser</b>

The input can be in an XML format.  The input can be from a File, an InputStream, or a String.  Every XML file must contain the outermost tag of <code>cmdline</code>.  Unnamed, or positional, arguments must have the attribute of "unnamed".  Multi-value arguments are specified by repeating the tag.  Each argument is a tag.  If it is an embedded parser (group) argument then it MUST be a tag.  It also must be a tag if it is unnamed (positional).  Any other argument can be specified as an attribute or a tag.

ICmdLine arguments = CmdLine.create(
"--type boolean --key upperCase --variable asUpperCase"
);
File userInput = new File("myCommandFile.xml");
arguments.parse(
XmlParser.getInstance(userInput),
this);

<b>Format of Input</b>

<b>Single value, named argument</b>

<cmdline>
<name>value</name>
</cmdline>

<b>Boolean argument</b>

<cmdline>
<myBoolean></myBoolean>
</cmdline>

<b>Single value, positional (unnamed) argument</b>

<cmdline>
<noname>value</noname>
</cmdline>

<b>Multi-value, named argument</b>

<cmdline>
<name>value</name>
<name>another value</name>
</cmdline>

<b>Multi-value, positional (unnamed) argument</b>

<cmdline>
<noname>value</noname>
<noname>another value</noname>
</cmdline>

You can also specify multi-value with commas in the same tag by using the delim attribute.

<cmdline>
<noname delim=",">value, another value</noname>
</cmdline>

<b>Single value within a named group argument</b>

<cmdline>
<aGroup>
<aName>aValue</aName>
</aGroup>
</cmdline>

You can also specify the argument as an attribute on a group (embedded parser).

<cmdline>
<aGroup aName="aValue"></aGroup>
</cmdline>

<b>NameSpaceParser</b>
The input can be in a Properties-like format.  The input can be from a File, an InputStream, or a String.

ICmdLine arguments = CmdLine.create(
"--type boolean --key upperCase --variable asUpperCase"
);
File userInput = new File("myCommandFile.xml");
arguments.parse(
NamespaceParser.getInstance(userInput),
this);
~~~~~

Format of Input
Each line in the file is one key=value pair. The key is the --key of the argument. If the argument is positional the key is empty. If the argument is a multi-value argument then it has a bracketed number as part of the key.

Single value, named argument

name=value

Boolean argument

myBoolean=

Single value, positional (unnamed) argument

=value

Multi-value, named argument

name[0]=value

name[1]=another value

Multi-value, positional (unnamed) argument

[0]=value

[1]=another value

Single value within a named group argument

aGroup.aName=aValue

Single value within a positional group argument

.aName=aValue

Multi-value within a positional multi-value group argument

[0].aName[0]=aValue

Multi-value within a named multi-value group argument

aGroup[0].aName[0]=aValue