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
 
# File 'lib/process_executer/options/base.rb', line 63

def initialize(**options_hash)
  @options_hash = allowed_options.transform_values(&:default).merge(options_hash)
  define_accessor_methods
  validate!
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:



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

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



144
145
146
 
# File 'lib/process_executer/options/base.rb', line 144

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) 


113
114
115
 
# File 'lib/process_executer/options/base.rb', line 113

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:



208
209
210
211
 
# File 'lib/process_executer/options/base.rb', line 208

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:



181
182
183
184
185
186
187
188
189
 
# File 'lib/process_executer/options/base.rb', line 181

def merge!(*other_options_hashes)
  original_options_hash = @options_hash
  @options_hash = original_options_hash.dup.merge!(*other_options_hashes)
  validate!
  self
rescue ProcessExecuter::ArgumentError
  @options_hash = original_options_hash
  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) 


125
126
127
 
# File 'lib/process_executer/options/base.rb', line 125

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) 


101
102
103
 
# File 'lib/process_executer/options/base.rb', line 101

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