public interface ArgsParser extends 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
ArgsParser
provides means for parsing command line arguments and
constructing a command line utility's help output.Modifier and Type | Method and 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. |
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. |
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
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
Option s (short- and the long-options), the
Switch es and the Operator 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) |
void |
setBannerFontPalette(char[] aColorPalette) |
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) |
default ArgsParser |
withBannerFontPalette(char[] aColorPalette) |
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) |
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 |
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) |
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) |
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). |
List<? extends Operand<?>> evalArgs(String[] aArgs) throws UnknownArgsException, AmbiguousArgsException, SuperfluousArgsException, ParseArgsException
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.aArgs
- The command line arguments to be evaluated.Operand
interfaces or its sub-types.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 typedefault List<? extends Operand<?>> evalArgs(List<String> aArgs) throws UnknownArgsException, AmbiguousArgsException, SuperfluousArgsException, ParseArgsException
evalArgs(String[])
with the difference that the elements
representing the arguments are passed as a list instead of an array.Condition getRootCondition()
Syntaxable
hierarchy to be traversed when determining the syntax for command line
arguments or when evaluating the command line arguments.Condition
in which's syntax this parser is
based.void setBannerFont(org.refcodes.textual.Font aBannerFont)
void setBannerFontPalette(char[] aColorPalette)
void setLineBreak(String aLineBreak)
SystemUtility.getLineBreak()()
value.aConsoleWidth
- The width to set.void setConsoleWidth(int aConsoleWidth)
SystemUtility.getConsoleWidth()
value, i.e. the console width is
set automatically to be the width of your terminal.aConsoleWidth
- The width to set or -1 to let the parser
automatically determine the console width.void setMaxConsoleWidth(int aMaxConsoleWidth)
aConsoleMaxWidth
- The maximum width to use.void setStandardOut(PrintStream aStandardOut)
PrintStream
and make other adjustments with
the result (with regards to the builder pattern).aStandardOut
- The standard out PrintStream
to set.void setErrorOut(PrintStream aErrorOut)
PrintStream
and make other adjustments with the
result (with regards to the builder pattern).aErrorOut
- The error out PrintStream
to set.void setSyntaxNotation(SyntaxNotation aSyntaxNotation)
SyntaxNotation
.aSyntaxNotation
- The SyntaxNotation
to set.void setLicenseNote(String aLicenseNote)
printHelp()
method when writing
out the licensing conditions.aLicenseNote
- The license note printed out by the
printHelp()
method.void setUsageLabel(String aUsageLabel)
printHelp()
method when writing
out the syntax.aUsageLabel
- The usage label printed out by the
printHelp()
method.void setCopyrightNote(String aCopyrightNote)
printHelp()
method when
writing out the copyright claim and make other adjustments with the
result (with regards to the builder pattern).aCopyrightNote
- The license note printed out by the
printHelp()
method.void setSeparatorChar(char aSeparatorChar)
printSeparatorLn()
method.aSeparatorChar
- The character used by the
printSeparatorLn()
method when printing out the line of
characters..default ArgsParser withBannerFont(org.refcodes.textual.Font aBannerFont)
default ArgsParser withBannerFontPalette(char[] aColorPalette)
default ArgsParser withLineBreak(String aLineBreak)
SystemUtility.getLineBreak()()
value.aConsoleWidth
- The width to set.ArgsParser
instance with regard to the builder
pattern.default ArgsParser withConsoleWidth(int aConsoleWidth)
SystemUtility.getConsoleWidth()
value.aConsoleWidth
- The width to set.ArgsParser
instance with regard to the builder
pattern.default ArgsParser withMaxConsoleWidth(int aMaxConsoleWidth)
aConsoleMaxWidth
- The maximum width to use.ArgsParser
instance with regard to the builder
pattern.default ArgsParser withStandardOut(PrintStream aStandardOut)
PrintStream
and make other adjustments with
the result (with regards to the builder pattern).aStandardOut
- The standard out PrintStream
to set.ArgsParser
instance with regard to the builder
pattern.default ArgsParser withErrorOut(PrintStream aErrorOut)
PrintStream
and make other adjustments with the
result (with regards to the builder pattern).aErrorOut
- The error out PrintStream
to set.ArgsParser
instance with regard to the builder
pattern.default ArgsParser withSyntaxNotation(SyntaxNotation aSyntaxNotation)
SyntaxNotation
and make other adjustments with the result
(with regards to the builder pattern).aSyntaxNotation
- The SyntaxNotation
to set.ArgsParser
instance with regard to the builder
pattern.default ArgsParser withLicenseNote(String aLicenseNote)
printHelp()
method when writing
out the licensing conditions and make other adjustments with the result
(with regards to the builder pattern).aLicenseNote
- The license note printed out by the
printHelp()
method.ArgsParser
instance with regard to the builder
pattern.default ArgsParser withUsageLabel(String aUsageLabel)
printHelp()
method when writing
out the syntax and make other adjustments with the result (with regards
to the builder pattern).aUsageLabel
- The usage label printed out by the
printHelp()
method.ArgsParser
instance with regard to the builder
pattern.default ArgsParser withCopyrightNote(String aCopyrightNote)
printHelp()
method when
writing out the copyright claim and make other adjustments with the
result (with regards to the builder pattern).aCopyrightNote
- The license note printed out by the
printHelp()
method.ArgsParser
instance with regard to the builder
pattern.default ArgsParser withSeparatorChar(char aSeparatorChar)
printSeparatorLn()
method.aSeparatorChar
- The character used by the
printSeparatorLn()
method when printing out the line of
characters..ArgsParser
instance with regard to the builder
pattern.default ArgsParser withTitle(String aTitle)
withTitle
in interface org.refcodes.mixin.TitleAccessor.TitleBuilder<ArgsParser>
default ArgsParser withName(String aName)
withName
in interface org.refcodes.mixin.NameAccessor.NameBuilder<ArgsParser>
default ArgsParser withDescription(String aDescription)
withDescription
in interface org.refcodes.mixin.DescriptionAccessor.DescriptionBuilder<ArgsParser>
void printBanner()
void printLicenseNote()
withLicenseNote(String)
method; with regards to to the console
width as specified by the withConsoleWidth(int)
method.void printUsage()
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 printDescription()
withDescription(String)
method with regards to the console width as specified by the
withConsoleWidth(int)
method.void printOptions()
Option
s (short- and the long-options), the
Switch
es and the Operator
and their description with
regards to the console width as specified by the
withConsoleWidth(int)
method.void printCopyrightNote()
withCopyrightNote(String)
method; with regards to to the console
width as specified by the withConsoleWidth(int)
method.void printSeparatorLn()
withSeparatorChar(char)
method; with regards to to the console
width as specified by the withConsoleWidth(int)
method.void printLn(String aLine)
withConsoleWidth(int)
method.aLine
- The line to be printed.void errorLn(String aLine)
withConsoleWidth(int)
method.aLine
- The line to be printed.void printLn()
void printHelp()
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()
Copyright © 2016. All rights reserved.