module Mixlib::CLI
Mixlib::CLI¶ ↑
Adds a DSL for defining command line options and methods for parsing those options to the including class.
Mixlib::CLI does some setup in initialize, so the including class must call `super()` if it defines a custom initializer.
DSL¶ ↑
When included, Mixlib::CLI also extends the including class with its ClassMethods, which define the DSL. The primary methods of the DSL are Mixlib::CLI::ClassMethods#option, which defines a command line option, and Mixlib::CLI::ClassMethods#banner, which defines the “usage” banner.
Parsing¶ ↑
Command line options are parsed by calling the instance method parse_options. After calling this method, the attribute config will contain a hash of `:option_name => value` pairs.
Constants
- VERSION
Attributes
Any arguments which were not parsed and placed in “config”–the leftovers.
A Hash containing the values supplied by command line options.
The behavior and contents of this Hash vary depending on whether Mixlib::CLI::ClassMethods#use_separate_default_options is enabled.
use_separate_default_options disabled¶ ↑
After initialization, config
will contain any default values
defined via the mixlib-config DSL. When parse_options is called,
user-supplied values (from ARGV) will be merged in.
use_separate_default_options enabled¶ ↑
After initialization, this will be an empty hash. When parse_options is called,
config
is populated only with user-supplied
values.
If Mixlib::CLI::ClassMethods#use_separate_default_options is enabled, this will be a Hash containing key value pairs of `:option_name => default_value` (populated during object initialization).
If use_separate_default_options is disabled, it will always be an empty hash.
Gives the command line options definition as configured in the DSL. These are used by parse_options to generate the option parsing code. To get the values supplied by the user, see config.
Public Class Methods
# File lib/mixlib/cli.rb, line 263 def self.included(receiver) receiver.extend(Mixlib::CLI::ClassMethods) end
Create a new Mixlib::CLI class. If you override this, make sure you call super!
Parameters¶ ↑
- *args<Array>
-
The array of arguments passed to the initializer
Returns¶ ↑
- object<Mixlib::Config>
-
Returns an instance of whatever you wanted :)
# File lib/mixlib/cli.rb, line 145 def initialize(*args) @options = Hash.new @config = Hash.new @default_config = Hash.new @opt_parser = nil # Set the banner @banner = self.class.banner # Dupe the class options for this instance klass_options = self.class.options klass_options.keys.inject(@options) { |memo, key| memo[key] = klass_options[key].dup; memo } # If use_separate_defaults? is on, default values go in @default_config defaults_container = if self.class.use_separate_defaults? @default_config else @config end # Set the default configuration values for this instance @options.each do |config_key, config_opts| config_opts[:on] ||= :on config_opts[:boolean] ||= false config_opts[:required] ||= false config_opts[:proc] ||= nil config_opts[:show_options] ||= false config_opts[:exit] ||= nil if config_opts.has_key?(:default) defaults_container[config_key] = config_opts[:default] end end super(*args) end
Public Instance Methods
# File lib/mixlib/cli.rb, line 248 def build_option_arguments(opt_setting) arguments = Array.new arguments << opt_setting[:short] if opt_setting.has_key?(:short) arguments << opt_setting[:long] if opt_setting.has_key?(:long) if opt_setting.has_key?(:description) description = opt_setting[:description] description << " (required)" if opt_setting[:required] arguments << description end arguments end
The option parser generated from the mixlib-cli DSL.
opt_parser
can be used to print a help message including the
banner and any CLI options via `puts #opt_parser`.
Returns¶ ↑
- #opt_parser<OptionParser>
-
The option parser object.
# File lib/mixlib/cli.rb, line 213 def opt_parser @opt_parser ||= OptionParser.new do |opts| # Set the banner opts.banner = banner # Create new options options.sort { |a, b| a[0].to_s <=> b[0].to_s }.each do |opt_key, opt_val| opt_args = build_option_arguments(opt_val) opt_method = case opt_val[:on] when :on :on when :tail :on_tail when :head :on_head else raise ArgumentError, "You must pass :on, :tail, or :head to :on" end parse_block = Proc.new() do |c| config[opt_key] = (opt_val[:proc] && opt_val[:proc].call(c)) || c puts opts if opt_val[:show_options] exit opt_val[:exit] if opt_val[:exit] end full_opt = [ opt_method ] opt_args.inject(full_opt) { |memo, arg| memo << arg; memo } full_opt << parse_block opts.send(*full_opt) end end end
Parses an array, by default ARGV, for command line options (as configured at the class level).
Parameters¶ ↑
- argv<Array>
-
The array of arguments to parse; defaults to ARGV
Returns¶ ↑
- argv<Array>
-
Returns any un-parsed elements.
# File lib/mixlib/cli.rb, line 189 def parse_options(argv=ARGV) argv = argv.dup opt_parser.parse!(argv) # Deal with any required values options.each do |opt_key, opt_value| if opt_value[:required] && !config.has_key?(opt_key) reqarg = opt_value[:short] || opt_value[:long] puts "You must supply #{reqarg}!" puts @opt_parser exit 2 end end @cli_arguments = argv argv end