org.refcodes.console

Interface ArgsParser

All Superinterfaces:

org.refcodes.mixin.mixins.DescriptionAccessor.DescriptionBuilder<ArgsParser>, org.refcodes.mixin.mixins.NameAccessor.NameBuilder<ArgsParser>

All Known Implementing Classes:

ArgsParserImpl

public interface ArgsParser
extends org.refcodes.mixin.mixins.NameAccessor.NameBuilder<ArgsParser>, org.refcodes.mixin.mixins.DescriptionAccessor.DescriptionBuilder<ArgsParser>

The ArgsParser provides means for parsing command line arguments and constructing a command line utility's help output.

Method Summary

Modifier and Type	Method and Description
List<? extends Operand<?>>	evalArgs(String[] aArgs) Evaluates the provided command line arguments and determines the according values by evaluating the root Condition.
Condition	getRootCondition() The root condition is the starting point node of a Syntaxable hierarchy to be traversed when determining the syntax for command line arguments or when evaluating the command line arguments.
void	printBanner() Prints the banner; the banner most probably is an ASCII art text block which's look depends strongly on the taste of the author implementing this interface.
void	printCopyrightNote() Prints the copyright note as specified by the setCopyrightNote(String) method; with regards to to the console width as specified by the setConsoleWidth(int) method.
void	printDescription() Prints the description as set by the DescriptionAccessor.DescriptionBuilder.setDescription(String) method with regards to the console width as specified by the setConsoleWidth(int) method.
void	printHelp() Prints the help to the standard output specified by the setStandardOut(PrintStream) method.
void	printLicenseNote() Prints the license note as specified by the setLicenseNote(String) method; with regards to to the console width as specified by the setConsoleWidth(int) method.
void	printLn() Prints an empty line / a line break.
void	printLn(String aLine) Prints the given line with regards to to the console width as specified by the setConsoleWidth(int) method.
void	printOptions() Prints the Options (short- and the long-options), the Switches and the Operator and their description with regards to the console width as specified by the setConsoleWidth(int) method.
void	printSeparatorLn() Prints a separator line using the separator character as specified by the setSeparatorChar(char) method; with regards to to the console width as specified by the setConsoleWidth(int) method.
void	printUsage() Prints the syntax as retrieved by the root Condition# with regards to the SyntaxNotation set by the setSyntaxNotation(SyntaxNotation) method; making use of the usage label as passed by the setUsageLabel(String) method.
ArgsParser	setConsoleWidth(int aConsoleWidth) Set the console with and make other adjustments with the result (with regards to the builder pattern).
ArgsParser	setCopyrightNote(String aCopyrightNote) Set the copyright note used by the printHelp() method when writing out the copyright claim and make other adjustments with the result (with regards to the builder pattern).
ArgsParser	setLicenseNote(String aLicenseNote) Set the license note used by the printHelp() method when writing out the licensing conditions and make other adjustments with the result (with regards to the builder pattern).
ArgsParser	setLineBreak(String aLineBreak) Set the console's line break and make other adjustments with the result (with regards to the builder pattern).
ArgsParser	setSeparatorChar(char aSeparatorChar) Set the character to be used when printing a separator line with the printSeparatorLn() method.
ArgsParser	setStandardOut(PrintStream aStandardOut) Set the standard out PrintStream and make other adjustments with the result (with regards to the builder pattern).
ArgsParser	setSyntaxNotation(SyntaxNotation aSyntaxNotation) Set the SyntaxNotation and make other adjustments with the result (with regards to the builder pattern).
ArgsParser	setUsageLabel(String aUsageLabel) Set the usage label used by the printHelp() method when writing out the syntax and make other adjustments with the result (with regards to the builder pattern).

Methods inherited from interface org.refcodes.mixin.mixins.NameAccessor.NameBuilder

setName

Methods inherited from interface org.refcodes.mixin.mixins.DescriptionAccessor.DescriptionBuilder

setDescription

Method Detail

evalArgs

List<? extends Operand<?>> evalArgs(String[] aArgs)
                             throws UnknownArgsException,
                                    AmbiguousArgsException,
                                    SuperfluousArgsException,
                                    ParseArgsException

Evaluates the provided command line arguments and determines the according values by evaluating the root Condition. In case of parsing failure, an according exception is thrown. ATTENTION: This method tests(!) for superfluous command line arguments being passed; e.g. command line arguments not being evaluated by any of the Syntaxable instance being traversed starting at the root Condition will be reported. Business logic therefore should invoke this root node's evalArgs(String[]) method instead of a Condition's Syntaxable.parseArgs(String[]) method; as ignoring superfluous command line arguments will cause unexpected behavior from the point of view of the invoker.

Parameters:

aArgs - The command line arguments to be evaluated.

Returns:

The list of evaluated command line arguments being instances of the Operand interfaces or its sub-types.

Throws:

UnknownArgsException - Thrown in case not one command line argument matched regarding the provided args vs. the expected args.

AmbiguousArgsException - Thrown in case at least one command line argument is ambiguous regarding expected args vs. provided args.

SuperfluousArgsException - Thrown in case there were arguments found not being used (superfluous arguments).

ParseArgsException - Thrown in case the provided command line arguments do not respect the required syntax or cannot be converted to the required type

getRootCondition

Condition getRootCondition()

The root condition is the starting point node of a Syntaxable hierarchy to be traversed when determining the syntax for command line arguments or when evaluating the command line arguments.

Returns:

The root Condition in which's syntax this parser is based.

setLineBreak

ArgsParser setLineBreak(String aLineBreak)

Set the console's line break and make other adjustments with the result (with regards to the builder pattern). A setting of null makes the instance use the SystemUtility.getLineBreak()() value.

Parameters:

aConsoleWidth - The width to set.

setConsoleWidth

ArgsParser setConsoleWidth(int aConsoleWidth)

Set the console with and make other adjustments with the result (with regards to the builder pattern). A setting of "-1" makes the instance use the SystemUtility.getConsoleWidth() value.

Parameters:

aConsoleWidth - The width to set.

setStandardOut

ArgsParser setStandardOut(PrintStream aStandardOut)

Set the standard out PrintStream and make other adjustments with the result (with regards to the builder pattern).

Parameters:

aStandardOut - The standard out PrintStream to set.

setSyntaxNotation

ArgsParser setSyntaxNotation(SyntaxNotation aSyntaxNotation)

Set the SyntaxNotation and make other adjustments with the result (with regards to the builder pattern).

Parameters:

aSyntaxNotation - The SyntaxNotation to set.

setLicenseNote

ArgsParser setLicenseNote(String aLicenseNote)

Set the license note used by the printHelp() method when writing out the licensing conditions and make other adjustments with the result (with regards to the builder pattern).

Parameters:

aLicenseNote - The license note printed out by the printHelp() method.

setUsageLabel

ArgsParser setUsageLabel(String aUsageLabel)

Set the usage label used by the printHelp() method when writing out the syntax and make other adjustments with the result (with regards to the builder pattern).

Parameters:

aUsageLabel - The usage label printed out by the printHelp() method.

setCopyrightNote

ArgsParser setCopyrightNote(String aCopyrightNote)

Set the copyright note used by the printHelp() method when writing out the copyright claim and make other adjustments with the result (with regards to the builder pattern).

Parameters:

aCopyrightNote - The license note printed out by the printHelp() method.

setSeparatorChar

ArgsParser setSeparatorChar(char aSeparatorChar)

Set the character to be used when printing a separator line with the printSeparatorLn() method.

Parameters:

aSeparatorChar - The character used by the printSeparatorLn() method when printing out the line of characters..

printBanner

void printBanner()

Prints the banner; the banner most probably is an ASCII art text block which's look depends strongly on the taste of the author implementing this interface.

printLicenseNote

void printLicenseNote()

Prints the license note as specified by the setLicenseNote(String) method; with regards to to the console width as specified by the setConsoleWidth(int) method.

printUsage

void printUsage()

Prints the syntax as retrieved by the root Condition# with regards to the SyntaxNotation set by the setSyntaxNotation(SyntaxNotation) method; making use of the usage label as passed by the setUsageLabel(String) method.

printDescription

void printDescription()

Prints the description as set by the DescriptionAccessor.DescriptionBuilder.setDescription(String) method with regards to the console width as specified by the setConsoleWidth(int) method.

printOptions

void printOptions()

Prints the Options (short- and the long-options), the Switches and the Operator and their description with regards to the console width as specified by the setConsoleWidth(int) method.

printCopyrightNote

void printCopyrightNote()

Prints the copyright note as specified by the setCopyrightNote(String) method; with regards to to the console width as specified by the setConsoleWidth(int) method.

printSeparatorLn

void printSeparatorLn()

Prints a separator line using the separator character as specified by the setSeparatorChar(char) method; with regards to to the console width as specified by the setConsoleWidth(int) method.

printLn

void printLn(String aLine)

Prints the given line with regards to to the console width as specified by the setConsoleWidth(int) method.

printLn

void printLn()

Prints an empty line / a line break.

printHelp

void printHelp()

Prints the help to the standard output specified by the setStandardOut(PrintStream) method. This method can make use of the more atomic methods printBanner(), printUsage(), printDescription(), printOptions() or printSeparatorLn() to print a help text which's look depends strongly on the taste of the author implementing this interface. In case you dislike the implementing author's taste, feel free to overwrite this method and compose your own help text from the building blocks such as printBanner(), printUsage(), printDescription(), printOptions() or printSeparatorLn()