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

Returns a new instance of 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).

Returns:

  • (Boolean) 


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.

Returns:

  • (Boolean) 


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).

Returns:

  • (Boolean) 


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.

Returns:

  • (Boolean) 


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.

Returns:

  • (Boolean) 


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.

Returns:

  • (Boolean) 


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.

Returns:

  • (Boolean) 


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

Returns:

  • (Boolean) 


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

Returns:

  • (Boolean) 


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

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