ryo.rb 0.5.5 → 0.5.7

data/lib/ryo/json.rb

@@ -1,45 +1,40 @@
 # frozen_string_literal: true
 
 ##
-# The {Ryo::JSON Ryo::JSON} module provides a number of methods
-# for coercing JSON data into a Ryo object. It must be required
-# separately to Ryo (ie: require "ryo/json"), and the methods of
-# this module are then available on the {Ryo Ryo} module.
+# The {Ryo::JSON Ryo::JSON} module provides a number of options
+# for coercing JSON data into a Ryo object. The methods of
+# this module are available on the {Ryo Ryo} module as singleton
+# methods
 module Ryo::JSON
-  require "json"
   extend self
 
   ##
   # @example
   #   Ryo.from_json(path: "/foo/bar/baz.json")
   #   Ryo.from_json(string: "[]")
-  #
   # @param [String] path
   #  The path to a JSON file
-  #
   # @param [String] string
   #  A blob of JSON
-  #
   # @param [Ryo] object
   #  {Ryo::Object Ryo::Object}, or {Ryo::BasicObject Ryo::BasicObject}
   #  Defaults to {Ryo::Object Ryo::Object}
-  #
   # @raise [SystemCallError]
   #  Might raise a number of Errno exceptions
-  #
   # @return [Ryo::Object, Ryo::BasicObject]
   #  Returns a Ryo object
   def from_json(path: nil, string: nil, object: Ryo::Object)
     if path && string
       raise ArgumentError, "Provide a path or string but not both"
     elsif path
+      require "json" unless defined?(JSON)
       object.from JSON.parse(File.binread(path))
     elsif string
+      require "json" unless defined?(JSON)
       object.from JSON.parse(string)
     else
       raise ArgumentError, "No path or string provided"
     end
   end
-
   Ryo.extend(self)
 end

data/lib/ryo/keywords.rb

@@ -2,8 +2,8 @@
 
 ##
 # The {Ryo::Keywords Ryo::Keywords} module implements Ryo equivalents
-# to some of JavaScript's keywords - for example: the **in** and **delete**
-# operators. The instance methods of this module are available as singleton
+# for some of JavaScript's keywords (eg: the **in** and **delete** operators).
+# The instance methods of this module are available as singleton
 # methods on the {Ryo} module.
 module Ryo::Keywords
   ##
@@ -24,44 +24,32 @@ module Ryo::Keywords
   alias_method :function, :fn
 
   ##
-  # Equivalent to JavaScript's **in** operator.
-  #
+  # Equivalent to JavaScript's **in** operator
   # @param [<Ryo::Object, Ryo::BasicObject>] ryo
-  #  A Ryo object.
-  #
+  #  A Ryo object
   # @param [<String, #to_s>] property
-  #  A property name.
-  #
+  #  A property name
   # @return [Boolean]
-  #  Returns true when **property** is a member of **ryo**, or its prototype chain.
+  #  Returns true when **property** is a member of **ryo**, or its prototype chain
   def in?(ryo, property)
     return false unless ryo
     property?(ryo, property) || in?(prototype_of(ryo), property)
   end
 
   ##
-  # The {#delete} method deletes a property from a Ryo object.
-  # More or less equivalent to JavaScript's "delete" operator.
-  #
-  # @note
-  #  This method does not delete properties from the prototype(s)
-  #  of a Ryo object. <br>
-  #  For that - see {Ryo::Reflect#delete! Ryo::Reflect#delete!}.
-  #
+  # The {#delete} method deletes a property from a Ryo object
+  # @see Ryo::Reflect#delete!
   # @param [<Ryo::Object, Ryo::BasicObject>] ryo
-  #  A Ryo object.
-  #
+  #  A Ryo object
   # @param [<String, #to_s>] property
-  #  A property name.
-  #
+  #  A property name
+  # @param [Integer] ancestors
+  #  The number of prototypes to traverse.
+  #  Defaults to the entire prototype chain.
   # @return [void]
-  def delete(ryo, property)
-    property = property.to_s
-    if property?(ryo, property)
-      table_of(ryo).delete(property)
-    else
-      return if getter_defined?(ryo, property)
-      define_method!(ryo, property) { ryo[property] }
+  def delete(ryo, property, ancestors: nil)
+    each_ryo(ryo, ancestors:) do
+      Ryo.property?(_1, property) ? table_of(_1).delete(property) : nil
     end
   end
 end

data/lib/ryo/object.rb

@@ -10,19 +10,17 @@ class Ryo::Object
   ##
   # @param props (see Ryo::Builder.build)
   # @param prototype (see Ryo::Builder.build)
-  #
   # @return [Ryo::Object]
-  #  Returns an instance of {Ryo::Object Ryo::Object}.
+  #  Returns an instance of {Ryo::Object Ryo::Object}
   def self.create(props, prototype = nil)
     Ryo::Builder.build(self, props, prototype)
   end
 
   ##
-  # Creates a Ryo object by recursively walking a Hash object.
+  # Creates a Ryo object by recursively walking a Hash object
   #
   # @param props (see Ryo::Builder.recursive_build)
   # @param prototype (see Ryo::Builder.recursive_build)
-  #
   # @return [Ryo::Object]
   #  Returns an instance of {Ryo::Object Ryo::Object}.
   def self.from(props, prototype = nil)
@@ -30,13 +28,12 @@ class Ryo::Object
   end
 
   ##
-  # Duplicates the internals of a Ryo object.
+  # Duplicates the internals of a Ryo object
   #
   # @param [Ryo::Object] ryo
-  #  A Ryo object.
-  #
+  #  A Ryo object
   # @return [Ryo::Object]
-  #  Returns a Ryo object.
+  #  Returns a Ryo object
   def initialize_dup(ryo)
     Ryo.set_table_of(self, Ryo.table_of(ryo).dup)
     Ryo.extend!(self, Ryo)
@@ -50,9 +47,8 @@ end
 #
 # @param props (see Ryo::Builder.build)
 # @param prototype (see Ryo::Builder.build)
-#
 # @return [Ryo::Object]
-#   Returns an instance of {Ryo::Object Ryo::Object}.
+#   Returns an instance of {Ryo::Object Ryo::Object}
 def Ryo.Object(props, prototype = nil)
   Ryo::Object.create(props, prototype)
 end

data/lib/ryo/reflect.rb

@@ -1,14 +1,16 @@
 # frozen_string_literal: true
 
 ##
-# The {Ryo::Reflect Ryo::Reflect} module implements equivalents
-# from JavaScript's [`Relfect` object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Reflect),
-# and equivalents for some of the static methods on JavaScript's
-# [`Object`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) constructor.
+# The {Ryo::Reflect Ryo::Reflect} module mirrors
+# JavaScript's [`Relfect` object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Reflect),
+# and some of the static methods on JavaScript's
+# [`Object`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)
+# as well.
 #
-# This module also implements Ryo-specific reflection features as well. The
-# instance methods of this module are available as singleton methods
-# on the {Ryo Ryo} module.
+# {Ryo::Reflect Ryo::Reflect} also implements Ryo-specific
+# reflection features. The instance methods of this module
+# are available as singleton methods on the {Ryo Ryo}
+# module.
 module Ryo::Reflect
   extend self
 
@@ -16,7 +18,7 @@ module Ryo::Reflect
   # @group JavaScript equivalents (Reflect)
 
   ##
-  # Equivalent to JavaScript's `Reflect.getPrototypeOf`.
+  # Equivalent to JavaScript's `Reflect.getPrototypeOf`
   #
   # @param [Ryo] ryo
   #  A Ryo object.
@@ -29,7 +31,7 @@ module Ryo::Reflect
   end
 
   ##
-  # Equivalent to JavaScript's `Reflect.setPrototypeOf`.
+  # Equivalent to JavaScript's `Reflect.setPrototypeOf`
   #
   # @param [Ryo] ryo
   #  A Ryo object.
@@ -45,17 +47,14 @@ module Ryo::Reflect
   end
 
   ##
-  # Equivalent to JavaScript's `Reflect.defineProperty`.
+  # Equivalent to JavaScript's `Reflect.defineProperty`
   #
   # @param [<Ryo::Object, Ryo::BasicObject>] ryo
-  #  A Ryo object.
-  #
+  #  A Ryo object
   # @param [<String, #to_s>] property
-  #  The name of the property.
-  #
+  #  The name of a property
   # @param [Object, BasicObject] value
-  #  The value of the property.
-  #
+  #  The property's value
   # @return [void]
   def define_property(ryo, property, value)
     table, property = table_of(ryo), property.to_s
@@ -76,13 +75,12 @@ module Ryo::Reflect
 
   ##
   # Equivalent to JavaScript's `Reflect.ownKeys`, and
-  # JavaScript's `Object.keys`.
+  # JavaScript's `Object.keys`
   #
   # @param [<Ryo::Object, Ryo::BasicObject>] ryo
-  #  A Ryo object.
-  #
+  #  A Ryo object
   # @return [Array<String>]
-  #  Returns the properties defined on a Ryo object.
+  #  Returns the properties defined on a Ryo object
   def properties_of(ryo)
     table_of(ryo).keys
   end
@@ -97,13 +95,11 @@ module Ryo::Reflect
   # and `Object.prototype.hasOwnProperty`.
   #
   # @param [<Ryo::Object, Ryo::BasicObject>] ryo
-  #  A Ryo object.
-  #
+  #  A Ryo object
   # @param [<String, #to_s>] property
-  #  A property name.
-  #
+  #  The name of a property
   # @return [Boolean]
-  #  Returns true when **property** is a member of a Ryo object.
+  #  Returns true when the property is a member of a Ryo object
   def property?(ryo, property)
     table_of(ryo).key?(property.to_s)
   end
@@ -111,14 +107,11 @@ module Ryo::Reflect
   ##
   # Equivalent to JavaScript's `Object.assign`.
   #
-  #
   # @param [Ryo, Hash, #to_hash] target
-  #  The target object.
-  #
+  #  The target object
   # @param [Ryo, Hash, #to_hash] sources
   #  A variable number of source objects that
-  #  will be merged into the target object.
-  #
+  #  will be merged with the target object
   # @return [Ryo]
   #  Returns the modified target object.
   def assign(target, *sources)
@@ -133,30 +126,10 @@ module Ryo::Reflect
   # @group Ryo-specific
 
   ##
-  # The {#delete!} method deletes a property from a Ryo object,
-  # and from the prototypes in its prototype chain.
-  #
-  # @see Ryo::Keywords#delete
-  #
   # @param [<Ryo::Object, Ryo::BasicObject>] ryo
-  #  A Ryo object.
-  #
-  # @param [<String, #to_s>] property
-  #  A property name.
-  #
-  # @return [void]
-  def delete!(ryo, property)
-    [ryo, *prototype_chain_of(ryo)].each do
-      Ryo.delete(_1, property.to_s)
-    end
-  end
-
-  ##
-  # @param [<Ryo::Object, Ryo::BasicObject>] ryo
-  #  A Ryo object.
-  #
+  #  A Ryo object
   # @return [Array<Ryo::Object, Ryo::BasicObject>]
-  #  Returns the prototype chain of a Ryo object.
+  #  Returns the prototype chain of a Ryo object
   def prototype_chain_of(ryo)
     prototypes = []
     loop do
@@ -169,20 +142,21 @@ module Ryo::Reflect
 
   ##
   # @param [<Ryo::Object, Ryo::BasicObject>] ryo
-  #  A Ryo object.
-  #
+  #  A Ryo object
   # @param [Boolean] recursive
   #  When true, nested Ryo objects are replaced by
-  #  their table as well.
-  #
+  #  their table as well
   # @return [Hash]
-  #  Returns the table of a Ryo object.
+  #  Returns the table of a Ryo object
   def table_of(ryo, recursive: false)
     table = kernel(:instance_variable_get).bind_call(ryo, :@_table)
     if recursive
       table.each do |key, value|
         if ryo?(value)
           table[key] = table_of(value, recursive:)
+        elsif value.respond_to?(:each)
+          table[key] = value.respond_to?(:each_pair) ?
+                       value : value.map { table_of(_1, recursive:) }
         end
       end
     end
@@ -190,14 +164,12 @@ module Ryo::Reflect
   end
 
   ##
-  # Sets the table of a Ryo object.
+  # Sets the table of a Ryo object
   #
   # @param [<Ryo::Object, Ryo::BasicObject>] ryo
-  #  A Ryo object.
-  #
+  #  A Ryo object
   # @param [Hash] table
-  #  The table to assign to a Ryo object.
-  #
+  #  The table
   # @return [nil]
   def set_table_of(ryo, table)
     kernel(:instance_variable_set)
@@ -207,51 +179,42 @@ module Ryo::Reflect
 
   ##
   # @param [<Ryo::Object, Ryo::BasicObject>] ryo
-  #  A Ryo object.
-  #
+  #  A Ryo object
   # @param [<String, Symbol>] method
-  #  The name of a method.
-  #
+  #  The name of a method
   # @param [::Object, ::BasicObject] args
-  #  Zero or more arguments to call **method** with.
-  #
+  #  Zero or more method arguments
   # @param [Proc] b
-  #  An optional block to pass to **method**.
-  #
+  #  An optional block
   # @return [::Object, ::BasicObject]
-  #  Returns the return value of the method call.
-  def call_method(ryo, method, *, &b)
+  def call_method(ryo, method, *args, &b)
     kernel(:__send__)
-      .bind_call(ryo, method, *, &b)
+      .bind_call(ryo, method, *args, &b)
   end
 
   ##
   # @param [<Ryo::Object, Ryo::BasicObject>] ryo
-  #  A Ryo object.
-  #
+  #  A Ryo object
   # @return [Class]
-  #  Returns the class of a Ryo object.
+  #  Returns the class of a Ryo object
   def class_of(ryo)
     kernel(:class).bind_call(ryo)
   end
 
   ##
   # @param [Ryo::Function, Object, BasicObject] obj
-  #  An object.
-  #
+  #  An object
   # @return [Boolean]
-  #  Returns true when the given object is a Ryo function.
+  #  Returns true when given a Ryo function
   def function?(obj)
     Ryo::Function === obj
   end
 
   ##
   # @param [Ryo::Function, Object, BasicObject] obj
-  #  An object.
-  #
+  #  An object
   # @return [Boolean]
-  #  Returns true when the given object is an instance
-  #  of {Ryo::Memo Ryo::Memo}.
+  #  Returns true when given a Ryo memo
   def memo?(obj)
     Ryo::Memo === obj
   end
@@ -264,33 +227,29 @@ module Ryo::Reflect
   #  Ryo.ryo?(Object.new) # => false
   #
   # @param [Object, BasicObject] obj
-  #  An object.
-  #
+  #  An object
   # @return [Boolean]
-  #  Returns true when the given object is a Ryo object.
+  #  Returns true when given a Ryo object
   def ryo?(obj)
     Ryo === obj
   end
 
   ##
   # @param [<Ryo::Object, Ryo::BasicObject>] ryo1
-  #  A Ryo object.
-  #
+  #  A Ryo object
   # @param [<Ryo::Object, Ryo::BasicObject>] ryo2
-  #  A Ryo object.
-  #
+  #  A Ryo object
   # @return [Boolean]
-  #  Returns true when two Ryo objects are the same object.
+  #  Returns true when the two Ryo objects are strictly equal
   def equal?(ryo1, ryo2)
     kernel(:equal?).bind_call(ryo1, ryo2)
   end
 
   ##
   # @param [<Ryo::Object, Ryo::BasicObject>] ryo
-  #  A Ryo object.
-  #
+  #  A Ryo object
   # @return [String]
-  #  Returns a String representation of a Ryo object.
+  #  Returns a String representation of a Ryo object
   def inspect_object(ryo)
     format(
       "#<Ryo object=%{object} proto=%{proto} table=%{table}>",
@@ -301,80 +260,5 @@ module Ryo::Reflect
   end
   # @endgroup
 
-  ##
-  # @param [<Ryo::Object, Ryo::BasicObject>] ryo
-  #  A Ryo object.
-  #
-  # @param [<String, Symbol>] method
-  #  The name of the method.
-  #
-  # @param [Proc] b
-  #  The method's body.
-  #
-  # @private
-  private def define_method!(ryo, method, &b)
-    kernel(:define_singleton_method)
-      .bind_call(ryo, method, &b)
-  end
-
-  ##
-  # @param [<Ryo::Object, Ryo::BasicObject>] ryo
-  #  A Ryo object.
-  #
-  # @param [<String, #to_s>] property
-  #  The name of the property.
-  #
-  # @return [Boolean]
-  #  Returns true when the property has been
-  #  defined with a getter method.
-  #
-  # @private
-  private def getter_defined?(ryo, property)
-    kernel(:method)
-      .bind_call(ryo, property)
-      .source_location
-      &.dig(0) == __FILE__
-  end
-
-  ##
-  #
-  # @param [<Ryo::Object, Ryo::BasicObject>] ryo
-  #  A Ryo object.
-  #
-  # @param [<String, #to_s>] property
-  #  The name of the property.
-  #
-  # @return [Boolean]
-  #  Returns true when the property has been
-  #  defined with a setter method.
-  #
-  # @private
-  private def setter_defined?(ryo, property)
-    getter_defined?(ryo, "#{property}=")
-  end
-
-  ##
-  # @private
-  private def merge!(obj1, obj2)
-    obj1, obj2 = to_hash(obj1), to_hash(obj2)
-    obj2.each { obj1[_1.to_s] = _2 }
-    obj1
-  end
-
-  ##
-  # @private
-  private def to_hash(obj)
-    if ryo?(obj)
-      table_of(obj)
-    else
-      Hash.try_convert(obj)
-    end
-  end
-
-  ##
-  # @private
-  def kernel(name)
-    Module.instance_method(name)
-  end
-  # @endgroup
+  include Ryo::Utils
 end

data/lib/ryo/utils.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+##
+# The {Ryo::Utils Ryo::Utils} module provides utility
+# methods that are internal to Ryo. This module
+# and its methods should not be used directly.
+# @api private
+module Ryo::Utils
+  private
+
+  ##
+  # @param [<Ryo::Object, Ryo::BasicObject>] ryo
+  #  A Ryo object
+  # @param [<String, Symbol>] method
+  #  The name of a method
+  # @param [Proc] b
+  #  The method's implementation
+  def define_method!(ryo, method, &b)
+    kernel(:define_singleton_method)
+      .bind_call(ryo, method, &b)
+  end
+
+  ##
+  # @param [<Ryo::Object, Ryo::BasicObject>] ryo
+  #  A Ryo object
+  # @param [<String, #to_s>] property
+  #  The name of a property
+  # @return [Boolean]
+  #  Returns true for a Ryo property that has a
+  #  corresponding getter method implemented by Ryo
+  def getter_defined?(ryo, property)
+    path = kernel(:method)
+      .bind_call(ryo, property)
+      .source_location
+      &.dig(0)
+    path ? File.dirname(path) == File.dirname(__FILE__) : false
+  end
+
+  ##
+  # @param [<Ryo::Object, Ryo::BasicObject>] ryo
+  #  A Ryo object
+  # @param [<String, #to_s>] property
+  #  The name of a property
+  # @return [Boolean]
+  #  Returns true for a Ryo property that has a
+  #  corresponding setter method implemented by Ryo
+  def setter_defined?(ryo, property)
+    getter_defined?(ryo, "#{property}=")
+  end
+
+  def merge!(obj1, obj2)
+    obj1, obj2 = to_hash(obj1), to_hash(obj2)
+    obj2.each { obj1[_1.to_s] = _2 }
+    obj1
+  end
+
+  def to_hash(obj)
+    if ryo?(obj)
+      table_of(obj)
+    else
+      Hash.try_convert(obj)
+    end
+  end
+
+  def kernel(name)
+    Module.instance_method(name)
+  end
+end

data/lib/ryo/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Ryo
-  VERSION = "0.5.5"
+  VERSION = "0.5.7"
 end

data/lib/ryo/yaml.rb

@@ -1,45 +1,40 @@
 # frozen_string_literal: true
 
 ##
-# The {Ryo::YAML Ryo::YAML} module provides a number of methods
-# for coercing YAML data into a Ryo object. It must be required
-# separately to Ryo (ie: require "ryo/yaml"), and the methods of
-# this module are then available on the {Ryo Ryo} module.
+# The {Ryo::YAML Ryo::YAML} module provides a number of options
+# for coercing YAML data into a Ryo object. The methods of
+# this module are available as singleton methods on the {Ryo Ryo}
+# module
 module Ryo::YAML
-  require "yaml"
   extend self
 
   ##
   # @example
   #   Ryo.from_yaml(path: "/foo/bar/baz.yaml")
   #   Ryo.from_yaml(string: "---\nfoo: bar\n")
-  #
   # @param [String] path
   #  The path to a YAML file
-  #
   # @param [String] string
   #  A blob of YAML
-  #
   # @param [Ryo] object
   #  {Ryo::Object Ryo::Object}, or {Ryo::BasicObject Ryo::BasicObject}
   #  Defaults to {Ryo::Object Ryo::Object}
-  #
   # @raise [SystemCallError]
   #  Might raise a number of Errno exceptions
-  #
   # @return [Ryo::Object, Ryo::BasicObject]
   #  Returns a Ryo object
   def from_yaml(path: nil, string: nil, object: Ryo::Object)
     if path && string
       raise ArgumentError, "Provide a path or string but not both"
     elsif path
+      require "yaml" unless defined?(YAML)
       object.from YAML.load_file(path)
     elsif string
+      require "yaml" unless defined?(YAML)
       object.from YAML.load(string)
     else
       raise ArgumentError, "No path or string provided"
     end
   end
-
   Ryo.extend(self)
 end