Class: ProcessExecuter::Options::Base

Inherits:
Object
  • Object
show all
Defined in:
lib/process_executer/options/base.rb

Overview

Defines, validates, and holds a set of option values

Options are defined by subclasses by overriding the define_options method.

Examples:

Define an options class with two options

class MyOptions < ProcessExecuter::Options::Base
  def define_options
    # Call super to include options defined in the parent class
    [
      *super,
      ProcessExecuter::Options::OptionDefinition.new(
        :option1, default: '', validator: method(:assert_is_string)
        ),
      ProcessExecuter::Options::OptionDefinition.new(
        :option2, default: '', validator: method(:assert_is_string)
      ),
      ProcessExecuter::Options::OptionDefinition.new(
        :option3, default: '', validator: method(:assert_is_string)
      )
    ]
  end
  def assert_is_string(key, value)
    return if value.is_a?(String)
    errors << "#{key} must be a String but was #{value}"
  end
end
options = MyOptions.new(option1: 'value1', option2: 'value2')
options.option1 # => 'value1'
options.option2 # => 'value2'

invalid option values

begin
  options = MyOptions.new(option1: 1, option2: 2)
rescue ProcessExecuter::ArgumentError => e
  e.message #=> "option1 must be a String but was 1\noption2 must be a String but was 2"
end

Direct Known Subclasses

SpawnOptions

Instance Method Summary collapse

Constructor Details

#initialize(**options_hash) ⇒ Base

Create a new Options object

Normally you would use a subclass instead of instantiating this class directly.

Examples:

options = MyOptions.new(option1: 'value1', option2: 'value2')

with invalid option values

begin
  options = MyOptions.new(option1: 1, option2: 2)
rescue ProcessExecuter::ArgumentError => e
  e.message #=> "option1 must be a String but was 1\noption2 must be a String but was 2"
end

Parameters:

  • options_hash (Hash) —

    a hash of options



63
64
65
66
67
68
69
 
# File 'lib/process_executer/options/base.rb', line 63

def initialize(**options_hash)
  @options_hash = allowed_options.transform_values(&:default).merge(options_hash)
  @errors = []
  assert_no_unknown_options
  define_accessor_methods
  validate_options
end

Instance Method Details

#allowed_options ⇒ Hash<Symbol, ProcessExecuter::Options::OptionDefinition>

All the allowed options as a hash whose keys are the option names

The returned hash what is returned from define_options but with the option names as keys. The values are instances of OptionDefinition.

The returned hash is frozen and cannot be modified.

Examples:

options = MyOptions.new(option1: 'value1', option2: 'value2')
options.allowed_options # => {
  option1: #<OptionDefinition>,
  option2: #<OptionDefinition>
}

Returns:



88
89
90
91
92
93
 
# File 'lib/process_executer/options/base.rb', line 88

def allowed_options
  @allowed_options ||=
    define_options.to_h do |option|
      [option.name, option]
    end.freeze
end

#each_with_object(obj) {|key_value, obj| ... } ⇒ Object

Iterate over each option with an object

Examples:

options = MyOptions.new(option1: 'value1', option2: 'value2')
options.each_with_object({}) { |(option_key, option_value), obj| obj[option_key] = option_value }
# => { option1: "value1", option2: "value2" }

Yields:

  • (key_value, obj)

Yield Parameters:

  • key_value (Array<Object, Object>) —

    An array containing the option key and its value

  • obj (Object) —

    The object passed to the block.

Returns:

  • (Object) —

    the obj passed to the block



146
147
148
 
# File 'lib/process_executer/options/base.rb', line 146

def each_with_object(obj, &)
  options_hash.each_with_object(obj, &)
end

#inspect ⇒ String

A string representation of the options

Examples:

options = MyOptions.new(option1: 'value1', option2: 'value2')
options.inspect # => '{:option1=>"value1", :option2=>"value2"}'

Returns:

  • (String) 


115
116
117
 
# File 'lib/process_executer/options/base.rb', line 115

def inspect
  options_hash.inspect
end

#merge(*other_options_hashes) ⇒ self.class

Returns a new options object formed by merging self with each of other_hashes

Examples:

options = MyOptions.new(option1: 'value1', option2: 'value2')
options.object_id # => 1025
h1 = { option2: 'new_value2' }
h2 = { option3: 'value3' }
merged_options = options.merge(h1, h2)
merged_options.object_id # => 1059

Parameters:

  • other_options_hashes (Array<Hash>) —

    the options to merge into the current options

Returns:

  • (self.class)

Raises:



213
214
215
216
 
# File 'lib/process_executer/options/base.rb', line 213

def merge(*other_options_hashes)
  merged_options = other_options_hashes.reduce(options_hash, :merge)
  self.class.new(**merged_options)
end

#merge!(*other_options_hashes) ⇒ self

Merge the given options into the current options object

Subsequent hashes' values overwrite earlier ones for the same key.

The merged options are checked the same way the constructor checks its options: unknown options and invalid option values raise a ProcessExecuter::ArgumentError. In that case, the current options object is left unchanged.

Examples:

options = MyOptions.new(option1: 'value1', option2: 'value2')
h1 = { option2: 'new_value2' }
h2 = { option3: 'value3' }
options.merge!(h1, h2) # => options with {option1: "value1", option2: "new_value2", option3: "value3"}

with an invalid option value

options = MyOptions.new(option1: 'value1')
begin
  options.merge!(option1: 1)
rescue ProcessExecuter::ArgumentError => e
  e.message #=> "option1 must be a String but was 1"
  options.option1 #=> 'value1'
end

Parameters:

  • other_options_hashes (Array<Hash>) —

    zero or more hashes to merge into the current options

Returns:

  • (self) —

    the current options object with the merged options

Raises:



183
184
185
186
187
188
189
190
191
192
193
194
 
# File 'lib/process_executer/options/base.rb', line 183

def merge!(*other_options_hashes)
  original_options_hash = @options_hash
  @options_hash = original_options_hash.dup.merge!(*other_options_hashes)
  @errors = []
  assert_no_unknown_options
  validate_options
  self
rescue ProcessExecuter::ArgumentError
  @options_hash = original_options_hash
  @errors = []
  raise
end

#to_h ⇒ Hash

A hash representation of the options

Examples:

options = MyOptions.new(option1: 'value1', option2: 'value2')
options.to_h # => { option1: "value1", option2: "value2" }

Returns:

  • (Hash) 


127
128
129
 
# File 'lib/process_executer/options/base.rb', line 127

def to_h
  options_hash.dup
end

#to_s ⇒ String

A string representation of the object that includes the options

Examples:

options = MyOptions.new(option1: 'value1', option2: 'value2')
options.to_s # => #<MyOptions option1: "value1", option2: "value2">'

Returns:

  • (String) 


103
104
105
 
# File 'lib/process_executer/options/base.rb', line 103

def to_s
  "#{super.to_s[0..-2]} #{inspect}>"
end