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.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. |
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 |
---|---|
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. |
AndConditionImpl |
An
AndConditionImpl represents a list of Syntaxable instances
of which all are be parsed successfully when the Syntaxable s'
Syntaxable.parseArgs(String[]) methods are invoked. |
ArgsParserImpl |
A straightforward implementation of the
ArgsParser interface. |
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.
|
EnumOptionImpl<T extends Enum<T>> |
The Class EnumOptionImpl.
|
ForceSwitchImpl |
A predefined force switch.
|
HelpSwitchImpl |
A predefined help switch.
|
IntegerOptionImpl |
The Class IntegerOptionImpl.
|
OptionalConditionImpl |
The Class OptionalConditionImpl.
|
OrConditionImpl |
An
OrConditionImpl represents a list of Syntaxable instances
of which at least one must be parsed successfully when the Syntaxable
s' Syntaxable.parseArgs(String[]) methods are invoked. |
QuietSwitchImpl |
A predefined "be quiet" switch.
|
StringOperandImpl | |
StringOptionImpl |
The Class StringOptionImpl.
|
SwitchImpl |
The Class SwitchImpl.
|
SysInfoSwitchImpl |
A predefined system information switch.
|
VerboseSwitchImpl |
A predefined verbose switch.
|
XorConditionImpl |
An
XorConditionImpl represents a list of Syntaxable instances
of which only one is allowed to be parsed successfully when the
Syntaxable s' Syntaxable.parseArgs(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) 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 |
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.
|
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", "A file" );
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();
import static org.refcodes.console.ConsoleSugar.*;
...
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" );
Switch 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( FontType.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
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
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.
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.
See also:
Copyright © 2017. All rights reserved.