Class: Acclaim::Option

Inherits:
Object
  • Object
show all
Defined in:
lib/acclaim/option.rb,
lib/acclaim/option/type.rb,
lib/acclaim/option/arity.rb,
lib/acclaim/option/parser.rb,
lib/acclaim/option/type/uri.rb,
lib/acclaim/option/type/date.rb,
lib/acclaim/option/type/time.rb,
lib/acclaim/option/type/float.rb,
lib/acclaim/option/type/string.rb,
lib/acclaim/option/type/symbol.rb,
lib/acclaim/option/parser/error.rb,
lib/acclaim/option/type/complex.rb,
lib/acclaim/option/type/integer.rb,
lib/acclaim/option/parser/regexp.rb,
lib/acclaim/option/type/pathname.rb,
lib/acclaim/option/type/rational.rb,
lib/acclaim/option/type/date_time.rb,
lib/acclaim/option/type/big_decimal.rb

Overview

Represents a command-line option.

Since:

  • 0.0.1

Defined Under Namespace

Modules: Type Classes: Arity, Parser

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(key, *args, &block) ⇒ Option

Initializes a command line option. The key is the object used to associate this option with a value. The other arguments may be:

short switches

Strings starting with '-', like: '-h'; '-v'

long switches

Strings starting with '--', like: '--help'; '--version'

description

Strings that don’t start with either '-' nor '--', like: 'Display this help text and exit.'; 'Display version and exit.'

class

The Class which will be used in parameter conversion. The default is String.

If no switches were specified, the key will be used to derive one. See Option::name_from for details.

The last argument can be a hash of options, which may specify:

:arity

The number of required and optional arguments. See Arity for defails. Defaults to no arguments.

:default

The default value for this option. Defaults to nil.

:description

The description. Overrides the one given among the other arguments.

:required

Whether or not the option must be present on the command line. Default is false.

:on_multiple

What to do if the option is encountered multiple times. Supported modes are :replace, :raise and :append (or :collect). New values will replace old ones by default.

Additionally, if a block is given, it will be called when the option is parsed with a ribbon instance and the parameters given to the option. The parameters will already be converted to this option’s specified type; if this is not desirable consider not specifying a class to the option or registering a custom type handler.

Since:

  • 0.0.1



72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
 
# File 'lib/acclaim/option.rb', line 72

def initialize(key, *args, &block)
  options = args.extract_ribbon!
  type = args.find { |arg| arg.is_a? Module }

  strings = args.flatten.select do |arg|
    arg.is_a? String
  end.group_by do |arg|
    arg =~ Parser::Regexp::SWITCH ? :switches : :description
  end.to_ribbon

  self.key = key
  self.names = strings.switches? { [ Option.name_from(key) ] }
  self.description = options.description? strings.description?([]).first
  self.on_multiple = options.on_multiple? :replace
  self.arity = options.arity?
  self.default = options.default?
  self.required = options.required?
  self.type = type || String
  self.handler = block
end

Instance Attribute Details

#default ⇒ Object

The default value for the option. Default is nil.

Since:

  • 0.0.1



26
27
28
 
# File 'lib/acclaim/option.rb', line 26

def default
  @default
end

#description ⇒ Object

The description of this option. If it responds to call, it will be called to determine the description at runtime.

Since:

  • 0.0.1



121
122
123
 
# File 'lib/acclaim/option.rb', line 121

def description
  (@description.respond_to?(:call) ? @description.call : @description).to_s
end

#handler ⇒ Object

This option’s custom handler.

Since:

  • 0.0.1



29
30
31
 
# File 'lib/acclaim/option.rb', line 29

def handler
  @handler
end

#key ⇒ Object

The key used to store the value of the option.

Since:

  • 0.0.1



14
15
16
 
# File 'lib/acclaim/option.rb', line 14

def key
  @key
end

#names ⇒ Object

The strings that refer to this option in the command line.

Since:

  • 0.0.1



17
18
19
 
# File 'lib/acclaim/option.rb', line 17

def names
  @names
end

#on_multiple ⇒ Object

How the parser should react when multiple instances of this option are found in the command line. It will, by default, replace the old value with the new one, but it can also collect all values or raise an error.

Since:

  • 0.0.1



34
35
36
 
# File 'lib/acclaim/option.rb', line 34

def on_multiple
  @on_multiple
end

#type ⇒ Object

The type the option’s value will be converted to. See Option::Type.

Since:

  • 0.0.1



23
24
25
 
# File 'lib/acclaim/option.rb', line 23

def type
  @type
end

Class Method Details

.name_from(key) ⇒ Object

Derives a name from the given key’s string representation. All underscores will be replaced with dashes.

If the string is empty, an ArgumentError will be raised. If the resulting name is not a valid switch, a NameError will be raised.

Raises:

  • (ArgumentError)

Since:

  • 0.0.1



180
181
182
183
184
185
186
187
 
# File 'lib/acclaim/option.rb', line 180

def name_from(key)
  name = key.to_s
  raise ArgumentError, "Can't derive name from empty key." if name.empty?
  name = (name.length == 1 ? '-' : '--') + name
  name.gsub! '_', '-'
  raise NameError, "Derived name is invalid: #{name}" unless name =~ Option::Parser::Regexp::SWITCH
  name
end

Instance Method Details

#=~(str) ⇒ Object

Returns true if the given string is equal to any of this option’s names.

Since:

  • 0.0.1



100
101
102
 
# File 'lib/acclaim/option.rb', line 100

def =~(str)
  names.include? str.strip
end

#arity ⇒ Object

Returns this option’s arity. See Arity for details.

Since:

  • 0.0.1



105
106
107
 
# File 'lib/acclaim/option.rb', line 105

def arity
  @arity ||= Arity.new
end

#arity=(arity_or_array) ⇒ Object

Sets this option’s arity. The value given may be an Arity, or an array in the form of [ required_parameters, optional_parameters ].

Since:

  • 0.0.1



111
112
113
114
115
116
117
 
# File 'lib/acclaim/option.rb', line 111

def arity=(arity_or_array)
  @arity = if arity.nil? or arity_or_array.is_a? Arity
    arity_or_array
  else
    Arity.new *arity_or_array
  end
end

#convert_parameters(*args) ⇒ Object

Converts all given arguments using the type handler for this option’s type.

Since:

  • 0.0.1



95
96
97
 
# File 'lib/acclaim/option.rb', line 95

def convert_parameters(*args)
  args.map { |arg| Type.handler_for(type).call arg }
end

#flag? ⇒ Boolean Also known as: bool?, boolean?, switch?

Returns true if this option takes no arguments.

Returns:

  • (Boolean)

Since:

  • 0.0.1



141
142
143
 
# File 'lib/acclaim/option.rb', line 141

def flag?
  arity.none?
end

#inspect ⇒ String

Generate human-readable string containing this option’s data.

Returns:

  • (String) —

    human-readable representation of this option

Since:

  • 0.4.0



158
159
160
161
162
163
164
165
166
167
168
169
 
# File 'lib/acclaim/option.rb', line 158

def inspect
  '#<%s %s (%s) %s = %p (%s) (1+ => %s) %s>' % [
    self.class,
    key,
    names.join('|'),
    type,
    default,
    arity,
    on_multiple,
    if required? then :required else :optional end
  ]
end

#require ⇒ Object

Require that this option be given on the command line.

Since:

  • 0.0.1



136
137
138
 
# File 'lib/acclaim/option.rb', line 136

def require
  self.required = true
end

#required=(value) ⇒ Object

Sets whether or not this option is required.

Since:

  • 0.0.1



131
132
133
 
# File 'lib/acclaim/option.rb', line 131

def required=(value)
  @required = value ? true : false
end

#required? ⇒ Boolean

Whether or not this option is required on the command line.

Returns:

  • (Boolean)

Since:

  • 0.0.1



126
127
128
 
# File 'lib/acclaim/option.rb', line 126

def required?
  @required
end