Module: Boson::Options

Defined in:
lib/boson/options.rb

Overview

This module contains the methods used to define the default option types.

Creating Your Own Option Type

Defining your own option type simply requires one method (create_@type) to parse the option value and create the desired object. To create an option type :date, you could create the following create_date method:

# Drop this in ~/.boson/commands/date_option.rb
module Boson::Options::Date
  def create_date(value)
    # value should be mm/dd
    Date.parse(value + "/#{Date.today.year}")
  end
end
Boson::OptionParser.send :include, Boson::Options::Date

Modify your config to load this new library by default:

:defaults:
- date_option

In a FileLibrary, we could then use this new option:

module Calendar
  #@options :day=>:date
  def appointments(options={})
    # ...
  end
end
# >> appointments '-d 10/10'   -> {:day=>#<Date: 4910229/2,0,2299161> }

As you can see, a date object is created from the :date option’s value and passed into appointments().

Some additional tips on the create_* method:

  • The argument passed to the method is the option value from the user.

  • To access the current option name use @current_option.

  • To access the hash of attributes the current option has use OptionParser.current_attributes. See OptionParser.new for more about option attributes.

There are two optional methods per option type: validate_@type and usage_for_@type i.e. validate_date and usage_for_date. Like create_@type, validate_@type takes the option’s value. If the value validation fails, raise an OptionParser::Error with a proper message. All user-defined option types automatically validate for an option value’s existence. The usage_for_* method takes an option’s name (i.e. –day) and returns a usage string to be wrapped in ‘[ ]’. If no usage is defined the default would look like ‘[–day=:date]’. Consider using the OptionParser.default_usage helper method for your usage.

Instance Method Summary collapse

Instance Method Details

#create_array(value) ⇒ Object 



65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
 
# File 'lib/boson/options.rb', line 65

def create_array(value)
  splitter = current_attributes[:split] || ','
  array = value.split(splitter)
  if (values = current_attributes[:values]) && (values = values.sort_by {|e| e.to_s })
    if current_attributes[:regexp]
      array = array.map {|e|
        (new_values = values.grep(/#{e}/)).empty? ? e : new_values
      }.compact.flatten.uniq
    else
      array.each {|e| array.delete(e) && array += values if e == '*'}
      array.map! {|e| auto_alias_value(values, e) }
    end
    validate_enum_values(values, array)
  end
  array
end

#create_boolean(value) ⇒ Object 



52
53
54
55
56
57
58
59
 
# File 'lib/boson/options.rb', line 52

def create_boolean(value)
  if (!@opt_types.key?(dasherize(@current_option)) && @current_option =~ /^no-(\w+)$/)
    opt = (opt = original_no_opt($1)) ? undasherize(opt) : $1
    (@current_option.replace(opt) && false)
  else
    true
  end
end

#create_hash(value) ⇒ Object 



82
83
84
85
86
87
88
89
90
91
92
 
# File 'lib/boson/options.rb', line 82

def create_hash(value)
  (keys = current_attributes[:keys]) && keys = keys.sort_by {|e| e.to_s }
  hash = parse_hash(value, keys)
  if keys
    hash = hash.inject({}) {|h,(k,v)|
      h[auto_alias_value(keys, k)] = v; h
    }
    validate_enum_values(keys, hash.keys)
  end
  hash
end

#create_numeric(value) ⇒ Object 



61
62
63
 
# File 'lib/boson/options.rb', line 61

def create_numeric(value)
  value.index('.') ? value.to_f : value.to_i
end

#create_string(value) ⇒ Object

:stopdoc: Parse/create methods



44
45
46
47
48
49
50
 
# File 'lib/boson/options.rb', line 44

def create_string(value)
  if (values = current_attributes[:values]) && (values = values.sort_by {|e| e.to_s})
    value = auto_alias_value(values, value)
    validate_enum_values(values, value)
  end
  value
end

#parse_hash(value, keys) ⇒ Object 



94
95
96
97
98
99
100
101
102
103
104
 
# File 'lib/boson/options.rb', line 94

def parse_hash(value, keys)
  splitter = current_attributes[:split] || ','
  if !value.include?(':') && current_attributes[:default_keys]
    value = current_attributes[:default_keys].to_s + ":#{value}"
  end

  # Creates array pairs, grouping array of keys with a value
  aoa = Hash[*value.split(/(?::)([^#{Regexp.quote(splitter)}]+)#{Regexp.quote(splitter)}?/)].to_a
  aoa.each_with_index {|(k,v),i| aoa[i][0] = keys.join(splitter) if k == '*' } if keys
  aoa.inject({}) {|t,(k,v)| k.split(splitter).each {|e| t[e] = v }; t }
end

#usage_for_array(opt) ⇒ Object 



136
137
138
 
# File 'lib/boson/options.rb', line 136

def usage_for_array(opt)
  default_usage opt, "A,B,C"
end

#usage_for_boolean(opt) ⇒ Object

Usage methods



124
125
126
 
# File 'lib/boson/options.rb', line 124

def usage_for_boolean(opt)
  opt
end

#usage_for_hash(opt) ⇒ Object 



140
141
142
 
# File 'lib/boson/options.rb', line 140

def usage_for_hash(opt)
  default_usage opt, "A:B,C:D"
end

#usage_for_numeric(opt) ⇒ Object 



132
133
134
 
# File 'lib/boson/options.rb', line 132

def usage_for_numeric(opt)
  default_usage opt, "N"
end

#usage_for_string(opt) ⇒ Object 



128
129
130
 
# File 'lib/boson/options.rb', line 128

def usage_for_string(opt)
  default_usage(opt, undasherize(opt).upcase)
end

#validate_hash(value) ⇒ Object 



117
118
119
120
121
 
# File 'lib/boson/options.rb', line 117

def validate_hash(value)
  if !value.include?(':') && !current_attributes[:default_keys]
    raise(OptionParser::Error, "invalid key:value pair for option '#{@current_option}'")
  end
end

#validate_numeric(value) ⇒ Object 



111
112
113
114
115
 
# File 'lib/boson/options.rb', line 111

def validate_numeric(value)
  unless value =~ OptionParser::NUMERIC and $& == value
    raise OptionParser::Error, "expected numeric value for option '#{@current_option}'; got #{value.inspect}"
  end
end

#validate_string(value) ⇒ Object

Validation methods

Raises:



107
108
109
 
# File 'lib/boson/options.rb', line 107

def validate_string(value)
  raise OptionParser::Error, "cannot pass '#{value}' as an argument to option '#{@current_option}'" if valid?(value)
end