- 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 Summary
Fields Modifier and Type Field Description protected java.util.Map<java.lang.String,AliasBuilder<C>>
aliases
protected boolean
aliasesMayChain
protected boolean
aliasesOverrideBuiltIns
protected boolean
allowAbbreviatedCommands
protected boolean
allowAbbreviatedOptions
protected java.lang.String
argsSeparator
private CliBuilder<C>
cliBuilder
protected CommandFactory<C>
commandFactory
protected ParserErrorHandler
errorHandler
protected java.lang.String
flagNegationPrefix
private char
forceBuiltInPrefix
protected java.util.Set<java.lang.String>
injectionAnnotationClasses
protected NumericTypeConverter
numericTypeConverter
protected java.util.List<OptionParser<C>>
optionParsers
protected TypeConverter
typeConverter
protected UserAliasSourceBuilder<C>
userAliasesBuilder
-
Constructor Summary
Constructors Constructor Description ParserBuilder()
ParserBuilder(CliBuilder<C> cliBuilder)
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description ParserMetadata<C>
build()
Builds the typestatic <T> ParserMetadata<T>
defaultConfiguration()
Gets the default configurationAliasBuilder<C>
getAlias(java.lang.String name)
Retrieves an alias builder for the given aliasCliBuilder<C>
parent()
Gets the parent CLI builder (if any)AliasBuilder<C>
withAlias(java.lang.String name)
Adds an aliasParserBuilder<C>
withAliasesChaining()
Sets that aliases may be defined in terms of other aliasesParserBuilder<C>
withAliasesOverridingBuiltIns()
Sets that aliases should override built-in commandsParserBuilder<C>
withAliasForceBuiltInPrefix(char prefix)
Sets a prefix character used in alias definitions to force use of a built-in as opposed to a chained aliasParserBuilder<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.ParserBuilder<C>
withCommandAbbreviation()
Sets that command abbreviation is enabledParserBuilder<C>
withCommandFactory(CommandFactory<C> commandFactory)
Specifies the command factory to useParserBuilder<C>
withCompositionAnnotations(java.lang.String... annotationClassNames)
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.ParserBuilder<C>
withDefaultCommandFactory()
Specifies that the default command factory should be usedParserBuilder<C>
withDefaultCompositionAnnotations()
Configures the parser to use the default set of composition annotations.ParserBuilder<C>
withDefaultErrorHandler()
Sets that the default error handler should be usedParserBuilder<C>
withDefaultNumericTypeConverter()
Indicates that default numeric type conversion should be usedParserBuilder<C>
withDefaultOptionParsers()
Configures the CLI to use the default set of option parsers in addition to any previously registeredParserBuilder<C>
withDefaultTypeConverter()
Sets that the default type converter should be usedParserBuilder<C>
withErrorHandler(ParserErrorHandler errorHandler)
Sets the error handler to useParserBuilder<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) tofalse
rather than the usual behaviour of setting it totrue
.ParserBuilder<C>
withNumericTypeConverter(NumericTypeConverter converter)
Indicates the desired numeric type converter to use, this is passed as an argument to the given type converterParserBuilder<C>
withOnlyDefaultOptionParsers()
Configures the CLI to use only the default set of option parsersParserBuilder<C>
withOptionAbbreviation()
Sets that option abbreviation is enabledParserBuilder<C>
withOptionParser(OptionParser<C> optionParser)
Configures the CLI to use the given option parserParserBuilder<C>
withOptionParsers(OptionParser<C>... optionParsers)
Configures the CLI to use the given option parsersParserBuilder<C>
withTypeConverter(TypeConverter converter)
Sets the type converter for the parserUserAliasSourceBuilder<C>
withUserAliases()
Gets a builder that provides detailed control over building user aliasesParserBuilder<C>
withUserAliases(java.lang.String programName)
Deprecated.UsewithUserAliases()
to access the user alias builder directly insteadParserBuilder<C>
withUserAliases(java.lang.String programName, java.lang.String searchLocation)
Deprecated.UsewithUserAliases()
to access the user alias builder directly insteadParserBuilder<C>
withUserAliases(java.lang.String filename, java.lang.String prefix, java.lang.String... searchLocations)
Deprecated.UsewithUserAliases()
to access the user alias builder directly insteadParserBuilder<C>
withUserAliases(java.lang.String filename, java.lang.String prefix, java.util.List<ResourceLocator> locators, java.lang.String... searchLocations)
Deprecated.UsewithUserAliases()
to access the user alias builder directly instead-
Methods inherited from class com.github.rvesse.airline.builder.AbstractBuilder
checkNotBlank, checkNotEmpty, checkNotNull
-
-
-
-
Field Detail
-
typeConverter
protected TypeConverter typeConverter
-
numericTypeConverter
protected NumericTypeConverter numericTypeConverter
-
aliases
protected final java.util.Map<java.lang.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 java.util.List<OptionParser<C>> optionParsers
-
argsSeparator
protected java.lang.String argsSeparator
-
flagNegationPrefix
protected java.lang.String flagNegationPrefix
-
userAliasesBuilder
protected UserAliasSourceBuilder<C> userAliasesBuilder
-
errorHandler
protected ParserErrorHandler errorHandler
-
injectionAnnotationClasses
protected java.util.Set<java.lang.String> injectionAnnotationClasses
-
cliBuilder
private final CliBuilder<C> cliBuilder
-
-
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
andArguments
. 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(java.lang.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 {@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.UsewithUserAliases()
to access the user alias builder directly insteadReads 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 nameThe default search location is a
.program
directory under the users home directory whereprogram
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.UsewithUserAliases()
to access the user alias builder directly insteadReads in user aliases from the default configuration file in the default locationThe default configuration file name is constructed by appending the
.config
extension to the defined program nameIf 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 namesearchLocation
- Location to search- Returns:
- Builder
-
withUserAliases
@Deprecated public ParserBuilder<C> withUserAliases(java.lang.String filename, java.lang.String prefix, java.lang.String... searchLocations)
Deprecated.UsewithUserAliases()
to access the user alias builder directly insteadReads in user aliases from the defined configuration file in the provided search locationsThis 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 wasalias.
and you had a propertyalias.foo
the resulting alias would befoo
.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 forprefix
- Prefix used to distinguish alias related properties from other propertiessearchLocations
- Search locations in order of preference- Returns:
- Builder
- Recursive aliases are only supported if
-
withUserAliases
@Deprecated public ParserBuilder<C> withUserAliases(java.lang.String filename, java.lang.String prefix, java.util.List<ResourceLocator> locators, java.lang.String... searchLocations)
Deprecated.UsewithUserAliases()
to access the user alias builder directly insteadReads in user aliases from the defined configuration file in the provided search locationThis 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 wasalias.
and you had a propertyalias.foo
the resulting alias would befoo
.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 forprefix
- Prefix used to distinguish alias related properties from other propertieslocators
- 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. Ifnull
then a default set are used.searchLocations
- Search locations in order of preference- Returns:
- Builder
- Recursive aliases are only supported if
-
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 parserOrder 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 parsersOrder 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 parsersThis is the default behaviour so this need only be called if you have previously configured some option parsers using the
withOptionParser(OptionParser)
orwithOptionParsers(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 registeredOrder 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) tofalse
rather than the usual behaviour of setting it totrue
. 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
-
build
public ParserMetadata<C> build()
Description copied from class:AbstractBuilder
Builds the type- Specified by:
build
in classAbstractBuilder<ParserMetadata<C>>
- Returns:
- Type instance
-
-