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:
Flag
es , Option
s and
Condition
s. You actually build the syntax tree for
your command line tool's supported arguments:
Option<String> theFile = new StringOption( "-f", "--file", "file", "A file" );
Flag theAdd = new Flag( "-a", null, "Add the specified file" );
Flag theDelete = new Flag( "-d", null, "Delete the specified file" );
Condition theXor = new XorCondition( theAdd, theDelete );
Syntaxable theOptional = new OptionalCondition( theXor );
Condition theAnd = new AndCondition( theOptional, theFile );
ArgsParser theArgsParser = new ArgsParserImpl( theAnd );
theArgsParser.printUsage();
// theArgsParser.printHelp();
import static org.refcodes.cli.CliSugar.*;
...
public static void main( String args[] ) {
Option<Integer> theWidth = intOption( "-w", "--width", "width", "Sets the console width" );
Option<Integer> thePort = intOption( "-p", "--port", "port", "Sets the port for the server" );
Option<Integer> theMaxConns = intOption( "-c", "--connections", "connections", "Sets the number of max. connections" );
Option<String> theUsername = stringOption( "-u", "--user", "username", "The username for HTTP Basic-Authentication" );
Option<String> theSecret = stringOption( "-s", "--secret", "secret", "The password for HTTP Basic-Authentication" );
Flag theHelp = helpSwitch( "Shows this help" );
Condition theRootCondition = xor(
and(
thePort, optional( theMaxConns ), optional( and( theUsername, theSecret ) ), optional( theWidth )
),
theHelp
);
ArgsParser theArgsParser = new ArgsParserImpl( theRootCondition );
theArgsParser.withSyntaxNotation( SyntaxNotation.REFCODES );
theArgsParser.withName( "TinyRestful" ).withTitle( "TINYRESTFUL" ).withCopyrightNote( "Copyright (c) by FUNCODES.CLUB, Munich, Germany." ).withLicenseNote( "Licensed under GNU General Public License, v3.0 and Apache License, v2.0" );
theArgsParser.withBannerFont( new FontImpl( FontFamily.DIALOG, FontStyle.BOLD, 14 ) ).withBannerFontPalette( AsciiColorPalette.MAX_LEVEL_GRAY.getPalette() );
theArgsParser.setDescription( "Tiny evil RESTful server. TinyRestfulServer makes heavy use of the REFCODES.ORG artifacts found together with the FUNCODES.CLUB sources at http://bitbucket.org/refcodes." );
List<? extends Operand<?>> theResult = theArgsParser.evalArgs( args );
...
}
...
Most obvious is the missing new
statement for instantiating the
parts of your command line parser as this is done by the statically imported
methods. ### Under the hood 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
StringOption
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
Flag
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
ArgsParser.evalArgs(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 ArgsParser.evalArgs(String[])
method.
An Option
has a state which changes with each invocation of the
ArgsParser.evalArgs(String[])
method.
Flag
:Flag
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.
Operation
:Operation
is an
argument representing a function or a method and is either provided or not
provided as of Operation.isEnabled()
. It must neither be prefixed
with "-" nor with "--" in contrast to the Option
or the Flag
type.
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.
See also:
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. |
ArgsParserAccessor |
Provides an accessor for a
ArgsParser property. |
ArgsParserAccessor.ArgsParserBuilder<B extends ArgsParserAccessor.ArgsParserBuilder<B>> |
Provides a builder method for a
ArgsParser property returning the
builder for applying multiple build operations. |
ArgsParserAccessor.ArgsParserMutator |
Provides a mutator for a
ArgsParser property. |
ArgsParserAccessor.ArgsParserProperty |
Provides a
ArgsParser property. |
ArgsParserMixin<B extends ArgsParserMixin<B>> |
This mixin provides builder additions (as of the builder pattern for chained
configuring method calls) for parsing command line arguments.
|
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. |
Option<T> |
An
Option represents a command line option with the according
option's value. |
RootConditionAccessor |
Provides an accessor for a root condition property.
|
RootConditionAccessor.RootConditionBuilder<B extends RootConditionAccessor.RootConditionBuilder<B>> |
Provides a builder method for a root condition property returning the
builder for applying multiple build operations.
|
RootConditionAccessor.RootConditionMutator |
Provides a mutator for a root condition property.
|
RootConditionAccessor.RootConditionProperty |
Provides a root condition property.
|
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. |
SyntaxUsage |
The
SyntaxUsage interface defines those methods required to create a
human readable usage String from the implementing instance. |
Class | Description |
---|---|
AbstractCondition |
The
AbstractCondition is an abstract implementation of an
Condition providing the boiler plate when implementing the
Condition interface. |
AbstractOperand<T> |
The
AbstractOperand is an abstract implementation of an
Operand providing the boiler plate when implementing the
Operand interface. |
AbstractOption<T> |
The
AbstractOption is an abstract implementation of an Option
providing the boiler plate when implementing the Option interface. |
AndCondition |
An
AndCondition contains (represents) a list of Condition
(Syntaxable ) instances (nested by the AndCondition ) of which
all are to be parsed successfully as of invoking the
Syntaxable.parseArgs(String[], String[]) methods. |
ArgsParserImpl |
A straightforward implementation of the
ArgsParser interface. |
ArrayOperand<T> |
Creates an array representation facade for the encapsulated
Operand . |
ArrayOption<T> |
Creates an array representation facade for the encapsulated
Option . |
CharOption | |
CliSugar | |
CliUtility |
This utility class provides method useful for the refcodes-cli artifact and
whose implementation has been motivated by the implementation of the
refcodes-cli artifact.
|
DebugFlag |
A predefined debug switch.
|
DoubleOption | |
EnumOption<T extends Enum<T>> |
The Class EnumOption.
|
ExampleUsage |
An example usage item describing a usage scenario.
|
FileOption | |
Flag |
The
Flag class implements the Option interface for
representing either a true or a false state: When a
flag is provided to your command line arguments, then it is considered to be
true , when it is omitted, then it is considered to be
false as of Flag.isEnabled() . |
FloatOption | |
ForceFlag |
A predefined force switch.
|
HelpFlag |
A predefined help switch.
|
IntOption | |
LongOption | |
Operation |
The
Operation is an argument representing a function or a method and
is either provided or not provided as of Operation.isEnabled() . |
OptionalCondition |
The
OptionalCondition can nested by an AndCondition and
encapsulates a Condition which may be provided but does not
necessarily needs to be provided in order for the AndCondition to
successfully parse the nested Condition items including the
OptionalCondition . |
OptionConditionFacade | |
OrCondition |
An
OrCondition represents a list of Condition
(Syntaxable ) instances of which at least one must be parsed
successfully when the Syntaxable s'
Syntaxable.parseArgs(String[], String[]) methods are invoked. |
QuietFlag |
A predefined "be quiet" switch.
|
StringOperand | |
StringOption | |
SysInfoFlag |
A predefined system information switch.
|
VerboseFlag |
A predefined verbose switch.
|
XorCondition |
An
XorCondition represents a list of Condition
(Syntaxable ) instances of which only one is allowed to be parsed
successfully when the Syntaxable.parseArgs(String[], String[]) methods
are invoked. |
Enum | Description |
---|---|
ExitCode |
Some default exit codes defined for CLI applications.
|
SyntaxNotation |
The
SyntaxNotation is used by a the
Syntaxable.toSyntax(SyntaxNotation, String, String) 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.
|
CliException |
Base exception for the console artifact.
|
CliException.ConsoleArgsException |
This abstract exception is the base exception for all command line
argument related exceptions.
|
CliException.ConsoleCliException |
The Class 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.
|
Copyright © 2021. All rights reserved.