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

Class ArgsParserImpl

  • All Implemented Interfaces:
    ArgsParser, ArgsParserMixin<ArgsParser>, RootConditionAccessor, org.refcodes.component.Resetable, org.refcodes.mixin.DescriptionAccessor, org.refcodes.mixin.DescriptionAccessor.DescriptionBuilder<ArgsParser>, org.refcodes.mixin.DescriptionAccessor.DescriptionMutator, org.refcodes.mixin.DescriptionAccessor.DescriptionProperty, org.refcodes.mixin.EscapeCodesStatusAccessor, org.refcodes.mixin.EscapeCodesStatusAccessor.EscapeCodeStatusBuilder<ArgsParser>, org.refcodes.mixin.EscapeCodesStatusAccessor.EscapeCodeStatusMutator, org.refcodes.mixin.EscapeCodesStatusAccessor.EscapeCodeStatusProperty, org.refcodes.mixin.NameAccessor, org.refcodes.mixin.NameAccessor.NameBuilder<ArgsParser>, org.refcodes.mixin.NameAccessor.NameMutator, org.refcodes.mixin.NameAccessor.NameProperty, org.refcodes.mixin.ResetEscapeCodeAccessor, org.refcodes.mixin.ResetEscapeCodeAccessor.ResetEscapeCodeBuilder<ArgsParser>, org.refcodes.mixin.ResetEscapeCodeAccessor.ResetEscapeCodeMutator, org.refcodes.mixin.ResetEscapeCodeAccessor.ResetEscapeCodeProperty, org.refcodes.mixin.TitleAccessor, org.refcodes.mixin.TitleAccessor.TitleBuilder<ArgsParser>, org.refcodes.mixin.TitleAccessor.TitleMutator, org.refcodes.mixin.TitleAccessor.TitleProperty, org.refcodes.textual.TextBoxGridAccessor, org.refcodes.textual.TextBoxGridAccessor.TextBoxGridBuilder<ArgsParser>, org.refcodes.textual.TextBoxGridAccessor.TextBoxGridMutator, org.refcodes.textual.TextBoxGridAccessor.TextBoxGridProperty
    public class ArgsParserImpl
extends Object
implements ArgsParser
    A straightforward implementation of the ArgsParser interface. The constructor only provides means to set the required attributes as the attributes to be adjusted optionally are already sufficiently pre-configured. For adjusting them, a flavor of the Builder-Pattern is provided with which you can easily chain the configuration of this instance; as them methods return the instance of this class being configured. This helps to prevent the telescoping constructor anti-pattern.

    The SyntaxNotation is pre-set with the SyntaxNotation.REFCODES notation.

    The console width id pre-configured with the console's width as determined by the SystemUtility.getTerminalWidth().

    The standard out PrintStream is pre-configured with the System.out PrintStream.

    The newline characters to be used for line breaks is "\r\n" on Windows machines and "\"n" on all other machines as of the SystemUtility.getLineBreak().

    See Also:
    "http://en.wikipedia.org/wiki/Builder_pattern"

    • Constructor Detail

      • ArgsParserImpl

        public ArgsParserImpl()
        Constructs the ArgsParser instance without any restrictions to the parsed arguments. The constructor only provides means to set the required attributes as the attributes to be adjusted optionally are already sufficiently pre-configured. For adjusting them, a flavor of the Builder-Pattern is provided with which you can easily chain the configuration of this instance; as them methods return the instance of this class being configured.

      • ArgsParserImpl

        public ArgsParserImpl​(ArgsSyntax aRootArgsSyntax)
        Constructs the ArgsParser instance with the given root ArgsSyntax and the default SyntaxNotation.REFCODES. The constructor only provides means to set the required attributes as the attributes to be adjusted optionally are already sufficiently pre-configured. For adjusting them, a flavor of the Builder-Pattern is provided with which you can easily chain the configuration of this instance; as them methods return the instance of this class being configured.
        Parameters:
        aRootArgsSyntax - The root condition being the node from which parsing the command line arguments starts.

      • ArgsParserImpl

        public ArgsParserImpl​(Option<?> aRootOption)
        Constructs the ArgsParser instance with the given root Option and the default SyntaxNotation.REFCODES. The constructor only provides means to set the required attributes as the attributes to be adjusted optionally are already sufficiently pre-configured. For adjusting them, a flavor of the Builder-Pattern is provided with which you can easily chain the configuration of this instance; as them methods return the instance of this class being configured.
        Parameters:
        aRootOption - The root option being the node from which parsing the command line arguments starts.

    • Method Detail

      • getLineSeparatorEscapeCode

        public String getLineSeparatorEscapeCode()
        Retrieves the line separator Escape-Code from the line separator Escape-Code property.
        Specified by:
        getLineSeparatorEscapeCode in interface ArgsParser
        Returns:
        The line separator Escape-Code stored by the line separator Escape-Code property.

      • setLineSeparatorEscapeCode

        public void setLineSeparatorEscapeCode​(String aLineSeparatorEscCode)
        Sets the line separator Escape-Code for the line separator Escape-Code property.
        Specified by:
        setLineSeparatorEscapeCode in interface ArgsParser
        Parameters:
        aLineSeparatorEscCode - The line separator Escape-Code to be stored by the line separator Escape-Code property.

      • getBannerEscapeCode

        public String getBannerEscapeCode()
        Retrieves the banner's content Escape-Code from the banner Escape-Code property.
        Specified by:
        getBannerEscapeCode in interface ArgsParser
        Returns:
        The banner Escape-Code stored by the banner Escape-Code property.

      • getBannerBorderEscapeCode

        public String getBannerBorderEscapeCode()
        Retrieves the banner's border Escape-Code from the banner border Escape-Code property.
        Specified by:
        getBannerBorderEscapeCode in interface ArgsParser
        Returns:
        The banner border Escape-Code stored by the banner border Escape-Code property.

      • setBannerEscapeCode

        public void setBannerEscapeCode​(String aBannerEscCode)
        Sets the banner's content Escape-Code for the banner Escape-Code property.
        Specified by:
        setBannerEscapeCode in interface ArgsParser
        Parameters:
        aBannerEscCode - The banner Escape-Code to be stored by the banner Escape-Code property.

      • setBannerBorderEscapeCode

        public void setBannerBorderEscapeCode​(String aBannerBorderEscCode)
        Sets the banner's border Escape-Code for the banner border Escape-Code property.
        Specified by:
        setBannerBorderEscapeCode in interface ArgsParser
        Parameters:
        aBannerBorderEscCode - The banner border Escape-Code to be stored by the banner border Escape-Code property.

      • getParameterEscapeCode

        public String getParameterEscapeCode()
        Retrieves the parameter Escape-Code from the parameter Escape-Code property.
        Specified by:
        getParameterEscapeCode in interface ArgsParser
        Returns:
        The parameter Escape-Code stored by the parameter Escape-Code property.

      • setParameterEscapeCode

        public void setParameterEscapeCode​(String aParamEscCode)
        Sets the parameter Escape-Code for the parameter Escape-Code property.
        Specified by:
        setParameterEscapeCode in interface ArgsParser
        Parameters:
        aParamEscCode - The parameter Escape-Code to be stored by the parameter Escape-Code property.

      • errorLn

        public void errorLn​(String aLine)
        Prints the given line to standard error with regards to to the console width as specified by the ArgsParser.withConsoleWidth(int) method.
        Specified by:
        errorLn in interface ArgsParser
        Parameters:
        aLine - The line to be printed.

      • evalArgs

        public 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 ArgsSyntax. 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 ArgsSyntax will be reported. Business logic therefore should invoke this root node's ArgsParser.evalArgs(String[]) method instead of a ArgsSyntax's Syntaxable.parseArgs(String[], String[]) method; as ignoring superfluous command line arguments will cause unexpected behavior from the point of view of the invoker.
        Specified by:
        evalArgs in interface ArgsParser
        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

      • getCopyrightNote

        public String getCopyrightNote()
        Retrieves the copyright.
        Specified by:
        getCopyrightNote in interface ArgsParser
        Returns:
        The copyright note.

      • getDelimiter

        protected char getDelimiter()
        Returns the delimiter to be used by colliding command line args when creating non colliding arg's aliases (keys for key/value-pairs).
        Returns:
        The according delimiter.

      • getDescription

        public String getDescription()
        Retrieves the description.
        Specified by:
        getDescription in interface ArgsParser
        Specified by:
        getDescription in interface org.refcodes.mixin.DescriptionAccessor
        Returns:
        The description.

      • getLicenseNote

        public String getLicenseNote()
        Retrieves the license.
        Specified by:
        getLicenseNote in interface ArgsParser
        Returns:
        The license note.

      • getName

        public String getName()
        Specified by:
        getName in interface org.refcodes.mixin.NameAccessor

      • getRootArgsSyntax

        public ArgsSyntax getRootArgsSyntax()
        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 root condition from the root condition property.
        Specified by:
        getRootArgsSyntax in interface ArgsParser
        Specified by:
        getRootArgsSyntax in interface RootConditionAccessor
        Returns:
        The root ArgsSyntax in which's syntax this parser is based.

      • getResetEscapeCode

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

      • setResetEscapeCode

        public void setResetEscapeCode​(String aResetEscCode)
        Specified by:
        setResetEscapeCode in interface org.refcodes.mixin.ResetEscapeCodeAccessor.ResetEscapeCodeMutator

      • getTitle

        public String getTitle()
        Specified by:
        getTitle in interface org.refcodes.mixin.TitleAccessor

      • printBanner

        public void printBanner()
        Prints the banner; the banner most probably is an ASCII_HEADER_ASCII_BODY art text block which's look depends strongly on the taste of the author implementing this interface.
        Specified by:
        printBanner in interface ArgsParser

      • printLn

        public void printLn()
        Prints an empty line / a line break.
        Specified by:
        printLn in interface ArgsParser

      • printLn

        public void printLn​(String aLine)
        Prints the given line to standard out with regards to to the console width as specified by the ArgsParser.withConsoleWidth(int) method.
        Specified by:
        printLn in interface ArgsParser
        Parameters:
        aLine - The line to be printed.

      • reset

        public void reset()
        Specified by:
        reset in interface org.refcodes.component.Resetable

      • setBannerFont

        public void setBannerFont​(org.refcodes.textual.Font aBannerFont)
        Sets the banner font.
        Specified by:
        setBannerFont in interface ArgsParser
        Parameters:
        aBannerFont - the new banner font

      • setBannerFontPalette

        public void setBannerFontPalette​(char[] aColorPalette)
        Sets the banner font palette.
        Specified by:
        setBannerFontPalette in interface ArgsParser
        Parameters:
        aColorPalette - the new banner font palette

      • setConsoleWidth

        public 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.
        Specified by:
        setConsoleWidth in interface ArgsParser
        Parameters:
        aConsoleWidth - The width to set or -1 to let the parser automatically determine the console width.

      • setCopyrightNote

        public void setCopyrightNote​(String aCopyrightNote)
        Set the copyright note used by the ArgsParser.printHelp() method when writing out the copyright claim and make other adjustments with the result (with regards to the Builder-Pattern).
        Specified by:
        setCopyrightNote in interface ArgsParser
        Parameters:
        aCopyrightNote - The license note printed out by the ArgsParser.printHelp() method.

      • setDescription

        public void setDescription​(String aDescription)
        Specified by:
        setDescription in interface org.refcodes.mixin.DescriptionAccessor.DescriptionMutator

      • setErrorOut

        public void setErrorOut​(PrintStream aErrorOut)
        Set the error out PrintStream and make other adjustments with the result (with regards to the Builder-Pattern).
        Specified by:
        setErrorOut in interface ArgsParser
        Parameters:
        aErrorOut - The error out PrintStream to set.

      • isEscapeCodesEnabled

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

      • setEscapeCodesEnabled

        public void setEscapeCodesEnabled​(boolean isEscCodeEnabled)
        Specified by:
        setEscapeCodesEnabled in interface org.refcodes.mixin.EscapeCodesStatusAccessor.EscapeCodeStatusMutator

      • getDescriptionEscapeCode

        public String getDescriptionEscapeCode()
        Retrieves the parameter's description Escape-Code from the parameter's description Escape-Code property.
        Specified by:
        getDescriptionEscapeCode in interface ArgsParser
        Returns:
        The description Escape-Code stored by the description Escape-Code property.

      • setDescriptionEscapeCode

        public void setDescriptionEscapeCode​(String aDescriptionEscCode)
        Sets the description Escape-Code for the description Escape-Code property.
        Specified by:
        setDescriptionEscapeCode in interface ArgsParser
        Parameters:
        aDescriptionEscCode - The description Escape-Code to be stored by the description Escape-Code property.

      • setLineBreak

        public void setLineBreak​(String aLineBreak)
        Set the console's line break. A setting of null makes the instance use the SystemUtility.getLineBreak() value.
        Specified by:
        setLineBreak in interface ArgsParser
        Parameters:
        aLineBreak - the new line break

      • setMaxConsoleWidth

        public 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.
        Specified by:
        setMaxConsoleWidth in interface ArgsParser
        Parameters:
        aMaxConsoleWidth - the new max console width

      • setName

        public void setName​(String aName)
        Specified by:
        setName in interface org.refcodes.mixin.NameAccessor.NameMutator

      • setStandardOut

        public void setStandardOut​(PrintStream aStandardOut)
        Set the standard out PrintStream and make other adjustments with the result (with regards to the Builder-Pattern).
        Specified by:
        setStandardOut in interface ArgsParser
        Parameters:
        aStandardOut - The standard out PrintStream to set.

      • setTitle

        public void setTitle​(String aTitle)
        Specified by:
        setTitle in interface org.refcodes.mixin.TitleAccessor.TitleMutator

      • getTextBoxGrid

        public org.refcodes.textual.TextBoxGrid getTextBoxGrid()
        Specified by:
        getTextBoxGrid in interface org.refcodes.textual.TextBoxGridAccessor

      • setTextBoxGrid

        public void setTextBoxGrid​(org.refcodes.textual.TextBoxGrid aTextBoxGrid)
        Specified by:
        setTextBoxGrid in interface org.refcodes.textual.TextBoxGridAccessor.TextBoxGridMutator

      • addExampleUsage

        public void addExampleUsage​(ExampleUsage aExampleUsage)
        Adds a usage example by providing a description of the example and the command line arguments required by the example.
        Specified by:
        addExampleUsage in interface ArgsParser
        Parameters:
        aExampleUsage - The description as well as the command line arguments used by the example.

      • fromArgs

        protected static List<? extends Operand<?>> fromArgs​(String[] aArgs,
                                                     char aDelimiter)
        Heuristically loads the arguments without any syntax required, e.g. without any root ArgsSyntax to be set.
        Parameters:
        aArgs - The arguments to be loaded.
        aDelimiter - The delimiter to resolve name clashes.
        Returns:
        A list of heuristically determined Flag and StringOperand instances.