Module: Mixlib::CLI

### Home Classes Methods

### In Files

- lib/mixlib/cli/version.rb
- lib/mixlib/cli.rb

### Namespace

- MODULE Mixlib::CLI::ClassMethods

### Methods

- ::included
- ::new
- #build_option_arguments
- #opt_parser
- #parse_options

### Files

- LICENSE
- NOTICE
- README.rdoc

### Class/Module Index

Quicksearch

- Mixlib
- Mixlib::CLI
- Mixlib::CLI::ClassMethods

No matching classes.

# 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 ClassMethods#option, which defines a command line option, and 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

banner[RW]

Banner for the option parser. If the option parser is printed, e.g., by `puts opt_parser`, this string will be used as the first line.

cli_arguments[RW]

Any arguments which were not parsed and placed in "config"--the leftovers.

config[RW]

A Hash containing the values supplied by command line options.

The behavior and contents of this Hash vary depending on whether 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.

default_config[RW]

If 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.

options[RW]

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

included(receiver) click to toggle source

    # File lib/mixlib/cli.rb, line 263
    def self.included(receiver)
      receiver.extend(Mixlib::CLI::ClassMethods)
    end

new(*args) click to toggle source

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

build_option_arguments(opt_setting) click to toggle source

    # 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

opt_parser() click to toggle source

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

parse_options(argv=ARGV) click to toggle source

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

[Validate]

Generated with the Darkfish Rdoc Generator 2.