Module: Mixlib::CLI::ClassMethods

Defined in:
lib/mixlib/cli.rb

Instance Method Summary collapse

Instance Method Details

Change the banner. Defaults to:

Usage: #{0} (options)

Parameters

bstring<String>

The string to set the banner to

Returns

@banner<String>

The current banner



210
211
212
213
214
215
216
217
 
# File 'lib/mixlib/cli.rb', line 210

def banner(bstring = nil)
  if bstring
    @banner = bstring
  else
    @banner ||= "Usage: #{$0} (options)"
    @banner
  end
end

#deprecated_option(name, replacement: nil, long: nil, short: nil, boolean: false, value_mapper: nil, keep: true) ⇒ Object

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.



151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
 
# 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) ⇒ Hash

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

i

Returns:

  • (Hash) —

    the config hash for the created option

Raises:

  • (ArgumentError) 


123
124
125
126
127
128
 
# 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 ⇒ Object

Get the hash of current options.

Returns

@options<Hash>

The current options hash.



184
185
186
187
 
# File 'lib/mixlib/cli.rb', line 184

def options
  @options ||= {}
  @options
end

#options=(val) ⇒ Object

Set the current options hash

Parameters

val<Hash>

The hash to set the options to

Returns

@options<Hash>

The current options hash.

Raises:

  • (ArgumentError) 


196
197
198
199
200
 
# 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) ⇒ Object

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



84
85
86
 
# 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? ⇒ Boolean

Returns:

  • (Boolean) 


88
89
90
 
# File 'lib/mixlib/cli.rb', line 88

def use_separate_defaults?
  @separate_default_options ||= false
end