Class: OptimistXL::Option

Inherits:
Object
  • Object
show all
Defined in:
lib/optimist_xl.rb

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Option

Returns a new instance of Option.



866
867
868
869
870
871
872
873
874
875
876
877
878
879
 
# File 'lib/optimist_xl.rb', line 866

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()
  @min_args = 1
  @max_args = 1
  # maximum max_args is likely ~~ 128*1024, as linux MAX_ARG_STRLEN is 128kiB
end

Instance Attribute Details

#default ⇒ Object

Returns the value of attribute default.



863
864
865
 
# File 'lib/optimist_xl.rb', line 863

def default
  @default
end

#long ⇒ Object

Returns the value of attribute long.



863
864
865
 
# File 'lib/optimist_xl.rb', line 863

def long
  @long
end

#max_args ⇒ Object (readonly)

Returns the value of attribute max_args.



901
902
903
 
# File 'lib/optimist_xl.rb', line 901

def max_args
  @max_args
end

#min_args ⇒ Object (readonly)

Returns the value of attribute min_args.



901
902
903
 
# File 'lib/optimist_xl.rb', line 901

def min_args
  @min_args
end

#multi_given=(value) ⇒ Object (writeonly)

Sets the attribute multi_given

Parameters:

  • value —

    the value to set the attribute multi_given to.



864
865
866
 
# File 'lib/optimist_xl.rb', line 864

def multi_given=(value)
  @multi_given = value
end

#name ⇒ Object

Returns the value of attribute name.



863
864
865
 
# File 'lib/optimist_xl.rb', line 863

def name
  @name
end

#permitted ⇒ Object

Returns the value of attribute permitted.



863
864
865
 
# File 'lib/optimist_xl.rb', line 863

def permitted
  @permitted
end

#permitted_response ⇒ Object

Returns the value of attribute permitted_response.



863
864
865
 
# File 'lib/optimist_xl.rb', line 863

def permitted_response
  @permitted_response
end

#short ⇒ Object (readonly)

Returns the value of attribute short.



862
863
864
 
# File 'lib/optimist_xl.rb', line 862

def short
  @short
end

Class Method Details

.create(name, _desc = "", opts = {}, _settings = {}) ⇒ Object

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



1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
 
# File 'lib/optimist_xl.rb', line 1034

def self.create(name, _desc="", opts={}, _settings={})

  opttype = OptimistXL::Parser.registry_getopttype(opts[:type])
  opttype_from_default = get_klass_from_default(opts, opttype)
  #DEBUG# puts "\nopt:#{opttype||'nil'} ofd:#{opttype_from_default}"  if opttype_from_default
  if opttype && opttype_from_default && !opttype.compatible_with?(opttype_from_default) # opttype.is_a? opttype_from_default.class
    raise ArgumentError, ":type specification (#{opttype.class}) and default type don't match (default type is #{opttype_from_default.class})" 
  end
  
  opt_inst = (opttype || opttype_from_default || OptimistXL::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

.handle_long_opt(lopt, name) ⇒ Object 



1105
1106
1107
1108
1109
1110
1111
1112
 
# File 'lib/optimist_xl.rb', line 1105

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

.handle_short_opt(sopt) ⇒ Object 



1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
 
# File 'lib/optimist_xl.rb', line 1114

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 =~ ::OptimistXL::Parser::INVALID_SHORT_ARG_REGEX
  end
  return sopt
end

.register_alias(*alias_keys) ⇒ Object

Provide a way to register symbol aliases to the Parser



1021
1022
1023
1024
1025
1026
 
# File 'lib/optimist_xl.rb', line 1021

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

Instance Method Details

#array_default? ⇒ Boolean

|@min_args | @max_args | ----------———–+ | 0 | 0 | formerly flag?==true (option without any arguments) | 1 | 1 | formerly single_arg?==true (single-parameter/normal option) | 1 | >1 | formerly multi_arg?==true | ? | ? | presumably illegal condition. untested.

Returns:

  • (Boolean) 


909
 
# File 'lib/optimist_xl.rb', line 909

def array_default? ; self.default.kind_of?(Array) ; end

#callback ⇒ Object 



913
 
# File 'lib/optimist_xl.rb', line 913

def callback ; opts(:callback) ; end

#compatible_with?(other_option) ⇒ Boolean

Check that an option is compatible with another option. By default, checking that they are the same class, but we can override this in the subclass as needed.

Returns:

  • (Boolean) 


885
886
887
 
# File 'lib/optimist_xl.rb', line 885

def compatible_with?(other_option)
  self.is_a? other_option.class
end

#desc ⇒ Object 



915
 
# File 'lib/optimist_xl.rb', line 915

def desc ; opts(:desc) ; end

#description_with_default(str) ⇒ Object

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



952
953
954
955
956
957
958
959
960
961
 
# File 'lib/optimist_xl.rb', line 952

def description_with_default(str)
  return str unless default
  default_s = case default
              when Array
                default.join(', ')
              else
                format_stdio(default).to_s
              end
  return "#{str} (Default: #{default_s})"
end

#description_with_permitted(str) ⇒ Object

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



964
965
966
967
968
969
970
971
972
973
974
975
976
 
# File 'lib/optimist_xl.rb', line 964

def description_with_permitted(str)
  permitted_s = case permitted
                when Array
                  permitted.map do |p|
                    format_stdio(p).to_s
                  end.join(', ')
                when Range
                  permitted.to_a.map(&:to_s).join(', ')
                when Regexp
                  permitted.to_s
                end
  return "#{str} (Permitted: #{permitted_s})"
end

#doesnt_need_autogen_short ⇒ Object 



911
 
# File 'lib/optimist_xl.rb', line 911

def doesnt_need_autogen_short ; !short.auto || !short.chars.empty? ; end

#educate ⇒ Object 



926
927
928
929
930
931
 
# File 'lib/optimist_xl.rb', line 926

def educate
  optionlist = []
  optionlist.concat(short.chars.map { |o| "-#{o}" })
  optionlist.concat(long.names.map { |o| "--#{o}" })
  optionlist.compact.join(', ') + type_format + (min_args==0 && default ? ", --no-#{long}" : "")
end

#format_stdio(obj) ⇒ Object

Format stdio like objects to a string



942
943
944
945
946
947
948
949
 
# File 'lib/optimist_xl.rb', line 942

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 ⇒ Object

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



934
935
936
937
938
939
 
# File 'lib/optimist_xl.rb', line 934

def full_description
  desc_str = desc
  desc_str = description_with_default desc_str if default
  desc_str = description_with_permitted desc_str if permitted
  desc_str
end

#multi ⇒ Object Also known as: multi? 



898
 
# File 'lib/optimist_xl.rb', line 898

def multi ; @multi_given ; end

#opts(key) ⇒ Object 



889
890
891
 
# File 'lib/optimist_xl.rb', line 889

def opts(key)
  @optshash[key]
end

#opts=(o) ⇒ Object 



893
894
895
 
# File 'lib/optimist_xl.rb', line 893

def opts=(o)
  @optshash = o
end

#parse(_paramlist, _neg_given) ⇒ Object

Raises:

  • (NotImplementedError) 


919
920
921
 
# File 'lib/optimist_xl.rb', line 919

def parse(_paramlist, _neg_given)
  raise NotImplementedError, "parse must be overridden for newly registered type"
end

#permitted_type_valid? ⇒ Boolean

Returns:

  • (Boolean) 


990
991
992
993
994
995
996
 
# File 'lib/optimist_xl.rb', line 990

def permitted_type_valid?
  return true if permitted.nil?
  return true if permitted.is_a? Array
  return true if permitted.is_a? Range
  return true if permitted.is_a? Regexp
  false
end

#permitted_valid_string ⇒ Object

Raises:

  • (StandardError) 


978
979
980
981
982
983
984
985
986
987
988
 
# File 'lib/optimist_xl.rb', line 978

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 StandardError, "invalid branch"
end

#permitted_value?(val) ⇒ Boolean

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

Returns:

  • (Boolean) 


1009
1010
1011
1012
1013
1014
1015
1016
1017
 
# File 'lib/optimist_xl.rb', line 1009

def permitted_value?(val)
  case permitted
  when nil then true
  when Regexp then val.match permitted
  when Range then permitted.to_a.map(&:to_s).include? val
  when Array then permitted.map(&:to_s).include? val
  else false
  end
end

#required? ⇒ Boolean

Returns:

  • (Boolean) 


917
 
# File 'lib/optimist_xl.rb', line 917

def required? ; opts(:required) ; end

#type_format ⇒ Object

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



924
 
# File 'lib/optimist_xl.rb', line 924

def type_format ; "" ; end

#validate_permitted(arg, value) ⇒ Object 



998
999
1000
1001
1002
1003
1004
1005
 
# File 'lib/optimist_xl.rb', line 998

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