leto 2.2.0 → 2.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b0362bb08490e1bd600bb8996a1be449584295433c047472864578b2d43a6cb5
-  data.tar.gz: de8244c6e7d6bd2a58453effbadf1e93f9956a0aace1fc0fcef1c97660e486f4
+  metadata.gz: f0297fbb39b4e2a4a72e314dde94542722e1f147cb7988181cc6a79529123474
+  data.tar.gz: afb6e6670df5f8e0f2ea10630c184d69f676457b0f78431a52944c3c6dff1d44
 SHA512:
-  metadata.gz: a8a4a40c37e53158ce69775451a56a2b939cecb01df5c8441a0c7a18b9e4c88db68d350dd57abbc2d87fd03c770335f2e92344e2fba4370280796bb46fce1d6e
-  data.tar.gz: b73106dde5c5f19b65c6b95ac6f0fdf4039ab84eaf6dfb53abe705e54e4b7c2f8951fd3ebe205cf53ca46faaccf3812cc1fc2e534979a8adfd99df07bc0a66fb
+  metadata.gz: afe909e7a3e5a99e2fd580f74b709a746b1cdf66c8e8c3c0d61569c2c49faa06accd3c5a628ab6e1f57d42a70a676a851a9f7ba5edbc66132456de84cac9bf93
+  data.tar.gz: 1071b59853ec209240c7a298310c548d498af3f8086666623b4911684764975c8905291aae5d711d5be8b43b33382910cfdfb52eab8c10d0414caa5b0e592051

data/CHANGELOG.md

@@ -1,5 +1,20 @@
 ## [Unreleased]
 
+## [2.4.0] - 2026-10-26
+
+### Added
+
+- support for `Complex` and `Rational` objects
+- support for `Hash#default` and `Hash#default_proc`
+- support for `Exception` fields
+- support for `Time` zones
+
+## [2.3.0] - 2026-09-29
+
+### Added
+
+- support for Ruby 4's native `Set` class
+
 ## [2.2.0] - 2026-09-03
 
 ### Added

data/Gemfile

@@ -5,6 +5,8 @@ source "https://rubygems.org"
 # Specify your gem's dependencies in leto.gemspec
 gemspec
 
+gem "irb"
+gem "ostruct"
 gem "rake", "~> 13.0"
 gem "rspec", "~> 3.0"
 

data/README.md

@@ -4,17 +4,13 @@
 [![Build Status](https://github.com/jaynetics/leto/actions/workflows/tests.yml/badge.svg)](https://github.com/jaynetics/leto/actions)
 [![Coverage](https://codecov.io/gh/jaynetics/leto/branch/main/graph/badge.svg?token=0993K9I8VC)](https://codecov.io/gh/jaynetics/leto)
 
-A generic object traverser for Ruby (named after the Greek [childbearing goddess Leto](https://www.theoi.com/Titan/TitanisLeto.html)).
+Leto is 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:
+It takes an object and recursively yields:
 
 - the given object
 - instance variables, class variables, constants
-- Hash keys and values
-- Enumerable members
-- Struct members
-- [Data](https://docs.ruby-lang.org/en/3.2/Data.html) members
-- Range begins and ends
+- any object attributes, such as Array members, that are built into Ruby ([full list](#built-ins))
 
 This makes stuff like deep-freezing fairly easy to implement:
 
@@ -28,7 +24,7 @@ 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).
+Note: the slightly smarter `Leto.deep_freeze` is one of the [included utility methods](#included-utils).
 
 ## Usage
 
@@ -37,51 +33,93 @@ 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) { |el| puts "#{el.class}: #{el}" }
+```
+
+This prints:
+
+```
+Array: [{a: ["b", "c".."d"]}]
+Hash: {a: ["b", "c".."d"]}
+Symbol: a
+Array: ["b", "c".."d"]
+String: b
+Range: c..d
+String: c
+String: d
+```
 
+Calls without a block return an `Enumerator`:
+
+```ruby
 Leto.call(object).to_a
 # => [[{:a=>["b", ["c".."d"]]}], {:a=>["b", ["c".."d"]]}, :a, ...]
+```
+
+`Leto.trace` behaves like `.call`, but also yields each (sub-)object's `Path`:
 
-# Leto::trace behaves like ::call, but also yields each (sub-)object's path:
+```ruby
 Leto.trace(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
+```
+
+This 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`:
+
+```ruby
 path = Leto.trace(object).map { |_el, path| path }.last # => #<Leto::Path...>
 path.resolve # => "d"
 Leto.dig(object, path) # => "d"
+```
+
+Arrays of Arrays, where the inner ones contain method names and arguments, are valid paths:
+
+```ruby
 Leto.dig(object, [[:[], 0], [:[], :a], [:[], 1], [:end]]) # => "d"
 ```
 
+<a name='built-ins'></a>
+
+### Supported built-in classes and attributes
+
+The following classes are built into Ruby and some of their attributes are not exposed as regular instance variables. Leto handles these explicitly.
+
+- `Complex` objects' real and imaginary parts
+- [`Data`](https://docs.ruby-lang.org/en/3.2/Data.html) members
+- `Enumerable` members
+- `Exception` messages, backtraces, causes, and various subclass fields
+- `Hash` keys, values, defaults, and default_procs
+- `Range` begins and ends
+- `Rational` numerators and denominators
+- `Set` members (including for [native Sets on Ruby >= 4.0](https://bugs.ruby-lang.org/issues/21216))
+- `Struct` and `OpenStruct` members
+- `Time` zones, including custom timezone objects
+
+<a name='included-utils'></a>
+
 ### Included utility methods
 
 - [`Leto.deep_freeze(obj)`](https://github.com/search?q=deep_freeze+repo%3Ajaynetics%2Fleto+path%3Alib%2Fleto%2Futils.rb&type=code)
   - similar to the version above, but avoids freezing Modules and unfreezables
+  - similar to [`Ractor.make_shareable`](https://docs.ruby-lang.org/en/4.0/Ractor.html#method-c-make_shareable)
 - [`Leto.deep_print(obj)`](https://github.com/search?q=deep_print+repo%3Ajaynetics%2Fleto+path%3Alib%2Fleto%2Futils.rb&type=code)
   - for debugging - prints more information than `pretty_print` does by default
 - [`Leto.deep_eql?(obj1, obj2)`](https://github.com/search?q=deep_eql+repo%3Ajaynetics%2Fleto+path%3Alib%2Fleto%2Futils.rb&type=code)
   - stricter version of `#eql?` that takes all ivars into consideration
 - [`Leto.deep_dup(obj)`](https://github.com/search?q=deep_dup+repo%3Ajaynetics%2Fleto+path%3Alib%2Fleto%2Futils.rb&type=code)
   - more thorough than [`active_support`](https://www.rubydoc.info/search/gems/activesupport?q=deep_dup) or [`deep_dup`](https://github.com/ollie/deep_dup) gems, e.g. dups ivars
+  - similar to [`Ractor.make_shareable(obj, copy: true)`](https://docs.ruby-lang.org/en/4.0/Ractor.html#method-c-make_shareable), but doesn't freeze
 - [`Leto.shared_mutable_state?(obj1, obj2, ...)`](https://github.com/search?q=shared_mutable_state+repo%3Ajaynetics%2Fleto+path%3Alib%2Fleto%2Futils.rb&type=code)
   - useful for debugging or verifying that a `#dup` implementation is sane
 - [`Leto.shared_mutables(obj1, obj2)`](https://github.com/search?q=shared_mutables+repo%3Ajaynetics%2Fleto+path%3Alib%2Fleto%2Futils.rb&type=code)
@@ -89,6 +127,19 @@ Leto.dig(object, [[:[], 0], [:[], :a], [:[], 1], [:end]]) # => "d"
 - [`Leto.shared_objects(obj1, obj2)`](https://github.com/search?q=shared_objects+repo%3Ajaynetics%2Fleto+path%3Alib%2Fleto%2Futils.rb&type=code)
   - returns all objects shared by `obj1` and `obj2`, whether mutable or not
 
+To make a shareable copy while leaving the original mutable:
+
+```ruby
+copy = Leto.deep_freeze(object, shareable: true, copy: true)
+```
+
+Duplicating a Proc does not duplicate its captured environment. Shareable freezing
+uses Ruby's rules for Procs, Methods, and other native objects, which vary between
+Ruby versions.
+
+Shareable freezing leaves Classes and Modules as they are, following Ractor's
+rules. `include_modules: true` applies to regular deep freezing.
+
 ## Benchmarks
 
 ```

data/lib/leto/call.rb

@@ -38,6 +38,10 @@ module Leto
           traverse(k, path&.+([[:keys], [:[], i]]), depth, max_depth, seen, block)
           traverse(obj[k], path&.+([[:[], k]]), depth, max_depth, seen, block)
         end
+        obj.default.nil? ||
+          traverse(obj.default, path&.+([[:default]]), depth, max_depth, seen, block)
+        obj.default_proc.nil? ||
+          traverse(obj.default_proc, path&.+([[:default_proc]]), depth, max_depth, seen, block)
       when Module
         obj.class_variables.each do |cvar_name|
           traverse(
@@ -60,12 +64,19 @@ module Leto
         obj.members.each do |member|
           traverse(obj[member], path&.+([[:[], member]]), depth, max_depth, seen, block)
         end
-      when Enumerable
-        obj.each_with_index do |el, idx|
-          traverse(el, path&.+([[:[], idx]]), depth, max_depth, seen, block)
-        end
       #{
-        defined?(Data) && Data.respond_to?(:define) && <<-DATA_FEATURE_RUBY
+        set_feature? && <<-SET_FEATURE_RUBY
+        when Set
+          obj.each_with_index do |el, idx|
+            traverse(
+              el, path&.+([[:to_a], [:[], idx]]),
+              depth, max_depth, seen, block
+            )
+          end
+        SET_FEATURE_RUBY
+      }
+      #{
+        data_feature? && <<-DATA_FEATURE_RUBY
         when Data
           obj.members.each do |member|
             traverse(
@@ -76,6 +87,35 @@ module Leto
           end
         DATA_FEATURE_RUBY
       }
+      when Enumerable
+        obj.each_with_index do |el, idx|
+          traverse(el, path&.+([[:[], idx]]), depth, max_depth, seen, block)
+        end
+      when Complex
+        traverse(obj.real,      path&.+([[:real]]), depth, max_depth, seen, block)
+        traverse(obj.imaginary, path&.+([[:imaginary]]), depth, max_depth, seen, block)
+      when Rational
+        traverse(obj.numerator,   path&.+([[:numerator]]), depth, max_depth, seen, block)
+        traverse(obj.denominator, path&.+([[:denominator]]), depth, max_depth, seen, block)
+      when Exception
+        %i[
+          message backtrace backtrace_locations cause name receiver args key
+          matchee result exit_value reason tag value path status signo errno
+        ].each do |attr|
+          attr = :original_message if attr == :message && obj.respond_to?(:original_message)
+          begin
+            value = obj.send(attr)
+          rescue ArgumentError
+            # Some exceptions have no receiver or key.
+            raise unless %i[receiver key].include?(attr)
+          rescue NoMethodError # ignore
+          end
+          value.nil? ||
+            traverse(value, path&.+([[attr]]), depth, max_depth, seen, block)
+        end
+      when Time
+        obj.zone.nil? ||
+          traverse(obj.zone, path&.+([[:zone]]), depth, max_depth, seen, block)
       end
     end
 

data/lib/leto/features.rb

@@ -0,0 +1,12 @@
+# feature detection code for ruby
+module Leto
+  def self.data_feature?
+    defined?(Data) && Data.respond_to?(:define)
+  end
+
+  # Pre-Ruby-4.0, Hash-backed Sets are traversed through their
+  # @hash instance variable and don't need custom handling.
+  def self.set_feature?
+    defined?(Set) && Set.respond_to?(:[]) && !Set[].instance_variable_defined?(:@hash)
+  end
+end

data/lib/leto/utils.rb

@@ -34,8 +34,14 @@ module Leto
         copy[*args] = deep_dup(el, include_modules: include_modules)
       when :send # Data
         copy = copy.with(args[0] => deep_dup(el, include_modules: include_modules))
+      when :to_a # Set
+        copy = (copy - [el]) + [deep_dup(el, include_modules: include_modules)]
       when :begin
-        return Range.new(deep_dup(obj.begin), deep_dup(obj.end), obj.exclude_end?)
+        return Range.new(
+          deep_dup(obj.begin, include_modules: include_modules),
+          deep_dup(obj.end, include_modules: include_modules),
+          obj.exclude_end?,
+        )
       end
     end
 

data/lib/leto/version.rb

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

data/lib/leto.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative 'leto/features'
 require_relative 'leto/call'
 require_relative 'leto/dig'
 require_relative 'leto/path'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: leto
 version: !ruby/object:Gem::Version
-  version: 2.2.0
+  version: 2.4.0
 platform: ruby
 authors:
 - Janosch Müller
@@ -27,6 +27,7 @@ files:
 - lib/leto.rb
 - lib/leto/call.rb
 - lib/leto/dig.rb
+- lib/leto/features.rb
 - lib/leto/path.rb
 - lib/leto/utils.rb
 - lib/leto/version.rb
@@ -50,7 +51,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.23
 specification_version: 4
 summary: Generic object traverser
 test_files: []