Mixlib::CLI

Project State: Active

Issues Response Time Maximum: 14 days

Pull Request Response Time Maximum: 14 days

Mixlib::CLI provides a class-based command line option parsing object, like the one used in Chef, Ohai and Relish. To use in your project:

require "mixlib/cli"

class MyCLI
  include Mixlib::CLI

  option :config_file,
    short: "-c CONFIG",
    long: "--config CONFIG",
    default: "config.rb",
    description: "The configuration file to use"

  option :log_level,
    short: "-l LEVEL",
    long: "--log_level LEVEL",
    description: "Set the log level (debug, info, warn, error, fatal)",
    required: true,
    in: [:debug, :info, :warn, :error, :fatal],
    proc: Proc.new { |l| l.to_sym }

  option :help,
    short: "-h",
    long: "--help",
    description: "Show this message",
    on: :tail,
    boolean: true,
    show_options: true,
    exit: 0

end

# ARGV = [ '-c', 'foo.rb', '-l', 'debug' ]
cli = MyCLI.new
cli.parse_options
cli.config[:config_file] # 'foo.rb'
cli.config[:log_level]   # :debug

If you are using this in conjunction with Mixlib::Config, you can do something like this (building on the above definition):

class MyConfig
  extend(Mixlib::Config)

  log_level   :info
  config_file "default.rb"
end

class MyCLI
  def run(argv = ARGV)
    parse_options(argv)
    MyConfig.merge!(config)
  end
end

c = MyCLI.new
# ARGV = [ '-l', 'debug' ]
c.run
MyConfig[:log_level] # :debug

For supported arguments to option, see the function documentation in lib/mixlib/cli.rb.

If you need access to the leftover options that aren't captured in the config, you can get at them through +cli_arguments+ (referring to the above definition of MyCLI).

# ARGV = [ '-c', 'foo.rb', '-l', 'debug', 'file1', 'file2', 'file3' ]
cli = MyCLI.new
cli.parse_options
cli.cli_arguments # [ 'file1', 'file2', 'file3' ]

Deprecating CLI Options

mixlib-cli 2.1.0 and later supports declaring options as deprecated. Using a deprecated option will result in a warning message being displayed. If a deprecated flag is supplied, its value is assigned to the replacement flag. You can control this assignment by specifying a value_mapper function in the arguments (see example below, and function docs)

Usage notes (see docs for arguments to Mixlib::CLI::ClassMethods#deprecated_option for more):

Define deprecated items last, after all non-deprecated items have been defined. You will see errors if your deprecated item references a replacement that hasn't been defined yet.
deprecated_option only takes a subset of 'option' configuration. You can only specify short, long - these should map to the short/long values of the option from before its deprecation.
- item description will automatically be generated along the lines of "-f/--flag is deprecated. Use -n/--new-flag instead."
- if the replacement argument is not given, item description will look like "-f/--flag is deprecated and will be removed in a future release"

Example

Given the following example:

# my_cli.rb

class MyCLI
  include Mixlib::CLI


  option :arg_not_required,
    description: "This takes no argument.",
    long: "--arg-not-required",
    short: "-n"

  option :arg_required,
    description: "This takes an argument.",
    long: "--arg-required ARG",
    short: "-a",
    in: ["a", "b", "c"]

  deprecated_option :dep_one,
    short: "-1",
    long: "--dep-one",
    # this deprecated option maps to the '--arg-not-required' option:
    replacement: :arg_not_required,
    # Do not keep 'dep_one' in `config` after parsing.
    keep: false

  deprecated_option :dep_two,
    short: "-2",
    long: "--dep-two ARG",
    replacement: :arg_required,
    # will map the  given value to a valid value for `--arg-required`.
    value_mapper: Proc.new { |arg|
      case arg
      when "q"; "invalid" # We'll use this to show validation still works
      when "z"; "a"
      when "x"; "b"
      else
        "c"
      end
    }

end

c = MyCLI.new()
c.parse_options

puts "arg_required: #{c.config[:arg_required]}" if c.config.key? :arg_required
puts "arg_not_required: #{c.config[:arg_not_required]}" if c.config.key? :arg_not_required
puts "dep_one: #{c.config[:dep_one]}" if c.config.key? :dep_one
puts "dep_two: #{c.config[:dep_two]}" if c.config.key? :dep_two

In this example, --dep-one will be used. Note that dep_one will not have a value of its own in options because keep: false was given to the deprecated option.

$ ruby my_cli.rb --dep-one

-1/--dep-one: This flag is deprecated. Use -n/--arg-not-required instead
arg_not_required: true

In this example, the value provided to dep-two will be converted to a value that --arg-required will accept,a nd populate :arg\_required with

$ ruby my_cli.rb --dep-two z # 'q' maps to 'invalid' in the value_mapper proc above

-2/--dep-two: This flag is deprecated. Use -a/--arg-required instead.

arg_required: a # The value is mapped to its replacement using the function provided.
dep_two: z  # the deprecated value is kept by default

In this example, the value provided to dep-two will be converted to a value that --arg-required will reject, showing how content rules are applied even when the input is coming from a deprecated option:

$ ruby my_cli.rb --dep-two q

-2/--dep-two: This flag is deprecated. Use -a/--arg-required instead.
-a/--arg-required: invalid is not one of the allowed values: 'a', 'b', or 'c'

Documentation

Class and module documentation is maintained using YARD. You can generate it by running:

rake docs

You can serve them locally with live refresh using:

bundle exec yard server --reload

Contributing

For information on contributing to this project please see our Contributing Documentation

License & Copyright

License:: Apache License, Version 2.0