leto 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 539f52438c18bb93115734b5c3c9dd5f8678886d392357c4fdca658b43d95357
+  data.tar.gz: bbe092a276d3241d39857cb81e8fb748108b15e67cbc0e421b7390545b8a066a
+SHA512:
+  metadata.gz: 9a0e610d258c35cf044c0118ccc10dff918edc8495df7448c058dbe6ad3201e540952fa67ac14e065229e1dd961788936e1343d30254743f47319609b5b4e169
+  data.tar.gz: c7e0fa4e9be9c2c0da092a7dbb88c78b9b11a12d8fb4f9d34e2ed97794ab2f26282c1fe31b04db5c70039198e675d2770ab0a7ae52edcb28049e7568c6c7bc56

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,28 @@
+inherit_gem:
+  relaxed-rubocop: .rubocop.yml
+
+AllCops:
+  NewCops: enable
+  SuggestExtensions: false
+  TargetRubyVersion: 2.6
+
+Gemspec/RequiredRubyVersion:
+  Enabled: false
+
+Gemspec/RequireMFA:
+  Enabled: false
+
+Layout/LineLength:
+  Max: 80
+
+Lint/AmbiguousBlockAssociation:
+  Enabled: false
+
+Lint/AmbiguousOperatorPrecedence:
+  Enabled: false
+
+Style/FetchEnvVar:
+  Enabled: false
+
+Style/FrozenStringLiteralComment:
+  Enabled: false

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [1.0.0] - 2023-02-24
+
+- Initial release

data/Gemfile

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in leto.gemspec
+gemspec
+
+gem "rake", "~> 13.0"
+
+gem "rspec", "~> 3.0"
+
+gem "rubocop", "~> 1.21"
+
+gem "relaxed-rubocop"

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2023 Janosch Müller
+
+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,101 @@
+# Leto
+
+[![Gem Version](https://badge.fury.io/rb/leto.svg)](http://badge.fury.io/rb/leto)
+[![Build Status](https://github.com/jaynetics/leto/workflows/tests/badge.svg)](https://github.com/jaynetics/leto/actions)
+
+A generic object traverser for Ruby (named after the Greek [childbearing goddess Leto](https://www.theoi.com/Titan/TitanisLeto.html)).
+
+Takes an object and recursively yields:
+
+- the given object
+- instance variables, class variables, constants
+- Hash keys and values
+- Enumerable members
+- Struct members
+- Range begins and ends
+
+This makes stuff like deep-freezing fairly easy to implement:
+
+```ruby
+my_object = [ { a: ['b', 'c'..'d'] } ]
+
+Leto.call(my_object, &:freeze)
+
+my_object.frozen? # => true
+my_object[0].frozen? # => true
+my_object[0][:a][1].begin.frozen? # => true
+```
+
+Note: the slightly smarter `Leto.deep_freeze` is one of the [included utility methods](#included-utility-methods).
+
+## Usage
+
+Basic example:
+
+```ruby
+object = [{ a: ['b', 'c'..'d'] }]
+
+Leto.call(object) { |el| p el }
+# prints:
+#
+# [{:a=>["b", ["c".."d"]]}]
+# {:a=>["b", ["c".."d"]]}
+# :a
+# ["b", ["c".."d"]]
+# "b"
+# "c".."d"
+# "c"
+# "d"
+
+Leto.call(object).to_a
+# => [[{:a=>["b", ["c".."d"]]}], {:a=>["b", ["c".."d"]]}, :a, ...]
+
+# all (sub-)objects have a path:
+Leto.call(object) { |el, path| puts "#{el.inspect.ljust(23)} @#{path}" }
+# prints:
+#
+# [{:a=>["b", "c".."d"]}] @#<Leto::Path [{:a=>["b", "c".."d"]}]>
+# {:a=>["b", "c".."d"]}   @#<Leto::Path [{:a=>["b", "c".."d"]}][0]>
+# :a                      @#<Leto::Path [{:a=>["b", "c".."d"]}][0].keys[0]>
+# ["b", "c".."d"]         @#<Leto::Path [{:a=>["b", "c".."d"]}][0][:a]>
+# "b"                     @#<Leto::Path [{:a=>["b", "c".."d"]}][0][:a][0]>
+# "c".."d"                @#<Leto::Path [{:a=>["b", "c".."d"]}][0][:a][1]>
+# "c"                     @#<Leto::Path [{:a=>["b", "c".."d"]}][0][:a][1].begin>
+# "d"                     @#<Leto::Path [{:a=>["b", "c".."d"]}][0][:a][1].end>
+
+# paths can be looked up with Leto::Path#resolve or Leto::dig
+path = Leto.call(object).map { |_el, path| path }.last # => #<Leto::Path...>
+path.resolve # => "d"
+Leto.dig(object, path) # => "d"
+Leto.dig(object, [[:[], 0], [:[], :a], [:[], 1], [:end]]) # => "d"
+```
+
+### Included utility methods
+
+- `Leto.deep_freeze(obj)`
+  - similar to the version above, but avoids freezing Modules and unfreezables
+- `Leto.deep_print(obj)`
+  - for debugging - prints more information than `pretty_print` does by default
+- `Leto.deep_eql?(obj1, obj2)`
+  - stricter version of `#eql?` that takes all ivars into consideration
+- `Leto.shared_mutable_state?(obj1, obj2)`
+  - useful for debugging or verifying that a `#dup` implementation is sane
+- `Leto.shared_mutables(obj1, obj2)`
+  - useful for debugging or verifying that a `#dup` implementation is sane
+- `Leto.shared_objects(obj1, obj2)`
+  - returns all objects shared by `obj1` and `obj2`, whether mutable or not
+
+## Benchmarks
+
+```
+    Leto.deep_freeze:     8762.1 i/s
+ IceNine.deep_freeze:     7390.3 i/s - 1.19x  (± 0.00) slower
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/jaynetics/leto.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/benchmark.rb

@@ -0,0 +1,11 @@
+require 'benchmark/ips'
+require 'ice_nine'
+require_relative 'lib/leto'
+
+obj = (0..9).to_h { |n| [n, [{ false => true, sym: ('a'..'z').to_a.shuffle }]] }
+
+Benchmark.ips do |x|
+  x.report('Leto.deep_freeze')    { Leto.deep_freeze(obj) }
+  x.report('IceNine.deep_freeze') { IceNine.deep_freeze(obj) }
+  x.compare!
+end; nil

data/leto.gemspec

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "lib/leto/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "leto"
+  spec.version = Leto::VERSION
+  spec.authors = ["Janosch Müller"]
+  spec.email = ["janosch84@gmail.com"]
+
+  spec.summary = "Generic object traverser"
+  spec.homepage = "https://github.com/jaynetics/leto"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 2.6.0"
+
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata["homepage_uri"] = spec.homepage
+
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (f == __FILE__) || f.match(%r{\A(?:(?:bin|test|spec|features)/|\.(?:git|circleci)|appveyor)})
+    end
+  end
+  spec.require_paths = ["lib"]
+end

data/lib/leto/call.rb

@@ -0,0 +1,64 @@
+module Leto
+  LEAKY_PROCESS_TMS = RUBY_VERSION.to_f <= 2.7
+
+  def self.call(obj, &block)
+    return enum_for(__method__, obj) unless block_given?
+
+    seen = {}.tap(&:compare_by_identity)
+    seen[Process::Tms] = true if LEAKY_PROCESS_TMS
+    path = block.arity == 2 ? Path.new(start: obj) : nil
+    traverse(obj, path, seen, block)
+    obj
+  end
+
+  def self.traverse(obj, path, seen, block)
+    return if seen[obj]
+
+    seen[obj] = true
+
+    path ? block.call(obj, path) : block.call(obj)
+
+    obj.instance_variables.each do |ivar_name|
+      traverse(
+        obj.instance_variable_get(ivar_name),
+        path&.+([[:instance_variable_get, ivar_name]]),
+        seen, block
+      )
+    end
+
+    case obj
+    when Hash
+      obj.keys.each_with_index do |k, i|
+        traverse(k, path&.+([[:keys], [:[], i]]), seen, block)
+        traverse(obj[k], path&.+([[:[], k]]), seen, block)
+      end
+    when Module
+      obj.class_variables.each do |cvar_name|
+        traverse(
+          obj.class_variable_get(cvar_name),
+          path&.+([[:class_variable_get, cvar_name]]),
+          seen, block
+        )
+      end
+      obj.constants.each do |const_name|
+        traverse(
+          obj.const_get(const_name),
+          path&.+([[:const_get, const_name]]),
+          seen, block
+        )
+      end
+    when Range
+      traverse(obj.begin, path&.+([[:begin]]), seen, block)
+      traverse(obj.end,   path&.+([[:end]]), seen, block)
+    when Struct
+      obj.members.each do |member|
+        traverse(obj[member], path&.+([[:[], member]]), seen, block)
+      end
+    when Enumerable
+      obj.each_with_index do |el, idx|
+        traverse(el, path&.+([[:[], idx]]), seen, block)
+      end
+    end
+  end
+  private_class_method :traverse
+end

data/lib/leto/dig.rb

@@ -0,0 +1,5 @@
+module Leto
+  def self.dig(obj, steps)
+    Leto::Path.new(start: obj, steps: steps).resolve
+  end
+end

data/lib/leto/path.rb

@@ -0,0 +1,51 @@
+# Light wrapper around Array, mostly for nicer display.
+module Leto
+  class Path
+    include Enumerable
+
+    attr_reader :start, :steps
+
+    def initialize(start:, steps: [])
+      @start = start
+      @steps = steps
+    end
+
+    def each(&block)
+      steps.each(&block)
+    end
+
+    def +(other)
+      self.class.new(start: start, steps: steps + other.to_a)
+    end
+
+    def resolve
+      steps.inject(start) do |obj, (method, *args)|
+        obj&.send(method, *args) or break obj
+      rescue StandardError => e
+        warn "#{__method__}: #{e.class} #{e.message}"
+      end
+    end
+
+    def ==(other)
+      other.to_a == steps
+    end
+
+    def inspect
+      start_str = start.inspect
+      start_str = "#{start_str[0..38]}…#{start_str[-1]}" if start_str.size > 40
+      [
+        "#<#{self.class} #{start_str}",
+        steps.map do |method, *args|
+          args_str = args.map(&:inspect).join(', ')
+          if method == :[]
+            "[#{args_str}]"
+          else
+            ".#{method}#{"(#{args_str})" unless args_str.empty?}"
+          end
+        end,
+        ">"
+      ].join
+    end
+    alias to_s inspect
+  end
+end

data/lib/leto/utils.rb

@@ -0,0 +1,64 @@
+module Leto
+  def self.deep_freeze(obj, include_modules: false)
+    call(obj) do |el|
+      el.freeze if el.respond_to?(:freeze) &&
+                   !el.frozen? &&
+                   (include_modules || !el.is_a?(Module))
+    end
+  end
+
+  def self.deep_print(obj, print_method: :inspect, indent: 4, show_path: true)
+    call(obj) do |el, path|
+      puts "#{' ' * path.count * indent}#{el.send(print_method)}" \
+           "#{"  @ #{path.inspect}" if show_path}" \
+           [0..78]
+    end
+    nil
+  end
+
+  def self.deep_eql?(obj1, obj2)
+    call(obj1).to_a == call(obj2).to_a
+  end
+
+  def self.shared_mutable_state?(obj1, obj2)
+    shared_mutables(obj1, obj2).any?
+  end
+
+  # returns [[shared_object, path1, path2], ...], e.g.:
+  # str1 = 'foo'.dup
+  # str2 = 'bar'.dup
+  # shared_mutables([str1, str2], [str2, str1]) # =>
+  # [
+  #   ["foo", [[:[], 0]], [[:[], 1]]],
+  #   ["bar", [[:[], 1]], [[:[], 0]]]
+  # ]
+  def self.shared_mutables(obj1, obj2)
+    shared_objects(obj1, obj2, filter: method(:mutable?))
+  end
+
+  def self.shared_objects(obj1, obj2, filter: nil)
+    objects_with_path1 = call(obj1).map { |el, path| [el, path] }
+    objects_with_path2 = call(obj2).map { |el, path| [el, path] }
+    objects_with_path1.each.with_object([]) do |(el1, path1), acc|
+      next if filter && !filter.call(el1)
+
+      objects_with_path2.reject do |el2, path2|
+        acc << [el1, path1, path2] if el1.equal?(el2)
+      end
+    end
+  end
+
+  def self.mutable?(obj)
+    !IMMUTABLE_CLASSES.include?(obj.class) && !obj.frozen?
+  end
+  private_class_method :mutable?
+
+  IMMUTABLE_CLASSES = [
+    FalseClass,
+    Float,
+    Integer,
+    NilClass,
+    Symbol,
+    TrueClass,
+  ].freeze
+end

data/lib/leto/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Leto
+  VERSION = "1.0.0"
+end

data/lib/leto.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative 'leto/call'
+require_relative 'leto/dig'
+require_relative 'leto/path'
+require_relative 'leto/utils'
+require_relative 'leto/version'

metadata

@@ -0,0 +1,60 @@
+--- !ruby/object:Gem::Specification
+name: leto
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Janosch Müller
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2023-02-24 00:00:00.000000000 Z
+dependencies: []
+description:
+email:
+- janosch84@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- CHANGELOG.md
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- benchmark.rb
+- leto.gemspec
+- lib/leto.rb
+- lib/leto/call.rb
+- lib/leto/dig.rb
+- lib/leto/path.rb
+- lib/leto/utils.rb
+- lib/leto/version.rb
+homepage: https://github.com/jaynetics/leto
+licenses:
+- MIT
+metadata:
+  changelog_uri: https://github.com/jaynetics/leto/blob/main/CHANGELOG.md
+  homepage_uri: https://github.com/jaynetics/leto
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.1
+signing_key:
+specification_version: 4
+summary: Generic object traverser
+test_files: []