See: Description
Interface | Description |
---|---|
ArgsAccessor |
Provides an accessor for a command line arguments (short "args") array.
|
ArgsAccessor.ArgsMutator |
Provides a mutator for a args property.
|
ArgsAccessor.ArgsProperty |
Provides a args property.
|
ArgsParser |
The
ArgsParser provides means for parsing command line arguments and
constructing a command line utility's help output. |
Condition |
The
Condition interface represents a node in the command line
arguments syntax tree; simply extending the Syntaxable interface and
adding the functionality of providing access to the added Operand s
(leafs). |
Operand<T> |
An
Operand represents a value parsed from command line arguments.An
Operand has a state which changes with each invocation of the
Syntaxable.parseArgs(String[]) method. |
Option<T> |
An
Option represents a command line option with the according
option's value. |
Switch | |
Syntaxable |
A
Syntaxable defines the methods at least required when building a
command line arguments syntax tree for traversing the syntax tree; either for
parsing command line arguments or for constructing the command line arguments
syntax. |
Class | Description |
---|---|
ConsoleSugar | |
ConsoleUtility |
This utility class provides method useful for the refcodes-console artifact
and whose implementation has been motivated by the implementation of the
refcodes-console artifact.
|
Enum | Description |
---|---|
ExitCode |
Some default exit codes defined for CLI applications.
|
SyntaxNotation |
The
SyntaxNotation is used by a the
Syntaxable.toSyntax(SyntaxNotation) method to determine which
notation to be used for the generated syntax. |
Exception | Description |
---|---|
AmbiguousArgsException |
Thrown in case at least one command line argument is ambiguous regarding
expected args vs. provided args.
|
ArgsMismatchException |
Thrown in case a command line arguments mismatch regarding provided and
expected args.
|
ConsoleException |
Base exception for the console artifact.
|
ConsoleException.ConsoleArgsException |
This abstract exception is the base exception for all command line
argument related exceptions.
|
ConsoleException.ConsoleCliException | |
ParseArgsException |
Thrown in case the provided command line arguments do not respect the
required syntax or cannot be converted to the required type.
|
SuperfluousArgsException |
Thrown in case there were arguments found not being used (superfluous
arguments).
|
UnknownArgsException |
Thrown in case not one command line argument matched regarding the provided
args vs. the expected args.
|
foo-bar [{ -a | -d }] -f <file>
"foo-bar" can be invoked either with an optional "-a" or with an optional "-d" switch, but not both of them at the same time, and a file "-f <file>" must be provided, else the passed arguments are rejected as not being valid.
Valid arguments would be:
Switch
es ,
Option
s and
Condition
s. You actually build the syntax tree
for your command line tool's supported arguments:
Option<String> theFile = new StringOptionImpl( "-f", "--file", "file", "The file to be processed" ); Switch theAdd = new SwitchImpl( "-a", null, "Add the specified file" ); Switch theDelete = new SwitchImpl( "-d", null, "Delete the specified file" ); Condition theXor = new XorConditionImpl( theAdd, theDelete ); Syntaxable theOptional = new OptionalImpl( theXor ); Condition theAnd = new AndConditionImpl( theOptional, theFile );ArgsParser theArgsParser = new ArgsParserImpl( theAnd ); theArgsParser.printUsage(); // theArgsParser.printHelp();
As seen above, you pass your root Condition
to
the ArgsParser
which then already can print out
your command line tool's usage string:
String
array to your parser
and let it parse it:
String[] args = new String[] { "-f", "someFile", "-d" }; List<? extends Operand<?>> theResult = theArgsParser.evalArgs( args ); File theConfigFile = new File( theFile.getValue() );
Now the leaves of your syntax tree are filled with the argument's values
according to the syntax you have been setting up: Your
StringOptionImpl
instance aliased
"theFile" now contains the value "someFile".
The "theResult" contains the parsed arguments for you to use in your business logic.
In case of argument rejection, a sub-type of the
ArgsMismatchException
is being thrown;
actually one of the exceptions
UnknownArgsException
,
AmbiguousArgsException
,
SuperfluousArgsException
or
ParseArgsException
is being thrown,
according to the cause of the rejection. So you can either catch the
ArgsMismatchException
or, if you need more
details on the cause, the other sub-exceptions.
Syntaxable
:Syntaxable
defines the methods at least required when building a
command line arguments syntax tree for traversing the syntax tree; either for
parsing command line arguments or for constructing the command line arguments
syntax.
By providing various implementations of the Syntaxable
's subclasses
such as Operand
, Option
or Condition
, a command line
arguments syntax tree can be constructed. This syntax tree can be use to
create a human readable (verbose) command line arguments syntax and to parse
an array of command line arguments for determining the Operand
s', the
Switch
es' or the Option
s' values.
Operand
:Operand
represents a value parsed from command line arguments. An
Operand
has a state which changes with each invocation of the
#parseArgs(String[])
method.
It is recommended to put your Operand
instance(s) at the end of your
top Condition
to enforce it to be the last Syntaxable
(s) when
parsing the command line arguments - this makes sure that any Option
s
pick their option arguments so that the Operand
(s) will correctly be
left over for parsing command line argument(s); the Operand
will not
pick by mistake an Option
argument.
Option
:Option
represents a command line option with the according
option's value. An Option
can be seen as a key / value(s) pair
defined in the command line arguments parsed via the
#parseArgs(String[])
method.
An Option
has a state which changes with each invocation of the
#parseArgs(String[])
method.
Switch
:Switch
is an Option
with a Boolean
state. Usually
switches are just set or omitted in the command line arguments with no value
provided; former representing a true
status and latter
representing a false
status.
Condition
:Condition
interface represents a node in the command line
arguments syntax tree; simply extending the Syntaxable
interface and
adding the functionality of providing access to the added Operand
s
(leafs). In future extensions, a Condition
might provide access to
the child Syntaxable
elements contained in a Condition
instance. As of the current findings, access to the children of the
Condition
node is not required and would make the interface
unnecessarily complicated.
Copyright © 2016. All rights reserved.