module Mixlib::CLI::ClassMethods
Public Instance Methods
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
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
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
# File lib/mixlib/cli.rb, line 88 def use_separate_defaults? @separate_default_options ||= false end