com.github.rvesse.airline.builder

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 Summary

Fields

Modifier and Type	Field and Description
protected Map<String,AliasBuilder<C>>	aliases
protected boolean	aliasesMayChain
protected boolean	aliasesOverrideBuiltIns
protected boolean	allowAbbreviatedCommands
protected boolean	allowAbbreviatedOptions
protected String	argsSeparator
protected CommandFactory<C>	commandFactory
protected ParserErrorHandler	errorHandler
protected String	flagNegationPrefix
protected NumericTypeConverter	numericTypeConverter
protected List<OptionParser<C>>	optionParsers
protected TypeConverter	typeConverter
protected UserAliasesSource<C>	userAliases

Constructor Summary

Constructors

Constructor and Description
ParserBuilder()

Method Summary

Methods

Modifier and Type	Method and Description
ParserMetadata<C>	build() Builds the type
static <T> ParserMetadata<T>	defaultConfiguration()
AliasBuilder<C>	getAlias(String name)
AliasBuilder<C>	withAlias(String name)
ParserBuilder<C>	withAliasesChaining()
ParserBuilder<C>	withAliasesOverridingBuiltIns()
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.
ParserBuilder<C>	withCommandAbbreviation()
ParserBuilder<C>	withCommandFactory(CommandFactory<C> commandFactory)
ParserBuilder<C>	withDefaultCommandFactory()
ParserBuilder<C>	withDefaultErrorHandler()
ParserBuilder<C>	withDefaultNumericTypeConverter() Indicates that default numeric type conversion should be used
ParserBuilder<C>	withDefaultOptionParsers() Configures the CLI to use the default set of option parsers in addition to any previously registered
ParserBuilder<C>	withDefaultTypeConverter()
ParserBuilder<C>	withErrorHandler(ParserErrorHandler errorHandler)
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.
ParserBuilder<C>	withNumericTypeConverter(NumericTypeConverter converter) Indicates the desired numeric type converter to use, this is passed as an argument to the given type converter
ParserBuilder<C>	withOnlyDefaultOptionParsers() Configures the CLI to use only the default set of option parsers
ParserBuilder<C>	withOptionAbbreviation()
ParserBuilder<C>	withOptionParser(OptionParser<C> optionParser) Configures the CLI to use the given option parser
ParserBuilder<C>	withOptionParsers(OptionParser<C>... optionParsers) Configures the CLI to use the given option parsers
ParserBuilder<C>	withTypeConverter(TypeConverter converter)
ParserBuilder<C>	withUserAliases(String programName) Reads in user aliases from the default configuration file in the default location.
ParserBuilder<C>	withUserAliases(String programName, String searchLocation) Reads in user aliases from the default configuration file in the default location
ParserBuilder<C>	withUserAliases(String filename, String prefix, String... searchLocations) Reads in user aliases from the default configuration file in the default location

Methods inherited from class com.github.rvesse.airline.builder.AbstractBuilder

checkNotBlank, checkNotEmpty, checkNotNull

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

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

optionParsers

protected final List<OptionParser<C>> optionParsers

argsSeparator

protected String argsSeparator

flagNegationPrefix

protected String flagNegationPrefix

userAliases

protected UserAliasesSource<C> userAliases

errorHandler

protected ParserErrorHandler errorHandler

Constructor Detail

ParserBuilder

public ParserBuilder()

Method Detail

defaultConfiguration

public static <T> ParserMetadata<T> defaultConfiguration()

withCommandFactory

public ParserBuilder<C> withCommandFactory(CommandFactory<C> commandFactory)

withDefaultCommandFactory

public ParserBuilder<C> withDefaultCommandFactory()

withAlias

public AliasBuilder<C> withAlias(String name)

getAlias

public AliasBuilder<C> getAlias(String name)

withUserAliases

public ParserBuilder<C> withUserAliases(String programName)

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

Returns:

Builder

Throws:

IOException

withUserAliases

public ParserBuilder<C> withUserAliases(String programName,
                               String searchLocation)

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:

searchLocation - Location to search

Returns:

Builder

Throws:

IOException

withUserAliases

public ParserBuilder<C> withUserAliases(String filename,
                               String prefix,
                               String... searchLocations)

Reads in user aliases from the default configuration file in the default 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

Returns:

Throws:

IOException

withAliasesOverridingBuiltIns

public ParserBuilder<C> withAliasesOverridingBuiltIns()

withAliasesChaining

public ParserBuilder<C> withAliasesChaining()

withCommandAbbreviation

public ParserBuilder<C> withCommandAbbreviation()

withOptionAbbreviation

public ParserBuilder<C> withOptionAbbreviation()

withTypeConverter

public ParserBuilder<C> withTypeConverter(TypeConverter converter)

withDefaultTypeConverter

public ParserBuilder<C> withDefaultTypeConverter()

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)

withDefaultErrorHandler

public ParserBuilder<C> withDefaultErrorHandler()

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:

optionParsers - Option parsers

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(Class) or #withOptionParsers(Class...) 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 -

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

build

public ParserMetadata<C> build()

Description copied from class: AbstractBuilder

Builds the type

Specified by:

build in class AbstractBuilder<ParserMetadata<C>>

Returns:

Type instance