Module: Mixlib::CLI

Defined in:
lib/mixlib/cli.rb,
lib/mixlib/cli/version.rb

Overview

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.

Defined Under Namespace

Modules: ClassMethods

Constant Summary collapse

VERSION = 
"1.5.0"

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Instance Attribute Details

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.



136
137
138
 
# File 'lib/mixlib/cli.rb', line 136

def banner
  @banner
end

#cli_arguments ⇒ Object

Any arguments which were not parsed and placed in “config”–the leftovers.



132
133
134
 
# File 'lib/mixlib/cli.rb', line 132

def cli_arguments
  @cli_arguments
end

#config ⇒ Object

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.



121
122
123
 
# File 'lib/mixlib/cli.rb', line 121

def config
  @config
end

#default_config ⇒ Object

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.



129
130
131
 
# File 'lib/mixlib/cli.rb', line 129

def default_config
  @default_config
end

#options ⇒ Object

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.



108
109
110
 
# File 'lib/mixlib/cli.rb', line 108

def options
  @options
end

Class Method Details

.included(receiver) ⇒ Object 



263
264
265
 
# File 'lib/mixlib/cli.rb', line 263

def self.included(receiver)
  receiver.extend(Mixlib::CLI::ClassMethods)
end

Instance Method Details

#build_option_arguments(opt_setting) ⇒ Object 



248
249
250
251
252
253
254
255
256
257
258
259
260
261
 
# 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

#initialize(*args) ⇒ Object

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 :)



145
146
147
148
149
150
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
179
180
 
# 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

#opt_parser ⇒ Object

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.



213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
 
# 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) ⇒ Object

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.



189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
 
# 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