CommandLine.Model.OptionSpec.Builder (picocli 3.9.6 API)
Date: 2019-04-06

picocli

## Class CommandLine.Model.OptionSpec.Builder

- java.lang.Object
- - picocli.CommandLine.Model.OptionSpec.Builder

- Enclosing class:
    CommandLine.Model.OptionSpec

      public static class CommandLine.Model.OptionSpec.Builder
      extends java.lang.Object

  Builder responsible for creating valid `OptionSpec` objects.
  Since:
    3.0

- - ### Method Summary

    All Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `CommandLine.Range` | `arity()` Returns how many arguments this option or positional parameter requires.
    `T` | `arity(CommandLine.Range arity)` Sets how many arguments this option or positional parameter requires, and returns this builder.
    `T` | `arity(java.lang.String range)` Sets how many arguments this option or positional parameter requires, and returns this builder.
    `java.lang.Class<?>[]` | `auxiliaryTypes()` Returns auxiliary type information used when the `type()` is a generic `Collection`, `Map` or an abstract class.
    `T` | `auxiliaryTypes(java.lang.Class<?>... types)` Sets auxiliary type information, and returns this builder.
    `CommandLine.Model.OptionSpec` | `build()` Returns a valid `OptionSpec` instance.
    `java.lang.Iterable<java.lang.String>` | `completionCandidates()` Returns the completion candidates for this option or positional parameter, or `null`.
    `T` | `completionCandidates(java.lang.Iterable<java.lang.String> completionCandidates)` Sets the completion candidates for this option or positional parameter, and returns this builder.
    `CommandLine.ITypeConverter<?>[]` | `converters()` Returns one or more `type converters` to use to convert the command line argument into a strongly typed value (or key-value pair for map fields).
    `T` | `converters(CommandLine.ITypeConverter<?>... cs)` Sets option/positional param-specific converter (or converters for Maps), and returns this builder.
    `java.lang.String` | `defaultValue()` Returns the default value of this option or positional parameter, before splitting and type conversion.
    `T` | `defaultValue(java.lang.String defaultValue)` Sets the default value of this option or positional parameter to the specified value, and returns this builder.
    `java.lang.String[]` | `description()` Returns the description of this option, used when generating the usage documentation.
    `T` | `description(java.lang.String... description)` Sets the description of this option, used when generating the usage documentation, and returns this builder.
    `java.lang.String` | `descriptionKey()` Returns the description key of this arg spec, used to get the description from a resource bundle.
    `T` | `descriptionKey(java.lang.String descriptionKey)` Sets the description key that is used to look up the description in a resource bundle, and returns this builder.
    `CommandLine.Model.IGetter` | `getter()` Returns the `CommandLine.Model.IGetter` that is responsible for supplying the value of this argument.
    `T` | `getter(CommandLine.Model.IGetter getter)` Sets the `CommandLine.Model.IGetter` that is responsible for getting the value of this argument, and returns this builder.
    `boolean` | `hasInitialValue()` Determines whether the option or positional parameter will be reset to the `initialValue()` before parsing new input.
    `T` | `hasInitialValue(boolean hasInitialValue)` Determines whether the option or positional parameter will be reset to the `initialValue()` before parsing new input.
    `boolean` | `help()` Deprecated. Use `usageHelp()` and `versionHelp()` instead.
    `CommandLine.Model.OptionSpec.Builder` | `help(boolean help)` Sets whether this option disables validation of the other arguments, and returns this builder.
    `boolean` | `hidden()` Returns whether this option should be excluded from the usage message.
    `T` | `hidden(boolean hidden)` Sets whether this option should be excluded from the usage message, and returns this builder.
    `boolean` | `hideParamSyntax()` Returns whether usage syntax decorations around the paramLabel should be suppressed.
    `T` | `hideParamSyntax(boolean hideParamSyntax)` Sets whether usage syntax decorations around the paramLabel should be suppressed.
    `java.lang.Object` | `initialValue()` Returns the initial value this option or positional parameter.
    `T` | `initialValue(java.lang.Object initialValue)` Sets the initial value of this option or positional parameter to the specified value, and returns this builder.
    `boolean` | `interactive()` Returns whether this option prompts the user to enter a value on the command line.
    `T` | `interactive(boolean interactive)` Sets whether this option prompts the user to enter a value on the command line, and returns this builder.
    `java.lang.String[]` | `names()` Returns one or more option names.
    `CommandLine.Model.OptionSpec.Builder` | `names(java.lang.String... names)` Replaces the option names with the specified values.
    `int` | `order()` Returns the position in the options list in the usage help message at which this option should be shown.
    `CommandLine.Model.OptionSpec.Builder` | `order(int order)` Sets the position in the options list in the usage help message at which this option should be shown, and returns this builder.
    `java.lang.String` | `paramLabel()` Returns the name of the option or positional parameter used in the usage help message.
    `T` | `paramLabel(java.lang.String paramLabel)` Sets the name of the option or positional parameter used in the usage help message, and returns this builder.
    `boolean` | `required()` Returns whether this is a required option or positional parameter.
    `T` | `required(boolean required)` Sets whether this is a required option or positional parameter, and returns this builder.
    `protected CommandLine.Model.OptionSpec.Builder` | `self()` Returns this builder.
    `CommandLine.Model.ISetter` | `setter()` Returns the `CommandLine.Model.ISetter` that is responsible for modifying the value of this argument.
    `T` | `setter(CommandLine.Model.ISetter setter)` Sets the `CommandLine.Model.ISetter` that is responsible for modifying the value of this argument, and returns this builder.
    `CommandLine.Help.Visibility` | `showDefaultValue()` Returns whether this option or positional parameter's default value should be shown in the usage help.
    `T` | `showDefaultValue(CommandLine.Help.Visibility visibility)` Sets whether this option or positional parameter's default value should be shown in the usage help, and returns this builder.
    `java.lang.String` | `splitRegex()` Returns a regular expression to split option parameter values or `""` if the value should not be split.
    `T` | `splitRegex(java.lang.String splitRegex)` Sets a regular expression to split option parameter values or `""` if the value should not be split, and returns this builder.
    `java.lang.String` | `toString()`
    `java.lang.Class<?>` | `type()` Returns the type to convert the option or positional parameter to before setting the value.
    `T` | `type(java.lang.Class<?> propertyType)` Sets the type to convert the option or positional parameter to before setting the value, and returns this builder.
    `boolean` | `usageHelp()` Returns whether this option allows the user to request usage help.
    `CommandLine.Model.OptionSpec.Builder` | `usageHelp(boolean usageHelp)` Sets whether this option allows the user to request usage help, and returns this builder.
    `boolean` | `versionHelp()` Returns whether this option allows the user to request version information.
    `CommandLine.Model.OptionSpec.Builder` | `versionHelp(boolean versionHelp)` Sets whether this option allows the user to request version information, and returns this builder.
    `T` | `withToString(java.lang.String toString)` Sets the string respresentation of this option or positional parameter to the specified value, and returns this builder.

    - ### Methods inherited from class java.lang.Object

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

- - ### Method Detail

    - #### build

          public CommandLine.Model.OptionSpec build()

      Returns a valid `OptionSpec` instance.

    - #### self

          protected CommandLine.Model.OptionSpec.Builder self()

      Returns this builder.

    - #### names

          public java.lang.String[] names()

      Returns one or more option names. At least one option name is required.
      See Also:
        `CommandLine.Option.names()`

    - #### help

          @Deprecated
          public boolean help()

      Deprecated. Use `usageHelp()` and `versionHelp()` instead.
      Returns whether this option disables validation of the other arguments.
      See Also:
        `CommandLine.Option.help()`

    - #### usageHelp

          public boolean usageHelp()

      Returns whether this option allows the user to request usage help.
      See Also:
        `CommandLine.Option.usageHelp()`

    - #### versionHelp

          public boolean versionHelp()

      Returns whether this option allows the user to request version information.
      See Also:
        `CommandLine.Option.versionHelp()`

    - #### order

          public int order()

      Returns the position in the options list in the usage help message at which this option should be shown. Options with a lower number are shown before options with a higher number. This attribute is only honored if `CommandLine.Model.UsageMessageSpec.sortOptions()` is `false` for this command.
      Since:
        3.9
      See Also:
        `CommandLine.Option.order()`

    - #### names

          public CommandLine.Model.OptionSpec.Builder names(java.lang.String... names)

      Replaces the option names with the specified values. At least one option name is required, and returns this builder.
      Returns:
        this builder instance to provide a fluent interface

    - #### help

          public CommandLine.Model.OptionSpec.Builder help(boolean help)

      Sets whether this option disables validation of the other arguments, and returns this builder.

    - #### usageHelp

          public CommandLine.Model.OptionSpec.Builder usageHelp(boolean usageHelp)

      Sets whether this option allows the user to request usage help, and returns this builder.

    - #### versionHelp

          public CommandLine.Model.OptionSpec.Builder versionHelp(boolean versionHelp)

      Sets whether this option allows the user to request version information, and returns this builder.

    - #### order

          public CommandLine.Model.OptionSpec.Builder order(int order)

      Sets the position in the options list in the usage help message at which this option should be shown, and returns this builder.
      Since:
        3.9

    - #### required

          public boolean required()

      Returns whether this is a required option or positional parameter.
      See Also:
        `CommandLine.Option.required()`

    - #### interactive

          public boolean interactive()

      Returns whether this option prompts the user to enter a value on the command line.
      See Also:
        `CommandLine.Option.interactive()`

    - #### description

          public java.lang.String[] description()

      Returns the description of this option, used when generating the usage documentation.
      See Also:
        `CommandLine.Option.description()`

    - #### descriptionKey

          public java.lang.String descriptionKey()

      Returns the description key of this arg spec, used to get the description from a resource bundle.
      Since:
        3.6
      See Also:
        `CommandLine.Option.descriptionKey()`, `CommandLine.Parameters.descriptionKey()`

    - #### arity

          public CommandLine.Range arity()

      Returns how many arguments this option or positional parameter requires.
      See Also:
        `CommandLine.Option.arity()`

    - #### paramLabel

          public java.lang.String paramLabel()

      Returns the name of the option or positional parameter used in the usage help message.
      See Also:
        `{@link Parameters#paramLabel()}`

    - #### hideParamSyntax

          public boolean hideParamSyntax()

      Returns whether usage syntax decorations around the paramLabel should be suppressed. The default is `false`: by default, the paramLabel is surrounded with `'['` and `']'` characters if the value is optional and followed by ellipses ("...") when multiple values can be specified.
      Since:
        3.6.0

    - #### auxiliaryTypes

          public java.lang.Class<?>[] auxiliaryTypes()

      Returns auxiliary type information used when the `type()` is a generic `Collection`, `Map` or an abstract class.
      See Also:
        `CommandLine.Option.type()`

    - #### converters

          public CommandLine.ITypeConverter<?>[] converters()

      Returns one or more `type converters` to use to convert the command line argument into a strongly typed value (or key-value pair for map fields). This is useful when a particular option or positional parameter should use a custom conversion that is different from the normal conversion for the arg spec's type.
      See Also:
        `CommandLine.Option.converter()`

    - #### splitRegex

          public java.lang.String splitRegex()

      Returns a regular expression to split option parameter values or `""` if the value should not be split.
      See Also:
        `CommandLine.Option.split()`

    - #### hidden

          public boolean hidden()

      Returns whether this option should be excluded from the usage message.
      See Also:
        `CommandLine.Option.hidden()`

    - #### type

          public java.lang.Class<?> type()

      Returns the type to convert the option or positional parameter to before setting the value.

    - #### defaultValue

          public java.lang.String defaultValue()

      Returns the default value of this option or positional parameter, before splitting and type conversion. A value of `null` means this option or positional parameter does not have a default.

    - #### initialValue

          public java.lang.Object initialValue()

      Returns the initial value this option or positional parameter. If `hasInitialValue()` is true, the option will be reset to the initial value before parsing (regardless of whether a default value exists), to clear values that would otherwise remain from parsing previous input.

    - #### hasInitialValue

          public boolean hasInitialValue()

      Determines whether the option or positional parameter will be reset to the `initialValue()` before parsing new input.

    - #### showDefaultValue

          public CommandLine.Help.Visibility showDefaultValue()

      Returns whether this option or positional parameter's default value should be shown in the usage help.

    - #### completionCandidates

          public java.lang.Iterable<java.lang.String> completionCandidates()

      Returns the completion candidates for this option or positional parameter, or `null`.
      Since:
        3.2

    - #### getter

          public CommandLine.Model.IGetter getter()

      Returns the `CommandLine.Model.IGetter` that is responsible for supplying the value of this argument.

    - #### setter

          public CommandLine.Model.ISetter setter()

      Returns the `CommandLine.Model.ISetter` that is responsible for modifying the value of this argument.

    - #### toString

          public java.lang.String toString()

      Overrides:
        `toString` in class `java.lang.Object`

    - #### required

          public T required(boolean required)

      Sets whether this is a required option or positional parameter, and returns this builder.

    - #### interactive

          public T interactive(boolean interactive)

      Sets whether this option prompts the user to enter a value on the command line, and returns this builder.

    - #### description

          public T description(java.lang.String... description)

      Sets the description of this option, used when generating the usage documentation, and returns this builder.
      See Also:
        `CommandLine.Option.description()`

    - #### descriptionKey

          public T descriptionKey(java.lang.String descriptionKey)

      Sets the description key that is used to look up the description in a resource bundle, and returns this builder.
      Since:
        3.6
      See Also:
        `CommandLine.Option.descriptionKey()`, `CommandLine.Parameters.descriptionKey()`

    - #### arity

          public T arity(java.lang.String range)

      Sets how many arguments this option or positional parameter requires, and returns this builder.

    - #### arity

          public T arity(CommandLine.Range arity)

      Sets how many arguments this option or positional parameter requires, and returns this builder.

    - #### paramLabel

          public T paramLabel(java.lang.String paramLabel)

      Sets the name of the option or positional parameter used in the usage help message, and returns this builder.

    - #### hideParamSyntax

          public T hideParamSyntax(boolean hideParamSyntax)

      Sets whether usage syntax decorations around the paramLabel should be suppressed. The default is `false`: by default, the paramLabel is surrounded with `'['` and `']'` characters if the value is optional and followed by ellipses ("...") when multiple values can be specified.
      Since:
        3.6.0

    - #### auxiliaryTypes

          public T auxiliaryTypes(java.lang.Class<?>... types)

      Sets auxiliary type information, and returns this builder.
      Parameters:
        `types` - the element type(s) when the `type()` is a generic `Collection` or a `Map`; or the concrete type when the `type()` is an abstract class.

    - #### converters

          public T converters(CommandLine.ITypeConverter<?>... cs)

      Sets option/positional param-specific converter (or converters for Maps), and returns this builder.

    - #### splitRegex

          public T splitRegex(java.lang.String splitRegex)

      Sets a regular expression to split option parameter values or `""` if the value should not be split, and returns this builder.

    - #### showDefaultValue

          public T showDefaultValue(CommandLine.Help.Visibility visibility)

      Sets whether this option or positional parameter's default value should be shown in the usage help, and returns this builder.

    - #### completionCandidates

          public T completionCandidates(java.lang.Iterable<java.lang.String> completionCandidates)

      Sets the completion candidates for this option or positional parameter, and returns this builder.
      Since:
        3.2

    - #### hidden

          public T hidden(boolean hidden)

      Sets whether this option should be excluded from the usage message, and returns this builder.

    - #### type

          public T type(java.lang.Class<?> propertyType)

      Sets the type to convert the option or positional parameter to before setting the value, and returns this builder.
      Parameters:
        `propertyType` - the type of this option or parameter. For multi-value options and positional parameters this can be an array, or a (sub-type of) Collection or Map.

    - #### defaultValue

          public T defaultValue(java.lang.String defaultValue)

      Sets the default value of this option or positional parameter to the specified value, and returns this builder. Before parsing the command line, the result of splitting and type converting this default value is applied to the option or positional parameter. A value of `null` or `"__no_default_value__"` means no default.

    - #### initialValue

          public T initialValue(java.lang.Object initialValue)

      Sets the initial value of this option or positional parameter to the specified value, and returns this builder. If `hasInitialValue()` is true, the option will be reset to the initial value before parsing (regardless of whether a default value exists), to clear values that would otherwise remain from parsing previous input.

    - #### hasInitialValue

          public T hasInitialValue(boolean hasInitialValue)

      Determines whether the option or positional parameter will be reset to the `initialValue()` before parsing new input.

    - #### getter

          public T getter(CommandLine.Model.IGetter getter)

      Sets the `CommandLine.Model.IGetter` that is responsible for getting the value of this argument, and returns this builder.

    - #### setter

          public T setter(CommandLine.Model.ISetter setter)

      Sets the `CommandLine.Model.ISetter` that is responsible for modifying the value of this argument, and returns this builder.

    - #### withToString

          public T withToString(java.lang.String toString)

      Sets the string respresentation of this option or positional parameter to the specified value, and returns this builder.