Interface Term

All Superinterfaces:
org.refcodes.mixin.DescriptionAccessor, org.refcodes.exception.ExceptionAccessor<ArgsSyntaxException>, MatchCountAccessor, org.refcodes.mixin.Resetable, org.refcodes.schema.Schemable, Synopsisable, org.refcodes.graphical.VisibleAccessor, org.refcodes.graphical.VisibleAccessor.VisibleBuilder<Term>, org.refcodes.graphical.VisibleAccessor.VisibleMutator, org.refcodes.graphical.VisibleAccessor.VisibleProperty
All Known Subinterfaces:
Condition, Directive<T>, Operand<T>, Option<T>, Property<T>
All Known Implementing Classes:
AbstractCondition, AbstractDirective, AbstractOperand, AbstractOption, AbstractProperty, AllCondition, AndCondition, AnyCondition, ArrayDirective, ArrayOperand, ArrayOption, BooleanDirective, BooleanOption, BooleanProperty, CasesCondition, CharDirective, CharOption, CharProperty, CleanFlag, ConfigOption, ConfigProperty, DaemonFlag, DebugFlag, DoubleDirective, DoubleOption, DoubleProperty, EnumDirective, EnumOption, EnumProperty, FileDirective, FileOption, FileProperty, Flag, FloatDirective, FloatOption, FloatProperty, ForceFlag, HelpFlag, InitFlag, IntDirective, IntOption, IntProperty, LongDirective, LongOption, LongProperty, NoneOperand, Operation, OrCondition, QuietFlag, StringDirective, StringOperand, StringOption, StringProperty, SysInfoFlag, VerboseFlag, XorCondition
public interface Term extends org.refcodes.mixin.Resetable, Synopsisable, org.refcodes.mixin.DescriptionAccessor, org.refcodes.schema.Schemable, org.refcodes.exception.ExceptionAccessor<ArgsSyntaxException>, MatchCountAccessor, org.refcodes.graphical.VisibleAccessor.VisibleProperty, org.refcodes.graphical.VisibleAccessor.VisibleBuilder<Term>
A Term represents a node within a command line argument syntax tree.

The syntax tree is used for two closely related purposes:

  • Parsing command line arguments and extracting evaluated values
  • Generating a human readable representation of the command line syntax

Concrete Term implementations such as Operand, Option, Flag or Condition define the structure and semantics of the command line interface. By composing these terms, complex syntaxes including optional branches and conditional argument groups can be expressed.

A Term may either be a leaf node that directly evaluates arguments or an inner node that delegates parsing and syntax generation to its child Term instances.

Parsing is performed by traversing the syntax tree and matching command line arguments against the defined terms. Successfully evaluated arguments are returned as Operand instances or subclasses thereof. Parsing errors are reported via ArgsSyntaxException.

A Term also supports:

  • Resetting internal state between parsing runs
  • Collecting match statistics for ambiguity resolution
  • Producing schema representations for documentation or tooling
  • Controlling visibility for help and usage output

The root Term typically exposes higher level entry points such as ArgsParser.evalArgs(String[]) which build upon the methods defined by this interface.

  • 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

    Nested classes/interfaces inherited from interface org.refcodes.graphical.VisibleAccessor

    org.refcodes.graphical.VisibleAccessor.VisibleBuilder<B extends org.refcodes.graphical.VisibleAccessor.VisibleBuilder<B>>, org.refcodes.graphical.VisibleAccessor.VisibleMutator, org.refcodes.graphical.VisibleAccessor.VisibleProperty

  • Method Summary

    Modifier and Type
    Method
    Description
    default Operand<?>[]
    argsParser(String[] aArgs)
    Parses the given command line arguments using this Term as the root of the syntax tree.
    ArgsSyntaxException
    getException()
    Retrieves the ArgsSyntaxException exception in case invoking parseArgs(String[], CliContext) failed.
    int
    getMatchCount()
    Determines the number of args being matched by the parseArgs(String[], CliContext) (and similar) method(s) of the according syntax.
    boolean
    isVisible()
    Operand<?>[]
    parseArgs(String[] aArgs, String[] aKeywords, CliContext aCliCtx)
    Parses the given command line arguments using the provided keyword set and CLI context.
    default Operand<?>[]
    parseArgs(String[] aArgs, CliContext aCliCtx)
    Parses the given command line arguments using the provided CLI context deriving its keyword.
    void
    setVisible(boolean isVisible)
    CliSchema
    toSchema()
    default String
    toSynopsis(CliContext aCliCtx)
    Creates the synopsis for the syntax hierarchy.
    default String
    toSyntax()
    Generates a human readable representation of this Term's syntax.
    default String
    toSyntax(String aArgumentEscapeCode, String aKeywordEscapeCode, String aResetEscapeCode)
    Creates a syntax including its arguments.
    String
    toSyntax(CliContext aCliCtx)
    Creates a syntax including its arguments.
    default String
    toSyntax(SyntaxNotation aSyntaxNotation)
    Creates a syntax including its arguments.
    default String
    toSyntax(SyntaxNotation aSyntaxNotation, String aArgumentEscapeCode, String aKeywordEscapeCode, String aResetEscapeCode)
    Creates a syntax including its arguments.
    <V> V
    toValue(String aAlias)
    Retrieves the value associated with the given alias after parsing.

    Methods inherited from interface org.refcodes.mixin.DescriptionAccessor

    getDescription

    Methods inherited from interface org.refcodes.mixin.Resetable

    reset

    Methods inherited from interface org.refcodes.schema.Schemable

    toSchema

    Methods inherited from interface org.refcodes.cli.Synopsisable

    toSynopsis, toSynopsis, toSynopsis, toSynopsis

    Methods inherited from interface org.refcodes.graphical.VisibleAccessor.VisibleBuilder

    withHide, withShow, withVisible

    Methods inherited from interface org.refcodes.graphical.VisibleAccessor.VisibleMutator

    hide, show

    Methods inherited from interface org.refcodes.graphical.VisibleAccessor.VisibleProperty

    letVisible

  • Method Details

    • argsParser

      default Operand<?>[] argsParser(String[] aArgs) throws ArgsSyntaxException
      Parses the given command line arguments using this Term as the root of the syntax tree.

      This is a convenience method that creates a default CliContext and delegates to parseArgs(String[], CliContext).

      The method evaluates this Term and, if applicable, recursively traverses its child terms. Successfully evaluated arguments are returned as Operand instances.

      This method does not detect superfluous arguments. Callers that require strict validation should use a root level method such as ArgsParser.evalArgs(String[]).

      Parameters:
      aArgs - The command line arguments to parse
      Returns:
      The evaluated operands
      Throws:
      ArgsSyntaxException - If the arguments do not match the syntax

    • parseArgs

      default Operand<?>[] parseArgs(String[] aArgs, CliContext aCliCtx) throws ArgsSyntaxException
      Parses the given command line arguments using the provided CLI context deriving its keyword.

      This is a convenience method that creates a default CliContext, derives its keywords and delegates to parseArgs(String[], String[], CliContext).

      The aKeywords parameter defines reserved tokens such as option names that must not be interpreted as operand values.

      This method does not validate whether all arguments have been consumed. Superfluous arguments must be handled by the caller.

      Parameters:
      aArgs - The command line arguments to parse
      aCliCtx - the cli ctx
      Returns:
      The evaluated operands
      Throws:
      ArgsSyntaxException - If the arguments do not match the syntax

    • parseArgs

      Operand<?>[] parseArgs(String[] aArgs, String[] aKeywords, CliContext aCliCtx) throws ArgsSyntaxException
      Parses the given command line arguments using the provided keyword set and CLI context.

      This method represents the core parsing operation. It evaluates this Term or, if this term is an inner node, delegates parsing to its child terms.

      The aKeywords parameter defines reserved tokens such as option names that must not be interpreted as operand values.

      This method does not validate whether all arguments have been consumed. Superfluous arguments must be handled by the caller.

      Parameters:
      aArgs - The command line arguments to parse
      aKeywords - Reserved option and keyword tokens
      aCliCtx - The CliContext controlling parsing and rendering
      Returns:
      The evaluated operands
      Throws:
      ArgsSyntaxException - If the arguments do not match the syntax

    • toSchema

      CliSchema toSchema()
      Specified by:
      toSchema in interface org.refcodes.schema.Schemable

    • toSynopsis

      default String toSynopsis(CliContext aCliCtx)
      Creates the synopsis for the syntax hierarchy.

      The difference between a synopsis and a syntax is the most outer parenthesis settings for some notations: The toSyntax(CliContext) method is called from inside a syntax tree whereas the Synopsisable.toSynopsis(CliContext) method is called from the hierarchy's root, as for some notations require the creation of the most outer braces.

      Specified by:
      toSynopsis in interface Synopsisable
      Parameters:
      aCliCtx - The CliContext for which the syntax is being generated.
      Returns:
      The human readable (verbose) command line arguments synopsis.

    • toSyntax

      default String toSyntax()
      Generates a human readable representation of this Term's syntax.

      This method is intended to be called from within the Term hierarchy. When generating syntax from the root term, use Synopsisable.toSynopsis(SyntaxNotation) instead.

      The returned syntax includes this term and, if applicable, the syntax of its child terms according to the active SyntaxNotation.

      Returns:
      The human readable command line syntax

    • toSyntax

      default String toSyntax(String aArgumentEscapeCode, String aKeywordEscapeCode, String aResetEscapeCode)
      Creates a syntax including its arguments.

      A specification differs from a syntax in that the specification provides the full definition not omitting any choices whereas the syntax only provides a syntactically correct variant. For example, having an option with a short option and a long option, the specification will show the short option and the long option whereas the syntax will only show either the short option or, if no short option is set, the long option.

      Note: This method uses the SyntaxNotation.LOGICAL be default!

      Parameters:
      aArgumentEscapeCode - The escape code to use when rendering (option's) arguments
      aKeywordEscapeCode - The escape code to be used when rendering keywords (options.)
      aResetEscapeCode - The escape code resetting any previously applied escape codes.
      Returns:
      The human readable command line syntax

    • toSyntax

      default String toSyntax(SyntaxNotation aSyntaxNotation)
      Creates a syntax including its arguments.

      A specification differs from a syntax in that the specification provides the full definition not omitting any choices whereas the syntax only provides a syntactically correct variant. For example, having an option with a short option and a long option, the specification will show the short option and the long option whereas the syntax will only show either the short option or, if no short option is set, the long option.

      Note: This method uses the default escape codes for syntax highlighting!

      Parameters:
      aSyntaxNotation - The syntax notation used for generating the command line arguments syntax.
      Returns:
      The human readable command line syntax

    • toSyntax

      default String toSyntax(SyntaxNotation aSyntaxNotation, String aArgumentEscapeCode, String aKeywordEscapeCode, String aResetEscapeCode)
      Creates a syntax including its arguments.

      A specification differs from a syntax in that the specification provides the full definition not omitting any choices whereas the syntax only provides a syntactically correct variant. For example, having an option with a short option and a long option, the specification will show the short option and the long option whereas the syntax will only show either the short option or, if no short option is set, the long option.

      Parameters:
      aSyntaxNotation - The syntax notation used for generating the command line arguments syntax.
      aArgumentEscapeCode - The escape code to use when rendering (option's) arguments
      aKeywordEscapeCode - The escape code to be used when rendering keywords (options.)
      aResetEscapeCode - The escape code resetting any previously applied escape codes.
      Returns:
      The human readable command line syntax

    • toSyntax

      String toSyntax(CliContext aCliCtx)
      Creates a syntax including its arguments.

      A specification differs from a syntax in that the specification provides the full definition not omitting any choices whereas the syntax only provides a syntactically correct variant. For example, having an option with a short option and a long option, the specification will show the short option and the long option whereas the syntax will only show either the short option or, if no short option is set, the long option.

      Parameters:
      aCliCtx - The CLI context controlling notation and formatting
      Returns:
      The human readable command line syntax

    • toValue

      <V> V toValue(String aAlias)
      Retrieves the value associated with the given alias after parsing.

      The syntax tree is searched for a Term that has produced a value for the specified alias.

      Type Parameters:
      V - The expected value type
      Parameters:
      aAlias - The alias to resolve
      Returns:
      The resolved value or null if not set

    • getMatchCount

      int getMatchCount()
      Determines the number of args being matched by the parseArgs(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 interface MatchCountAccessor
      Returns:
      The number of args matching the according syntax (tree).

    • getException

      ArgsSyntaxException getException()
      Retrieves the ArgsSyntaxException exception in case invoking parseArgs(String[], CliContext) failed. The exception (and the according suppressed ones alongside the causes) does not necessarily have been thrown by the parseArgs(String[], CliContext) method depending on the semantics of the Term handing the exception (the AnyCondition provides any exceptions it caught even though it did not throw them as of its semantics).
      Specified by:
      getException in interface org.refcodes.exception.ExceptionAccessor<ArgsSyntaxException>
      Returns:
      The ArgsSyntaxException exception occurring while parsing the arguments.

    • setVisible

      void setVisible(boolean isVisible)

      Visibility in this context means displaying or hiding this Term's existence to the user (defaults to true).

      Specified by:
      setVisible in interface org.refcodes.graphical.VisibleAccessor.VisibleMutator

    • isVisible

      boolean isVisible()

      Visibility in this context means displaying or hiding this Term's existence to the user (defaults to true).

      Specified by:
      isVisible in interface org.refcodes.graphical.VisibleAccessor