Class: OpenStruct
- Inherits:
-
Object
- Object
- OpenStruct
- 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
= OpenStruct.new(:queued? => true)
.queued? # => true
.send("queued?=", false)
.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 collapse
- VERSION =
"0.3.0"
- InspectKey =
:nodoc:
:__inspect_key__
Instance Attribute Summary collapse
-
#table ⇒ Object
(also: #table!)
readonly
:nodoc:.
Instance Method Summary collapse
-
#==(other) ⇒ Object
Compares this object and
other
for equality. -
#[](name) ⇒ Object
:call-seq: ostruct -> object.
-
#[]=(name, value) ⇒ Object
(also: #set_ostruct_member_value!)
:call-seq: ostruct = obj -> obj.
-
#delete_field(name) ⇒ Object
Removes the named field from the object.
-
#dig(name, *names) ⇒ Object
:call-seq: ostruct.dig(name, *identifiers) -> object.
-
#each_pair ⇒ Object
:call-seq: ostruct.each_pair {|name, value| block } -> ostruct ostruct.each_pair -> Enumerator.
-
#encode_with(coder) ⇒ Object
Provides marshalling support for use by the YAML library.
-
#eql?(other) ⇒ Boolean
Compares this object and
other
for equality. - #freeze ⇒ Object
-
#hash ⇒ Object
Computes a hash code for this OpenStruct.
-
#init_with(coder) ⇒ Object
Provides marshalling support for use by the YAML library.
-
#initialize(hash = nil) ⇒ OpenStruct
constructor
Creates a new OpenStruct object.
-
#inspect ⇒ Object
(also: #to_s)
Returns a string containing a detailed summary of the keys and values.
-
#marshal_dump ⇒ Object
Provides marshalling support for use by the Marshal library.
-
#marshal_load(x) ⇒ Object
Provides marshalling support for use by the Marshal library.
- #to_h(&block) ⇒ Object
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">
126 127 128 129 130 131 132 |
# File 'lib/ostruct.rb', line 126 def initialize(hash=nil) 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:
248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 |
# File 'lib/ostruct.rb', line 248 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 else begin super rescue NoMethodError => err err.backtrace.shift raise! end end end |
Instance Attribute Details
#table ⇒ Object (readonly) Also known as: table!
:nodoc:
372 373 374 |
# File 'lib/ostruct.rb', line 372 def table @table 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
389 390 391 392 |
# File 'lib/ostruct.rb', line 389 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
276 277 278 |
# File 'lib/ostruct.rb', line 276 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
291 292 293 294 295 |
# File 'lib/ostruct.rb', line 291 def []=(name, value) name = name.to_sym new_ostruct_member!(name) @table[name] = value end |
#delete_field(name) ⇒ Object
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>
338 339 340 341 342 343 344 345 346 347 |
# File 'lib/ostruct.rb', line 338 def delete_field(name) sym = name.to_sym begin singleton_class.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) ⇒ 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
313 314 315 316 317 318 319 320 |
# File 'lib/ostruct.rb', line 313 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"]]
199 200 201 202 203 |
# File 'lib/ostruct.rb', line 199 def each_pair return to_enum(__method__) { @table.size } unless block_given? @table.each_pair{|p| yield p} self end |
#encode_with(coder) ⇒ Object
Provides marshalling support for use by the YAML library.
412 413 414 415 416 417 418 419 420 |
# File 'lib/ostruct.rb', line 412 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?.
399 400 401 402 |
# File 'lib/ostruct.rb', line 399 def eql?(other) return false unless other.kind_of?(OpenStruct) @table.eql?(other.table!) end |
#freeze ⇒ Object
243 244 245 246 |
# File 'lib/ostruct.rb', line 243 def freeze @table.freeze super end |
#hash ⇒ Object
Computes a hash code for this OpenStruct.
405 406 407 |
# File 'lib/ostruct.rb', line 405 def hash # :nodoc: @table.hash end |
#init_with(coder) ⇒ Object
Provides marshalling support for use by the YAML library.
425 426 427 428 429 430 431 432 433 434 |
# File 'lib/ostruct.rb', line 425 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.
354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 |
# File 'lib/ostruct.rb', line 354 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.
208 209 210 |
# File 'lib/ostruct.rb', line 208 def marshal_dump # :nodoc: @table end |
#marshal_load(x) ⇒ Object
Provides marshalling support for use by the Marshal library.
215 216 217 218 |
# File 'lib/ostruct.rb', line 215 def marshal_load(x) # :nodoc: x.each_key{|key| new_ostruct_member!(key)} @table = x end |
#to_h(&block) ⇒ Object
170 171 172 173 174 175 176 |
# File 'lib/ostruct.rb', line 170 def to_h(&block) if block @table.to_h(&block) else @table.dup end end |