In Files

  • ostruct.rb

Class/Module Index [+]

Quicksearch

OpenStruct

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.pension = 300

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

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

australia = OpenStruct.new(:country => "Australia", :population => 20_000_000)
p australia   # -> <OpenStruct country="Australia" population=20000000>

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

measurements = OpenStruct.new("length (in inches)" => 24)
measurements.send("length (in inches)")  # -> 24

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

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

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

first_pet == second_pet   # -> false

first_pet.delete_field(:owner)
first_pet == second_pet   # -> true

Implementation:

An OpenStruct utilizes Ruby’s method lookup structure to and find and define the necessary methods for properties. This is accomplished through the method method_missing and define_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.

Public Class Methods

new(hash=nil) click to toggle source

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", :population => 20_000_000 }
data = OpenStruct.new(hash)

p data        # -> <OpenStruct country="Australia" population=20000000>
 
               # File ostruct.rb, line 87
def initialize(hash=nil)
  @table = {}
  if hash
    hash.each_pair do |k, v|
      k = k.to_sym
      @table[k] = v
      new_ostruct_member(k)
    end
  end
end
            

Public Instance Methods

==(other) click to toggle source

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.

 
               # File ostruct.rb, line 263
def ==(other)
  return false unless other.kind_of?(OpenStruct)
  @table == other.table
end
            
[](name) click to toggle source

Returns the value of a member.

person = OpenStruct.new('name' => 'John Smith', 'age' => 70)
person[:age] # => 70, same as ostruct.age
 
               # File ostruct.rb, line 196
def [](name)
  @table[name.to_sym]
end
            
[]=(name, value) click to toggle source

Sets the value of a member.

person = OpenStruct.new('name' => 'John Smith', 'age' => 70)
person[:age] = 42 # => equivalent to ostruct.age = 42
person.age # => 42
 
               # File ostruct.rb, line 207
def []=(name, value)
  modifiable[new_ostruct_member(name)] = value
end
            
delete_field(name) click to toggle source

Remove the named field from the object. Returns the value that the field contained if it was defined.

require 'ostruct'

person = OpenStruct.new('name' => 'John Smith', 'age' => 70)

person.delete_field('name')  # => 'John Smith'
 
               # File ostruct.rb, line 221
def delete_field(name)
  sym = name.to_sym
  singleton_class.__send__(:remove_method, sym, "#{name}=")
  @table.delete sym
end
            
each_pair() click to toggle source

Yields all attributes (as a symbol) along with the corresponding values or returns an enumerator if not block is given. Example:

require 'ostruct'
data = OpenStruct.new("country" => "Australia", :population => 20_000_000)
data.each_pair.to_a  # => [[:country, "Australia"], [:population, 20000000]]
 
               # File ostruct.rb, line 127
def each_pair
  return to_enum __method__ unless block_given?
  @table.each_pair{|p| yield p}
end
            
eql?(other) click to toggle source

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

 
               # File ostruct.rb, line 273
def eql?(other)
  return false unless other.kind_of?(OpenStruct)
  @table.eql?(other.table)
end
            
hash() click to toggle source

Compute a hash-code for this OpenStruct. Two hashes with the same content will have the same hash code (and will be eql?).

 
               # File ostruct.rb, line 281
def hash
  @table.hash
end
            
initialize_copy(orig) click to toggle source

Duplicate an OpenStruct object members.

 
               # File ostruct.rb, line 99
def initialize_copy(orig)
  super
  @table = @table.dup
  @table.each_key{|key| new_ostruct_member(key)}
end
            
inspect() click to toggle source

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

 
               # File ostruct.rb, line 232
def inspect
  str = "#<#{self.class}"

  ids = (Thread.current[InspectKey] ||= [])
  if ids.include?(object_id)
    return str << ' ...>'
  end

  ids << object_id
  begin
    first = true
    for k,v in @table
      str << "," unless first
      first = false
      str << " #{k}=#{v.inspect}"
    end
    return str << '>'
  ensure
    ids.pop
  end
end
            
Also aliased as: to_s
marshal_dump() click to toggle source

Provides marshalling support for use by the Marshal library.

 
               # File ostruct.rb, line 135
def marshal_dump
  @table
end
            
marshal_load(x) click to toggle source

Provides marshalling support for use by the Marshal library.

 
               # File ostruct.rb, line 142
def marshal_load(x)
  @table = x
  @table.each_key{|key| new_ostruct_member(key)}
end
            
to_h() click to toggle source

Converts the OpenStruct to a hash with keys representing each attribute (as symbols) and their corresponding values Example:

require 'ostruct'
data = OpenStruct.new("country" => "Australia", :population => 20_000_000)
data.to_h   # => {:country => "Australia", :population => 20000000 }
 
               # File ostruct.rb, line 114
def to_h
  @table.dup
end
            
to_s() click to toggle source
Alias for: inspect

Protected Instance Methods

modifiable() click to toggle source

Used internally to check if the OpenStruct is able to be modified before granting access to the internal Hash table to be modified.

 
               # File ostruct.rb, line 151
def modifiable
  begin
    @modifiable = true
  rescue
    raise TypeError, "can't modify frozen #{self.class}", caller(3)
  end
  @table
end
            
new_ostruct_member(name) click to toggle source

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.

 
               # File ostruct.rb, line 166
def new_ostruct_member(name)
  name = name.to_sym
  unless respond_to?(name)
    define_singleton_method(name) { @table[name] }
    define_singleton_method("#{name}=") { |x| modifiable[name] = x }
  end
  name
end
            

Commenting is here to help enhance the documentation. For example, code samples, or clarification of the documentation.

If you have questions about Ruby or the documentation, please post to one of the Ruby mailing lists. You will get better, faster, help that way.

If you wish to post a correction of the docs, please do so, but also file bug report so that it can be corrected for the next release. Thank you.

If you want to help improve the Ruby documentation, please visit Documenting-ruby.org.

blog comments powered by Disqus