Package org.refcodes.console

Interface ArgsParser

All Superinterfaces:

ArgsParserMixin<ArgsParser>, org.refcodes.mixin.DescriptionAccessor.DescriptionBuilder<ArgsParser>, org.refcodes.mixin.DescriptionAccessor.DescriptionMutator, org.refcodes.mixin.NameAccessor.NameBuilder<ArgsParser>, org.refcodes.mixin.NameAccessor.NameMutator, org.refcodes.component.Resetable, RootConditionAccessor, org.refcodes.mixin.TitleAccessor.TitleBuilder<ArgsParser>, org.refcodes.mixin.TitleAccessor.TitleMutator

All Known Implementing Classes:

ArgsParserImpl

public interface ArgsParser
extends ArgsParserMixin<ArgsParser>, org.refcodes.mixin.TitleAccessor.TitleMutator, org.refcodes.mixin.TitleAccessor.TitleBuilder<ArgsParser>, org.refcodes.mixin.NameAccessor.NameMutator, org.refcodes.mixin.NameAccessor.NameBuilder<ArgsParser>, org.refcodes.mixin.DescriptionAccessor.DescriptionMutator, org.refcodes.mixin.DescriptionAccessor.DescriptionBuilder<ArgsParser>, org.refcodes.component.Resetable, RootConditionAccessor

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

Nested Class Summary

Nested classes/interfaces inherited from interface org.refcodes.console.RootConditionAccessor

RootConditionAccessor.RootConditionBuilder<B extends RootConditionAccessor.RootConditionBuilder<B>>, RootConditionAccessor.RootConditionMutator, RootConditionAccessor.RootConditionProperty

Method Summary

Modifier and Type	Method	Description
void	errorLn(String aLine)	Prints the given line to standard error with regards to to the console width as specified by the withConsoleWidth(int) method.
List<? extends Operand<?>>	evalArgs(String[] aArgs)	Evaluates the provided command line arguments and determines the according values by evaluating the root Condition.
default List<? extends Operand<?>>	evalArgs(List<String> aArgs)	Same as evalArgs(String[]) with the difference that the elements representing the arguments are passed as a list instead of an array.
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 withCopyrightNote(String) method; with regards to to the console width as specified by the withConsoleWidth(int) method.
void	printDescription()	Prints the description as set by the withDescription(String) method with regards to the console width as specified by the withConsoleWidth(int) method.
void	printHelp()	Prints the help to the standard output specified by the withStandardOut(PrintStream) method.
void	printLicenseNote()	Prints the license note as specified by the withLicenseNote(String) method; with regards to to the console width as specified by the withConsoleWidth(int) method.
void	printLn()	Prints an empty line / a line break.
void	printLn(String aLine)	Prints the given line to standard out with regards to to the console width as specified by the withConsoleWidth(int) method.
void	printOptions()	Prints the Options (short- and the long-options), the Switches and the Operand and their description with regards to the console width as specified by the withConsoleWidth(int) method.
void	printSeparatorLn()	Prints a separator line using the separator character as specified by the withSeparatorChar(char) method; with regards to to the console width as specified by the withConsoleWidth(int) method.
void	printUsage()	Prints the syntax as retrieved by the root Condition with regards to the SyntaxNotation set by the withSyntaxNotation(SyntaxNotation) method; making use of the usage label as passed by the withUsageLabel(String) method.
void	setBannerFont(org.refcodes.textual.Font aBannerFont)	Sets the banner font.
void	setBannerFontPalette(char[] aColorPalette)	Sets the banner font palette.
void	setConsoleWidth(int aConsoleWidth)	Set the console with.
void	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).
void	setErrorOut(PrintStream aErrorOut)	Set the error out PrintStream and make other adjustments with the result (with regards to the Builder-Pattern).
void	setLicenseNote(String aLicenseNote)	Set the license note used by the printHelp() method when writing out the licensing conditions.
void	setLineBreak(String aLineBreak)	Set the console's line break.
void	setMaxConsoleWidth(int aMaxConsoleWidth)	Set the maximum console width to use in case the console width is greater than the maximum you want.
void	setSeparatorChar(char aSeparatorChar)	Set the character to be used when printing a separator line with the printSeparatorLn() method.
void	setStandardOut(PrintStream aStandardOut)	Set the standard out PrintStream and make other adjustments with the result (with regards to the Builder-Pattern).
void	setSyntaxNotation(SyntaxNotation aSyntaxNotation)	Set the SyntaxNotation.
void	setUsageLabel(String aUsageLabel)	Set the usage label used by the printHelp() method when writing out the syntax.
default ArgsParser	withBannerFont(org.refcodes.textual.Font aBannerFont)	With banner font.
default ArgsParser	withBannerFontPalette(char[] aColorPalette)	With banner font palette.
default ArgsParser	withConsoleWidth(int aConsoleWidth)	Set the console with.
default ArgsParser	withCopyrightNote(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).
default ArgsParser	withDescription(String aDescription)	With description.
default ArgsParser	withErrorOut(PrintStream aErrorOut)	Set the error out PrintStream and make other adjustments with the result (with regards to the Builder-Pattern).
default ArgsParser	withEvalArgs(String[] aArgs)	Same as evalArgs(String[]) with the difference that this class's instance being invoked is returned as of the builder pattern.
default ArgsParser	withEvalArgs(List<String> aArgs)	Same as evalArgs(List) with the difference that this class's instance being invoked is returned as of the builder pattern.
default ArgsParser	withLicenseNote(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).
default ArgsParser	withLineBreak(String aLineBreak)	Set the console's line break.
default ArgsParser	withMaxConsoleWidth(int aMaxConsoleWidth)	Set the maximum console width to use in case the console width is greater than the maximum you want.
default ArgsParser	withName(String aName)	With name.
default ArgsParser	withParseArgs(String[] aArgs)	Calls evalArgs(String[]) and returns this invoked instance as of the builder pattern.
default ArgsParser	withSeparatorChar(char aSeparatorChar)	Set the character to be used when printing a separator line with the printSeparatorLn() method.
default ArgsParser	withStandardOut(PrintStream aStandardOut)	Set the standard out PrintStream and make other adjustments with the result (with regards to the Builder-Pattern).
default ArgsParser	withSyntaxNotation(SyntaxNotation aSyntaxNotation)	Set the SyntaxNotation and make other adjustments with the result (with regards to the Builder-Pattern).
default ArgsParser	withTitle(String aTitle)	With title.
default ArgsParser	withUsageLabel(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.console.ArgsParserMixin

withParseArgs

Methods inherited from interface org.refcodes.mixin.DescriptionAccessor.DescriptionMutator

setDescription

Methods inherited from interface org.refcodes.mixin.NameAccessor.NameMutator

setName

Methods inherited from interface org.refcodes.component.Resetable

reset

Methods inherited from interface org.refcodes.mixin.TitleAccessor.TitleMutator

setTitle

Method Detail

withParseArgs

default ArgsParser withParseArgs(String[] aArgs)
                          throws UnknownArgsException,
                                 AmbiguousArgsException,
                                 SuperfluousArgsException,
                                 ParseArgsException

Calls evalArgs(String[]) and returns this invoked instance as of the builder pattern. Evaluates the provided command line arguments.

Specified by:

withParseArgs in interface ArgsParserMixin<ArgsParser>

Parameters:

aArgs - The command line arguments to be evaluated.

Returns:

This instance as of the builder pattern to chain further method calls.

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

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

evalArgs

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

Same as evalArgs(String[]) with the difference that the elements representing the arguments are passed as a list instead of an array.

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

withEvalArgs

default ArgsParser withEvalArgs(String[] aArgs)
                         throws UnknownArgsException,
                                AmbiguousArgsException,
                                SuperfluousArgsException,
                                ParseArgsException

Same as evalArgs(String[]) with the difference that this class's instance being invoked is returned as of the builder pattern.

Parameters:

aArgs - The command line arguments to be evaluated.

Returns:

This invoked instance as of the builder pattern to chain method calls.

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

withEvalArgs

default ArgsParser withEvalArgs(List<String> aArgs)
                         throws UnknownArgsException,
                                AmbiguousArgsException,
                                SuperfluousArgsException,
                                ParseArgsException

Same as evalArgs(List) with the difference that this class's instance being invoked is returned as of the builder pattern.

Parameters:

aArgs - The command line arguments to be evaluated.

Returns:

This invoked instance as of the builder pattern to chain method calls.

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. Retrieves the rootCondition from the rootCondition property.

Specified by:

getRootCondition in interface RootConditionAccessor

Returns:

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

setBannerFont

void setBannerFont(org.refcodes.textual.Font aBannerFont)

Sets the banner font.

Parameters:

aBannerFont - the new banner font

setBannerFontPalette

void setBannerFontPalette(char[] aColorPalette)

Sets the banner font palette.

Parameters:

aColorPalette - the new banner font palette

setLineBreak

void setLineBreak(String aLineBreak)

Set the console's line break. A setting of null makes the instance use the SystemUtility.getLineBreak() value.

Parameters:

aLineBreak - the new line break

setConsoleWidth

void setConsoleWidth(int aConsoleWidth)

Set the console with. A setting of "-1" makes the instance use the SystemUtility.getTerminalWidth() value, i.e. the console width is set automatically to be the width of your terminal.

Parameters:

aConsoleWidth - The width to set or -1 to let the parser automatically determine the console width.

setMaxConsoleWidth

void setMaxConsoleWidth(int aMaxConsoleWidth)

Set the maximum console width to use in case the console width is greater than the maximum you want. This is most useful when the console width is determined automatically to be the width of your terminal.

Parameters:

aMaxConsoleWidth - the new max console width

setStandardOut

void 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.

setErrorOut

void setErrorOut(PrintStream aErrorOut)

Set the error out PrintStream and make other adjustments with the result (with regards to the Builder-Pattern).

Parameters:

aErrorOut - The error out PrintStream to set.

setSyntaxNotation

void setSyntaxNotation(SyntaxNotation aSyntaxNotation)

Set the SyntaxNotation.

Parameters:

aSyntaxNotation - The SyntaxNotation to set.

setLicenseNote

void setLicenseNote(String aLicenseNote)

Set the license note used by the printHelp() method when writing out the licensing conditions.

Parameters:

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

setUsageLabel

void setUsageLabel(String aUsageLabel)

Set the usage label used by the printHelp() method when writing out the syntax.

Parameters:

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

setCopyrightNote

void 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

void 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..

withBannerFont

default ArgsParser withBannerFont(org.refcodes.textual.Font aBannerFont)

With banner font.

Parameters:

aBannerFont - the banner font

Returns:

the args parser

withBannerFontPalette

default ArgsParser withBannerFontPalette(char[] aColorPalette)

With banner font palette.

Parameters:

aColorPalette - the color palette

Returns:

the args parser

withLineBreak

default ArgsParser withLineBreak(String aLineBreak)

Set the console's line break. A setting of null makes the instance use the SystemUtility.getLineBreak() value.

Parameters:

aLineBreak - the line break

Returns:

This ArgsParser instance with regard to the builder pattern.

withConsoleWidth

default ArgsParser withConsoleWidth(int aConsoleWidth)

Set the console with. A setting of "-1" makes the instance use the SystemUtility.getTerminalWidth() value.

Parameters:

aConsoleWidth - The width to set.

Returns:

This ArgsParser instance with regard to the builder pattern.

withMaxConsoleWidth

default ArgsParser withMaxConsoleWidth(int aMaxConsoleWidth)

Set the maximum console width to use in case the console width is greater than the maximum you want. This is most useful when the console width is determined automatically to be the width of your terminal.

Parameters:

aMaxConsoleWidth - the max console width

Returns:

This ArgsParser instance with regard to the builder pattern.

withStandardOut

default ArgsParser withStandardOut(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.

Returns:

This ArgsParser instance with regard to the builder pattern.

withErrorOut

default ArgsParser withErrorOut(PrintStream aErrorOut)

Set the error out PrintStream and make other adjustments with the result (with regards to the Builder-Pattern).

Parameters:

aErrorOut - The error out PrintStream to set.

Returns:

This ArgsParser instance with regard to the builder pattern.

withSyntaxNotation

default ArgsParser withSyntaxNotation(SyntaxNotation aSyntaxNotation)

Set the SyntaxNotation and make other adjustments with the result (with regards to the Builder-Pattern).

Parameters:

aSyntaxNotation - The SyntaxNotation to set.

Returns:

This ArgsParser instance with regard to the builder pattern.

withLicenseNote

default ArgsParser withLicenseNote(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.

Returns:

This ArgsParser instance with regard to the builder pattern.

withUsageLabel

default ArgsParser withUsageLabel(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.

Returns:

This ArgsParser instance with regard to the builder pattern.

withCopyrightNote

default ArgsParser withCopyrightNote(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.

Returns:

This ArgsParser instance with regard to the builder pattern.

withSeparatorChar

default ArgsParser withSeparatorChar(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..

Returns:

This ArgsParser instance with regard to the builder pattern.

withTitle

default ArgsParser withTitle(String aTitle)

With title.

Specified by:

withTitle in interface org.refcodes.mixin.TitleAccessor.TitleBuilder<ArgsParser>

Parameters:

aTitle - the title

Returns:

the args parser

withName

default ArgsParser withName(String aName)

With name.

Specified by:

withName in interface org.refcodes.mixin.NameAccessor.NameBuilder<ArgsParser>

Parameters:

aName - the name

Returns:

the args parser

withDescription

default ArgsParser withDescription(String aDescription)

With description.

Specified by:

withDescription in interface org.refcodes.mixin.DescriptionAccessor.DescriptionBuilder<ArgsParser>

Parameters:

aDescription - the description

Returns:

the args parser

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 withLicenseNote(String) method; with regards to to the console width as specified by the withConsoleWidth(int) method.

printUsage

void printUsage()

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

printDescription

void printDescription()

Prints the description as set by the withDescription(String) method with regards to the console width as specified by the withConsoleWidth(int) method.

printOptions

void printOptions()

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

printCopyrightNote

void printCopyrightNote()

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

printSeparatorLn

void printSeparatorLn()

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

printLn

void printLn(String aLine)

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

Parameters:

aLine - The line to be printed.

errorLn

void errorLn(String aLine)

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

Parameters:

aLine - The line to be printed.

printLn

void printLn()

Prints an empty line / a line break.

printHelp

void printHelp()

Prints the help to the standard output specified by the withStandardOut(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()