Package org.refcodes.console
Getting started:
Consider you have a tool called "foo-bar" to be invoked with the below allowed argument combinations (syntax):
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:
- foo-bar -f someFile
- foo-bar -d -f anyFile
- foo-bar -f otherFile -a
- foo-bar -a -f otherFile
- foo-bar -f someFile -b
- foo-bar -a someFile -f
- foo-bar -a -d -f anyFile
- foo-bar -a -x -f otherFile
Construct your parser:
First build your syntax usingFlag
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" );
Flag theAdd = new FlagImpl( "-a", null, "Add the specified file" );
Flag theDelete = new FlagImpl( "-d", null, "Delete the specified file" );
Condition theXor = new XorConditionImpl( theAdd, theDelete );
Syntaxable theOptional = new OptionalConditionImpl( theXor );
Condition theAnd = new AndConditionImpl( theOptional, theFile );
ArgsParser theArgsParser = new ArgsParserImpl( theAnd );
theArgsParser.printUsage();
// theArgsParser.printHelp();
Using syntactic sugar
The [`TinyRestfulServer`](https://bitbucket.org/refcodes/funcodes-tinyrestful/raw /master/src/main/java/club/funcodes/tinyrestful/TinyRestfulServer.java) demo application uses `syntactic sugar` for setting up the command line arguments parser:
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" );
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( 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:
Test (invoke) your parser:
In real live you would pass your main-method's args[] array to the parser. Now just for a test-run, pass aString
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
Flag
es' or the Option
s' values.
Operand
:
An 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
:
An 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
:
A 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.
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). 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 Summary 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 TheArgsParser
provides means for parsing command line arguments and constructing a command line utility's help output.ArgsParserAccessor Provides an accessor for aArgsParser
property.ArgsParserAccessor.ArgsParserBuilder<B extends ArgsParserAccessor.ArgsParserBuilder<B>> Provides a builder method for aArgsParser
property returning the builder for applying multiple build operations.ArgsParserAccessor.ArgsParserMutator Provides a mutator for aArgsParser
property.ArgsParserAccessor.PropertiesProperty Provides aArgsParser
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 TheCondition
interface represents a node in the command line arguments syntax tree; simply extending theSyntaxable
interface and adding the functionality of providing access to the addedOperand
s (leafs).Flag Operand<T> AnOperand
represents a value parsed from command line arguments.Option<T> AnOption
represents a command line option with the according option's value.RootConditionAccessor Provides an accessor for a rootCondition property.RootConditionAccessor.RootConditionBuilder<B extends RootConditionAccessor.RootConditionBuilder<B>> Provides a builder method for a rootCondition property returning the builder for applying multiple build operations.RootConditionAccessor.RootConditionMutator Provides a mutator for a rootCondition property.RootConditionAccessor.RootConditionProperty Provides a rootCondition property.Syntaxable ASyntaxable
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 TheSyntaxUsage
interface defines those methods required to create a human readable usageString
from the implementing instance. -
Class Summary Class Description AbstractCondition TheAbstractCondition
is an abstract implementation of anCondition
providing the boiler plate when implementing theCondition
interface.AbstractOperand<T> TheAbstractOperand
is an abstract implementation of anOperand
providing the boiler plate when implementing theOperand
interface.AbstractOption<T> TheAbstractOption
is an abstract implementation of anOption
providing the boiler plate when implementing theOption
interface.AndConditionImpl AnAndConditionImpl
represents a list ofSyntaxable
instances of which all are be parsed successfully when theSyntaxable
s'Syntaxable.parseArgs(String[])
methods are invoked.ArgsParserImpl A straightforward implementation of theArgsParser
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 java.lang.Enum<T>> The Class EnumOptionImpl.FlagImpl ForceFlagImpl A predefined force switch.HelpFlagImpl A predefined help switch.IntegerOptionImpl The Class IntegerOptionImpl.OptionalConditionImpl The Class OptionalConditionImpl.OrConditionImpl AnOrConditionImpl
represents a list ofSyntaxable
instances of which at least one must be parsed successfully when theSyntaxable
s'Syntaxable.parseArgs(String[])
methods are invoked.QuietFlagImpl A predefined "be quiet" switch.StringOperandImpl AnOperand
(neither a short option nor a long option prepended nor being a switch) being sString
.StringOptionImpl The Class StringOptionImpl.SysInfoFlagImpl A predefined system information switch.VerboseFlagImpl A predefined verbose switch.XorConditionImpl AnXorConditionImpl
represents a list ofSyntaxable
instances of which only one is allowed to be parsed successfully when theSyntaxable
s'Syntaxable.parseArgs(String[])
methods are invoked. -
Enum Summary Enum Description ExitCode Some default exit codes defined for CLI applications.SyntaxNotation TheSyntaxNotation
is used by a theSyntaxable.toSyntax(SyntaxNotation)
method to determine which notation to be used for the generated syntax. -
Exception Summary 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.