Class: OpenStruct

Relationships & Source Files
Inherits:	Object
Defined in:	lib/ostruct.rb

Overview

An OpenStruct is a data structure, similar to a Hash, that allows the definition of arbitrary attributes with their accompanying values. This is accomplished by using Ruby’s metaprogramming to define methods on the class itself.

Examples

require "ostruct"

person = OpenStruct.new
person.name = "John Smith"
person.age  = 70

person.name      # => "John Smith"
person.age       # => 70
person.address   # => nil

An OpenStruct employs a Hash internally to store the attributes and values and can even be initialized with one:

australia = OpenStruct.new(:country => "Australia", :capital => "Canberra")
  # => #<OpenStruct country="Australia", capital="Canberra">

Hash keys with spaces or characters that could normally not be used for method calls (e.g. ()[]*) will not be immediately available on the OpenStruct object as a method for retrieval or assignment, but can still be reached through the Object#send method or using [].

measurements = OpenStruct.new("length (in inches)" => 24)
measurements[:"length (in inches)"]       # => 24
measurements.send("length (in inches)")   # => 24

message = OpenStruct.new(:queued? => true)
message.queued?                           # => true
message.send("queued?=", false)
message.queued?                           # => false

Removing the presence of an attribute requires the execution of the delete_field method as setting the property value to nil will not remove the attribute.

first_pet  = OpenStruct.new(:name => "Rowdy", :owner => "John Smith")
second_pet = OpenStruct.new(:name => "Rowdy")

first_pet.owner = nil
first_pet                 # => #<OpenStruct name="Rowdy", owner=nil>
first_pet == second_pet   # => false

first_pet.delete_field(:owner)
first_pet                 # => #<OpenStruct name="Rowdy">
first_pet == second_pet   # => true

Ractor compatibility: A frozen OpenStruct with shareable values is itself shareable.

Caveats

An OpenStruct utilizes Ruby’s method lookup structure to find and define the necessary methods for properties. This is accomplished through the methods method_missing and define_singleton_method.

This should be a consideration if there is a concern about the performance of the objects that are created, as there is much more overhead in the setting of these properties compared to using a Hash or a Struct. Creating an open struct from a small Hash and accessing a few of the entries can be 200 times slower than accessing the hash directly.

This is a potential security issue; building OpenStruct from untrusted user data (e.g. JSON web request) may be susceptible to a “symbol denial of service” attack since the keys create methods and names of methods are never garbage collected.

This may also be the source of incompatibilities between Ruby versions:

o = OpenStruct.new
o.then # => nil in Ruby < 2.6, enumerator for Ruby >= 2.6

Builtin methods may be overwritten this way, which may be a source of bugs or security issues:

o = OpenStruct.new
o.methods # => [:to_h, :marshal_load, :marshal_dump, :each_pair, ...
o.methods = [:foo, :bar]
o.methods # => [:foo, :bar]

To help remedy clashes, OpenStruct uses only protected/private methods ending with ! and defines aliases for builtin public methods by adding a !:

o = OpenStruct.new(make: 'Bentley', class: :luxury)
o.class # => :luxury
o.class! # => OpenStruct

It is recommended (but not enforced) to not use fields ending in !; Note that a subclass’ methods may not be overwritten, nor can OpenStruct’s own methods ending with !.

For all these reasons, consider not using OpenStruct at all.

Constant Summary

HAS_PERFORMANCE_WARNINGS = private
# File 'lib/ostruct.rb', line 112

begin
  Warning[:performance]
  true
rescue NoMethodError, ArgumentError
  false
end

InspectKey = Internal use only
# File 'lib/ostruct.rb', line 383
```
:__inspect_key__
```
VERSION =
# File 'lib/ostruct.rb', line 110
```
"0.6.0"
```

Class Method Summary

.new(hash = nil) ⇒ OpenStruct constructor

Creates a new OpenStruct object.

Instance Attribute Summary

#table! readonly protected

Alias for #table.
#table (also: #table!) readonly Internal use only

Instance Method Summary

#==(other)

Compares this object and other for equality.
#[](name) ⇒ Object

Returns the value of an attribute, or nil if there is no such attribute.
#[]=(name, obj) ⇒ Object (also: #set_ostruct_member_value!)

Sets the value of an attribute.
#delete_field(name, &block)

Removes the named field from the object and returns the value the field contained if it was defined.
#dig(name, *identifiers) ⇒ Object

Finds and returns the object in nested objects that is specified by name and identifiers.
#each_pair {|name, value| ... } ⇒ ostruct

Yields all attributes (as symbols) along with the corresponding values or returns an enumerator if no block is given.
#eql?(other) ⇒ Boolean

Compares this object and other for equality.
#freeze
#inspect (also: #to_s)

Returns a string containing a detailed summary of the keys and values.
#to_h(&block)

See additional method definition at line 182.
#to_s

Alias for #inspect.
#block_given! private
#raise! private

Other builtin private methods we use:
#set_ostruct_member_value!(name, value) private

Alias for #[]=.
#encode_with(coder) Internal use only

Provides marshalling support for use by the YAML library.
#hash Internal use only

Computes a hash code for this OpenStruct.
#init_with(coder) Internal use only

Provides marshalling support for use by the YAML library.
#marshal_dump Internal use only

Provides marshalling support for use by the Marshal library.
#marshal_load(hash) Internal use only

Alias for #update_to_values!.
#initialize_clone(orig) private Internal use only

Duplicates an OpenStruct object’s Hash table.
#initialize_dup(orig) private Internal use only
#is_method_protected!(name) private Internal use only
#method_missing(mid, *args) private Internal use only
#new_ostruct_member!(name) private Internal use only

Used internally to defined properties on the OpenStruct.
#update_to_values!(hash) (also: #marshal_load) private Internal use only

Constructor Details

.new(hash = nil) ⇒ `OpenStruct`

Creates a new OpenStruct object. By default, the resulting OpenStruct object will have no attributes.

The optional #hash, if given, will generate attributes and values (can be a Hash, an OpenStruct or a Struct). For example:

require "ostruct"
hash = { "country" => "Australia", :capital => "Canberra" }
data = OpenStruct.new(hash)

data   # => #<OpenStruct country="Australia", capital="Canberra">

[ GitHub ]

# File 'lib/ostruct.rb', line 134


def initialize(hash=nil)
  if HAS_PERFORMANCE_WARNINGS && Warning[:performance]
     warn "OpenStruct use is discouraged for performance reasons", uplevel: 1, category: :performance
  end

  if hash
    update_to_values!(hash)
  else
    @table = {}
  end
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(mid, *args) (private)

This method is for internal use only.

[ GitHub ]

# File 'lib/ostruct.rb', line 274


private def method_missing(mid, *args) # :nodoc:
  len = args.length
  if mname = mid[/.*(?==\z)/m]
    if len != 1
      raise! ArgumentError, "wrong number of arguments (given #{len}, expected 1)", caller(1)
    end
    set_ostruct_member_value!(mname, args[0])
  elsif len == 0
    @table[mid]
  else
    begin
      super
    rescue NoMethodError => err
      err.backtrace.shift
      raise!
    end
  end
end

Instance Attribute Details

#table (readonly) Also known as: #table!

This method is for internal use only.

[ GitHub ]

# File 'lib/ostruct.rb', line 406


attr_reader :table # :nodoc:

#table! (readonly, protected)

Alias for #table.

[ GitHub ]

# File 'lib/ostruct.rb', line 407


alias table! table

Instance Method Details

#==(other)

Compares this object and other for equality. An OpenStruct is equal to other when other is an OpenStruct and the two objects’ Hash tables are equal.

require "ostruct"
first_pet  = OpenStruct.new("name" => "Rowdy")
second_pet = OpenStruct.new(:name  => "Rowdy")
third_pet  = OpenStruct.new("name" => "Rowdy", :age => nil)

first_pet == second_pet   # => true
first_pet == third_pet    # => false

[ GitHub ]

# File 'lib/ostruct.rb', line 423


def ==(other)
  return false unless other.kind_of?(OpenStruct)
  @table == other.table!
end

#[](name) ⇒ `Object`

Returns the value of an attribute, or nil if there is no such attribute.

require "ostruct"
person = OpenStruct.new("name" => "John Smith", "age" => 70)
person[:age]   # => 70, same as person.age

[ GitHub ]

# File 'lib/ostruct.rb', line 303


def [](name)
  @table[name.to_sym]
end

#[]=(name, obj) ⇒ `Object` Also known as: #set_ostruct_member_value!

Sets the value of an attribute.

require "ostruct"
person = OpenStruct.new("name" => "John Smith", "age" => 70)
person[:age] = 42   # equivalent to person.age = 42
person.age          # => 42

[ GitHub ]

# File 'lib/ostruct.rb', line 318


def []=(name, value)
  name = name.to_sym
  new_ostruct_member!(name)
  @table[name] = value
end

#block_given! (private)

[ GitHub ]

# File 'lib/ostruct.rb', line 486


alias_method :block_given!, :block_given?

#delete_field(name, &block)

Removes the named field from the object and returns the value the field contained if it was defined. You may optionally provide a block. If the field is not defined, the result of the block is returned, or a NameError is raised if no block was given.

require "ostruct"

person = OpenStruct.new(name: "John", age: 70, pension: 300)

person.delete_field!("age")  # => 70
person                       # => #<OpenStruct name="John", pension=300>

Setting the value to nil will not remove the attribute:

person.pension = nil
person                 # => #<OpenStruct name="John", pension=nil>

person.delete_field('number')  # => NameError

person.delete_field('number') { 8675_309 } # => 8675309

[ GitHub ]

# File 'lib/ostruct.rb', line 371


def delete_field(name, &block)
  sym = name.to_sym
  begin
    singleton_class.remove_method(sym, "#{sym}=")
  rescue NameError
  end
  @table.delete(sym) do
    return yield if block
    raise! NameError.new("no field `#{sym}' in #{self}", sym)
  end
end

#dig(name, *identifiers) ⇒ `Object`

Finds and returns the object in nested objects that is specified by name and identifiers. The nested objects may be instances of various classes. See Dig Methods.

Examples:

require "ostruct"
address = OpenStruct.new("city" => "Anytown NC", "zip" => 12345)
person  = OpenStruct.new("name" => "John Smith", "address" => address)
person.dig(:address, "zip") # => 12345
person.dig(:business_address, "zip") # => nil

[ GitHub ]

# File 'lib/ostruct.rb', line 340


def dig(name, *names)
  begin
    name = name.to_sym
  rescue NoMethodError
    raise! TypeError, "#{name} is not a symbol nor a string"
  end
  @table.dig(name, *names)
end

#each_pair {|name, value| ... } ⇒ `ostruct` #each_pair ⇒ `Enumerator`

Yields all attributes (as symbols) along with the corresponding values or returns an enumerator if no block is given.

require "ostruct"
data = OpenStruct.new("country" => "Australia", :capital => "Canberra")
data.each_pair.to_a   # => [[:country, "Australia"], [:capital, "Canberra"]]

[ GitHub ]

# File 'lib/ostruct.rb', line 211


def each_pair
  return to_enum(__method__) { @table.size } unless defined?(yield)
  @table.each_pair{|p| yield p}
  self
end

#encode_with(coder)

This method is for internal use only.

Provides marshalling support for use by the YAML library.

[ GitHub ]

# File 'lib/ostruct.rb', line 446


def encode_with(coder) # :nodoc:
  @table.each_pair do |key, value|
    coder[key.to_s] = value
  end
  if @table.size == 1 && @table.key?(:table) # support for legacy format
    # in the very unlikely case of a single entry called 'table'
    coder['legacy_support!'] = true # add a bogus second entry
  end
end

#eql?(other) ⇒ `Boolean`

Compares this object and other for equality. An OpenStruct is eql? to other when other is an OpenStruct and the two objects’ Hash tables are eql?.

[ GitHub ]

# File 'lib/ostruct.rb', line 433


def eql?(other)
  return false unless other.kind_of?(OpenStruct)
  @table.eql?(other.table!)
end

#freeze

[ GitHub ]

# File 'lib/ostruct.rb', line 269


def freeze
  @table.freeze
  super
end

#hash

This method is for internal use only.

Computes a hash code for this OpenStruct.

[ GitHub ]

# File 'lib/ostruct.rb', line 439


def hash # :nodoc:
  @table.hash
end

#init_with(coder)

This method is for internal use only.

Provides marshalling support for use by the YAML library.

[ GitHub ]

# File 'lib/ostruct.rb', line 459


def init_with(coder) # :nodoc:
  h = coder.map
  if h.size == 1 # support for legacy format
    key, val = h.first
    if key == 'table'
      h = val
    end
  end
  update_to_values!(h)
end

#initialize_clone(orig) (private)

This method is for internal use only.

Duplicates an OpenStruct object’s Hash table.

[ GitHub ]

# File 'lib/ostruct.rb', line 147


private def initialize_clone(orig) # :nodoc:
  super # clones the singleton class for us
  @table = @table.dup unless @table.frozen?
end

#initialize_dup(orig) (private)

This method is for internal use only.

[ GitHub ]

# File 'lib/ostruct.rb', line 152


private def initialize_dup(orig) # :nodoc:
  super
  update_to_values!(@table)
end

#inspect Also known as: #to_s

Returns a string containing a detailed summary of the keys and values.

[ GitHub ]

# File 'lib/ostruct.rb', line 388


def inspect
  ids = (Thread.current[InspectKey] ||= [])
  if ids.include?(object_id)
    detail = ' ...'
  else
    ids << object_id
    begin
      detail = @table.map do |key, value|
        " #{key}=#{value.inspect}"
      end.join(',')
    ensure
      ids.pop
    end
  end
  ['#<', self.class!, detail, '>'].join
end

#is_method_protected!(name) (private)

This method is for internal use only.

[ GitHub ]

# File 'lib/ostruct.rb', line 251


private def is_method_protected!(name) # :nodoc:
  if !respond_to?(name, true)
    false
  elsif name.match?(/!$/)
    true
  else
    owner = method!(name).owner
    if owner.class == ::Class
      owner < ::OpenStruct
    else
      self.class!.ancestors.any? do |mod|
        return false if mod == ::OpenStruct
        mod == owner
      end
    end
  end
end

#marshal_dump

This method is for internal use only.

Provides marshalling support for use by the Marshal library.

[ GitHub ]

# File 'lib/ostruct.rb', line 220


def marshal_dump # :nodoc:
  @table
end

#marshal_load(hash)

This method is for internal use only.

Alias for #update_to_values!.

[ GitHub ]

# File 'lib/ostruct.rb', line 227


alias_method :marshal_load, :update_to_values! # :nodoc:

#new_ostruct_member!(name) (private)

This method is for internal use only.

Used internally to defined properties on the OpenStruct. It does this by using the metaprogramming function define_singleton_method for both the getter method and the setter method.

[ GitHub ]

# File 'lib/ostruct.rb', line 234


def new_ostruct_member!(name) # :nodoc:
  unless @table.key?(name) || is_method_protected!(name)
    if defined?(::Ractor)
      getter_proc = nil.instance_eval{ Proc.new { @table[name] } }
      setter_proc = nil.instance_eval{ Proc.new {|x| @table[name] = x} }
      ::Ractor.make_shareable(getter_proc)
      ::Ractor.make_shareable(setter_proc)
    else
      getter_proc = Proc.new { @table[name] }
      setter_proc = Proc.new {|x| @table[name] = x}
    end
    define_singleton_method!(name, &getter_proc)
    define_singleton_method!("#{name}=", &setter_proc)
  end
end

#raise! (private)

Other builtin private methods we use:

[ GitHub ]

# File 'lib/ostruct.rb', line 481


alias_method :raise!, :raise

#set_ostruct_member_value!(name, value) (private)

Alias for #[]=.

[ GitHub ]

# File 'lib/ostruct.rb', line 323


alias_method :set_ostruct_member_value!, :[]=

#to_h(&block)

See additional method definition at line 182.

[ GitHub ]

# File 'lib/ostruct.rb', line 190


def to_h(&block)
  if block
    @table.to_h(&block)
  else
    @table.dup
  end
end

#to_s

Alias for #inspect.

[ GitHub ]

# File 'lib/ostruct.rb', line 404


alias :to_s :inspect

#update_to_values!(hash) (private) Also known as: #marshal_load

This method is for internal use only.

[ GitHub ]

# File 'lib/ostruct.rb', line 157


private def update_to_values!(hash) # :nodoc:
  @table = {}
  hash.each_pair do |k, v|
    set_ostruct_member_value!(k, v)
  end
end

Class: OpenStruct

Overview

Examples

Caveats

Constant Summary

Class Method Summary

Instance Attribute Summary

Instance Method Summary

Constructor Details

.new(hash = nil) ⇒ OpenStruct

Dynamic Method Handling

#method_missing(mid, *args) (private)

Instance Attribute Details

#table (readonly) Also known as: #table!

#table! (readonly, protected)

Instance Method Details

#==(other)

#[](name) ⇒ Object

#[]=(name, obj) ⇒ Object Also known as: #set_ostruct_member_value!

#block_given! (private)

#delete_field(name, &block)

#dig(name, *identifiers) ⇒ Object

#each_pair {|name, value| ... } ⇒ ostruct #each_pair ⇒ Enumerator

#encode_with(coder)

#eql?(other) ⇒ Boolean

#freeze

#hash

#init_with(coder)

#initialize_clone(orig) (private)

#initialize_dup(orig) (private)

#inspect Also known as: #to_s

#is_method_protected!(name) (private)

#marshal_dump

#marshal_load(hash)

#new_ostruct_member!(name) (private)

#raise! (private)

#set_ostruct_member_value!(name, value) (private)

#to_h(&block)

#to_s

#update_to_values!(hash) (private) Also known as: #marshal_load

.new(hash = nil) ⇒ `OpenStruct`

#[](name) ⇒ `Object`

#[]=(name, obj) ⇒ `Object` Also known as: #set_ostruct_member_value!

#dig(name, *identifiers) ⇒ `Object`

#each_pair {|name, value| ... } ⇒ `ostruct` #each_pair ⇒ `Enumerator`

#eql?(other) ⇒ `Boolean`