org.refcodes.console.package-info Maven / Gradle / Ivy
Show all versions of refcodes-console Show documentation
// /////////////////////////////////////////////////////////////////////////////
// REFCODES.ORG
// =============================================================================
// This code is copyright (c) by Siegfried Steiner, Munich, Germany and licensed
// under the following (see "http://en.wikipedia.org/wiki/Multi-licensing")
// licenses:
// =============================================================================
// GNU General Public License, v3.0 ("http://www.gnu.org/licenses/gpl-3.0.html")
// together with the GPL linking exception applied; as being applied by the GNU
// Classpath ("http://www.gnu.org/software/classpath/license.html")
// =============================================================================
// Apache License, v2.0 ("http://www.apache.org/licenses/LICENSE-2.0")
// =============================================================================
// Please contact the copyright holding author(s) of the software artifacts in
// question for licensing issues not being covered by the above listed licenses,
// also regarding commercial licensing models or regarding the compatibility
// with other open source licenses.
// /////////////////////////////////////////////////////////////////////////////
/**
* 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
*
* Invalid arguments would be:
*
* - foo-bar -f someFile -b
*
- foo-bar -a someFile -f
*
- foo-bar -a -d -f anyFile
*
- foo-bar -a -x -f otherFile
*
* This means that additional switches not supported are not valid. The parser
* detects such situations and you can print out a help message in such cases.
*
* Construct your parser:
*
* First build your syntax using {@link org.refcodes.console.Switch}es ,
* {@link org.refcodes.console.Option}s and
* {@link org.refcodes.console.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 {@link org.refcodes.console.Condition} to
* the {@link org.refcodes.console.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 a {@link java.lang.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
* {@link org.refcodes.console.impls.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
* {@link org.refcodes.console.ArgsMismatchException} is being thrown;
* actually one of the exceptions
* {@link org.refcodes.console.UnknownArgsException},
* {@link org.refcodes.console.AmbiguousArgsException},
* {@link org.refcodes.console.SuperfluousArgsException} or
* {@link org.refcodes.console.ParseArgsException} is being thrown,
* according to the cause of the rejection. So you can either catch the
* {@link org.refcodes.console.ArgsMismatchException} or, if you need more
* details on the cause, the other sub-exceptions.
*
*
{@link org.refcodes.console.Syntaxable}:
*
* {@link 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 {@link Syntaxable}'s subclasses
* such as {@link Operand}, {@link Option} or {@link 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 {@link Operand}s', the
* {@link Switch}es' or the {@link Option}s' values.
*
*
{@link org.refcodes.console.Operand}:
*
* An {@link Operand} represents a value parsed from command line arguments. An
* {@link Operand} has a state which changes with each invocation of the
* {@link #parseArgs(String[])} method.
*
* It is recommended to put your {@link Operand} instance(s) at the end of your
* top {@link Condition} to enforce it to be the last {@link Syntaxable}(s) when
* parsing the command line arguments - this makes sure that any {@link Option}s
* pick their option arguments so that the {@link Operand}(s) will correctly be
* left over for parsing command line argument(s); the {@link Operand} will not
* pick by mistake an {@link org.refcodes.console.Option} argument.
*
*
{@link org.refcodes.console.Option}:
*
* An {@link Option} represents a command line option with the according
* option's value. An {@link Option} can be seen as a key / value(s) pair
* defined in the command line arguments parsed via the
* {@link #parseArgs(String[])} method.
*
* An {@link Option} has a state which changes with each invocation of the
* {@link #parseArgs(String[])} method.
*
*
{@link org.refcodes.console.Switch}:
*
* A {@link Switch} is an {@link Option} with a {@link 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.
*
* {@link org.refcodes.console.Condition}:
*
* The {@link Condition} interface represents a node in the command line
* arguments syntax tree; simply extending the {@link Syntaxable} interface and
* adding the functionality of providing access to the added {@link Operand}s
* (leafs). In future extensions, a {@link Condition} might provide access to
* the child {@link Syntaxable} elements contained in a {@link Condition}
* instance. As of the current findings, access to the children of the
* {@link Condition} node is not required and would make the interface
* unnecessarily complicated.
*
*
* @see org.refcodes.console.impls.StringOptionImpl
* @see org.refcodes.console.impls.SwitchImpl
* @see org.refcodes.console.impls.StringOperandImpl
* @see org.refcodes.console.impls.XorConditionImpl
* @see org.refcodes.console.impls.AndConditionImpl
* @see org.refcodes.console.impls.OptionalConditionImpl
*/
package org.refcodes.console;