Class: Slop::Option

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

Constant Summary collapse

DEFAULT_CONFIG = 
{
  help: true,
  tail: false,
  underscore_flags: true,
  required: false,
}

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(flags, desc, **config, &block) ⇒ Option 



30
31
32
33
34
35
36
 
# File 'lib/slop/option.rb', line 30

def initialize(flags, desc, **config, &block)
  @flags  = flags
  @desc   = desc
  @config = DEFAULT_CONFIG.merge(config)
  @block  = block
  reset
end

Instance Attribute Details

#block ⇒ Object (readonly)

A custom proc that yields the option value when it’s executed.



25
26
27
 
# File 'lib/slop/option.rb', line 25

def block
  @block
end

#config ⇒ Object (readonly)

A Hash of configuration options.



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

def config
  @config
end

#count ⇒ Object (readonly)

An Integer count for the total times this option has been executed.



21
22
23
 
# File 'lib/slop/option.rb', line 21

def count
  @count
end

#desc ⇒ Object (readonly)

A custom description used for the help text.



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

def desc
  @desc
end

#flags ⇒ Object (readonly)

An Array of flags this option matches.



11
12
13
 
# File 'lib/slop/option.rb', line 11

def flags
  @flags
end

#value ⇒ Object

Returns the value for this option. Falls back to the default (or nil).



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

def value
  @value || default_value
end

Instance Method Details

#call(_value) ⇒ Object

This method is called immediately when an option is found. Override it in sub-classes.

Raises:



71
72
73
74
 
# File 'lib/slop/option.rb', line 71

def call(_value)
  raise NotImplementedError,
    "you must override the `call' method for option #{self.class}"
end

#default_value ⇒ Object

Returns the default value for this option (default is nil).



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

def default_value
  config[:default]
end

#ensure_call(value) ⇒ Object

Since ‘call()` can be used/overriden in subclasses, this method is used to do general tasks like increment count. This ensures you don’t have to call ‘super` when overriding `call()`. It’s used in the Parser.



49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
 
# File 'lib/slop/option.rb', line 49

def ensure_call(value)
  @count += 1

  if value.nil? && expects_argument?
    if default_value
      @value = default_value
    elsif !suppress_errors?
      raise Slop::MissingArgument.new("missing argument for #{flag}", flags)
    end
  else
    if validate_type? && !valid?(value) && !suppress_errors?
      raise Slop::InvalidOptionValue.new("invalid value for #{flag}", flags)
    end

    @value = valid?(value) && call(value)
  end

  block.call(@value) if block.respond_to?(:call)
end

#expects_argument? ⇒ Boolean

Override this if this option type does not expect an argument (i.e a boolean option type).



84
85
86
 
# File 'lib/slop/option.rb', line 84

def expects_argument?
  true
end

#finish(_result) ⇒ Object

By default this method does nothing. It’s called when all options have been parsed and allows you to mutate the ‘@value` attribute according to other options.



79
80
 
# File 'lib/slop/option.rb', line 79

def finish(_result)
end

#flag ⇒ Object

Returns all flags joined by a comma. Used by the help string.



122
123
124
 
# File 'lib/slop/option.rb', line 122

def flag
  flags.join(", ")
end

#help? ⇒ Boolean

Returns true if this option should be displayed in help text.



146
147
148
 
# File 'lib/slop/option.rb', line 146

def help?
  config[:help]
end

#key ⇒ Object

Returns the last key as a symbol. Used in Options.to_hash.



127
128
129
130
131
 
# File 'lib/slop/option.rb', line 127

def key
  key = config[:key] || flags.last.sub(/\A--?/, '')
  key = key.tr '-', '_' if underscore_flags?
  key.to_sym
end

#null? ⇒ Boolean

Override this if you want to ignore the return value for an option (i.e so Result#to_hash does not include it).



90
91
92
 
# File 'lib/slop/option.rb', line 90

def null?
  false
end

#required? ⇒ Boolean

Returns true if an exception should be raised when this option isn’t supplied.



110
111
112
 
# File 'lib/slop/option.rb', line 110

def required?
  config[:required]
end

#reset ⇒ Object

Reset the option count and value. Used when calling .reset on the Parser.



40
41
42
43
 
# File 'lib/slop/option.rb', line 40

def reset
  @value = nil
  @count = 0
end

#suppress_errors? ⇒ Boolean

Returns true if we should ignore errors that cause exceptions to be raised.



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

def suppress_errors?
  config[:suppress_errors]
end

#tail ⇒ Object

Returns 1 if this option should be added to the tail of the help text. Used for sorting.



157
158
159
 
# File 'lib/slop/option.rb', line 157

def tail
  tail? ? 1 : -1
end

#tail? ⇒ Boolean

Returns true if this option should be added to the tail of the help text.



151
152
153
 
# File 'lib/slop/option.rb', line 151

def tail?
  config[:tail]
end

#to_s(offset: 0) ⇒ Object

Returns the help text for this option (flags and description).



162
163
164
 
# File 'lib/slop/option.rb', line 162

def to_s(offset: 0)
  "%-#{offset}s  %s" % [flag, desc]
end

#underscore_flags? ⇒ Boolean

Returns true if this option should be displayed with dashes transformed into underscores.



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

def underscore_flags?
  config[:underscore_flags]
end

#valid?(value) ⇒ Boolean

Override this if you want to provide a custom validator for a type. This method must return whether the provided value is valid for the current argument’s type



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

def valid?(value)
  true
end

#validate_type? ⇒ Boolean

Returns true if an exception should be raised when this option value can’t be parsed into the desired type or does not conform to the expected type’s format



117
118
119
 
# File 'lib/slop/option.rb', line 117

def validate_type?
  config[:validate_type] || config[:validate_types]
end