module Mixlib::CLI::ClassMethods

Public Instance Methods

banner(bstring = nil) click to toggle source

Change the banner. Defaults to:

Usage: #{0} (options)

Parameters

bstring<String>

The string to set the banner to

Returns

@banner<String>

The current banner

deprecated_option(name, replacement: nil, long: nil, short: nil, boolean: false, value_mapper: nil, keep: true) click to toggle source

Declare a deprecated option

Add a deprecated command line option.

name<Symbol>

The name of the deprecated option

replacement<Symbol>

The name of the option that replaces this option.

long<String>

The original long flag name, or flag name with argument, eg “–user USER”

short<String>

The original short-form flag name, eg “-u USER”

boolean<String>

true if this is a boolean flag, eg “–[no-]option”.

value_mapper<Proc/1>

a block that accepts the original value from the deprecated option,

and converts it to a value suitable for the new option.
If not provided, the value provided to the deprecated option will be
assigned directly to the converted option.
keep<Boolean>

Defaults to true, this ensures that `options` is populated when the deprecated flag is used. If set to false, only the value in `replacement` will be set. Results undefined if no replacement is provided. You can use this to enforce the transition to non-deprecated keys in your code.

Returns

<Hash>

The config hash for the created option.

# File lib/mixlib/cli.rb, line 151
def deprecated_option(name,
  replacement: nil,
  long: nil,
  short: nil,
  boolean: false,
  value_mapper: nil,
  keep: true)

  description = if replacement
                  replacement_cfg = options[replacement]
                  display_name = CLI::Formatter.combined_option_display_name(replacement_cfg[:short], replacement_cfg[:long])
                  "This flag is deprecated. Use #{display_name} instead."
                else
                  "This flag is deprecated and will be removed in a future release."
                end
  value_mapper ||= Proc.new { |v| v }

  option(name,
    long: long,
    short: short,
    boolean: boolean,
    description: description,
    on: :tail,
    deprecated: true,
    keep: keep,
    replacement: replacement,
    value_mapper: value_mapper)
end
option(name, args) click to toggle source

Add a command line option.

Parameters

name<Symbol>

The name of the option to add

args<Hash>

A hash of arguments for the option, specifying how it should be parsed.

Supported arguments:
  :short   - The short option, just like from optparse. Example: "-l LEVEL"
  :long    - The long option, just like from optparse. Example: "--level LEVEL"
  :description - The description for this item, just like from optparse.
  :default - A default value for this option.  Default values will be populated
  on parse into `config` or `default_default`, depending `use_separate_defaults`
  :boolean - indicates the flag is a boolean. You can use this if the flag takes no arguments
             The config value will be set to 'true' if the flag is provided on the CLI and this
             argument is set to true. The config value will be set to false only
             if it has a default value of false
  :required - When set, the option is required.  If the command is run without this option,
             it will print a message informing the user of the missing requirement, and exit. Default is false.
  :proc     - Proc that will be invoked if the human has specified this option.
              Two forms are supported:
              Proc/1 - provided value is passed in.
              Proc/2 - first argument is provided value. Second is the cli flag option hash.
              Both versions return the value to be assigned to the option.
  :show_options - this option is designated as one that shows all supported options/help when invoked.
  :exit     - exit your program with the exit code when this option is given. Example: 0
  :in       - array containing a list of valid values. The value provided at run-time for the option is
              validated against this. If it is not in the list, it will print a message and exit.
  :on :head OR :tail - force this option to display at the beginning or end of the
                       option list, respectively

@return <Hash>

the config hash for the created option

i

# File lib/mixlib/cli.rb, line 123
def option(name, args)
  @options ||= {}
  raise(ArgumentError, "Option name must be a symbol") unless name.is_a?(Symbol)

  @options[name.to_sym] = args
end
options() click to toggle source

Get the hash of current options.

Returns

@options<Hash>

The current options hash.

# File lib/mixlib/cli.rb, line 184
def options
  @options ||= {}
  @options
end
options=(val) click to toggle source

Set the current options hash

Parameters

val<Hash>

The hash to set the options to

Returns

@options<Hash>

The current options hash.

# File lib/mixlib/cli.rb, line 196
def options=(val)
  raise(ArgumentError, "Options must receive a hash") unless val.is_a?(Hash)

  @options = val
end
use_separate_default_options(true_or_false) click to toggle source

When this setting is set to true, default values supplied to the mixlib-cli DSL will be stored in a separate Hash

# File lib/mixlib/cli.rb, line 84
def use_separate_default_options(true_or_false)
  @separate_default_options = true_or_false
end
use_separate_defaults?() click to toggle source
# File lib/mixlib/cli.rb, line 88
def use_separate_defaults?
  @separate_default_options ||= false
end