Class ParserBuilder<C>

java.lang.Object
com.github.rvesse.airline.builder.AbstractBuilder<ParserMetadata<C>>
com.github.rvesse.airline.builder.ParserBuilder<C>
Type Parameters:
C - Command type

public class ParserBuilder<C> extends AbstractBuilder<ParserMetadata<C>>
Builder for parser configurations
  • Field Details

    • typeConverter

      protected TypeConverter typeConverter
    • numericTypeConverter

      protected NumericTypeConverter numericTypeConverter
    • aliases

      protected final Map<String,AliasBuilder<C>> aliases
    • commandFactory

      protected CommandFactory<C> commandFactory
    • allowAbbreviatedCommands

      protected boolean allowAbbreviatedCommands
    • allowAbbreviatedOptions

      protected boolean allowAbbreviatedOptions
    • aliasesOverrideBuiltIns

      protected boolean aliasesOverrideBuiltIns
    • aliasesMayChain

      protected boolean aliasesMayChain
    • forceBuiltInPrefix

      private char forceBuiltInPrefix
    • optionParsers

      protected final List<OptionParser<C>> optionParsers
    • argsSeparator

      protected String argsSeparator
    • flagNegationPrefix

      protected String flagNegationPrefix
    • userAliasesBuilder

      protected UserAliasSourceBuilder<C> userAliasesBuilder
    • errorHandler

      protected ParserErrorHandler errorHandler
    • injectionAnnotationClasses

      protected Set<String> injectionAnnotationClasses
    • cliBuilder

      private final CliBuilder<C> cliBuilder
  • Constructor Details

    • ParserBuilder

      public ParserBuilder()
    • ParserBuilder

      public ParserBuilder(CliBuilder<C> cliBuilder)
  • Method Details

    • 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(Collection<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
    • withCompositionAnnotations

      public ParserBuilder<C> withCompositionAnnotations(String... annotationClassNames)
      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 invalid input: '{@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. </p> @return Builder @since 2.9.0'

    • withAlias

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

      public AliasBuilder<C> getAlias(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(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(String programName, 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(String filename, String prefix, 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(String filename, String prefix, List<ResourceLocator> locators, 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(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(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:
      IllegalStateException - Thrown if there is no parent CLI builder
    • build

      public ParserMetadata<C> build()
      Description copied from class: AbstractBuilder
      Builds the type
      Specified by:
      build in class AbstractBuilder<ParserMetadata<C>>
      Returns:
      Type instance