- All Superinterfaces:
org.refcodes.mixin.DescriptionAccessor
,org.refcodes.exception.ExceptionAccessor<ArgsSyntaxException>
,MatchCountAccessor
,org.refcodes.mixin.Resetable
,org.refcodes.mixin.Schemable
,Synopsisable
- All Known Subinterfaces:
Condition
,Operand<T>
,Option<T>
,PropertyOption<T>
- All Known Implementing Classes:
AbstractCondition
,AbstractOperand
,AbstractOption
,AbstractPropertyOption
,AllCondition
,AndCondition
,AnyCondition
,ArrayOperand
,ArrayOption
,BooleanOption
,BooleanProperty
,CasesCondition
,CharOption
,CharProperty
,CleanFlag
,ConfigOption
,ConfigProperty
,DaemonFlag
,DebugFlag
,DoubleOption
,DoubleProperty
,EnumOption
,EnumProperty
,FileOption
,FileProperty
,Flag
,FloatOption
,FloatProperty
,ForceFlag
,HelpFlag
,InitFlag
,IntOption
,IntProperty
,LongOption
,LongProperty
,NoneOperand
,Operation
,OrCondition
,QuietFlag
,StringOperand
,StringOption
,StringProperty
,SysInfoFlag
,VerboseFlag
,XorCondition
public interface Term
extends org.refcodes.mixin.Resetable, Synopsisable, org.refcodes.mixin.DescriptionAccessor, org.refcodes.mixin.Schemable, org.refcodes.exception.ExceptionAccessor<ArgsSyntaxException>, MatchCountAccessor
A
Term
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 Term
'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.-
Nested Class Summary
Nested classes/interfaces inherited from interface org.refcodes.mixin.DescriptionAccessor
org.refcodes.mixin.DescriptionAccessor.DescriptionBuilder<B extends org.refcodes.mixin.DescriptionAccessor.DescriptionBuilder<B>>, org.refcodes.mixin.DescriptionAccessor.DescriptionMutator, org.refcodes.mixin.DescriptionAccessor.DescriptionProperty
Nested classes/interfaces inherited from interface org.refcodes.exception.ExceptionAccessor
org.refcodes.exception.ExceptionAccessor.ExceptionBuilder<EXC extends Throwable,
B extends org.refcodes.exception.ExceptionAccessor.ExceptionBuilder<EXC, B>>, org.refcodes.exception.ExceptionAccessor.ExceptionMutator<EXC extends Throwable>, org.refcodes.exception.ExceptionAccessor.ExceptionProperty<EXC extends Throwable> Nested classes/interfaces inherited from interface org.refcodes.cli.MatchCountAccessor
MatchCountAccessor.MatchCountBuilder<B extends MatchCountAccessor.MatchCountBuilder<B>>, MatchCountAccessor.MatchCountMutator, MatchCountAccessor.MatchCountProperty
-
Method Summary
Modifier and TypeMethodDescriptionRetrieves theArgsSyntaxException
exception in case invokingparseArgs(String[], CliContext)
failed.int
Determines the number of args being matched by theparseArgs(String[], CliContext)
(and similar) method(s) of the according syntax.Operand<?>[]
parseArgs
(String[] aArgs, String[] aOptions, CliContext aCliContext) Parses the provided command line arguments and determines the according values by evaluating thisTerm
instance or, in case of being a node in the syntax tree (such as aCondition
, traversing the childTerm
instances'parseArgs(String[], String[], CliContext)
methods.default Operand<?>[]
parseArgs
(String[] aArgs, CliContext aCliCtx) Parses the provided command line arguments and determines the according values by evaluating thisTerm
instance or, in case of being a node in the syntax tree (such as aCondition
, traversing the childTerm
instances'parseArgs(String[], String[], CliContext)
methods.toSchema()
default String
toSynopsis
(CliContext aCliCtx) Returns the human readable (verbose) syntax of the implementing class ATTENTION: As of different parenthesis settings for some notations regarding the rootTerm
and the childTerm
s, the methodtoSyntax(CliContext)
is called from inside aTerm
hierarchy.default String
toSyntax()
This method is to be called from inside theTerm
hierarchy; use the methodSynopsisable.toSynopsis(SyntaxNotation)
in case you invoke syntax retrieval from the rootTerm
.default String
This method is to be called from inside theTerm
hierarchy; use the methodSynopsisable.toSynopsis(SyntaxNotation)
in case you invoke syntax retrieval from the rootTerm
.toSyntax
(CliContext aCliCtx) This method is to be called from inside theTerm
hierarchy; use the methodSynopsisable.toSynopsis(SyntaxNotation)
in case you invoke syntax retrieval from the rootTerm
.default String
toSyntax
(SyntaxNotation aSyntaxNotation) This method is to be called from inside theTerm
hierarchy; use the methodSynopsisable.toSynopsis(SyntaxNotation)
in case you invoke syntax retrieval from the rootTerm
.default String
toSyntax
(SyntaxNotation aSyntaxNotation, String aOptEscCode, String aParamEscCode, String aResetEscCode) This method is to be called from inside theTerm
hierarchy; use the methodSynopsisable.toSynopsis(SyntaxNotation)
in case you invoke syntax retrieval from the rootTerm
.<V> V
Searches for a value being set for the given for given alias in the syntax tree parsing the command line arguments; if a node in the syntax tree has a value for the given alias, then this value is returned.Methods inherited from interface org.refcodes.mixin.DescriptionAccessor
getDescription
Methods inherited from interface org.refcodes.mixin.Resetable
reset
Methods inherited from interface org.refcodes.cli.Synopsisable
toSynopsis, toSynopsis, toSynopsis, toSynopsis
-
Method Details
-
parseArgs
Parses the provided command line arguments and determines the according values by evaluating thisTerm
instance or, in case of being a node in the syntax tree (such as aCondition
, traversing the childTerm
instances'parseArgs(String[], String[], CliContext)
methods. In case of successfully parsing thisTerm
and / or the childTerm
instances, the evaluated command line arguments are returned: Depending on theTerm
subclasses representing the evaluated command line arguments, instances ofFlag
classes,Option
classes orOperand
classes may be found in the result. In case of parsing failure, an according exception is thrown. ATTENTION: This method does not test for superfluous command line arguments being passed; e.g. command line arguments not being evaluated by any of theTerm
instance being traversed. This method is commonly used by a rootTerm
'sParseArgs.evalArgs(String[])
method, which delegates to theparseArgs(String[], String[], CliContext)
method and after which it determines whether there are superfluous arguments to be taken care of (by throwing an according exception). Business logic therefore should invoke the root node'sparseArgs(String[], String[], CliContext)
method as ignoring superfluous command line arguments will aCause unexpected behavior from the point of view of the invoker.- Parameters:
aArgs
- The command line arguments to be parsed.aCliCtx
- TheCliContext
to use when parsing the arguments.- Returns:
- The list of evaluated command line arguments being instances of
the
Operand
interfaces or its sub-types. - Throws:
ArgsSyntaxException
- thrown in case of a command line arguments mismatch regarding provided and expected args.
-
parseArgs
Operand<?>[] parseArgs(String[] aArgs, String[] aOptions, CliContext aCliContext) throws ArgsSyntaxException Parses the provided command line arguments and determines the according values by evaluating thisTerm
instance or, in case of being a node in the syntax tree (such as aCondition
, traversing the childTerm
instances'parseArgs(String[], String[], CliContext)
methods. In case of successfully parsing thisTerm
and / or the childTerm
instances, the evaluated command line arguments are returned: Depending on theTerm
subclasses representing the evaluated command line arguments, instances ofFlag
classes,Option
classes orOperand
classes may be found in the result. In case of parsing failure, an according exception is thrown. ATTENTION: This method does not test for superfluous command line arguments being passed; e.g. command line arguments not being evaluated by any of theTerm
instance being traversed. This method is commonly used by a rootTerm
'sParseArgs.evalArgs(String[])
method, which delegates to theparseArgs(String[], String[], CliContext)
method and after which it determines whether there are superfluous arguments to be taken care of (by throwing an according exception). Business logic therefore should invoke the root node'sparseArgs(String[], String[], CliContext)
method as ignoring superfluous command line arguments will aCause unexpected behavior from the point of view of the invoker.- Parameters:
aArgs
- The command line arguments to be parsed.aOptions
- The list of options (short and as well as long) which are reserved and cannot be used as value.aCliContext
- the cli context- Returns:
- The list of evaluated command line arguments being instances of
the
Operand
interfaces or its sub-types. - Throws:
ArgsSyntaxException
- thrown in case of a command line arguments mismatch regarding provided and expected args.
-
toSchema
CliSchema toSchema()- Specified by:
toSchema
in interfaceorg.refcodes.mixin.Schemable
-
toSynopsis
Returns the human readable (verbose) syntax of the implementing class ATTENTION: As of different parenthesis settings for some notations regarding the rootTerm
and the childTerm
s, the methodtoSyntax(CliContext)
is called from inside aTerm
hierarchy. In case the syntax is to be retrieved from the rootTerm
or an encapsulating and different type, then the applicable method to be called isSynopsisable.toSynopsis(SyntaxNotation)
, as for some notations it will for example not create the most outer braces.- Specified by:
toSynopsis
in interfaceSynopsisable
- Parameters:
aCliCtx
- TheCliContext
for which the syntax is being generated.- Returns:
- The human readable (verbose) command line arguments syntax.
-
toSyntax
This method is to be called from inside theTerm
hierarchy; use the methodSynopsisable.toSynopsis(SyntaxNotation)
in case you invoke syntax retrieval from the rootTerm
. Returns the human readable (verbose) syntax of thisTerm
instance including, in case of being a node in the syntax tree (such as aCondition
, the syntax of the childTerm
instances. ATTENTION: As of different parenthesis settings for some notations regarding the rootTerm
and the childTerm
s, the methodtoSyntax(CliContext)
is called from inside theTerm
hierarchy. In case the syntax is to be retrieved from the rootTerm
, then the applicable method to be called isSynopsisable.toSynopsis(SyntaxNotation)
, as for some notations it will for example not create the most outer braces. This method uses theSyntaxNotation.LOGICAL
be default!- Returns:
- The human readable (verbose) command line arguments syntax.
-
toSyntax
This method is to be called from inside theTerm
hierarchy; use the methodSynopsisable.toSynopsis(SyntaxNotation)
in case you invoke syntax retrieval from the rootTerm
. Returns the human readable (verbose) syntax of thisTerm
instance including, in case of being a node in the syntax tree (such as aCondition
, the syntax of the childTerm
instances. ATTENTION: As of different parenthesis settings for some notations regarding the rootTerm
and the childTerm
s, the methodtoSyntax(CliContext)
is called from inside theTerm
hierarchy. In case the syntax is to be retrieved from the rootTerm
, then the applicable method to be called isSynopsisable.toSynopsis(SyntaxNotation)
, as for some notations it will for example not create the most outer braces.- Parameters:
aCliCtx
- TheCliContext
for which the syntax is being generated.- Returns:
- The human readable (verbose) command line arguments syntax.
-
toSyntax
This method is to be called from inside theTerm
hierarchy; use the methodSynopsisable.toSynopsis(SyntaxNotation)
in case you invoke syntax retrieval from the rootTerm
. Returns the human readable (verbose) syntax of thisTerm
instance including, in case of being a node in the syntax tree (such as aCondition
, the syntax of the childTerm
instances. ATTENTION: As of different parenthesis settings for some notations regarding the rootTerm
and the childTerm
s, the methodtoSyntax(CliContext)
is called from inside theTerm
hierarchy. In case the syntax is to be retrieved from the rootTerm
, then the applicable method to be called isSynopsisable.toSynopsis(SyntaxNotation)
, as for some notations it will for example not create the most outer braces. This method uses theSyntaxNotation.LOGICAL
be default!- Parameters:
aOptEscCode
- The escape code to be used when processing an option, e.g. this can be an ANSI Escape-Code to highlight the option.aParamEscCode
- The escape code to be used when processing a keyword, e.g. this can be an ANSI Escape-Code to highlight the option and/or parameters.aResetEscCode
- The escape code to close (reset) any Escape-Code being set before.- Returns:
- The human readable (verbose) command line arguments syntax.
-
toSyntax
This method is to be called from inside theTerm
hierarchy; use the methodSynopsisable.toSynopsis(SyntaxNotation)
in case you invoke syntax retrieval from the rootTerm
. Returns the human readable (verbose) syntax of thisTerm
instance including, in case of being a node in the syntax tree (such as aCondition
, the syntax of the childTerm
instances. ATTENTION: As of different parenthesis settings for some notations regarding the rootTerm
and the childTerm
s, the methodtoSyntax(CliContext)
is called from inside theTerm
hierarchy. In case the syntax is to be retrieved from the rootTerm
, then the applicable method to be called isSynopsisable.toSynopsis(SyntaxNotation)
, as for some notations it will for example not create the most outer braces.- Parameters:
aSyntaxNotation
- The syntax notation used for generating the command line arguments syntax.- Returns:
- The human readable (verbose) command line arguments syntax.
-
toSyntax
default String toSyntax(SyntaxNotation aSyntaxNotation, String aOptEscCode, String aParamEscCode, String aResetEscCode) This method is to be called from inside theTerm
hierarchy; use the methodSynopsisable.toSynopsis(SyntaxNotation)
in case you invoke syntax retrieval from the rootTerm
. Returns the human readable (verbose) syntax of thisTerm
instance including, in case of being a node in the syntax tree (such as aCondition
, the syntax of the childTerm
instances. ATTENTION: As of different parenthesis settings for some notations regarding the rootTerm
and the childTerm
s, the methodtoSyntax(SyntaxNotation, String, String, String)
is called from inside theTerm
hierarchy. In case the syntax is to be retrieved from the rootTerm
, then the applicable method to be called isSynopsisable.toSynopsis(SyntaxNotation)
, as for some notations it will for example not create the most outer braces.- Parameters:
aSyntaxNotation
- The syntax notation used for generating the command line arguments syntax.aOptEscCode
- The escape code to be used when processing an option, e.g. this can be an ANSI Escape-Code to highlight the option.aParamEscCode
- The escape code to be used when processing a keyword, e.g. this can be an ANSI Escape-Code to highlight the option and/or parameters.aResetEscCode
- The escape code to close (reset) any Escape-Code being set before.- Returns:
- The human readable (verbose) command line arguments syntax.
-
toValue
Searches for a value being set for the given for given alias in the syntax tree parsing the command line arguments; if a node in the syntax tree has a value for the given alias, then this value is returned.- Type Parameters:
V
- The type of the value being expected.- Parameters:
aAlias
- The alias for which to seek for a value being set.- Returns:
- The according value or null if none has been set for the given alias.
-
getMatchCount
int getMatchCount()Determines the number of args being matched by theparseArgs(String[], CliContext)
(and similar) method(s) of the according syntax. This way we can determine which part of the syntax (tree) had most matches.- Specified by:
getMatchCount
in interfaceMatchCountAccessor
- Returns:
- The number of args matching the according syntax (tree).
-
getException
ArgsSyntaxException getException()Retrieves theArgsSyntaxException
exception in case invokingparseArgs(String[], CliContext)
failed. The exception (and the according suppressed ones alongside the causes) does not necessarily have been thrown by theparseArgs(String[], CliContext)
method depending on the semantics of theTerm
handing the exception (theAnyCondition
provides any exceptions it caught even though it did not throw them as of its semantics).- Specified by:
getException
in interfaceorg.refcodes.exception.ExceptionAccessor<ArgsSyntaxException>
- Returns:
- The
ArgsSyntaxException
exception occurring while parsing the arguments.
-