Class: OpenStruct

Inherits:
Object show all
Defined in:
lib/ostruct.rb,
ext/json/lib/json/add/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.

Direct Known Subclasses

JSON::GenericObject

Constant Summary collapse

VERSION = 
"0.6.0"
InspectKey =

:nodoc:

:__inspect_key__

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(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">



134
135
136
137
138
139
140
141
142
143
144
 
# 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) ⇒ Object (private)

:nodoc:



274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
 
# 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 ⇒ Object (readonly) Also known as: table!

:nodoc:



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

def table
  @table
end

Class Method Details

.json_create(object) ⇒ Object

See #as_json.



13
14
15
 
# File 'ext/json/lib/json/add/ostruct.rb', line 13

def self.json_create(object)
  new(object['t'] || object[:t])
end

Instance Method Details

#==(other) ⇒ Object

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



423
424
425
426
 
# File 'lib/ostruct.rb', line 423

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

#[](name) ⇒ Object

:call-seq:

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



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

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

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

:call-seq:

ostruct[name] = obj  -> obj

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



318
319
320
321
322
 
# File 'lib/ostruct.rb', line 318

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

#as_json ⇒ Object

Methods OpenStruct#as_json and OpenStruct.json_create may be used to serialize and deserialize a OpenStruct object; see Marshal.

Method OpenStruct#as_json serializes self, returning a 2-element hash representing self:

require 'json/add/ostruct'
x = OpenStruct.new('name' => 'Rowdy', :age => nil).as_json
# => {"json_class"=>"OpenStruct", "t"=>{:name=>'Rowdy', :age=>nil}}

Method JSON.create deserializes such a hash, returning a OpenStruct object:

OpenStruct.json_create(x)
# => #<OpenStruct name='Rowdy', age=nil>



33
34
35
36
37
38
39
40
 
# File 'ext/json/lib/json/add/ostruct.rb', line 33

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, &block) ⇒ Object

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



371
372
373
374
375
376
377
378
379
380
381
 
# 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, *names) ⇒ Object

:call-seq:

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



340
341
342
343
344
345
346
347
 
# 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 ⇒ Object

:call-seq:

ostruct.each_pair {|name, value| block }  -> ostruct
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"]]



211
212
213
214
215
 
# 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) ⇒ Object

Provides marshalling support for use by the YAML library.



446
447
448
449
450
451
452
453
454
 
# 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?.

Returns:

  • (Boolean) 


433
434
435
436
 
# File 'lib/ostruct.rb', line 433

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

#freeze ⇒ Object 



269
270
271
272
 
# File 'lib/ostruct.rb', line 269

def freeze
  @table.freeze
  super
end

#hash ⇒ Object

Computes a hash code for this OpenStruct.



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

def hash # :nodoc:
  @table.hash
end

#init_with(coder) ⇒ Object

Provides marshalling support for use by the YAML library.



459
460
461
462
463
464
465
466
467
468
 
# 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

#inspect ⇒ Object Also known as: to_s

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



388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
 
# 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

#marshal_dump ⇒ Object

Provides marshalling support for use by the Marshal library.



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

def marshal_dump # :nodoc:
  @table
end

#to_h(&block) ⇒ Object 



182
183
184
185
186
187
188
 
# File 'lib/ostruct.rb', line 182

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

#to_json(*args) ⇒ Object

Returns a JSON string representing self:

require 'json/add/ostruct'
puts OpenStruct.new('name' => 'Rowdy', :age => nil).to_json

Output:

{"json_class":"OpenStruct","t":{'name':'Rowdy',"age":null}}



51
52
53
 
# File 'ext/json/lib/json/add/ostruct.rb', line 51

def to_json(*args)
  as_json.to_json(*args)
end