ryo.rb 0.4.4

data/lib/ryo/builder.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+##
+# {Ryo::Builder Ryo::Builder} is a module that's used underneath Ryo's public
+# interface when creating instances of {Ryo::Object Ryo::Object}, and
+# {Ryo::BasicObject Ryo::BasicObject}. This module is not intended to be
+# used directly.
+#
+# @api private
+module Ryo::Builder
+  ##
+  # @param [<Ryo::Object, Ryo::BasicObject>] buildee
+  #  The class of the object to build.
+  #
+  # @param [<Hash, Ryo::Object, Ryo::BasicObject, #each_pair>] props
+  #  A Hash object, an object that implements "#each_pair", or a Ryo object.
+  #
+  # @param [<Ryo::Object, Ryo::BasicObject>, nil] prototype
+  #  The prototype, or nil for none.
+  #
+  # @return [<Ryo::Object, Ryo::BasicObject>]
+  #  Returns a Ryo object.
+  #
+  # @note
+  #  When "props" is given as a Ryo object, a duplicate Ryo object is
+  #  returned in its place.
+  def self.build(buildee, props, prototype = nil)
+    if Ryo.ryo?(props)
+      build(builedee, Ryo.table_of(props), prototype || Ryo.prototype_of(props))
+    else
+      ryo = buildee.new
+      Ryo.set_prototype_of(ryo, prototype)
+      Ryo.set_table_of(ryo, {})
+      Ryo.extend!(ryo, Ryo)
+      props.each_pair { ryo[_1] = _2 }
+      ryo
+    end
+  end
+
+  ##
+  # Creates a Ryo object by recursively walking a Hash object, or an Array of Hash objects.
+  #
+  # @example
+  #   objects = Ryo.from([{x: 0, y: 0}, "foo", {point: {x: 0, y: 0}}])
+  #   objects[0].x       # => 0
+  #   objects[1]         # => "foo"
+  #   objects[2].point.x # => 0
+  #
+  # @param buildee (see Ryo::Builder.build)
+  #
+  # @param [<Hash, Ryo::Object, Ryo::BasicObject, Array, #each_pair, #each> ] props
+  #   A Hash object, a Ryo object, or an array composed of either Hash / Ryo objects.
+  #
+  # @param prototype (see Ryo::Builder.build)
+  #
+  # @return (see Ryo::Builder.build)
+  #
+  # @note
+  #  When "props" is given as a Ryo object, a duplicate Ryo object is
+  #  returned in its place.
+  def self.recursive_build(buildee, props, prototype = nil)
+    if Ryo.ryo?(props)
+      recursive_build(buildee, Ryo.table_of(props), prototype || Ryo.prototype_of(props))
+    elsif eachless?(props)
+      raise TypeError, "The provided object does not implement #each / #each_pair"
+    elsif !props.respond_to?(:each_pair)
+      map(props) do
+        noop = Ryo.ryo?(_1) || !_1.respond_to?(:each_pair)
+        noop ? _1 : recursive_build(buildee, _1)
+      end
+    else
+      visited = {}
+      props.each_pair { visited[_1] = map_value(buildee, _2) }
+      build(buildee, visited, prototype)
+    end
+  end
+
+  ##
+  # @private
+  def self.map_value(buildee, value)
+    if Ryo.ryo?(value) || eachless?(value)
+      value
+    elsif value.respond_to?(:each_pair)
+      recursive_build(buildee, value)
+    elsif value.respond_to?(:each)
+      map(value) { map_value(buildee, _1) }
+    end
+  end
+  private_class_method :map_value
+
+  ##
+  # @private
+  def self.eachless?(value)
+    !value.respond_to?(:each) && !value.respond_to?(:each_pair)
+  end
+  private_class_method :eachless?
+
+  ##
+  # @private
+  def self.map(obj)
+    ary = []
+    obj.each { ary.push(yield(_1)) }
+    ary
+  end
+  private_class_method :map
+end

data/lib/ryo/enumerable.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+##
+# The {Ryo::Enumerable Ryo::Enumerable} module implements methods
+# for iterating through and performing operations on Ryo objects.
+# The methods implemented by this module are available as singleton
+# methods on the {Ryo} module.
+module Ryo::Enumerable
+  ##
+  # The {#each} methods iterates a Ryo object, and yields a key / value pair.
+  # When a block is not given, {#each} returns an Enumerator.
+  #
+  # @example
+  #  point_a = Ryo(x: 1, y: 2)
+  #  point_b = Ryo(y: 1)
+  #  Ryo.each(point_b) { p [_1, _2] }
+  #  # ["y", 1]
+  #  # ["y", 2]
+  #  # ["x", 1]
+  #
+  # @param [Ryo::Object, Ryo::BasicObject] ryo
+  #  A Ryo object.
+  #
+  # @param ancestors (see #each_ryo)
+  #
+  # @return [<Enumerator, Array>]
+  #  Returns an Enumerator when a block is not given, otherwise returns an Array.
+  def each(ryo, ancestors: nil)
+    return enum_for(:each, ryo) unless block_given?
+    each_ryo(ryo, ancestors: ancestors) do |_, key, value|
+      yield(key, value)
+    end
+  end
+
+  ##
+  # The {#each_ryo} method iterates through a Ryo object, and its prototypes.
+  # {#each_ryo} yields three parameters: a Ryo object, a key, and a value.
+  #
+  # @example
+  #  point_a = Ryo(x: 1, y: 2)
+  #  point_b = Ryo({y: 3}, point_a)
+  #  Ryo.each_ryo(point_b) { |ryo, key, value| p [ryo, key, value] }
+  #  # [point_b, "y", 3]
+  #  # [point_a, "x", 1]
+  #  # [point_a, "y", 2]
+  #
+  # @param [<Ryo::BasicObject, Ryo::Object>] ryo
+  #  A Ryo object.
+  #
+  # @param [Integer] ancestors
+  #   `ancestors` is an integer that determines how far up the prototype chain a
+  #   {Ryo::Enumerable Ryo::Enumerable}  method can go. 0 covers a Ryo object,
+  #   and none of the prototypes in its prototype chain. 1 covers a Ryo object,
+  #   and one of the prototypes in its prototype chain - and so on. The default
+  #   behavior is to traverse the entire prototype chain.
+  #
+  # @return [<Ryo::BasicObject, Ryo::Object>]
+  def each_ryo(ryo, ancestors: nil)
+    proto_chain = [ryo, *prototype_chain_of(ryo)]
+    ancestors ||= -1
+    proto_chain[0..ancestors].each do |ryo|
+      properties_of(ryo).each do |key|
+        yield(ryo, key, ryo[key])
+      end
+    end
+    ryo
+  end
+
+  ##
+  # The {#map} method creates a copy of a Ryo object, and then performs a map operation
+  # on the copy and its prototypes.
+  #
+  # @param (see #map!)
+  # @return (see #map!)
+  def map(ryo, ancestors: nil, &b)
+    map!(Ryo.dup(ryo), ancestors: ancestors, &b)
+  end
+
+  ##
+  # The {#map!} method performs an in-place map operation on a Ryo object, and its prototypes.
+  #
+  # @example
+  #  point = Ryo(x: 2, y: 4)
+  #  Ryo.map!(point) { _2 * 2 }
+  #  [point.x, point.y]
+  #  # => [4, 8]
+  #
+  # @param [<Ryo::Object, Ryo::BasicObject>] ryo
+  #  A Ryo object.
+  #
+  # @param ancestors (see #each_ryo)
+  #
+  # @return [<Ryo::Object, Ryo::BasicObject>]
+  def map!(ryo, ancestors: nil)
+    each_ryo(ryo, ancestors: ancestors) do |ryo, key, value|
+      ryo[key] = yield(key, value)
+    end
+  end
+
+  ##
+  # The {#select} method creates a copy of a Ryo object, and then performs a filter operation
+  # on the copy and its prototypes.
+  #
+  # @param (see #select!)
+  # @return (see #select!)
+  def select(ryo, ancestors: nil, &b)
+    select!(Ryo.dup(ryo), ancestors: ancestors, &b)
+  end
+
+  ##
+  # The {#select!} method performs an in-place filter operation on a Ryo object, and
+  # its prototypes.
+  #
+  # @example
+  #  point_a = Ryo(x: 1, y: 2, z: 3)
+  #  point_b = Ryo({z: 4}, point_a)
+  #  Ryo.select!(point_b) { |key, value| %w(x y).include?(key) }
+  #  [point_b.x, point_b.y, point_b.z]
+  #  # => [1, 2, nil]
+  #
+  # @param [<Ryo::Object, Ryo::BasicObject>] ryo
+  #  A Ryo object.
+  #
+  # @param ancestors (see #each_ryo)
+  #
+  # @return [<Ryo::Object, Ryo::BasicObject>]
+  def select!(ryo, ancestors: nil)
+    each_ryo(ryo, ancestors: ancestors) do |ryo, key, value|
+      delete(ryo, key) unless yield(key, value)
+    end
+  end
+
+  ##
+  # The {#reject} method creates a copy of a Ryo object, and then performs a filter operation
+  # on the copy and its prototypes.
+  #
+  # @param (see #reject!)
+  # @return (see #reject!)
+  def reject(ryo, ancestors: nil, &b)
+    reject!(Ryo.dup(ryo), ancestors: ancestors, &b)
+  end
+
+  ##
+  # The {#reject!} method performs an in-place filter operation on a Ryo object, and
+  # its prototypes.
+  #
+  # @example
+  #  point_a = Ryo(x: 1, y: 2, z: 3)
+  #  point_b = Ryo({z: 4}, point_a)
+  #  Ryo.reject!(point_b) { |key, value| value > 2 }
+  #  [point_b.x, point_b.y, point_b.z]
+  #  # => [1, 2, nil]
+  #
+  # @param [<Ryo::Object, Ryo::BasicObject>] ryo
+  #  A Ryo object.
+  #
+  # @param ancestors (see #each_ryo)
+  #
+  # @return [<Ryo::Object, Ryo::BasicObject>]
+  def reject!(ryo, ancestors: nil)
+    each_ryo(ryo, ancestors: ancestors) do |ryo, key, value|
+      delete(ryo, key) if yield(key, value)
+    end
+  end
+
+  ##
+  # The {#any?} method iterates through a Ryo object, and its prototypes - yielding a
+  # key / value pair to a block. If the block ever returns a truthy value, {#any?} will
+  # break from the iteration and return true - otherwise false will be returned.
+  #
+  # @param ancestors (see #each_ryo)
+  # @return [Boolean]
+  def any?(ryo, ancestors: nil)
+    each_ryo(ryo, ancestors: ancestors) do |_, key, value|
+      return true if yield(key, value)
+    end
+    false
+  end
+
+  ##
+  # The {#all?} method iterates through a Ryo object, and its prototypes - yielding a
+  # key / value pair to a block. If the block ever returns a falsey value, {#all?} will
+  # break from the iteration and return false - otherwise true will be returned.
+  #
+  # @param ancestors (see #each_ryo)
+  # @return [Boolean]
+  def all?(ryo, ancestors: nil)
+    each_ryo(ryo, ancestors: ancestors) do |_, key, value|
+      return false unless yield(key, value)
+    end
+    true
+  end
+
+  ##
+  # The {#find} method iterates through a Ryo object, and its prototypes - yielding a
+  # key / value pair to a block. If the block ever returns a truthy value, {#find} will
+  # break from the iteration and return a Ryo object - otherwise nil will be returned.
+  #
+  # @example
+  #  point_a = Ryo(x: 5)
+  #  point_b = Ryo({y: 10}, point_a)
+  #  point_c = Ryo({z: 15}, point_b)
+  #  ryo = Ryo.find(point_c) { |key, value| value == 5 }
+  #  ryo == point_a # => true
+  #
+  # @param ancestors (see #each_ryo)
+  # @return [<Ryo::Object, Ryo::BasicObject>, nil]
+  def find(ryo, ancestors: nil)
+    each_ryo(ryo, ancestors: ancestors) do |ryo, key, value|
+      return ryo if yield(key, value)
+    end
+    nil
+  end
+end

data/lib/ryo/function.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+##
+# The {Ryo::Function Ryo::Function} class represents a Ryo
+# function. The class is usually not used directly but through
+# {Ryo::Keywords#fn Ryo.fn}. A Ryo function has a special relationship
+# with Ryo objects: when a Ryo function is assigned as a property
+# on a Ryo object - the "self" of the function becomes bound to the
+# Ryo object.
+class Ryo::Function
+  ##
+  # @param [Proc] body
+  #  The body of the function as a block.
+  #
+  # @return [Ryo::Function]
+  #  Returns an instance of {Ryo::Function Ryo::Function}.
+  def initialize(&body)
+    @body = body
+    @ryo = nil
+    @to_proc = nil
+  end
+
+  ##
+  # @return [<Ryo::Object, Ryo::BasicObject>]
+  #  Returns the object that the function's "self" is bound to.
+  def receiver
+    @ryo
+  end
+  alias_method :self, :receiver
+
+  ##
+  # Change the receiver (self) of the function.
+  #
+  # @param [<Ryo::Object, Ryo::BasicObject>] ryo
+  #  A Ryo object.
+  #
+  # @return [nil]
+  def bind!(ryo)
+    @ryo = ryo
+    @to_proc = nil
+  end
+
+  ##
+  # Call the function.
+  def call(...)
+    to_proc.call(...)
+  end
+
+  ##
+  # @return [Proc]
+  #  Returns the function as a lambda bound to {#receiver}.
+  def to_proc
+    @to_proc ||= lambda!(@body)
+  end
+
+  private
+
+  def lambda!(body)
+    ryo, lambda = @ryo, nil
+    Module.new do
+      define_method(:__function__, &body)
+      lambda = instance_method(:__function__)
+               .bind(ryo)
+               .to_proc
+    end
+    lambda
+  end
+end

data/lib/ryo/keywords.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+##
+# 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
+# methods on the {Ryo} module.
+module Ryo::Keywords
+  ##
+  # @example
+  #   point = Ryo(x: 0, y: 0, print: Ryo.fn { print x, y, "\n" })
+  #   point.print.()
+  #
+  # @param [Proc] b
+  #  The function's body.
+  #
+  # @return [Ryo::Function]
+  #  Returns a Ryo function.
+  #
+  # @see Ryo::Function Ryo::Function
+  def fn(&b)
+    Ryo::Function.new(&b)
+  end
+  alias_method :function, :fn
+
+  ##
+  # Equivalent to JavaScript's **in** operator.
+  #
+  # @param [<Ryo::Object, Ryo::BasicObject>] ryo
+  #  A Ryo object.
+  #
+  # @param [<String, #to_s>] property
+  #  A property name.
+  #
+  # @return [Boolean]
+  #  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!}.
+  #
+  # @param [<Ryo::Object, Ryo::BasicObject>] ryo
+  #  A Ryo object.
+  #
+  # @param [<String, #to_s>] property
+  #  A property name.
+  #
+  # @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] }
+    end
+  end
+end

data/lib/ryo/lazy.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+class Ryo::Lazy < Ryo::Function
+end

data/lib/ryo/object.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+##
+# {Ryo::Object Ryo::Object} is a Ryo object and subclass of
+# Ruby's Object class that can be created by using
+# [Ryo()](https://0x1eef.github.io/x/ryo.rb/top-level-namespace.html#Ryo-instance_method),
+# {Ryo.Object Ryo.Object()}, {Ryo::Object.from Ryo::Object.from},
+# or {Ryo::Object.create Ryo::Object.create}.
+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}.
+  def self.create(props, prototype = nil)
+    Ryo::Builder.build(self, props, prototype)
+  end
+
+  ##
+  # 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)
+    Ryo::Builder.recursive_build(self, props, prototype)
+  end
+
+  ##
+  # Duplicates the internals of a Ryo object.
+  #
+  # @param [Ryo::Object] ryo
+  #  A Ryo object.
+  #
+  # @return [Ryo::Object]
+  #  Returns a Ryo object.
+  def initialize_dup(ryo)
+    Ryo.set_table_of(self, Ryo.table_of(ryo).dup)
+    Ryo.extend!(self, Ryo)
+  end
+end
+
+##
+# @example
+#  point = Ryo::Object(x: 0, y: 0)
+#  p [point.x, point.y] # => [0, 0]
+#
+# @param props (see Ryo::Builder.build)
+# @param prototype (see Ryo::Builder.build)
+#
+# @return [Ryo::Object]
+#   Returns an instance of {Ryo::Object Ryo::Object}.
+def Ryo.Object(props, prototype = nil)
+  Ryo::Object.create(props, prototype)
+end