Class: Acclaim::Option
- Inherits:
-
Object
- Object
- Acclaim::Option
- 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.
Defined Under Namespace
Modules: Type Classes: Arity, Parser
Instance Attribute Summary collapse
-
#default ⇒ Object
The default value for the option.
-
#description ⇒ Object
The description of this option.
-
#handler ⇒ Object
This option’s custom handler.
-
#key ⇒ Object
The key used to store the value of the option.
-
#names ⇒ Object
The strings that refer to this option in the command line.
-
#on_multiple ⇒ Object
How the parser should react when multiple instances of this option are found in the command line.
-
#type ⇒ Object
The type the option’s value will be converted to.
Class Method Summary collapse
-
.name_from(key) ⇒ Object
Derives a name from the given key’s string representation.
Instance Method Summary collapse
-
#=~(str) ⇒ Object
Returns true if the given string is equal to any of this option’s names.
-
#arity ⇒ Object
Returns this option’s arity.
-
#arity=(arity_or_array) ⇒ Object
Sets this option’s arity.
-
#convert_parameters(*args) ⇒ Object
Converts all given arguments using the type handler for this option’s type.
-
#flag? ⇒ Boolean
(also: #bool?, #boolean?, #switch?)
Returns
true
if this option takes no arguments. -
#initialize(key, *args, &block) ⇒ Option
constructor
Initializes a command line option.
-
#require ⇒ Object
Require that this option be given on the command line.
-
#required=(value) ⇒ Object
Sets whether or not this option is required.
-
#required? ⇒ Boolean
Whether or not this option is required on the command line.
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 isString
.
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.
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) = 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 = .description? strings.description?([]).first self.on_multiple = .on_multiple? :replace self.arity = .arity? self.default = .default? self.required = .required? self.type = type || String self.handler = block end |
Instance Attribute Details
#default ⇒ Object
The default value for the option. Default is nil
.
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.
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.
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.
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.
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.
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.
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.
163 164 165 166 167 168 169 170 |
# File 'lib/acclaim/option.rb', line 163 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.
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.
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 ]
.
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.
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.
141 142 143 |
# File 'lib/acclaim/option.rb', line 141 def flag? arity and arity.none? end |
#require ⇒ Object
Require that this option be given on the command line.
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.
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.
126 127 128 |
# File 'lib/acclaim/option.rb', line 126 def required? @required end |