class Optimist::Option

Attributes

default[RW]
long[RW]
multi_given[W]
name[RW]
permitted[RW]
permitted_response[RW]
short[RW]

Public Class Methods

create(name, desc="", opts={}, settings={}) click to toggle source

Determines which type of object to create based on arguments passed to Optimist::opt. This is trickier in Optimist, than other cmdline parsers (e.g. Slop) because we allow the default: to be able to set the option's type.

# File lib/optimist.rb, line 926
def self.create(name, desc="", opts={}, settings={})

  opttype = Optimist::Parser.registry_getopttype(opts[:type])
  opttype_from_default = get_klass_from_default(opts, opttype)

  raise ArgumentError, ":type specification and default type don't match (default type is #{opttype_from_default.class})" if opttype && opttype_from_default && (opttype.class != opttype_from_default.class)

  opt_inst = (opttype || opttype_from_default || Optimist::BooleanOption.new)

  ## fill in :long
  opt_inst.long.set(name, opts[:long], opts[:alt])

  ## fill in :short
  opt_inst.short.add opts[:short]

  ## fill in :multi
  multi_given = opts[:multi] || false
  opt_inst.multi_given = multi_given

  ## 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
  opt_inst
end
new() click to toggle source
# File lib/optimist.rb, line 770
def initialize
  @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
register_alias(*alias_keys) click to toggle source

Provide a way to register symbol aliases to the Parser

# File lib/optimist.rb, line 913
def self.register_alias(*alias_keys)
  alias_keys.each do |alias_key|
    # pass in the alias-key and the class
    Parser.register(alias_key, self)
  end
end

Private Class Methods

get_klass_from_default(opts, opttype) click to toggle source
# File lib/optimist.rb, line 976
def self.get_klass_from_default(opts, opttype)
  ## for options with :multi => true, an array default doesn't imply
  ## a multi-valued argument. for that you have to specify a :type
  ## as well. (this is how we disambiguate an ambiguous situation;
  ## see the docs for Parser#opt for details.)

  disambiguated_default = if opts[:multi] && opts[:default].is_a?(Array) && opttype.nil?
                            opts[:default].first
                          else
                            opts[:default]
                          end

  return nil if disambiguated_default.nil?
  type_from_default = get_type_from_disdef(opts[:default], opttype, disambiguated_default)
  return Optimist::Parser.registry_getopttype(type_from_default)
end
get_type_from_disdef(optdef, opttype, disambiguated_default) click to toggle source
# File lib/optimist.rb, line 963
def self.get_type_from_disdef(optdef, opttype, disambiguated_default)
  if disambiguated_default.is_a? Array
    return(optdef.first.class.name.downcase + "s") if !optdef.empty?
    if opttype
      raise ArgumentError, "multiple argument type must be plural" unless opttype.multi_arg?
      return nil
    else
      raise ArgumentError, "multiple argument type cannot be deduced from an empty array"
    end
  end
  return disambiguated_default.class.name.downcase
end

Public Instance Methods

array_default?() click to toggle source

note: Option-Types with both multi_arg? and flag? false are single-parameter (normal) options.

# File lib/optimist.rb, line 803
def array_default? ; self.default.kind_of?(Array) ; end
callback() click to toggle source
# File lib/optimist.rb, line 807
def callback ; opts(:callback) ; end
desc() click to toggle source
# File lib/optimist.rb, line 808
def desc ; opts(:desc) ; end
doesnt_need_autogen_short() click to toggle source
# File lib/optimist.rb, line 805
def doesnt_need_autogen_short ; !short.auto || short.chars.any? ; end
educate() click to toggle source
# File lib/optimist.rb, line 819
def educate
  optionlist = []
  optionlist.concat(short.chars.map { |o| "-#{o}" })
  optionlist.concat(long.names.map { |o| "--#{o}" })
  optionlist.compact.join(', ') + type_format + (flag? && default ? ", --no-#{long.long}" : "")
end
flag?() click to toggle source

Indicates a flag option, which is an option without an argument

# File lib/optimist.rb, line 791
def flag? ; false ; end
format_stdio(obj) click to toggle source

Format stdio like objects to a string

# File lib/optimist.rb, line 835
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
full_description() click to toggle source

Format the educate-line description including the default and permitted value(s)

# File lib/optimist.rb, line 827
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
multi() click to toggle source
# File lib/optimist.rb, line 796
def multi ; @multi_given ; end
Also aliased as: multi?
multi?()
Alias for: multi
multi_arg?() click to toggle source

Indicates that this is a multivalued (Array type) argument

# File lib/optimist.rb, line 800
def multi_arg? ; false ; end
opts(key) click to toggle source
# File lib/optimist.rb, line 782
def opts(key)
  @optshash[key]
end
opts=(o) click to toggle source
# File lib/optimist.rb, line 786
def opts=(o)
  @optshash = o
end
parse(_paramlist, _neg_given) click to toggle source
# File lib/optimist.rb, line 812
def parse(_paramlist, _neg_given)
  raise NotImplementedError, "parse must be overridden for newly registered type"
end
permitted_type_valid?() click to toggle source
# File lib/optimist.rb, line 868
def permitted_type_valid?
  case permitted
  when NilClass, Array, Range, Regexp then true
  else false
  end
end
permitted_valid_string() click to toggle source
# File lib/optimist.rb, line 856
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
permitted_value?(val) click to toggle source

incoming values from the command-line should be strings, so we should stringify any permitted types as the basis of comparison.

# File lib/optimist.rb, line 886
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
required?() click to toggle source
# File lib/optimist.rb, line 810
def required? ; opts(:required) ; end
single_arg?() click to toggle source
# File lib/optimist.rb, line 792
def single_arg?
  !self.multi_arg? && !self.flag?
end
type_format() click to toggle source

provide type-format string. default to empty, but user should probably override it

# File lib/optimist.rb, line 817
def type_format ; "" ; end
validate_permitted(arg, value) click to toggle source
# File lib/optimist.rb, line 875
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

Private Instance Methods

default_description_str(str) click to toggle source

Generate the default value string for the educate line

# File lib/optimist.rb, line 845
        def default_description_str str
  default_s = case default
              when Array
                default.join(', ')
              else
                format_stdio(default).to_s
              end
  defword = str.end_with?('.') ? 'Default' : 'default'
  " (#{defword}: #{default_s})"
end
permitted_description_str(str) click to toggle source

Generate the permitted values string for the educate line

# File lib/optimist.rb, line 897
        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