OpenStruct

class OpenStruct

Parent:: Object

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

json_create(object) Show source

Deserializes JSON string by constructing new Struct object with values t serialized by to_json.

# File ext/json/lib/json/add/ostruct.rb, line 11
def self.json_create(object)
  new(object['t'] || object[:t])
end

new(hash=nil) Show 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 lib/ostruct.rb, line 91
def initialize(hash=nil)
  @table = {}
  if hash
    hash.each_pair do |k, v|
      k = k.to_sym
      @table[k] = v
    end
  end
end

Public Instance Methods

==(other) Show 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 lib/ostruct.rb, line 311
def ==(other)
  return false unless other.kind_of?(OpenStruct)
  @table == other.table!
end

[](name) Show source

Returns the value of a member.

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

# File lib/ostruct.rb, line 220
def [](name)
  @table[name.to_sym]
end

[]=(name, value) Show 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 lib/ostruct.rb, line 231
def []=(name, value)
  modifiable?[new_ostruct_member!(name)] = value
end

as_json(*) Show source

Returns a hash, that will be turned into a JSON object and represent this object.

# File ext/json/lib/json/add/ostruct.rb, line 17
def as_json(*)
  klass = self.class.name
  klass.to_s.empty? and raise JSON::JSONError, "Only named structs are supported!"
  {
    JSON.create_id => klass,
    't'            => table,
  }
end

delete_field(name) Show 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 lib/ostruct.rb, line 263
def delete_field(name)
  sym = name.to_sym
  begin
    singleton_class.__send__(:remove_method, sym, "#{sym}=")
  rescue NameError
  end
  @table.delete(sym) do
    raise NameError.new("no field `#{sym}' in #{self}", sym)
  end
end

dig(name, *names) Show source

Retrieves the value object corresponding to the each name objects repeatedly.

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

# File lib/ostruct.rb, line 244
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() { |p| ... } Show 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 lib/ostruct.rb, line 129
def each_pair
  return to_enum(__method__) { @table.size } unless block_given?
  @table.each_pair{|p| yield p}
  self
end

eql?(other) Show 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 lib/ostruct.rb, line 321
def eql?(other)
  return false unless other.kind_of?(OpenStruct)
  @table.eql?(other.table!)
end

freeze() Show source

Calls superclass method Object#freeze

# File lib/ostruct.rb, line 186
def freeze
  @table.each_key {|key| new_ostruct_member!(key)}
  super
end

hash() Show 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 lib/ostruct.rb, line 329
def hash
  @table.hash
end

initialize_copy(orig) Show source

Duplicate an OpenStruct object members.

Calls superclass method

# File lib/ostruct.rb, line 102
def initialize_copy(orig)
  super
  @table = @table.dup
end

inspect() Show source

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

# File lib/ostruct.rb, line 279
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() Show source

Provides marshalling support for use by the Marshal library.

# File lib/ostruct.rb, line 138
def marshal_dump
  @table
end

marshal_load(x) Show source

Provides marshalling support for use by the Marshal library.

# File lib/ostruct.rb, line 145
def marshal_load(x)
  @table = x
end

respond_to_missing?(mid, include_private = false) Show source

Calls superclass method Object#respond_to_missing?

# File lib/ostruct.rb, line 191
def respond_to_missing?(mid, include_private = false)
  mname = mid.to_s.chomp("=").to_sym
  @table.key?(mname) || super
end

to_h() Show 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 lib/ostruct.rb, line 116
def to_h
  @table.dup
end

to_json(*args) Show source

Stores class name (OpenStruct) with this struct's values v as a JSON string.

# File ext/json/lib/json/add/ostruct.rb, line 28
def to_json(*args)
  as_json.to_json(*args)
end

to_s()

Alias for: inspect

Ruby Core © 1993–2017 Yukihiro Matsumoto
Licensed under the Ruby License.
Ruby Standard Library © contributors
Licensed under their own licenses.