ruby / 2.5.3 / openstruct.html /

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

measurements = OpenStruct.new("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

Implementation

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.

Public Class Methods

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

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

new (hash=nil) Show source
# File lib/ostruct.rb, line 90
def initialize(hash=nil)
  @table = {}
  if hash
    hash.each_pair do |k, v|
      k = k.to_sym
      @table[k] = v
    end
  end
end

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

Public Instance Methods

== (other) Show source
# File lib/ostruct.rb, line 344
def ==(other)
  return false unless other.kind_of?(OpenStruct)
  @table == other.table!
end

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
ostruct[name] → object Show source
# File lib/ostruct.rb, line 229
def [](name)
  @table[name.to_sym]
end

Returns the value of an attribute.

require "ostruct"
person = OpenStruct.new("name" => "John Smith", "age" => 70)
person[:age]   # => 70, same as person.age
ostruct[name] = obj → obj Show source
# File lib/ostruct.rb, line 244
def []=(name, value)
  modifiable?[new_ostruct_member!(name)] = value
end

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
as_json (*) Show source
# 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

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

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

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

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>
dig(name, ...) → object Show source
# File lib/ostruct.rb, line 268
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

Extracts the nested value specified by the sequence of name objects by calling dig at each step, returning nil if any intermediate step is nil.

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

data = OpenStruct.new(:array => [1, [2, 3]])

data.dig(:array, 1, 0)   # => 2
data.dig(:array, 0, 0)   # TypeError: Integer does not have #dig method
each_pair {|name, value| block } → ostruct Show source
each_pair → Enumerator
# File lib/ostruct.rb, line 130
def each_pair
  return to_enum(__method__) { @table.size } unless block_given?
  @table.each_pair{|p| yield p}
  self
end

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

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

freeze () Show source
# File lib/ostruct.rb, line 187
def freeze
  @table.each_key {|key| new_ostruct_member!(key)}
  super
end
Calls superclass method Object#freeze
hash () Show source
# File lib/ostruct.rb, line 364
def hash
  @table.hash
end

Computes a hash code for this OpenStruct. Two OpenStruct objects with the same content will have the same hash code (and will compare using eql?).

See also Object#hash.

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

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

Also aliased as: to_s
marshal_dump () Show source
# File lib/ostruct.rb, line 139
def marshal_dump
  @table
end

Provides marshalling support for use by the Marshal library.

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

Provides marshalling support for use by the Marshal library.

to_h () Show source
# File lib/ostruct.rb, line 114
def to_h
  @table.dup
end

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

require "ostruct"
data = OpenStruct.new("country" => "Australia", :capital => "Canberra")
data.to_h   # => {:country => "Australia", :capital => "Canberra" }
to_json (*args) Show source
# File ext/json/lib/json/add/ostruct.rb, line 28
def to_json(*args)
  as_json.to_json(*args)
end

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

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.