Module org.refcodes.cli
Package org.refcodes.cli

Class CliContext

java.lang.Object
org.refcodes.cli.CliContext
All Implemented Interfaces:
ArgumentEscapeCodeAccessor, CliMetrics, Optionable, OptionEscapeCodeAccessor, SyntaxMetricsAccessor, org.refcodes.mixin.EscapeCodesStatusAccessor, org.refcodes.mixin.ResetEscapeCodeAccessor
public class CliContext extends Object implements CliMetrics, Optionable
The CliContext describes the context in which an ParseArgs is running. The CliContext may depend on the operating system or user settings applied, when running the ParseArgs implementations.

  • Constructor Details

    • CliContext

      public CliContext()
      Constructs an accordingly preconfigured CliContext instance.

    • CliContext

      public CliContext(boolean isEscapeCodesEnabled)
      Constructs an accordingly configured CliContext instance.
      Parameters:
      isEscapeCodesEnabled - Determines whether using escape codes when rendering a Term node's syntax.

    • CliContext

      public CliContext(CliMetrics aCliMetrics)
      Constructs an accordingly configured CliContext instance.
      Parameters:
      aCliMetrics - The CliMetrics describing the CliContext.

    • CliContext

      public CliContext(CliMetrics aCliMetrics, SyntaxMetrics aSyntaxMetrics)
      Constructs an accordingly configured CliContext instance.
      Parameters:
      aCliMetrics - The CliMetrics describing the CliContext.
      aSyntaxMetrics - When being provided, then it overrides the SyntaxMetrics provided by the CliMetrics.

    • CliContext

      public CliContext(CliMetrics aCliMetrics, SyntaxMetrics aSyntaxMetrics, boolean isEscapeCodesEnabled)
      Constructs an accordingly configured CliContext instance.
      Parameters:
      aCliMetrics - The CliMetrics describing the CliContext.
      aSyntaxMetrics - When being provided, then it overrides the SyntaxMetrics provided by the CliMetrics.
      isEscapeCodesEnabled - Overrides the according EscapeCodesStatusAccessor.isEscapeCodesEnabled() attribute. This is useful when using the CliContext instance for generating exception massages which must not have ANSI escape codes.

    • CliContext

      public CliContext(String aArgumentEscapeCode, String aOptionEscapeCode, String aResetEscapeCode)
      Constructs an accordingly configured CliContext instance.
      Parameters:
      aArgumentEscapeCode - The escape code to use when rendering (option's) arguments
      aOptionEscapeCode - The escape code to be used when rendering options.
      aResetEscapeCode - The escape code resetting any previously applied escape codes.

    • CliContext

      public CliContext(SyntaxMetrics aSyntaxMetrics)
      Constructs an accordingly configured CliContext instance.
      Parameters:
      aSyntaxMetrics - The SyntaxMetrics describing the syntax notation to be used such as the SyntaxNotation definitions.

    • CliContext

      public CliContext(SyntaxMetrics aSyntaxMetrics, boolean isEscapeCodesEnabled)
      Constructs an accordingly configured CliContext instance.
      Parameters:
      aSyntaxMetrics - The SyntaxMetrics describing the syntax notation to be used such as the SyntaxNotation definitions.
      isEscapeCodesEnabled - Determines whether using escape codes when rendering a Term node's syntax.

    • CliContext

      public CliContext(SyntaxMetrics aSyntaxMetrics, Character aShortOptionPrefix, String aLongOptionPrefix, boolean isEscapeCodesEnabled, String aArgumentEscapeCode, String aOptionEscapeCode, String aResetEscapeCode)
      Constructs an accordingly configured CliContext instance.
      Parameters:
      aSyntaxMetrics - The SyntaxMetrics describing the syntax notation to be used such as the SyntaxNotation definitions.
      aShortOptionPrefix - The short option prefix to be used when parsing Option elements.
      aLongOptionPrefix - The long option prefix to be used when parsing Option elements.
      isEscapeCodesEnabled - Determines whether using escape codes when rendering a Term node's syntax.
      aArgumentEscapeCode - The escape code to use when rendering (option's) arguments
      aOptionEscapeCode - The escape code to be used when rendering options.
      aResetEscapeCode - The escape code resetting any previously applied escape codes.

    • CliContext

      public CliContext(SyntaxMetrics aSyntaxMetrics, String aArgumentEscapeCode, String aOptionEscapeCode, String aResetEscapeCode)
      Constructs an accordingly configured CliContext instance.
      Parameters:
      aSyntaxMetrics - The SyntaxMetrics describing the syntax notation to be used such as the SyntaxNotation definitions.
      aArgumentEscapeCode - The escape code to use when rendering (option's) arguments
      aOptionEscapeCode - The escape code to be used when rendering options.
      aResetEscapeCode - The escape code resetting any previously applied escape codes.

  • Method Details

    • getArgumentEscapeCode

      public String getArgumentEscapeCode()
      Retrieves the argument Escape-Code from the argument Escape-Code property.
      Specified by:
      getArgumentEscapeCode in interface ArgumentEscapeCodeAccessor
      Returns:
      The argument Escape-Code stored by the argument Escape-Code property.

    • getOptionEscapeCode

      public String getOptionEscapeCode()
      Retrieves the option Escape-Code from the option Escape-Code property.
      Specified by:
      getOptionEscapeCode in interface OptionEscapeCodeAccessor
      Returns:
      The option Escape-Code stored by the option Escape-Code property.

    • getResetEscapeCode

      public String getResetEscapeCode()
      Specified by:
      getResetEscapeCode in interface org.refcodes.mixin.ResetEscapeCodeAccessor

    • getSyntaxMetrics

      public SyntaxMetrics getSyntaxMetrics()
      Retrieves the SyntaxMetrics from the SyntaxMetrics property.
      Specified by:
      getSyntaxMetrics in interface SyntaxMetricsAccessor
      Returns:
      The SyntaxMetrics stored by the decorator (enabled) tags property.

    • isEscapeCodesEnabled

      public boolean isEscapeCodesEnabled()
      Specified by:
      isEscapeCodesEnabled in interface org.refcodes.mixin.EscapeCodesStatusAccessor

    • isOption

      public boolean isOption(String aArg)
      Determines whether the given argument is an option in terms of this context, e.g. whether it starts either with a short option prefix (as of ShortOptionPrefixAccessor.getShortOptionPrefix() or a long option prefix (as of LongOptionPrefixAccessor.getLongOptionPrefix()).
      Parameters:
      aArg - The argument to be tested whether it matches the option pattern as of this context.
      Returns:
      True in case the argument may be a short option or a long option, e.g. it is prefixed accordingly.

    • toAllOptions

      public String[] toAllOptions(Term aConstituent)
      Determines all options (short and long) found in the provided Term node and its children.
      Parameters:
      aConstituent - The element (with its children if applicable) from which to determine the options.
      Returns:
      An array containing all found options.

    • toArgumentEscapeCode

      public String toArgumentEscapeCode()
      Constructs the argument escape code depending on the escape code status (as of isEscapeCodesEnabled()) and whether the argument escape code is not null or null (as of getArgumentEscapeCode()). In case escape codes are enabled and the argument escape code is set, then the argument escape code is returned, else an empty String.
      Returns:
      The argument escape code or an empty String depending on the escape code status and the argument escape code's value.

    • toArgumentSpec

      public String toArgumentSpec(Operand<?> aOperand)
      Creates the argument specification from the provided Operand. In case we got a Flag, then there will be an empty argument specification as the Flag implies a argument. If the Operand is an option, then the argument will be prefixed and suffixed different to an Operand type.
      Parameters:
      aOperand - The operand from which to get the argument specification.
      Returns:
      The argument specification.

    • toArgumentSpec

      public String toArgumentSpec(Operand<?> aOperand, int aMin, int aMax)
      Creates the argument specification from the provided Operand. In case we got a Flag, then there will be an empty argument specification as the Flag implies an argument. If the Operand is an option, then the argument will be prefixed and suffixed different to an Operand type.
      Parameters:
      aOperand - The operand from which to get the argument specification.
      aMin - The minimum value for the operand.
      aMax - The maximum value for the operand.
      Returns:
      The argument specification.

    • toExpandOptions

      public String[] toExpandOptions(String[] aArgs)
      Expands the provided args' short options and returns the resulting args. A short option prefix may be used to denote multiple short options, given a short option prefix being used is "-", then the argument "-xyz" is expanded to be "-x", "-y" and "-z".
      Parameters:
      aArgs - The args to be expanded.
      Returns:
      The expanded args.

    • toLongOption

      public String toLongOption(Option<?> aOption)
      Creates the CliContext instance specific prefixed long option String from the provided Option by prefixing the Option's long option (as of Option.getLongOption()) with the long option prefix (as of LongOptionPrefixAccessor.getLongOptionPrefix()).
      Parameters:
      aOption - The Option from which to create the according prefixed long option String.
      Returns:
      The accordingly prefixed long option String or null if there is no long option set for the provided Option or the Option is null.

    • toOptionUsage

      public String toOptionUsage(Option<?> aOption)
      Creates the CliContext instance specific preferred prefixed option String, being the short option (as of toShortOption(Option)) or, in case of the short option being null, the long option (as of toLongOption(Option)).
      Parameters:
      aOption - The Option from which to create the accordingly prefixed option String.
      Returns:
      The accordingly prefixed option String or null if there is neither a short option nor a long option set for the provided Option or the Option is null.

    • toOptionSpec

      public String toOptionSpec(Option<?> aOption)
      Creates the CliContext instance specific option notation String (without any arguments), consisting of the short option (as of toShortOption(Option)) and(!) the long option (as of toLongOption(Option)) as of them not being null.
      Parameters:
      aOption - The Option from which to create the according option notation String.
      Returns:
      The according notation of the Option (without any arguments).

    • toOptionEscapeCode

      public String toOptionEscapeCode()
      Constructs the option escape code depending on the escape code status (as of isEscapeCodesEnabled()) and whether the option escape code is not null or null (as of getOptionEscapeCode()). In case escape codes are enabled and the option escape code is set, then the option escape code is returned, else an empty String.
      Returns:
      The option escape code or an empty String depending on the escape code status and the option escape code's value.

    • toOptions

      public String[] toOptions(Option<?> aOption)
      Retrieves an array of the context specific options being configured for the given Option instance, being the long option (when set) and the short option (when set), by prepending the according runtime specific short option and long option prefix (if applicable).
      Specified by:
      toOptions in interface Optionable
      Parameters:
      aOption - The Option instance for which to get the configured short and long options.
      Returns:
      The array of options being the long option (if not null) and the short option (if not null) with the according context specific prefixes.

    • toResetEscapeCode

      public String toResetEscapeCode()
      Constructs the reset escape code depending on the escape code status (as of isEscapeCodesEnabled()) and whether the reset escape code is not null or null (as of getResetEscapeCode()). In case escape codes are enabled and the reset escape code is set, then the reset escape code is returned, else an empty String.
      Returns:
      The reset escape code or an empty String depending on the escape code status and the reset escape code's value.

    • toShortOption

      public String toShortOption(Option<?> aOption)
      Creates the CliContext instance specific prefixed short option String from the provided Option by prefixing the Option's short option (as of Option.getShortOption()) with the short option prefix (as of ShortOptionPrefixAccessor.getShortOptionPrefix()).
      Parameters:
      aOption - The Option from which to create the according prefixed short option String.
      Returns:
      The accordingly prefixed short option String or null if there is no short option set for the provided Option or the Option is null.

    • toSpec

      public String toSpec(Operand<?> aOperand)
      Creates a specification for the given Operand and its arguments.
      Parameters:
      aOperand - The Operand for which to generate the specification.
      Returns:
      The according specification text.

    • toUsage

      public String toUsage(Operand<?> aOperand)
      Creates a specification for the given Operand and its arguments. In case of having an Option provided, then the short option and the long option are declared by the notation (as of toOptionSpec(Option)).
      Parameters:
      aOperand - The Operand for which to generate the specification.
      Returns:
      The according usage text.

    • builder

      public static CliContext.Builder builder()
      Creates a CliContext.Builder used to fluently construct CliContext instances.
      Returns:
      The CliContext.Builder for constructing CliContext instances.