ryo.rb 0.4.4

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 61ffcab409332ea4c6979e302c9d27f467575ef2b8167f07805e7f20ad523002
+  data.tar.gz: fb5f3050e9a373616e377a5d76c0605f7ce6e655ca8a2822619dd63d7426182d
+SHA512:
+  metadata.gz: 1158833ffda85f18fabdb7f7830fe0a104f91bfe5d19d2f0d8a21e51ac5d95d34dd6744d100b0ba6e0c5c6ece7ecdd38a80f59f2ceb55898403d490de9be14b6
+  data.tar.gz: c92c24f793503360539dc314c1c15d9349f23efee1cc29ca9af2dab497528d1b7186f77ee839f7ce36592c223ae6a4b8bdd058cb00091361a098268bad0e5af3

data/.github/workflows/specs.yml

@@ -0,0 +1,23 @@
+name: Ryo specs
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  specs:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        ruby: [3.1, 3.2]
+    runs-on: ${{ matrix.os }}
+    steps:
+    - uses: actions/checkout@v2
+    - uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby }}
+    - run: bundle install
+    - run: rspec -Ilib -rryo spec/

data/.gitignore

@@ -0,0 +1,6 @@
+doc/
+.*rc
+.*_history
+.yardoc
+*.lock
+pkg/

data/.gitlab-ci.yml

@@ -0,0 +1,9 @@
+stages:
+  - test
+
+test-ruby32:
+  stage: test
+  image: ruby:3.2.1
+  script:
+    - bundle install
+    - bundle exec rspec spec/

data/.rubocop.yml

@@ -0,0 +1,56 @@
+##
+# Plugins
+require:
+  - standard
+  - rubocop-rspec
+
+##
+# Defaults: standard-rb
+inherit_gem:
+  standard: config/base.yml
+
+##
+# Enabled cops
+Style/FrozenStringLiteralComment:
+  Enabled: true
+
+##
+# Disabled cops
+Layout/MultilineMethodCallIndentation:
+  Enabled: false
+Style/LambdaCall:
+  Enabled: false
+Lint/AssignmentInCondition:
+  Enabled: false
+
+##
+# Disabled cops (rspec)
+RSpec/FilePath:
+  Enabled: false
+RSpec/NestedGroups:
+  Enabled: false
+RSpec/NotToNot:
+  Enabled: false
+RSpec/EmptyLineAfterHook:
+  Enabled: false
+RSpec/EmptyLineAfterSubject:
+  Enabled: false
+RSpec/DescribedClass:
+  Enabled: false
+RSpec/MultipleExpectations:
+  Enabled: false
+RSpec/EmptyLineAfterFinalLet:
+  Enabled: false
+Style/NilComparison:
+  Exclude:
+    - spec/ryo_object_spec.rb
+RSpec/DescribeClass:
+  Enabled: false
+
+AllCops:
+  Include:
+    - 'lib/*.rb'
+    - 'lib/**/*.rb'
+    - 'spec/*.rb'
+    - 'spec/**/*.rb'
+  TargetRubyVersion: 3.2

data/.yardoc-template/default/fulldoc/html/css/0x1eef.css

@@ -0,0 +1,15 @@
+#main #content #filecontents p, .discussion p, ul.param li, div.note {
+  max-width: 768px;
+}
+
+#toc {
+  position: fixed;
+  right: 25px;
+  display: none;
+}
+
+@media screen and (min-width: 1280px) {
+  #toc {
+    display: block;
+  }
+}

data/.yardoc-template/default/layout/html/setup.rb

@@ -0,0 +1,5 @@
+def stylesheets
+  s = super
+  s << "css/0x1eef.css"
+  s
+end

data/.yardoc-template/default/module/setup.rb

@@ -0,0 +1,7 @@
+##
+# Sort methods in ascending order based
+# on the line number where a method is
+# defined.
+def sort_listing(listing)
+  listing.sort_by { _1.files[1] }
+end

data/.yardopts

@@ -0,0 +1,4 @@
+-m markdown -M redcarpet --hide-void-return --no-private -t default -p .yardoc-template
+-
+README.md
+LICENSE.txt

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+gem "test-cmd.rb", github: "0x1eef/test-cmd.rb", tag: "v0.4.0"
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright 2022
+0x1eef
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,373 @@
+## About
+
+Ryo implements prototype-based inheritance, in Ruby.
+
+Ryo's implementation of prototype-based inheritance offers
+a flexible approach for establishing object relationships,
+and building configuration objects. Ryo can also act as a
+recursive OpenStruct alternative. JavaScript's implementation of
+prototype-based inheritance served as a reference point
+for Ryo's implementation.
+
+## Examples
+
+### Prototypes
+
+#### Point object
+
+The following example demonstrates how prototype-based inheritance is
+implemented in Ryo. The example introduces three objects to form a
+single point object with the properties, "x" and "y". The
+[Ryo()](https://0x1eef.github.io/x/ryo.rb/top-level-namespace.html#Ryo-instance_method)
+method seen in the example returns an instance of
+[Ryo::Object](https://0x1eef.github.io/x/ryo.rb/Ryo/Object.html):
+
+```ruby
+require "ryo"
+
+point_x = Ryo(x: 5)
+point_y = Ryo({y: 10}, point_x)
+point = Ryo({}, point_y)
+p [point.x, point.y]
+
+##
+# [5, 10]
+```
+
+#### Ryo.fn
+
+The following example demonstrates a Ryo function.
+[`Ryo.fn`](https://0x1eef.github.io/x/ryo.rb/Ryo/Keywords.html#function-instance_method)
+will bind its `self` to the Ryo object it is assigned to, and when the function
+is called it will have access to the properties of the Ryo object:
+
+```ruby
+require "ryo"
+
+point_x = Ryo(x: 5)
+point_y = Ryo({y: 10}, point_x)
+point = Ryo({
+  multiply: Ryo.fn { |m| [x * m, y * m] }
+}, point_y)
+p point.multiply.call(2)
+
+##
+# [10, 20]
+```
+
+#### Ryo.lazy
+
+The following example demonstrates a lazy Ryo value.
+[`Ryo.lazy`](https://0x1eef.github.io/x/ryo.rb/Ryo.html#lazy-class_method)
+creates a lazy value that is not evaluated until a property is accessed
+for the first time. It is similar to a Ryo function but it does not require
+that the `#call` method be used, and after the property is accessed for the
+first time the lazy value is replaced by the evaluated value:
+
+```ruby
+require "ryo"
+
+point_x = Ryo(x: Ryo.lazy { 5 })
+point_y = Ryo({y: Ryo.lazy { 10 }}, point_x)
+point = Ryo({sum: Ryo.lazy { x + y }}, point_y)
+print "point.x = ", point.x, "\n"
+print "point.y = ", point.y, "\n"
+print "point.sum = ", point.sum, "\n"
+
+##
+# point.x = 5
+# point.y = 10
+# point.sum = 15
+```
+
+
+### Iteration
+
+#### Ryo.each
+
+The
+[`Ryo.each`](https://0x1eef.github.io/x/ryo.rb/Ryo.html#each-class_method)
+method can iterate through the properties of a Ryo object, and
+its prototype(s). Ryo is designed to not mix its implementation
+with the objects it creates -  that's why
+[`Ryo.each`](https://0x1eef.github.io/x/ryo.rb/Ryo.html#each-class_method)
+is not implemented directly on a Ryo object.
+
+A demonstration of [`Ryo.each`](https://0x1eef.github.io/x/ryo.rb/Ryo.html#each-class_method):
+
+```ruby
+require "ryo"
+
+point = Ryo(x: 10, y: 20)
+Ryo.each(point) do |key, value|
+  p [key, value]
+end
+
+##
+# ["x", 10]
+# ["y", 20]
+```
+
+#### Ryo.map!
+
+[`Ryo::Enumerable`](http://0x1eef.github.io/x/ryo.rb/Ryo/Enumerable.html)
+methods can return a new copy of a Ryo object and its prototypes, or mutate
+a Ryo object and its prototypes in-place. The following example demonstrates
+an in-place map operation on a Ryo object with
+[`Ryo.map!`](http://0x1eef.github.io/x/ryo.rb/Ryo/Enumerable.html#map!-instance_method).
+The counterpart of
+[`Ryo.map!`](http://0x1eef.github.io/x/ryo.rb/Ryo/Enumerable.html#map!-instance_method)
+is
+[`Ryo.map`](http://0x1eef.github.io/x/ryo.rb/Ryo/Enumerable.html#map-instance_method),
+and it returns a new copy of a Ryo object and its prototypes.
+
+A demonstration of [`Ryo.map!`](http://0x1eef.github.io/x/ryo.rb/Ryo/Enumerable.html#map!-instance_method):
+
+```ruby
+require "ryo"
+
+point_x = Ryo(x: 2)
+point_y = Ryo({y: 4}, point_x)
+point = Ryo({}, point_y)
+
+Ryo.map!(point) { |key, value| value * 2 }
+p [point.x, point.y]
+p [point_x.x, point_y.y]
+
+##
+# [4, 8]
+# [4, 8]
+```
+
+#### Ancestors
+
+All [`Ryo::Enumerable`](http://0x1eef.github.io/x/ryo.rb/Ryo/Enumerable.html)
+methods support an optional `ancestors` option.
+
+`ancestors` is an integer that determines how far up the prototype chain a
+[`Ryo::Enumerable`](https://0x1eef.github.io/x/ryo.rb/Ryo/Enumerable.html)
+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.
+
+When the `ancestors` option is not provided, the default behavior of
+[`Ryo::Enumerable`](http://0x1eef.github.io/x/ryo.rb/Ryo/Enumerable.html)
+methods is to traverse the entire prototype chain. The following example
+demonstrates using the `ancestors` option with
+[`Ryo.find`](https://0x1eef.github.io/x/ryo.rb/Ryo.html#find-class_method):
+
+```ruby
+require "ryo"
+
+point_x = Ryo(x: 5)
+point_y = Ryo({y: 10}, point_x)
+point = Ryo({}, point_y)
+
+p Ryo.find(point, ancestors: 0) { |k,v| v == 5 }   # => nil
+p Ryo.find(point, ancestors: 1) { |k,v| v == 5 }   # => nil
+p Ryo.find(point, ancestors: 2) { |k,v| v == 5 }.x # => point_x.x
+p Ryo.find(point) { |k,v| v == 5 }.x # => point_x.x
+```
+
+### Recursion
+
+#### Ryo.from
+
+The [`Ryo.from`](https://0x1eef.github.io/x/ryo.rb/Ryo.html#from-class_method) method has
+the same interface as the [`Ryo`](https://0x1eef.github.io/x/ryo.rb/top-level-namespace.html#Ryo-instance_method)
+method, but it is implemented to recursively walk a Hash object and create Ryo objects
+from other Hash objects found along the way. Recursion is not the default behavior
+because it has the potential to be slow when given a complex Hash object that's
+very large - otherwise there shouldn't be a noticeable performance impact.
+
+The following example demonstrates [`Ryo.from`](https://0x1eef.github.io/x/ryo.rb/Ryo.html#from-class_method):
+
+```ruby
+require "ryo"
+
+point = Ryo.from({
+  x: {to_i: 0},
+  y: {to_i: 10}
+})
+p [point.x.to_i, point.y.to_i]
+
+##
+# [0, 10]
+```
+
+#### Ryo.from with an Array
+
+The [`Ryo.from`](https://0x1eef.github.io/x/ryo.rb/Ryo.html#from-class_method) method can
+walk an Array object, and create Ryo objects from Hash objects found along the way.
+An object that can't be turned into a Ryo object is left as-is. The following
+example demonstrates how that works in practice:
+
+``` ruby
+require "ryo"
+
+points = Ryo.from([
+  {x: {to_i: 2}},
+  "foobar",
+  {y: {to_i: 4}}
+])
+
+p points[0].x.to_i
+p points[1]
+p points[2].y.to_i
+
+##
+# 2
+# "foobar"
+# 4
+```
+
+#### Ryo.from with OpenStruct
+
+All methods that can create Ryo objects support turning a Struct, or OpenStruct object
+into a Ryo object. The following example demonstrates how
+[`Ryo.from`](https://0x1eef.github.io/x/ryo.rb/Ryo.html#from-class_method)
+can recursively turn an OpenStruct object into Ryo objects. The example also assigns
+a prototype to the Ryo object created from the OpenStruct:
+
+``` ruby
+require "ryo"
+require "ostruct"
+
+point = Ryo.from(
+  OpenStruct.new(x: {to_i: 5}),
+  Ryo.from(y: {to_i: 10})
+)
+p [point.x.to_i, point.y.to_i]
+
+##
+# [5, 10]
+```
+
+### BasicObject
+
+#### Ryo::BasicObject
+
+All of the previous examples have been working with instances of
+[Ryo::Object](https://0x1eef.github.io/x/ryo.rb/Ryo/Object.html),
+a subclass of Ruby's Object class. In comparison, [Ryo::BasicObject](https://0x1eef.github.io/x/ryo.rb/Ryo/BasicObject.html) -
+a subclass of Ruby's BasicObject class, provides an object
+with fewer methods. The following example demonstrates
+how to create an instance of [Ryo::BasicObject](https://0x1eef.github.io/x/ryo.rb/Ryo/BasicObject.html):
+
+```ruby
+require "ryo"
+
+point_x = Ryo::BasicObject(x: 0)
+point_y = Ryo::BasicObject({y: 0}, point_x)
+point = Ryo::BasicObject({}, point_y)
+p [point.x, point.y]
+
+##
+# [0, 0]
+```
+
+#### Ryo::BasicObject.from
+
+[Ryo::BasicObject.from](https://0x1eef.github.io/x/ryo.rb/Ryo/BasicObject.html#from-class_method)
+is identical to Ryo.from but rather than returning instance(s) of [Ryo::Object](https://0x1eef.github.io/x/ryo.rb/Ryo/Object.html)
+it returns instance(s) of [Ryo::BasicObject](https://0x1eef.github.io/x/ryo.rb/Ryo/BasicObject.html)
+instead:
+
+```ruby
+require "ryo"
+
+point = Ryo::BasicObject.from({
+  x: {to_i: 2},
+  y: {to_i: 4}
+})
+p [point.x.to_i, point.y.to_i]
+
+##
+# [2, 4]
+```
+
+### Collisions
+
+#### Resolution strategy
+
+When a property and method collide, Ryo tries to find the best resolution. Since Ryo properties
+don't accept arguments, and methods can - we are able to distinguish a property from a method in
+many cases.
+
+Consider this example, where a property collides with the `Kernel#then` method. This example
+would work the same for other methods that accept a block and/or arguments:
+
+```ruby
+require "ryo"
+
+ryo = Ryo::Object(then: 12)
+p ryo.then # => 12
+p ryo.then { 34 } # => 34
+```
+
+### Beyond Hash objects
+
+#### Duck typing
+
+The documentation has used simple terms to describe the objects that Ryo works
+with: Hash and Array objects. But actually, Ryo uses duck typing, so any object
+that implements `#each_pair` can be treated as a Hash object, and any object that
+implements `#each` can be treated as an Array object. Note that only
+[Ryo.from](https://0x1eef.github.io/x/ryo.rb/Ryo.html#from-class_method),
+[Ryo::Object.from](https://0x1eef.github.io/x/ryo.rb/Ryo/Object.html#from-class_method)
+and
+[Ryo::BasicObject.from](https://0x1eef.github.io/x/ryo.rb/Ryo/BasicObject.html#from-class_method)
+can handle Array/#each objects.
+
+Here's an example of how to turn your own custom object, which implements
+`#each_pair`, into a Ryo object:
+
+``` ruby
+require "ryo"
+
+class Point
+  def initialize
+    @x = 5
+    @y = 10
+  end
+
+  def each_pair
+    yield("x", @x)
+    yield("y", @y)
+  end
+end
+
+point = Ryo(Point.new)
+p point.x # => 5
+p point.y # => 10
+```
+
+## Sources
+
+* [Source code (GitHub)](https://github.com/0x1eef/ryo.rb#readme)
+* [Source code (GitLab)](https://gitlab.com/0x1eef/ryo.rb#about)
+
+## <a id='install'>Install</a>
+
+Ryo is distributed as a RubyGem through its git repositories. <br>
+[GitHub](https://github.com/0x1eef/ryo.rb),
+and
+[GitLab](https://gitlab.com/0x1eef/ryo.rb)
+are available as sources.
+
+**Gemfile**
+
+```ruby
+gem "ryo.rb", github: "0x1eef/ryo.rb", tag: "v0.4.4"
+```
+
+## Thanks
+
+Thanks to
+[@awfulcooking (mooff)](https://github.com/awfulcooking)
+for the helpful discussions and advice.
+
+## License
+
+This project is released under the terms of the MIT license. <br>
+See [./LICENSE.txt](./LICENSE.txt) for details.

data/Rakefile

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"

data/lib/ryo/basic_object.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+##
+# {Ryo::BasicObject Ryo::BasicObject} is a Ryo object and subclass
+# of Ruby's BasicObject class that can be created by using
+# {Ryo.BasicObject Ryo.BasicObject()},
+# {Ryo::BasicObject.from Ryo::BasicObject.from}, or
+# {Ryo::BasicObject.create Ryo::BasicObject.create}.
+class Ryo::BasicObject < BasicObject
+  ##
+  # @param props (see Ryo::Builder.build)
+  # @param prototype (see Ryo::Builder.build)
+  #
+  # @return [Ryo::BasicObject]
+  #  Returns an instance of {Ryo::BasicObject Ryo::BasicObject}.
+  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::BasicObject]
+  #  Returns an instance of {Ryo::BasicObject Ryo::BasicObject}.
+  def self.from(props, prototype = nil)
+    ::Ryo::Builder.recursive_build(self, props, prototype)
+  end
+
+  ##
+  # Duplicates the internals of a Ryo object.
+  #
+  # @param [Ryo::BasicObject] ryo
+  #  A Ryo object.
+  #
+  # @return [Ryo::BasicObject]
+  #  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::BasicObject(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::BasicObject]
+#   Returns an instance of {Ryo::BasicObject Ryo::BasicObject}.
+def Ryo.BasicObject(props, prototype = nil)
+  Ryo::BasicObject.create(props, prototype)
+end