class Optimist::Option
Attributes
Public Class Methods
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
# 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
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
# 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
# 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
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
# File lib/optimist.rb, line 807 def callback ; opts(:callback) ; end
# File lib/optimist.rb, line 808 def desc ; opts(:desc) ; end
# File lib/optimist.rb, line 805 def doesnt_need_autogen_short ; !short.auto || short.chars.any? ; end
# 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}" : "") end
Indicates a flag option, which is an option without an argument
# File lib/optimist.rb, line 791 def flag? ; false ; end
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
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
# File lib/optimist.rb, line 796 def multi ; @multi_given ; end
Indicates that this is a multivalued (Array type) argument
# File lib/optimist.rb, line 800 def multi_arg? ; false ; end
# File lib/optimist.rb, line 782 def opts(key) @optshash[key] end
# File lib/optimist.rb, line 786 def opts=(o) @optshash = o end
# File lib/optimist.rb, line 812 def parse(_paramlist, _neg_given) raise NotImplementedError, "parse must be overridden for newly registered type" end
# File lib/optimist.rb, line 868 def permitted_type_valid? case permitted when NilClass, Array, Range, Regexp then true else false end end
# 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
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
# File lib/optimist.rb, line 810 def required? ; opts(:required) ; end
# File lib/optimist.rb, line 792 def single_arg? !self.multi_arg? && !self.flag? end
provide type-format string. default to empty, but user should probably override it
# File lib/optimist.rb, line 817 def type_format ; "" ; end
# 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
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
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