Class ParserBuilder<C>

    • Field Detail

      • aliases

        protected final java.util.Map<java.lang.String,​AliasBuilder<C>> aliases
      • allowAbbreviatedCommands

        protected boolean allowAbbreviatedCommands
      • allowAbbreviatedOptions

        protected boolean allowAbbreviatedOptions
      • aliasesOverrideBuiltIns

        protected boolean aliasesOverrideBuiltIns
      • aliasesMayChain

        protected boolean aliasesMayChain
      • forceBuiltInPrefix

        private char forceBuiltInPrefix
      • optionParsers

        protected final java.util.List<OptionParser<C>> optionParsers
      • argsSeparator

        protected java.lang.String argsSeparator
      • flagNegationPrefix

        protected java.lang.String flagNegationPrefix
      • injectionAnnotationClasses

        protected java.util.Set<java.lang.String> injectionAnnotationClasses
    • Constructor Detail

      • ParserBuilder

        public ParserBuilder()
      • ParserBuilder

        public ParserBuilder​(CliBuilder<C> cliBuilder)
    • Method Detail

      • defaultConfiguration

        public static <T> ParserMetadata<T> defaultConfiguration()
        Gets the default configuration
        Type Parameters:
        T - Command type to parse
        Returns:
        Default configuration
      • withCommandFactory

        public ParserBuilder<C> withCommandFactory​(CommandFactory<C> commandFactory)
        Specifies the command factory to use
        Parameters:
        commandFactory - Command Factory
        Returns:
        Builder
      • withDefaultCommandFactory

        public ParserBuilder<C> withDefaultCommandFactory()
        Specifies that the default command factory should be used
        Returns:
        Builder
      • withCompositionAnnotations

        public ParserBuilder<C> withCompositionAnnotations​(java.util.Collection<java.lang.String> annotationClassNames)
        Specifies the class names of annotations that Airline should consider to mark a field for further inspection and injection to enable composition.

        Fields marked with these annotations will have the value type of the field scanned for further Airline annotated fields e.g. Option and Arguments. This allows separating groups of options and arguments out into reusable classes that can be composed into your command classes without relying on inheritance.

        Parameters:
        annotationClassNames - Annotation class names
        Returns:
        Builder
        Since:
        2.9.0
      • withDefaultCompositionAnnotations

        public ParserBuilder<C> withDefaultCompositionAnnotations()
        Configures the parser to use the default set of composition annotations.

        Currently this is the following to provide backwards compatibility with past Airline releases:

        • com.github.rvesse.airline.annotations.AirlineModule

        NB: As of {@code 3.0.0) the default set was reduced to just {@code com.github.rvesse.airline.annotations.AirlineModule} and require that users explicitly configure additional annotation classes as they see fit. If you are not currently using a dependency injection framework that requires some form of {@code Inject} annotation we would recommend that you transition to using {@link AirlineModule} in your Airline applications.

        Returns:
        Builder
        Since:
        2.9.0
      • withAlias

        public AliasBuilder<C> withAlias​(java.lang.String name)
        Adds an alias
        Parameters:
        name - Alias name
        Returns:
        Alias Builder
      • getAlias

        public AliasBuilder<C> getAlias​(java.lang.String name)
        Retrieves an alias builder for the given alias
        Parameters:
        name - Alias name
        Returns:
        Alias Builder
      • withAliasForceBuiltInPrefix

        public ParserBuilder<C> withAliasForceBuiltInPrefix​(char prefix)
        Sets a prefix character used in alias definitions to force use of a built-in as opposed to a chained alias
        Parameters:
        prefix - Prefix character
        Returns:
        Parser build
      • withUserAliases

        public UserAliasSourceBuilder<C> withUserAliases()
        Gets a builder that provides detailed control over building user aliases
        Returns:
        User aliases builder
      • withUserAliases

        @Deprecated
        public ParserBuilder<C> withUserAliases​(java.lang.String programName)
        Deprecated.
        Use withUserAliases() to access the user alias builder directly instead
        Reads in user aliases from the default configuration file in the default location.

        The default configuration file name is constructed by appending the .config extension to the defined program name

        The default search location is a .program directory under the users home directory where program is the defined program name.

        If you prefer to control these values explicitly and for more detail on the configuration format please see the withUserAliases(String, String, String...) method

        Parameters:
        programName - Program Name
        Returns:
        Builder
      • withUserAliases

        @Deprecated
        public ParserBuilder<C> withUserAliases​(java.lang.String programName,
                                                java.lang.String searchLocation)
        Deprecated.
        Use withUserAliases() to access the user alias builder directly instead
        Reads in user aliases from the default configuration file in the default location

        The default configuration file name is constructed by appending the .config extension to the defined program name

        If you prefer to control this value explicitly and for more detail on the configuration format please see the withUserAliases(String, String, String...) method

        Parameters:
        programName - Program name
        searchLocation - Location to search
        Returns:
        Builder
      • withUserAliases

        @Deprecated
        public ParserBuilder<C> withUserAliases​(java.lang.String filename,
                                                java.lang.String prefix,
                                                java.lang.String... searchLocations)
        Deprecated.
        Use withUserAliases() to access the user alias builder directly instead
        Reads in user aliases from the defined configuration file in the provided search locations

        This file is in standard Java properties format with the key being the alias and the value being the arguments for this alias. Arguments are whitespace separated though quotes (") may be used to wrap arguments that need to contain whitespace. Quotes may be escaped within quoted arguments and whitespace may be escaped within unquoted arguments. Note that since Java property values are interpreted as Java strings it is necessary to double escape the backslash i.e. \\" for this to work properly.

         example=command --option value
         quoted=command "long argument"
         escaped=command whitespace\\ escape "quote\\"escape"
         

        The search locations should be given in order of preference, the file will be loaded from all search locations in which it exists such that values from the locations occurring first in the search locations list take precedence. This allows for having multiple locations for your configuration file and layering different sets of aliases over each other e.g. system, user and local aliases.

        The prefix is used to filter properties from the properties file such that you can include aliases with other configuration settings in your configuration files. When a prefix is used only properties that start with the prefix are interpreted as alias definitions and the actual alias is the property name with the prefix removed. For example if your prefix was alias. and you had a property alias.foo the resulting alias would be foo.

        Notes

        • Recursive aliases are only supported if withAliasesChaining()} is specified and will result in errors when used otherwise. Even when recursive aliases are enabled aliases cannot use circular references.
        • Aliases cannot override built-ins unless you have called withAliasesOverridingBuiltIns() on your builder
        Parameters:
        filename - Filename to look for
        prefix - Prefix used to distinguish alias related properties from other properties
        searchLocations - Search locations in order of preference
        Returns:
        Builder
      • withUserAliases

        @Deprecated
        public ParserBuilder<C> withUserAliases​(java.lang.String filename,
                                                java.lang.String prefix,
                                                java.util.List<ResourceLocator> locators,
                                                java.lang.String... searchLocations)
        Deprecated.
        Use withUserAliases() to access the user alias builder directly instead
        Reads in user aliases from the defined configuration file in the provided search location

        This file is in standard Java properties format with the key being the alias and the value being the arguments for this alias. Arguments are whitespace separated though quotes (") may be used to wrap arguments that need to contain whitespace. Quotes may be escaped within quoted arguments and whitespace may be escaped within unquoted arguments. Note that since Java property values are interpreted as Java strings it is necessary to double escape the backslash i.e. \\" for this to work properly.

         example=command --option value
         quoted=command "long argument"
         escaped=command whitespace\\ escape "quote\\"escape"
         

        The search locations should be given in order of preference, the file will be loaded from all search locations in which it exists such that values from the locations occurring first in the search locations list take precedence. This allows for having multiple locations for your configuration file and layering different sets of aliases over each other e.g. system, user and local aliases.

        The prefix is used to filter properties from the properties file such that you can include aliases with other configuration settings in your configuration files. When a prefix is used only properties that start with the prefix are interpreted as alias definitions and the actual alias is the property name with the prefix removed. For example if your prefix was alias. and you had a property alias.foo the resulting alias would be foo.

        Notes

        • Recursive aliases are only supported if withAliasesChaining()} is specified and will result in errors when used otherwise. Even when recursive aliases are enabled aliases cannot use circular references.
        • Aliases cannot override built-ins unless you have called withAliasesOverridingBuiltIns() on your builder
        Parameters:
        filename - Filename to look for
        prefix - Prefix used to distinguish alias related properties from other properties
        locators - Locators used to resolve search locations to actual locations, this is what enables things like ~/ to be used to refer to the users home directory. If null then a default set are used.
        searchLocations - Search locations in order of preference
        Returns:
        Builder
      • withAliasesOverridingBuiltIns

        public ParserBuilder<C> withAliasesOverridingBuiltIns()
        Sets that aliases should override built-in commands
        Returns:
        Builder
      • withAliasesChaining

        public ParserBuilder<C> withAliasesChaining()
        Sets that aliases may be defined in terms of other aliases
        Returns:
        Builder
      • withCommandAbbreviation

        public ParserBuilder<C> withCommandAbbreviation()
        Sets that command abbreviation is enabled
        Returns:
        Builder
      • withOptionAbbreviation

        public ParserBuilder<C> withOptionAbbreviation()
        Sets that option abbreviation is enabled
        Returns:
        Builder
      • withTypeConverter

        public ParserBuilder<C> withTypeConverter​(TypeConverter converter)
        Sets the type converter for the parser
        Parameters:
        converter - Type converter
        Returns:
        Builder
      • withDefaultTypeConverter

        public ParserBuilder<C> withDefaultTypeConverter()
        Sets that the default type converter should be used
        Returns:
        Builder
      • withNumericTypeConverter

        public ParserBuilder<C> withNumericTypeConverter​(NumericTypeConverter converter)
        Indicates the desired numeric type converter to use, this is passed as an argument to the given type converter
        Parameters:
        converter - Numeric type converter
        Returns:
        Builder
      • withDefaultNumericTypeConverter

        public ParserBuilder<C> withDefaultNumericTypeConverter()
        Indicates that default numeric type conversion should be used
        Returns:
        Builder
      • withErrorHandler

        public ParserBuilder<C> withErrorHandler​(ParserErrorHandler errorHandler)
        Sets the error handler to use
        Parameters:
        errorHandler - Error handler
        Returns:
        Builder
      • withDefaultErrorHandler

        public ParserBuilder<C> withDefaultErrorHandler()
        Sets that the default error handler should be used
        Returns:
        Builder
      • withOptionParser

        public ParserBuilder<C> withOptionParser​(OptionParser<C> optionParser)
        Configures the CLI to use the given option parser

        Order of registration is important, if you have previously registered any parsers then those will be used prior to the one given here

        Parameters:
        optionParser - Option parser
        Returns:
        Builder
      • withOptionParsers

        public ParserBuilder<C> withOptionParsers​(OptionParser<C>... optionParsers)
        Configures the CLI to use the given option parsers

        Order of registration is important, if you have previously registered any parsers then those will be used prior to those given here

        Parameters:
        optionParsers - Option parsers
        Returns:
        Builder
      • withOnlyDefaultOptionParsers

        public ParserBuilder<C> withOnlyDefaultOptionParsers()
        Configures the CLI to use only the default set of option parsers

        This is the default behaviour so this need only be called if you have previously configured some option parsers using the withOptionParser(OptionParser) or withOptionParsers(OptionParser...) methods and wish to reset the configuration to the default.

        If you wish to instead add the default parsers in addition to your custom parsers you should instead call withDefaultOptionParsers()

        Returns:
        Builder
      • withDefaultOptionParsers

        public ParserBuilder<C> withDefaultOptionParsers()
        Configures the CLI to use the default set of option parsers in addition to any previously registered

        Order of registration is important, if you have previously registered any parsers then those will be used prior to those in the default set.

        Returns:
        Builder
      • withArgumentsSeparator

        public ParserBuilder<C> withArgumentsSeparator​(java.lang.String separator)
        Sets the arguments separator, this is a token used to indicate the point at which no further options will be seen and all further tokens should be treated as arguments.

        This is useful for disambiguating where arguments may be misinterpreted as options. The default value of this is the standard -- used by many command line tools.

        Parameters:
        separator - Arguments separator
        Returns:
        Builder
      • withFlagNegationPrefix

        public ParserBuilder<C> withFlagNegationPrefix​(java.lang.String prefix)
        Sets the flag negation prefix, this is used to determine whether to set a flag option (a zero arity option) to false rather than the usual behaviour of setting it to true. Options must have appropriately prefixed names defined for this prefix to have any effect i.e. setting it does not automatically enable negation for flag options.
        Parameters:
        prefix - Flag negation prefix
        Returns:
        Builder
      • parent

        public CliBuilder<C> parent()
        Gets the parent CLI builder (if any)
        Returns:
        Parent CLI builder
        Throws:
        java.lang.IllegalStateException - Thrown if there is no parent CLI builder