ostruct 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d125c51b4a6541c0dcb5422065b685c156e847218380e2c01f1ef8fac08e40dc
-  data.tar.gz: 7c5aa451998687071f22794e2e24ea644e7a6698e4eebe608ccd42a6cdf3199c
+  metadata.gz: 44161760b6aef61a50eddb473940b3a23c75682afbd4e9573124ee4ae0afbf50
+  data.tar.gz: 757b50ba4015029f3fcacaa00e94b685eff032d65ea894e0523de585903e3775
 SHA512:
-  metadata.gz: c58234c3f25e5eee4f47faf91c0016051e9bd72016d38a54248b1695424016d4cb46be9a09ef29837cd268cac57f0c7eebe1e5c330d218c580b304f1210764bc
-  data.tar.gz: 3698d2ab77b8c9904b43143795226e9f3abce36a55fc2923fc7ed65f4cf48d60790ec55e2f43d6bfb75c0f010aa23b32c08d73c00f6468420f4fc8131dce22dc
+  metadata.gz: e8020aad504a528f4b6bb3abd3b9a6993d9abbbdd3bb6e1306c3e33d21d5628a5119d78b4b749ae44cf98ed2bc707a9012f38ea1eb0a378e16b9db384af84dd3
+  data.tar.gz: 7201f711580ee6590ba6598328a611cea8ef82cd4b2cba636b2b684c0d01e2a52baff2494ac2428b0b3998b8f11ef0fc766025526310bd74ad15ebbf302d61f4

data/README.md

@@ -1,6 +1,6 @@
-# OpenStruct
+# OpenStruct [![Version](https://badge.fury.io/rb/ostruct.svg)](https://badge.fury.io/rb/ostruct) [![Default Gem](https://img.shields.io/badge/stdgem-default-9c1260.svg)](https://stdgems.org/ostruct/) [![Test](https://github.com/ruby/ostruct/workflows/test/badge.svg)](https://github.com/ruby/ostruct/actions?query=workflow%3Atest)
 
-An OpenStruct is a data structure, similar to a Hash, that allows the definition of arbitrary attributes with their ccompanying values. This is accomplished by using Ruby's metaprogramming to define methods on the class itself.
+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.
 
 ## Installation
 

data/lib/ostruct.rb

@@ -36,9 +36,10 @@
 # Hash keys with spaces or characters that could normally not be used for
 # method calls (e.g. <code>()[]*</code>) 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.
+# 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)
@@ -61,8 +62,9 @@
 #   first_pet                 # => #<OpenStruct name="Rowdy">
 #   first_pet == second_pet   # => true
 #
+# Ractor compatibility: A frozen OpenStruct with shareable values is itself shareable.
 #
-# == Implementation
+# == Caveats
 #
 # An OpenStruct utilizes Ruby's method lookup structure to find and define the
 # necessary methods for properties. This is accomplished through the methods
@@ -71,8 +73,41 @@
 # 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.
 #
 class OpenStruct
+  VERSION = "0.3.0"
 
   #
   # Creates a new OpenStruct object.  By default, the resulting OpenStruct
@@ -89,31 +124,64 @@ class OpenStruct
   #   data   # => #<OpenStruct country="Australia", capital="Canberra">
   #
   def initialize(hash=nil)
-    @table = {}
     if hash
-      hash.each_pair do |k, v|
-        k = k.to_sym
-        @table[k] = v
-      end
+      update_to_values!(hash)
+    else
+      @table = {}
     end
   end
 
   # Duplicates an OpenStruct object's Hash table.
-  def initialize_copy(orig) # :nodoc:
+  private def initialize_clone(orig) # :nodoc:
+    super # clones the singleton class for us
+    @table = @table.dup unless @table.frozen?
+  end
+
+  private def initialize_dup(orig) # :nodoc:
     super
-    @table = @table.dup
+    update_to_values!(@table)
+  end
+
+  private def update_to_values!(hash) # :nodoc:
+    @table = {}
+    hash.each_pair do |k, v|
+      set_ostruct_member_value!(k, v)
+    end
   end
 
+  #
+  # call-seq:
+  #   ostruct.to_h                        -> hash
+  #   ostruct.to_h {|name, value| block } -> hash
   #
   # Converts the OpenStruct to a hash with keys representing
   # each attribute (as symbols) and their corresponding values.
   #
+  # If a block is given, the results of the block on each pair of
+  # the receiver will be used as pairs.
+  #
   #   require "ostruct"
   #   data = OpenStruct.new("country" => "Australia", :capital => "Canberra")
   #   data.to_h   # => {:country => "Australia", :capital => "Canberra" }
-  #
-  def to_h
-    @table.dup
+  #   data.to_h {|name, value| [name.to_s, value.upcase] }
+  #               # => {"country" => "AUSTRALIA", "capital" => "CANBERRA" }
+  #
+  if {test: :to_h}.to_h{ [:works, true] }[:works] # RUBY_VERSION < 2.6 compatibility
+    def to_h(&block)
+      if block
+        @table.to_h(&block)
+      else
+        @table.dup
+      end
+    end
+  else
+    def to_h(&block)
+      if block
+        @table.map(&block).to_h
+      else
+        @table.dup
+      end
+    end
   end
 
   #
@@ -137,83 +205,60 @@ class OpenStruct
   #
   # Provides marshalling support for use by the Marshal library.
   #
-  def marshal_dump
+  def marshal_dump # :nodoc:
     @table
   end
 
   #
   # Provides marshalling support for use by the Marshal library.
   #
-  def marshal_load(x)
+  def marshal_load(x) # :nodoc:
+    x.each_key{|key| new_ostruct_member!(key)}
     @table = x
   end
 
-  #
-  # Used internally to check if the OpenStruct is able to be
-  # modified before granting access to the internal Hash table to be modified.
-  #
-  def modifiable? # :nodoc:
-    begin
-      @modifiable = true
-    rescue
-      exception_class = defined?(FrozenError) ? FrozenError : RuntimeError
-      raise exception_class, "can't modify frozen #{self.class}", caller(3)
-    end
-    @table
-  end
-  private :modifiable?
-
-  # ::Kernel.warn("do not use OpenStruct#modifiable", uplevel: 1)
-  alias modifiable modifiable? # :nodoc:
-  protected :modifiable
-
   #
   # 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.
   #
   def new_ostruct_member!(name) # :nodoc:
-    name = name.to_sym
-    unless singleton_class.method_defined?(name)
-      define_singleton_method(name) { @table[name] }
-      define_singleton_method("#{name}=") {|x| modifiable?[name] = x}
+    unless @table.key?(name) || is_method_protected!(name)
+      define_singleton_method!(name) { @table[name] }
+      define_singleton_method!("#{name}=") {|x| @table[name] = x}
     end
-    name
   end
   private :new_ostruct_member!
 
-  # ::Kernel.warn("do not use OpenStruct#new_ostruct_member", uplevel: 1)
-  alias new_ostruct_member new_ostruct_member! # :nodoc:
-  protected :new_ostruct_member
+  private def is_method_protected!(name) # :nodoc:
+    if !respond_to?(name, true)
+      false
+    elsif name.match?(/!$/)
+      true
+    else
+      method!(name).owner < OpenStruct
+    end
+  end
 
   def freeze
-    @table.each_key {|key| new_ostruct_member!(key)}
+    @table.freeze
     super
   end
 
-  def respond_to_missing?(mid, include_private = false) # :nodoc:
-    mname = mid.to_s.chomp("=").to_sym
-    @table&.key?(mname) || super
-  end
-
-  def method_missing(mid, *args) # :nodoc:
+  private def method_missing(mid, *args) # :nodoc:
     len = args.length
     if mname = mid[/.*(?==\z)/m]
       if len != 1
-        raise ArgumentError, "wrong number of arguments (#{len} for 1)", caller(1)
-      end
-      modifiable?[new_ostruct_member!(mname)] = args[0]
-    elsif len == 0 # and /\A[a-z_]\w*\z/ =~ mid #
-      if @table.key?(mid)
-        new_ostruct_member!(mid) unless frozen?
-        @table[mid]
+        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
+        raise!
       end
     end
   end
@@ -222,7 +267,7 @@ class OpenStruct
   # :call-seq:
   #   ostruct[name]  -> object
   #
-  # Returns the value of an attribute.
+  # Returns the value of an attribute, or `nil` if there is no such attribute.
   #
   #   require "ostruct"
   #   person = OpenStruct.new("name" => "John Smith", "age" => 70)
@@ -244,34 +289,32 @@ class OpenStruct
   #   person.age          # => 42
   #
   def []=(name, value)
-    modifiable?[new_ostruct_member!(name)] = value
+    name = name.to_sym
+    new_ostruct_member!(name)
+    @table[name] = value
   end
+  alias_method :set_ostruct_member_value!, :[]=
+  private :set_ostruct_member_value!
 
-  #
   # :call-seq:
-  #   ostruct.dig(name, ...)  -> object
+  #   ostruct.dig(name, *identifiers) -> object
   #
-  # 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+.
+  # 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}[rdoc-ref:doc/dig_methods.rdoc].
   #
+  # 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
-  #
-  #   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
-  #
+  #   person.dig(:address, "zip") # => 12345
+  #   person.dig(:business_address, "zip") # => nil
   def dig(name, *names)
     begin
       name = name.to_sym
     rescue NoMethodError
-      raise TypeError, "#{name} is not a symbol nor a string"
+      raise! TypeError, "#{name} is not a symbol nor a string"
     end
     @table.dig(name, *names)
   end
@@ -284,7 +327,7 @@ class OpenStruct
   #
   #   person = OpenStruct.new(name: "John", age: 70, pension: 300)
   #
-  #   person.delete_field("age")   # => 70
+  #   person.delete_field!("age")  # => 70
   #   person                       # => #<OpenStruct name="John", pension=300>
   #
   # Setting the value to +nil+ will not remove the attribute:
@@ -299,7 +342,7 @@ class OpenStruct
     rescue NameError
     end
     @table.delete(sym) do
-      raise NameError.new("no field `#{sym}' in #{self}", sym)
+      raise! NameError.new("no field `#{sym}' in #{self}", sym)
     end
   end
 
@@ -322,13 +365,13 @@ class OpenStruct
         ids.pop
       end
     end
-    ['#<', self.class, detail, '>'].join
+    ['#<', self.class!, detail, '>'].join
   end
   alias :to_s :inspect
 
   attr_reader :table # :nodoc:
-  protected :table
   alias table! table
+  protected :table!
 
   #
   # Compares this object and +other+ for equality.  An OpenStruct is equal to
@@ -359,11 +402,43 @@ class OpenStruct
   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.
-  def hash
+  def hash # :nodoc:
     @table.hash
   end
+
+  #
+  # Provides marshalling support for use by the YAML library.
+  #
+  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
+
+  #
+  # Provides marshalling support for use by the YAML library.
+  #
+  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
+
+  # Make all public methods (builtin or our own) accessible with `!`:
+  instance_methods.each do |method|
+    new_name = "#{method}!"
+    alias_method new_name, method
+  end
+  # Other builtin private methods we use:
+  alias_method :raise!, :raise
+  private :raise!
 end

data/ostruct.gemspec

@@ -1,8 +1,15 @@
 # frozen_string_literal: true
 
+name = File.basename(__FILE__, ".gemspec")
+version = ["lib", Array.new(name.count("-")+1, "..").join("/")].find do |dir|
+  break File.foreach(File.join(__dir__, dir, "#{name.tr('-', '/')}.rb")) do |line|
+    /^\s*VERSION\s*=\s*"(.*)"/ =~ line and break $1
+  end rescue nil
+end
+
 Gem::Specification.new do |spec|
-  spec.name          = "ostruct"
-  spec.version       = "0.1.0"
+  spec.name          = name
+  spec.version       = version
   spec.authors       = ["Marc-Andre Lafortune"]
   spec.email         = ["ruby-core@marc-andre.ca"]
 
@@ -10,8 +17,9 @@ Gem::Specification.new do |spec|
   spec.description   = %q{Class to build custom data structures, similar to a Hash.}
   spec.homepage      = "https://github.com/ruby/ostruct"
   spec.license       = "BSD-2-Clause"
+  spec.required_ruby_version = ">= 2.5.0"
 
-  spec.files         = [".gitignore", ".travis.yml", "Gemfile", "LICENSE.txt", "README.md", "Rakefile", "bin/console", "bin/setup", "lib/ostruct.rb", "ostruct.gemspec"]
+  spec.files         = [".gitignore", "Gemfile", "LICENSE.txt", "README.md", "Rakefile", "bin/console", "bin/setup", "lib/ostruct.rb", "ostruct.gemspec"]
   spec.bindir        = "exe"
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ostruct
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Marc-Andre Lafortune
-autorequire: 
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2018-12-04 00:00:00.000000000 Z
+date: 2020-09-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -46,7 +46,6 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".gitignore"
-- ".travis.yml"
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -59,7 +58,7 @@ homepage: https://github.com/ruby/ostruct
 licenses:
 - BSD-2-Clause
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -67,16 +66,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 2.5.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.6
-signing_key: 
+rubygems_version: 3.0.8
+signing_key:
 specification_version: 4
 summary: Class to build custom data structures, similar to a Hash.
 test_files: []

data/.travis.yml

@@ -1,6 +0,0 @@
-sudo: false
-language: ruby
-rvm:
-  - 2.5.1
-  - ruby-head
-before_install: gem install bundler -v 1.15.4