ryo.rb 0.5.3 → 0.5.6

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)
@@ -134,16 +127,13 @@ module Ryo::Reflect
 
   ##
   # The {#delete!} method deletes a property from a Ryo object,
-  # and from the prototypes in its prototype chain.
+  # and from the prototypes in its prototype chain
   #
   # @see Ryo::Keywords#delete
-  #
   # @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 [void]
   def delete!(ryo, property)
     [ryo, *prototype_chain_of(ryo)].each do
@@ -153,10 +143,9 @@ module Ryo::Reflect
 
   ##
   # @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 +158,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 +180,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,19 +195,14 @@ 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, *args, &b)
     kernel(:__send__)
       .bind_call(ryo, method, *args, &b)
@@ -227,31 +210,27 @@ module Ryo::Reflect
 
   ##
   # @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 +243,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 +276,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.3"
+  VERSION = "0.5.6"
 end

data/lib/ryo/yaml.rb

@@ -0,0 +1,45 @@
+# 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.
+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
+      object.from YAML.load_file(path)
+    elsif string
+      object.from YAML.load(string)
+    else
+      raise ArgumentError, "No path or string provided"
+    end
+  end
+
+  Ryo.extend(self)
+end

data/lib/ryo.rb

@@ -15,6 +15,7 @@
 #   point = Ryo.assign(Ryo({}), {x: 0}, {y: 0})
 #   point.x # => 0
 module Ryo
+  require_relative "ryo/utils"
   require_relative "ryo/reflect"
   require_relative "ryo/keywords"
   require_relative "ryo/builder"
@@ -30,13 +31,11 @@ module Ryo
 
   ##
   # @param [<Ryo::Object, Ryo::BasicObject>] ryo
-  #  A Ryo object.
-  #
+  #  A Ryo object
   # @param [Module] mod
-  #  A module to extend a Ryo object with.
-  #
+  #  The module to extend a Ryo object with
   # @return [<Ryo::Object, Ryo::BasicObject>]
-  #  Returns a Ryo object extended by **mod**.
+  #  Returns an extended Ryo object
   def self.extend!(ryo, mod)
     kernel(:extend).bind_call(ryo, mod)
   end
@@ -45,10 +44,9 @@ module Ryo
   # Duplicates a Ryo object, and its prototype(s).
   #
   # @param [<Ryo::Object, Ryo::BasicObject>] ryo
-  #  A Ryo object.
-  #
+  #  A Ryo object
   # @return [<Ryo::Object, Ryo::BasicObject>]
-  #  Returns a duplicated Ryo object.
+  #  Returns a duplicated Ryo object
   def self.dup(ryo)
     duplicate = extend!(
       kernel(:dup).bind_call(ryo),
@@ -61,13 +59,12 @@ module Ryo
   end
 
   ##
-  # Creates a memoized Ryo value.
+  # Creates a memoized Ryo value
   #
   # @param [Proc] b
-  #  A Proc that is memoized after being accessed for the first time.
-  #
+  #  A Proc that is memoized after being accessed for the first time
   # @return [Ryo::Memo]
-  #  Returns an instance of {Ryo::Memo Ryo::Memo}.
+  #  Returns an instance of {Ryo::Memo Ryo::Memo}
   def self.memo(&b)
     Ryo::Memo.new(&b)
   end
@@ -76,36 +73,32 @@ module Ryo
   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.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.from(props, prototype = nil)
     Ryo::Object.from(props, prototype)
   end
 
   ##
-  # Returns the prototype of self, or "nil" if self has no prototype.
-  #
   # @return [<Ryo::Object, Ryo::BasicObject>, nil]
+  #  Returns the prototype of self, or nil if self has no prototype
   def __proto__
     @_proto
   end
 
   ##
+  # @note
+  #  This method will first query self for a property,
+  #  and if the property is not found the query is sent
+  #  to {Ryo#__proto__ Ryo#__proto__} instead
   # @param [String] property
-  #  A property name.
-  #
+  #  The name of a property
   # @return [<Object, BasicObject>, nil]
-  #  Returns the value at **property**, or nil.
-  #
-  # @note
-  #  This method will first try to read **property** from self, and if
-  #  it is not found on self the chain of prototypes will be traversed
-  #  through instead.
+  #  Returns the property's value, or nil
   def [](property)
     property = property.to_s
     if Ryo.property?(self, property)
@@ -118,14 +111,11 @@ module Ryo
   end
 
   ##
-  # Assigns a property to self.
+  # Assign a property
   #
   # @param [String] property
-  #  A property name.
-  #
+  #  The name of a property
   # @param [<Object,BasicObject>] value
-  #  The value.
-  #
   # @return [void]
   def []=(property, value)
     Ryo.define_property(self, property.to_s, value)
@@ -133,10 +123,8 @@ module Ryo
 
   ##
   # @param [<Ryo::Object, Ryo::BasicObject>, Hash, #to_h] other
-  #  An object to compare against.
-  #
   # @return [Boolean]
-  #  Returns true **other** is equal to self.
+  #  Returns true **other** is equal to self
   def ==(other)
     if Ryo.ryo?(other)
       @_table == Ryo.table_of(other)
@@ -150,14 +138,14 @@ module Ryo
 
   ##
   # @return [String]
-  #  Returns a String representation of a Ryo object.
+  #  Returns a String representation of a Ryo object
   def inspect
     Ryo.inspect_object(self)
   end
 
   ##
   # @return [Hash]
-  #  Returns the hash table used by a Ryo object.
+  #  Returns the lookup table of a Ryo object
   def to_h
     Ryo.table_of(self, recursive: true)
   end
@@ -200,9 +188,8 @@ end
 ##
 # @param props (see Ryo::Builder.build)
 # @param prototype (see Ryo::Builder.build)
-#
 # @return [Ryo::Object]
-#  Returns a Ryo object.
+#  Returns a Ryo object
 def Ryo(props, prototype = nil)
   Ryo::Object.create(props, prototype)
 end

data/ryo.rb.gemspec

@@ -12,6 +12,7 @@ Gem::Specification.new do |gem|
   gem.require_paths = ["lib"]
   gem.description = "Ryo implements prototype-based inheritance, in Ruby"
   gem.summary = gem.description
+  gem.required_ruby_version = ">= 3.2"
   gem.add_development_dependency "yard", "~> 0.9"
   gem.add_development_dependency "redcarpet", "~> 3.5"
   gem.add_development_dependency "rspec", "~> 3.10"

data/share/ryo.rb/examples/1.0_prototypes_point_object.rb

@@ -1,3 +1,4 @@
+#!/usr/bin/env ruby
 # frozen_string_literal: true
 
 require_relative "setup"

data/share/ryo.rb/examples/1.1_prototypes_ryo_fn.rb

@@ -1,3 +1,4 @@
+#!/usr/bin/env ruby
 # frozen_string_literal: true
 
 require_relative "setup"

data/share/ryo.rb/examples/2.0_iteration_each.rb

@@ -1,3 +1,4 @@
+#!/usr/bin/env ruby
 # frozen_string_literal: true
 
 require_relative "setup"

data/share/ryo.rb/examples/2.1_iteration_map.rb

@@ -1,3 +1,4 @@
+#!/usr/bin/env ruby
 # frozen_string_literal: true
 
 require_relative "setup"

data/share/ryo.rb/examples/2.2_iteration_ancestors.rb

@@ -1,3 +1,4 @@
+#!/usr/bin/env ruby
 # frozen_string_literal: true
 
 require_relative "setup"

data/share/ryo.rb/examples/3.0_recursion_ryo_from.rb

@@ -1,3 +1,4 @@
+#!/usr/bin/env ruby
 # frozen_string_literal: true
 
 require_relative "setup"

data/share/ryo.rb/examples/3.1_recursion_ryo_from_with_array.rb

@@ -1,3 +1,4 @@
+#!/usr/bin/env ruby
 # frozen_string_literal: true
 
 require_relative "setup"