optimist 3.0.1 → 3.2.0

data/lib/optimist.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # lib/optimist.rb -- optimist command-line processing library
 # Copyright (c) 2008-2014 William Morgan.
 # Copyright (c) 2014 Red Hat, Inc.
@@ -6,9 +8,7 @@
 require 'date'
 
 module Optimist
-  # note: this is duplicated in gemspec
-  # please change over there too
-VERSION = "3.0.1"
+VERSION = "3.2.0"
 
 ## Thrown by Parser in the event of a commandline error. Not needed if
 ## you're using the Optimist::options entry.
@@ -37,6 +37,50 @@ FLOAT_RE = /^-?((\d+(\.\d+)?)|(\.\d+))([eE][-+]?[\d]+)?$/
 ## Regex for parameters
 PARAM_RE = /^-(-|\.$|[^\d\.])/
 
+# Abstract class for a constraint.  Do not use by itself.
+class Constraint
+  def initialize(syms)
+    @idents = syms
+  end
+  def validate(given_args:, specs:)
+    overlap = @idents & given_args.keys
+    if error_condition(overlap.size)
+      longargs = @idents.map { |sym| "--#{specs[sym].long.long}" }
+      raise CommandlineError, error_message(longargs)
+    end
+  end
+end
+
+# A Dependency constraint.  Useful when Option A requires Option B also be used.
+class DependConstraint < Constraint
+  def error_condition(overlap_size)
+    (overlap_size != 0) && (overlap_size != @idents.size)
+  end
+  def error_message(longargs)
+    "#{longargs.join(', ')} have a dependency and must be given together"
+  end
+end
+
+# A Conflict constraint.  Useful when Option A cannot be used with Option B.
+class ConflictConstraint < Constraint
+  def error_condition(overlap_size)
+    (overlap_size != 0) && (overlap_size != 1)
+  end
+  def error_message(longargs)
+    "only one of #{longargs.join(', ')} can be given"
+  end
+end
+
+# An Either-Or constraint. For Mutually exclusive options
+class EitherConstraint < Constraint
+  def error_condition(overlap_size)
+    overlap_size != 1
+  end
+  def error_message(longargs)
+    "one and only one of #{longargs.join(', ')} is required"
+  end
+end
+
 ## The commandline parser. In typical usage, the methods in this class
 ## will be handled internally by Optimist::options. In this case, only the
 ## #opt, #banner and #version, #depends, and #conflicts methods will
@@ -70,8 +114,6 @@ class Parser
     return @registry[lookup].new
   end
 
-  INVALID_SHORT_ARG_REGEX = /[\d-]/ #:nodoc:
-
   ## The values from the commandline that were not interpreted by #parse.
   attr_reader :leftovers
 
@@ -84,6 +126,12 @@ class Parser
   ##  ignore options that it does not recognize.
   attr_accessor :ignore_invalid_options
 
+  DEFAULT_SETTINGS = {
+    exact_match: true,
+    implicit_short_opts: true,
+    suggestions: true
+  }
+
   ## Initializes the parser, and instance-evaluates any block given.
   def initialize(*a, &b)
     @version = nil
@@ -99,8 +147,17 @@ class Parser
     @synopsis = nil
     @usage = nil
 
-    # instance_eval(&b) if b # can't take arguments
-    cloaker(&b).bind(self).call(*a) if b
+    ## allow passing settings through Parser.new as an optional hash.
+    ## but keep compatibility with non-hashy args, though.
+    begin
+      settings_hash = Hash[*a]
+      @settings = DEFAULT_SETTINGS.merge(settings_hash)
+      a=[] ## clear out args if using as settings-hash
+    rescue ArgumentError
+      @settings = DEFAULT_SETTINGS
+    end
+
+    self.instance_exec(*a, &b) if block_given?
   end
 
   ## Define an option. +name+ is the option name, a unique identifier
@@ -116,6 +173,7 @@ class Parser
   ## [+:default+] Set the default value for an argument. Without a default value, the hash returned by #parse (and thus Optimist::options) will have a +nil+ value for this key unless the argument is given on the commandline. The argument type is derived automatically from the class of the default value given, so specifying a +:type+ is not necessary if a +:default+ is given. (But see below for an important caveat when +:multi+: is specified too.) If the argument is a flag, and the default is set to +true+, then if it is specified on the the commandline the value will be +false+.
   ## [+:required+] If set to +true+, the argument must be provided on the commandline.
   ## [+:multi+] If set to +true+, allows multiple occurrences of the option on the commandline. Otherwise, only a single instance of the option is allowed. (Note that this is different from taking multiple parameters. See below.)
+  ## [+:permitted+] Specify an Array of permitted values for an option. If the user provides a value outside this list, an error is thrown.
   ##
   ## Note that there are two types of argument multiplicity: an argument
   ## can take multiple values, e.g. "--arg 1 2 3". An argument can also
@@ -150,10 +208,19 @@ class Parser
     o = Option.create(name, desc, opts)
 
     raise ArgumentError, "you already have an argument named '#{name}'" if @specs.member? o.name
-    raise ArgumentError, "long option name #{o.long.inspect} is already taken; please specify a (different) :long" if @long[o.long]
-    raise ArgumentError, "short option name #{o.short.inspect} is already taken; please specify a (different) :short" if @short[o.short]
-    @long[o.long] = o.name
-    @short[o.short] = o.name if o.short?
+    
+    o.long.names.each do |lng|
+      raise ArgumentError, "long option name #{lng.inspect} is already taken; please specify a (different) :long/:alt" if @long[lng]
+      @long[lng] = o.name
+    end
+
+    o.short.chars.each do |short|
+      raise ArgumentError, "short option name #{short.inspect} is already taken; please specify a (different) :short" if @short[short]
+      @short[short] = o.name
+    end
+
+    raise ArgumentError, "permitted values for option #{o.long.long.inspect} must be either nil, Range, Regexp or an Array;" unless o.permitted_type_valid?
+
     @specs[o.name] = o
     @order << [:opt, o.name]
   end
@@ -190,13 +257,19 @@ class Parser
   ## better modeled with Optimist::die.
   def depends(*syms)
     syms.each { |sym| raise ArgumentError, "unknown option '#{sym}'" unless @specs[sym] }
-    @constraints << [:depends, syms]
+    @constraints << DependConstraint.new(syms)
   end
 
   ## Marks two (or more!) options as conflicting.
   def conflicts(*syms)
     syms.each { |sym| raise ArgumentError, "unknown option '#{sym}'" unless @specs[sym] }
-    @constraints << [:conflicts, syms]
+    @constraints << ConflictConstraint.new(syms)
+  end
+
+  ## Marks two (or more!) options as required but mutually exclusive.
+  def either(*syms)
+    syms.each { |sym| raise ArgumentError, "unknown option '#{sym}'" unless @specs[sym] }
+    @constraints << EitherConstraint.new(syms)
   end
 
   ## Defines a set of words which cause parsing to terminate when
@@ -226,6 +299,56 @@ class Parser
     @educate_on_error = true
   end
 
+  ## Match long variables with inexact match.
+  ## If we hit a complete match, then use that, otherwise see how many long-options partially match.
+  ## If only one partially matches, then we can safely use that.
+  ## Otherwise, we raise an error that the partially given option was ambiguous.
+  def perform_inexact_match(arg, partial_match)  # :nodoc:
+    return @long[partial_match] if @long.has_key?(partial_match)
+    partially_matched_keys = @long.keys.select { |opt| opt.start_with?(partial_match) }
+    case partially_matched_keys.size
+    when 0 ; nil
+    when 1 ; @long[partially_matched_keys.first]
+    else ; raise CommandlineError, "ambiguous option '#{arg}' matched keys (#{partially_matched_keys.join(',')})"
+    end
+  end
+  private :perform_inexact_match
+
+  def handle_unknown_argument(arg, candidates, suggestions)
+    errstring = "unknown argument '#{arg}'"
+    if (suggestions &&
+      Module::const_defined?("DidYouMean") &&
+      Module::const_defined?("DidYouMean::JaroWinkler") &&
+      Module::const_defined?("DidYouMean::Levenshtein"))
+      input = arg.sub(/^[-]*/,'')
+
+      # Code borrowed from did_you_mean gem
+      jw_threshold = 0.75
+      seed = candidates.select {|candidate| DidYouMean::JaroWinkler.distance(candidate, input) >= jw_threshold } \
+               .sort_by! {|candidate| DidYouMean::JaroWinkler.distance(candidate.to_s, input) } \
+               .reverse!
+      # Correct mistypes
+      threshold   = (input.length * 0.25).ceil
+      has_mistype = seed.rindex {|c| DidYouMean::Levenshtein.distance(c, input) <= threshold }
+      corrections = if has_mistype
+                      seed.take(has_mistype + 1)
+                    else
+                      # Correct misspells
+                      seed.select do |candidate|
+                        length    = input.length < candidate.length ? input.length : candidate.length
+
+                        DidYouMean::Levenshtein.distance(candidate, input) < length
+                      end.first(1)
+                    end
+      unless corrections.empty?
+        dashdash_corrections = corrections.map{|s| "--#{s}" }
+        errstring += ".  Did you mean: [#{dashdash_corrections.join(', ')}] ?"
+      end
+    end
+    raise CommandlineError, errstring
+  end
+  private :handle_unknown_argument
+
   ## Parses the commandline. Typically called by Optimist::options,
   ## but you can call it directly if you need more control.
   ##
@@ -243,7 +366,7 @@ class Parser
       vals[sym] = [] if opts.multi && !opts.default # multi arguments default to [], not nil
     end
 
-    resolve_default_short_options!
+    resolve_default_short_options! if @settings[:implicit_short_opts]
 
     ## resolve symbols
     given_args = {}
@@ -261,10 +384,15 @@ class Parser
         else                       raise CommandlineError, "invalid argument syntax: '#{arg}'"
       end
 
-      sym = nil if arg =~ /--no-/ # explicitly invalidate --no-no- arguments
+      if arg.start_with?("--no-") # explicitly invalidate --no-no- arguments
+        sym = nil
+      ## Support inexact matching of long-arguments like perl's Getopt::Long
+      elsif !sym && !@settings[:exact_match] && arg.match(/^--(\S+)$/)
+        sym = perform_inexact_match(arg, $1)
+      end
 
       next nil if ignore_invalid_options && !sym
-      raise CommandlineError, "unknown argument '#{arg}'" unless sym
+      handle_unknown_argument(arg, @long.keys, @settings[:suggestions]) unless sym
 
       if given_args.include?(sym) && !@specs[sym].multi?
         raise CommandlineError, "option '#{arg}' specified multiple times"
@@ -296,20 +424,12 @@ class Parser
     raise HelpNeeded if given_args.include? :help
 
     ## check constraint satisfaction
-    @constraints.each do |type, syms|
-      constraint_sym = syms.find { |sym| given_args[sym] }
-      next unless constraint_sym
-
-      case type
-      when :depends
-        syms.each { |sym| raise CommandlineError, "--#{@specs[constraint_sym].long} requires --#{@specs[sym].long}" unless given_args.include? sym }
-      when :conflicts
-        syms.each { |sym| raise CommandlineError, "--#{@specs[constraint_sym].long} conflicts with --#{@specs[sym].long}" if given_args.include?(sym) && (sym != constraint_sym) }
-      end
+    @constraints.each do |const|
+      const.validate(given_args: given_args, specs: @specs)
     end
 
     required.each do |sym, val|
-      raise CommandlineError, "option --#{@specs[sym].long} must be specified" unless given_args.include? sym
+      raise CommandlineError, "option --#{@specs[sym].long.long} must be specified" unless given_args.include? sym
     end
 
     ## parse parameters
@@ -322,6 +442,12 @@ class Parser
         params << (opts.array_default? ? opts.default.clone : [opts.default])
       end
 
+      if params.first && opts.permitted
+        params.first.each do |val|
+          opts.validate_permitted(arg, val)
+        end
+      end
+
       vals["#{sym}_given".intern] = true # mark argument as specified on the commandline
 
       vals[sym] = opts.parse(params, negative_given)
@@ -382,7 +508,7 @@ class Parser
 
       spec = @specs[opt]
       stream.printf "  %-#{leftcol_width}s    ", left[opt]
-      desc = spec.description_with_default
+      desc = spec.full_description
 
       stream.puts wrap(desc, :width => width - rightcol_start - 1, :prefix => rightcol_start)
     end
@@ -427,7 +553,7 @@ class Parser
   def die(arg, msg = nil, error_code = nil)
     msg, error_code = nil, msg if msg.kind_of?(Integer)
     if msg
-      $stderr.puts "Error: argument --#{@specs[arg].long} #{msg}."
+      $stderr.puts "Error: argument --#{@specs[arg].long.long} #{msg}."
     else
       $stderr.puts "Error: #{arg}."
     end
@@ -450,7 +576,7 @@ private
     until i >= args.length
       return remains += args[i..-1] if @stop_words.member? args[i]
       case args[i]
-      when /^--$/ # arg terminator
+      when "--" # arg terminator
         return remains += args[(i + 1)..-1]
       when /^--(\S+?)=(.*)$/ # long argument with equals
         num_params_taken = yield "--#{$1}", [$2]
@@ -475,7 +601,7 @@ private
         end
         i += 1
       when /^-(\S+)$/ # one or more short arguments
-        short_remaining = ""
+        short_remaining = []
         shortargs = $1.split(//)
         shortargs.each_with_index do |a, j|
           if j == (shortargs.length - 1)
@@ -485,7 +611,7 @@ private
             unless num_params_taken
               short_remaining << a
               if @stop_on_unknown
-                remains << "-#{short_remaining}"
+                remains << "-#{short_remaining.join}"
                 return remains += args[i + 1..-1]
               end
             else
@@ -495,8 +621,8 @@ private
             unless yield "-#{a}", []
               short_remaining << a
               if @stop_on_unknown
-                short_remaining += shortargs[j + 1..-1].join
-                remains << "-#{short_remaining}"
+                short_remaining << shortargs[j + 1..-1].join
+                remains << "-#{short_remaining.join}"
                 return remains += args[i + 1..-1]
               end
             end
@@ -504,7 +630,7 @@ private
         end
 
         unless short_remaining.empty?
-          remains << "-#{short_remaining}"
+          remains << "-#{short_remaining.join}"
         end
         i += 1
       else
@@ -533,11 +659,10 @@ private
   def resolve_default_short_options!
     @order.each do |type, name|
       opts = @specs[name]
-      next if type != :opt || opts.short
-
-      c = opts.long.split(//).find { |d| d !~ INVALID_SHORT_ARG_REGEX && !@short.member?(d) }
+      next if type != :opt || opts.doesnt_need_autogen_short
+      c = opts.long.long.split(//).find { |d| d !~ Optimist::ShortNames::INVALID_ARG_REGEX && !@short.member?(d) }
       if c # found a character to use
-        opts.short = c
+        opts.short.add c
         @short[c] = name
       end
     end
@@ -563,30 +688,94 @@ private
     ret
   end
 
-  ## instance_eval but with ability to handle block arguments
-  ## thanks to _why: http://redhanded.hobix.com/inspect/aBlockCostume.html
-  def cloaker(&b)
-    (class << self; self; end).class_eval do
-      define_method :cloaker_, &b
-      meth = instance_method :cloaker_
-      remove_method :cloaker_
-      meth
+end
+
+class LongNames
+  def initialize
+    @truename = nil
+    @long = nil
+    @alts = []
+  end
+
+  def make_valid(lopt)
+    return nil if lopt.nil?
+    case lopt.to_s
+    when /^--([^-].*)$/ then $1
+    when /^[^-]/        then lopt.to_s
+    else                     raise ArgumentError, "invalid long option name #{lopt.inspect}"
+    end
+  end
+
+  def set(name, lopt, alts)
+    @truename = name
+    lopt = lopt ? lopt.to_s : name.to_s.gsub("_", "-")
+    @long = make_valid(lopt)
+    alts = [alts] unless alts.is_a?(Array) # box the value
+    @alts = alts.map { |alt| make_valid(alt) }.compact
+  end
+
+  # long specified with :long has precedence over the true-name
+  def long ; @long || @truename ; end
+
+  # all valid names, including alts
+  def names
+    [long] + @alts
+  end
+
+end
+
+class ShortNames
+
+  INVALID_ARG_REGEX = /[\d-]/ #:nodoc:
+
+  def initialize
+    @chars = []
+    @auto = true
+  end
+
+  attr_reader :chars, :auto
+
+  def add(values)
+    values = [values] unless values.is_a?(Array) # box the value
+    values = values.compact
+    if values.include?(:none)
+      if values.size == 1
+        @auto = false
+        return
+      end
+      raise ArgumentError, "Cannot use :none with any other values in short option: #{values.inspect}"
+    end
+    values.each do |val|
+      strval = val.to_s
+      sopt = case strval
+             when /^-(.)$/ then $1
+             when /^.$/ then strval
+             else raise ArgumentError, "invalid short option name '#{val.inspect}'"
+             end
+
+      if sopt =~ INVALID_ARG_REGEX
+        raise ArgumentError, "short option name '#{sopt}' can't be a number or a dash" 
+      end
+      @chars << sopt
     end
   end
+
 end
 
 class Option
 
-  attr_accessor :name, :short, :long, :default
+  attr_accessor :name, :short, :long, :default, :permitted, :permitted_response
   attr_writer :multi_given
 
   def initialize
-    @long = nil
-    @short = nil
+    @long = LongNames.new
+    @short = ShortNames.new # can be an Array of one-char strings, a one-char String, nil or :none
     @name = nil
     @multi_given = false
     @hidden = false
     @default = nil
+    @permitted = nil
+    @permitted_response = "option '%{arg}' only accepts %{valid_string}"
     @optshash = Hash.new()
   end
 
@@ -613,7 +802,7 @@ class Option
 
   def array_default? ; self.default.kind_of?(Array) ; end
 
-  def short? ; short && short != :none ; end
+  def doesnt_need_autogen_short ; !short.auto || short.chars.any? ; end
 
   def callback ; opts(:callback) ; end
   def desc ; opts(:desc) ; end
@@ -628,23 +817,96 @@ class Option
   def type_format ; "" ; end
 
   def educate
-    (short? ? "-#{short}, " : "") + "--#{long}" + type_format + (flag? && default ? ", --no-#{long}" : "")
+    optionlist = []
+    optionlist.concat(short.chars.map { |o| "-#{o}" })
+    optionlist.concat(long.names.map { |o| "--#{o}" })
+    optionlist.compact.join(', ') + type_format + (flag? && default ? ", --no-#{long}" : "")
+  end
+
+  ## Format the educate-line description including the default and permitted value(s)
+  def full_description
+    desc_str = desc
+    desc_str += default_description_str(desc) if default
+    desc_str += permitted_description_str(desc) if permitted
+    desc_str
+  end
+
+  ## Format stdio like objects to a string
+  def format_stdio(obj)
+    case obj
+    when $stdout   then '<stdout>'
+    when $stdin    then '<stdin>'
+    when $stderr   then '<stderr>'
+    else obj # pass-through-case
+    end
   end
 
-  ## Format the educate-line description including the default-value(s)
-  def description_with_default
-    return desc unless default
+  ## Generate the default value string for the educate line
+  private def default_description_str str
     default_s = case default
-                when $stdout   then '<stdout>'
-                when $stdin    then '<stdin>'
-                when $stderr   then '<stderr>'
                 when Array
                   default.join(', ')
                 else
-                  default.to_s
+                  format_stdio(default).to_s
                 end
-    defword = desc.end_with?('.') ? 'Default' : 'default'
-    return "#{desc} (#{defword}: #{default_s})"
+    defword = str.end_with?('.') ? 'Default' : 'default'
+    " (#{defword}: #{default_s})"
+  end
+
+  def permitted_valid_string
+    case permitted
+    when Array
+      return "one of: " + permitted.to_a.map(&:to_s).join(', ')
+    when Range
+      return "value in range of: #{permitted}"
+    when Regexp
+      return "value matching: #{permitted.inspect}"
+    end
+    raise NotImplementedError, "invalid branch"
+  end
+
+  def permitted_type_valid?
+    case permitted
+    when NilClass, Array, Range, Regexp then true
+    else false
+    end
+  end
+
+  def validate_permitted(arg, value)
+    return true if permitted.nil?
+    unless permitted_value?(value)
+      format_hash = {arg: arg, given: value, value: value, valid_string: permitted_valid_string(), permitted: permitted }
+      raise CommandlineError, permitted_response % format_hash
+    end
+    true
+  end
+  
+  # incoming values from the command-line should be strings, so we should
+  # stringify any permitted types as the basis of comparison.
+  def permitted_value?(val)
+    case permitted
+    when nil then true
+    when Regexp then val.match? permitted
+    when Range then permitted.include? as_type(val)
+    when Array then permitted.map(&:to_s).include? val
+    else false
+    end
+  end
+
+  ## Generate the permitted values string for the educate line
+  private def permitted_description_str str
+    permitted_s = case permitted
+                  when Array
+                    permitted.map do |p|
+                      format_stdio(p).to_s
+                    end.join(', ')
+                  when Range, Regexp
+                    permitted.inspect
+                  else
+                    raise NotImplementedError
+                  end
+    permword = str.end_with?('.') ? 'Permitted' : 'permitted'
+    " (#{permword}: #{permitted_s})"
   end
 
   ## Provide a way to register symbol aliases to the Parser
@@ -671,10 +933,10 @@ class Option
     opt_inst = (opttype || opttype_from_default || Optimist::BooleanOption.new)
 
     ## fill in :long
-    opt_inst.long = handle_long_opt(opts[:long], name)
+    opt_inst.long.set(name, opts[:long], opts[:alt])
 
     ## fill in :short
-    opt_inst.short = handle_short_opt(opts[:short])
+    opt_inst.short.add opts[:short]
 
     ## fill in :multi
     multi_given = opts[:multi] || false
@@ -683,8 +945,13 @@ class Option
     ## fill in :default for flags
     defvalue = opts[:default] || opt_inst.default
 
+    ## fill in permitted values
+    permitted = opts[:permitted] || nil
+
     ## autobox :default for :multi (multi-occurrence) arguments
     defvalue = [defvalue] if defvalue && multi_given && !defvalue.kind_of?(Array)
+    opt_inst.permitted = permitted
+    opt_inst.permitted_response = opts[:permitted_response] if opts[:permitted_response]
     opt_inst.default = defvalue
     opt_inst.name = name
     opt_inst.opts = opts
@@ -723,29 +990,6 @@ class Option
     return Optimist::Parser.registry_getopttype(type_from_default)
   end
 
-  def self.handle_long_opt(lopt, name)
-    lopt = lopt ? lopt.to_s : name.to_s.gsub("_", "-")
-    lopt = case lopt
-           when /^--([^-].*)$/ then $1
-           when /^[^-]/        then lopt
-           else                     raise ArgumentError, "invalid long option name #{lopt.inspect}"
-           end
-  end
-
-  def self.handle_short_opt(sopt)
-    sopt = sopt.to_s if sopt && sopt != :none
-    sopt = case sopt
-           when /^-(.)$/          then $1
-           when nil, :none, /^.$/ then sopt
-           else                   raise ArgumentError, "invalid short option name '#{sopt.inspect}'"
-           end
-
-    if sopt
-      raise ArgumentError, "a short option name can't be a number or a dash" if sopt =~ ::Optimist::Parser::INVALID_SHORT_ARG_REGEX
-    end
-    return sopt
-  end
-
 end
 
 # Flag option.  Has no arguments. Can be negated with "no-".
@@ -765,11 +1009,12 @@ end
 class FloatOption < Option
   register_alias :float, :double
   def type_format ; "=<f>" ; end
+  def as_type(param) ; param.to_f ; end
   def parse(paramlist, _neg_given)
     paramlist.map do |pg|
       pg.map do |param|
         raise CommandlineError, "option '#{self.name}' needs a floating-point number" unless param.is_a?(Numeric) || param =~ FLOAT_RE
-        param.to_f
+        as_type(param)
       end
     end
   end
@@ -779,11 +1024,12 @@ end
 class IntegerOption < Option
   register_alias :int, :integer, :fixnum
   def type_format ; "=<i>" ; end
+  def as_type(param) ; param.to_i ; end
   def parse(paramlist, _neg_given)
     paramlist.map do |pg|
       pg.map do |param|
         raise CommandlineError, "option '#{self.name}' needs an integer" unless param.is_a?(Numeric) || param =~ /^-?[\d_]+$/
-        param.to_i
+        as_type(param)
       end
     end
   end
@@ -816,9 +1062,10 @@ end
 # Option class for handling Strings.
 class StringOption < Option
   register_alias :string
+  def as_type(val) ; val.to_s ; end
   def type_format ; "=<s>" ; end
   def parse(paramlist, _neg_given)
-    paramlist.map { |pg| pg.map(&:to_s) }
+    paramlist.map { |pg| pg.map { |param| as_type(param) } }
   end
 end
 
@@ -916,7 +1163,22 @@ end
 ##   ## if called with --monkey
 ##   p opts # => {:monkey=>true, :name=>nil, :num_limbs=>4, :help=>false, :monkey_given=>true}
 ##
-## See more examples at http://optimist.rubyforge.org.
+## Settings:
+##   Optimist::options and Optimist::Parser.new accept +settings+ to control how
+##   options are interpreted.  These settings are given as hash arguments, e.g:
+##
+##   opts = Optimist::options(ARGV, exact_match: false) do
+##     opt :foobar, 'messed up'
+##     opt :forget, 'forget it'
+##   end
+##
+##  +settings+ include:
+##  * :exact_match  : (default=true) Allow minimum unambigous number of characters to match a long option
+##  * :suggestions  : (default=true) Enables suggestions when unknown arguments are given and DidYouMean is installed.  DidYouMean comes standard with Ruby 2.3+
+##  * :implicit_short_opts : (default=true) Short options will only be created where explicitly defined.  If you do not like short-options, this will prevent having to define :short=> :none for all of your options.
+##  Because Optimist::options uses a default argument for +args+, you must pass that argument when using the settings feature.
+##
+## See more examples at https://www.manageiq.org/optimist
 def options(args = ARGV, *a, &b)
   @last_parser = Parser.new(*a, &b)
   with_standard_exception_handling(@last_parser) { @last_parser.parse args }