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),
      ProcessExecuter::Options::OptionDefinition.new(:option2)
    ]
  end
end
options_hash = { options1: 'value1', option2: 'value2' }
options = MyOptions.new(options_hash)
options.option1 # => 'value1'
options.option2 # => 'value2'

Direct Known Subclasses

SpawnOptions

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(**options) ⇒ Base

Create a new Options object

Examples:

options = ProcessExecuter::Options.new(out: $stdout, err: $stderr, timeout_after: 10)

Parameters:

  • options (Hash) —

    Process.spawn options plus additional options listed below.

    See Process.spawn for a list of valid options that can be passed to Process.spawn.

Options Hash (**options):

  • :timeout_after (Integer, Float, nil) —

    Number of seconds to wait for the process to terminate. Any number may be used, including Floats to specify fractional seconds. A value of 0 or nil will allow the process to run indefinitely.


44
45
46
47
48
49
50
 
# File 'lib/process_executer/options/base.rb', line 44

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

Instance Attribute Details

#errors ⇒ Array<String> (readonly)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

The list of validation errors

Validators should add an error messages to this array.

Examples:

options = ProcessExecuter::Options::RunOptions.new(timeout_after: 'not_a_number', raise_errors: 'yes')
#=> raises an Argument error with the following message:
    timeout_after must be nil or a non-negative real number but was "not_a_number"
    raise_errors must be true or false but was "yes""
 errors # => [
   "timeout_after must be nil or a non-negative real number but was \"not_a_number\"",
   "raise_errors must be true or false but was \"yes\""
 ]

Returns:

  • (Array<String>) 

159
160
161
 
# File 'lib/process_executer/options/base.rb', line 159

def errors
  @errors
end

Instance Method Details

#allowed_options ⇒ Hash

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.allowed_options # => { timeout_after: #<OptionDefinition>, ... }

Returns:

  • (Hash) 

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

def allowed_options
  @allowed_options ||=
    define_options.each_with_object({}) do |option, hash|
      hash[option.name] = option
    end.freeze
end

#each_with_object(obj) {|option_key, option_value, obj| ... }

This method returns an undefined value.

Iterate over each option with an object

Examples:

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

Yields:

  • (option_key, option_value, obj) 

105
106
107
 
# File 'lib/process_executer/options/base.rb', line 105

def each_with_object(obj, &)
  @options.each_with_object(obj, &)
end

#inspect ⇒ String

A string representation of the options

Examples:

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

Returns:

  • (String) 

85
86
87
 
# File 'lib/process_executer/options/base.rb', line 85

def inspect
  options.inspect
end

#merge!(**other_options)

This method returns an undefined value.

Merge the given options into the current options

Examples:

options = ProcessExecuter::Options.new(option1: 'value1', option2: 'value2')
options.merge!(option2: 'new_value2', option3: 'value3')
options.option2 # => 'new_value2'
options.option3 # => 'value3'

Parameters:

  • other_options (Hash) —

    the options to merge into the current options


118
119
120
 
# File 'lib/process_executer/options/base.rb', line 118

def merge!(**other_options)
  @options.merge!(other_options)
end

#to_h ⇒ Hash

A hash representation of the options

Examples:

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

Returns:

  • (Hash) 

94
95
96
 
# File 'lib/process_executer/options/base.rb', line 94

def to_h
  @options.dup
end

#to_s ⇒ String

A string representation of the object that includes the options

Examples:

options = ProcessExecuter::Options.new(option1: 'value1', option2: 'value2')
options.to_s # => #<ProcessExecuter::Options:0x00007f8f9b0b3d20 option1: "value1", option2: "value2">'

Returns:

  • (String) 

76
77
78
 
# File 'lib/process_executer/options/base.rb', line 76

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

#with(**options_hash) ⇒ self.class

A shallow copy of self with options copied but not the values they reference

If any keyword arguments are given, the copy will be created with the respective option values updated.

Examples:

options_hash = { option1: 'value1', option2: 'value2' }
options = ProcessExecuter::MyOptions.new(options_hash)
copy = options.with(option1: 'new_value1')
copy.option1 # => 'new_value1'
copy.option2 # => 'value2'
options.option1 # => 'value1'
options.option2 # => 'value2'

Returns:

  • (self.class) 

139
140
141
 
# File 'lib/process_executer/options/base.rb', line 139

def with(**options_hash)
  self.class.new(**@options, **options_hash)
end