weak 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 86165785c0d1874c5c54d7a72c3b703f5a21832cf0df8ffa917b4793dc40c502
-  data.tar.gz: a02c81a859c4f887181a2e33a124d6584a987d40cde92770fd1d6953a836f10d
+  metadata.gz: d99367de841cfb268442bccc306c3d43858cb6280a462cd513f21eb6c88ec366
+  data.tar.gz: da3360b4705d18a122a936a7a9dec0ab57839afc3dd846a24fc06dba46f645dd
 SHA512:
-  metadata.gz: 60d9a3259f88cd37a001b60fdf5247a856d1c637a54d0085712b347ab9b4c0dda330e8cabe69ead1bdf8193fdb70d8a0f7b419ea407afdcbea0b8e659331473c
-  data.tar.gz: b2dbc7c76ee9fd24d1a06df292e4683f5f5eb1a1b7a2d9db6ab653e691e818d3d6b3975589e020c47daede1b50ab48a4c417830af1c7b4cac12a9e2b61dc47f1
+  metadata.gz: 0abea00e5797abd15e865b366963ed481eaa70d519bb6cb46f1c21a68e836c9a5f8b7fb8450449671b250c155b4849e60df650f94d9b98d7ef74068366af8b38
+  data.tar.gz: 8e2ec5a83169a5f9e12fa965bc12e529fda24a05374eba811bc4dd6ee91f002e7de402b7372e44d234334cbe44d54f555eddff6f81a1286135ac06fe4b3faa31

data/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 ## [Unreleased]
 
+### Features
+
+- Add `Weak::Cache` as a thread-safe wrapper around `Weak::Map` to provide an object cache.
+
+### Bug Fixes
+
+- Fix `Weak::Map#store` method alias to `Weak::Map#[]=`. Previously, it was errouneously aliased to `Weak::Map#[]`.
+
+### Improvements
+
+- Adapt `Weak::Set#inspect` output to more resemble the output of `Set#inspect` in Ruby 4.0
+- Fix typos in code documentation
+- Use `require_relative` instead of require for all gem files
+- Add addititional specs for `Weak::Map`
+- Clarify humanistic usage policy
+
+## [0.2.1] - 2025-12-27
+
+- Fix typos in code documentation
+- Ignore some unnecessary methods defined on some `Weak::Set` implementations in `set_spec`
+- Run specs on JRuby 10 in Github Actions
+- Retry TruffleRuby rspec runs on Github Actions to avoid random failures due to flakey GC.
+- Extract `UNDEFINED` to its own file and require it where used.
+- Add more details about the gem version in `Weak::Version`
+- Handle object cycles in `pretty_print`.
+
 ## [0.2.0] - 2025-04-09
 
 - Add `Weak::Map#delete_if`
@@ -15,7 +41,6 @@
 
 - Initial version of `Weak::Set` to store an unordered collection of objects.
 - Initial version of `Weak::Map` to store key-value pairs of objects.
-
 - Support for Ruby 3.0 using the following impementations
     - Ruby (aka. MRI, aka. YARV) >= 3.0
     - JRuby >= 9.4

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2025 Holger Just
+Copyright (c) 2025 - 2026 Holger Just
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,6 +1,11 @@
 # Weak
 
 [![gem version badge](https://badge.fury.io/rb/weak.svg)](https://rubygems.org/gems/weak)
+[![license badge](https://img.shields.io/badge/license-MIT-brightgreen.svg)](#license)
+[![github repo badge](https://img.shields.io/badge/github-meineerde/weak-blue.svg)](https://github.com/meineerde/weak)
+[![documentation badge](https://img.shields.io/badge/docs-rubydoc.info-blue.svg)](https://www.rubydoc.info/gems/weak)
+
+[![code style: standard badge](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://github.com/standardrb/standard)
 [![CI status badge](https://github.com/meineerde/weak/actions/workflows/ci.yml/badge.svg)](https://github.com/meineerde/weak/actions/workflows/ci.yml)
 [![Coverage Status](https://coveralls.io/repos/github/meineerde/weak/badge.svg?branch=main)](https://coveralls.io/github/meineerde/weak?branch=main)
 
@@ -12,7 +17,10 @@ We provide multiple classes which behave similar to their standard-library count
 
 `Weak::Set` behaves similar to the [Set](https://docs.ruby-lang.org/en/3.4/Set.html) class of the Ruby standard library, but all values are only weakly referenced. That way, all values can be garbage collected and silently removed from the set unless they are still referenced from some other live object.
 
-Compared to the `Set` class however, there are a few differences:
+> [!CAUTION]
+> `Weak::Set` objects are not inherently thread-safe. When accessing a weak set from multiple threads or fibers, you MUST use a mutex or another locking mechanism.
+
+Compared to the `Set` class, there are a few differences:
 
   - All element references are weak, allowing each element to be garbage collected unless there is a strong reference to it somwhere else.
   - We do not necessarily retain the order of elements as they are inserted into the `Weak::Set`. You should not rely on a specific order.
@@ -24,13 +32,13 @@ require "weak/set"
 set = Weak::Set.new
 
 set << "some string"
-# => #<Weak::Set {"some string"}>
+# => Weak::Set["some string"]
 
 # Do some work, wait a bit, or force a garbage collection run
 3.times { GC.start }
 
 set
-# => #<Weak::Set {}>
+# => Weak::Set[]
 ```
 
 ## Weak::Map
@@ -38,11 +46,14 @@ set
 `Weak::Map` behaves similar to a `Hash` or an `ObjectSpace::WeakMap` in Ruby (aka. MRI, aka. YARV). 
 Both keys and values are weak references, allowing either of them to be garbage collected. If either the key or the value of a pair is garbage collected, the entire pair will be removed from the `Weak::Map`.
 
-Compared to the `Set` class however, there are a few differences:
+> [!CAUTION]
+> `Weak::Map` objects are not inherently thread-safe. When accessing a weak map from multiple threads or fibers, you MUST use a mutex or another locking mechanism.
+
+Compared to the `Hash` class, there are a few differences:
 
   - Key and value references are weak, allowing each key-value pair to be garbage collected unless there is a strong reference to boith the key and the value somewhere else.
   - We do not necessarily retain the order of elements as they are inserted into the `Weak::Map`. You should not rely on a specific order.
-  - Map membership is governed by object identity of the key rather than by using the `hash` and `eql?` methods of the elements. A `Weak::Map` thus works similat to a `Hash` marked as [compare_by_identity](https://docs.ruby-lang.org/en/3.4/Hash.html#method-i-compare_by_identity).
+  - Map membership is governed by object identity of the key rather than by using its `hash` and `eql?` methods. A `Weak::Map` thus works similar to a `Hash` marked as [compare_by_identity](https://docs.ruby-lang.org/en/3.4/Hash.html#method-i-compare_by_identity).
   - You can freely change both keys and values added to the `Weak::Map`.
 
 ```ruby
@@ -59,15 +70,35 @@ map
 # => #<Weak::Map {}>
 ```
 
+## Weak::Cache
+
+`Weak::Cache` is a thread-safe wrapper around `Weak::Map`. The class behaves similar to an `ActiveSupport::Cache::Store`.
+
+> [!TIP]
+> `Weak::Cache` objects can safely be used from multiple threads and fibers concurrently without any additional locks.
+
+Similar to a `Weak:Map`, both keys and values are weak references. Cache entries are removed if either the key of the value is garbage collected.
+
+```ruby
+require "weak/cache"
+cache = Weak::Cache.new
+
+# By default, we return nil for missing keys
+cache[:key] # => nil
+
+# With fetch, we can get a key and if it's missing, write a value for it
+cache.fetch(:key) { |key| key.upcase } # => :KEY
+
+# The value stored in the fetch above is stored in the cache
+cache[:key] # => :KEY
+```
+
 ## Usage
 
 Please refer to the documentation at:
 
 - [📘 Documentation](https://www.rubydoc.info/gems/weak)
-- [💥 Development Documentation](https://www.rubydoc.info/github/meineerde/weak/main) of the [main branch](https://github.com/meineerde/weak/tree/main)
-
-> [!WARNING]
-> The Weak collections are not inherently thread-safe. When accessing a collection from multiple threads or fibers, you MUST use a mutex or another locking mechanism.
+- [💥 Development Documentation](https://www.rubydoc.info/github/meineerde/weak) of the [main branch](https://github.com/meineerde/weak/tree/main)
 
 The Weak collections use Ruby's [ObjectSpace::WeakMap](https://docs.ruby-lang.org/en/3.4/ObjectSpace/WeakMap.html) under the hood. Unfortunately, different Ruby implementations and versions such as Ruby (aka. MRI, aka. YARV), JRuby, or TruffleRuby show quite diverse behavior in their respective `ObjectSpace::WeakMap` implementations. To provide a unified behavior on all supported Rubies, we use multiple different storage strategies.
 
@@ -158,7 +189,7 @@ During `checkout` we remember a reference to the returned connection object in t
 
 If the caller just "forgets" the connection, our pool will also forget it during the next Ruby garbage collection run.
 
-If the caller returns the connection by calling `checkin` again, we can verify that we have in fact created the object by deleting it from the `@outstanding` list. That way, the a checked-out connection can be checked-in again only once and only if it was initially created by the `ConnectionPool`.
+If the caller returns the connection by calling `checkin` again, we can verify that we have in fact created the object by deleting it from the `@outstanding` list. That way, a checked-out connection can be checked-in again only once and only if it was initially created by the `ConnectionPool`.
 
 ### Weak::Map Example
 
@@ -169,6 +200,8 @@ Even if a single object is wrapped in multiple `LockedObject` instances, we stil
 If all LockedObject instances for an `obj` and the `obj` itself vanish by being garbage collected, the associated mutex will also be garbage collected without requiring any external coordination.
 
 ```ruby
+require "weak/map"
+
 class LockedObject < BasicObject
   LOCKS = Weak::Map.new
   LOCKS_MUTEX = Mutex.new
@@ -211,21 +244,60 @@ string = "foo"
 end
 ```
 
+### Weak::Cache Example
+
+We can simplify the above example by using `Weak::Cache`.
+
+```ruby
+require "weak/cache"
+
+class LockedObject < BasicObject
+  LOCKS = Weak::Cache.new
+
+  def initialize(obj)
+    @obj = obj
+    @mutex = LOCKS.fetch(obj) { Mutex.new }
+  end
+
+  private
+
+  def method_missing(m, *args, **kwargs, &block)
+    @mutex.synchronize do
+      obj.public_send(m, *args, **kwargs, &block)
+    end
+  end
+
+  def respond_to_missing?(m)
+    obj.respond_to?(m)
+  end
+end
+```
+
+The `LockedObject` class we have defined here works exactly the same the the one in the `Weak::Map` example above. However, it avoids having to use a separate mutex for  accessing the `LOCKS` cache.
+
+In our `LockedObject#initialize`, if the given object already has an associated mutex in the `LOCKS` cache, we return it directly. If there was no previous mutex however, the `fetch` method will call the provided block and will store the result (i.e. the new `Mutex`) in the cache and return it.
+
+Subsequent invocations of `fetch` will return the same mutex again, unless it was garbage collected in the meantime.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `bundle exec rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
-[![code style: standard badge](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://github.com/standardrb/standard)
-
-We follow the Standard Ruby style. Please make sure that all code is formatted according to the Standard rules. This is enforced by the CI. Please try to keep all code lines at or below 100 characters in length.
+We follow the [Standard Ruby code style](https://github.com/standardrb/standard). Please make sure that all code is formatted according to the Standard rules. This is enforced by the CI. Please try to keep all code lines at or below 100 characters in length.
 
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/meineerde/weak. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/meineerde/weak/blob/main/CODE_OF_CONDUCT.md).
 
-## License
+## License and Usage Policy
+
+Weak is available as free and open source under the terms of the [MIT License](https://github.com/meineerde/weak/blob/main/LICENSE.txt).
+
+This license does not preclude you from using Weak with AI-encumbered or AI-associated projects, but you do not have the author's consent to do so. This may seem like a contradiction, but copyright is a blunt tool that does not in general have the humanistic nuance to describe something like "you can legally do this thing, but if you do, you're an asshole."
+
+We also explicitly affirm: Trans Rights Are Human Rights. If you do not agree, please refrain from using Weak.
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+(Thanks to [Cassandra Granade](https://codeberg.org/cgranade/do#license-and-ai-policy) for the inspiration.)
 
 ## Code of Conduct
 

data/lib/weak/cache.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+# Copyright (c) Holger Just
+#
+# This software may be modified and distributed under the terms
+# of the MIT license. See the LICENSE.txt file for details.
+
+require_relative "map"
+
+##
+module Weak
+  # `Weak::Cache` provides a thread-safe wrapper around {Weak::Map} to provide
+  # an object cache. As with a {Weak::Map}, keys and values are both weakly
+  # referenced so that a stored key-value pair vanishes if either the key or
+  # the value is garbage-collected.
+  #
+  # We implement an interface similar to that of `ActiveSupport::Cache::Store`.
+  class Cache
+    # Returns a new empty {Weak::Cache} object
+    def initialize
+      @map = Map.new
+      @mutex = Mutex.new
+    end
+
+    # Clears the entire cache.
+    #
+    # @return [self]
+    def clear
+      @mutex.synchronize { @map.clear }
+      self
+    end
+
+    # {Weak::Cache} objects can't be frozen since this is not enforced by the
+    # underlying {Weak::Map}, resp. its `ObjectSpace::WeakMap` implementation.
+    # Thus, we try to signal this by not actually setting the `frozen?` flag and
+    # ignoring attempts to freeze us with just a warning.
+    #
+    # @param freeze [Bool, nil] ignored; we always behave as if this is false.
+    #   If this is set to a truethy value, we emit a warning.
+    # @return [Weak::Cache] a new `Weak::Cache` object containing the same elements
+    #   as `self`
+    def clone(freeze: false)
+      warn("Can't freeze #{self.class}") if freeze
+      @mutex.synchronize { super(freeze: false) }
+    end
+
+    # Deletes an entry in the cache. Returns `true` if an entry was deleted,
+    # `false` otherwise.
+    #
+    # @param key [Object] the key to delete
+    # @return [Bool] `true` if the entry was deleted, `false` otherwise
+    # @!macro weak_map_note_object_equality
+    def delete(key)
+      @mutex.synchronize {
+        @map.delete(key) do
+          return false
+        end
+        true
+      }
+    end
+
+    # @return [Weak::Cache] a new `Weak::Cache` object containing the same elements
+    #   as `self`
+    def dup
+      @mutex.synchronize { super }
+    end
+
+    def each_key(&block)
+      return enum_for(__method__) { size } unless block_given?
+      keys.each(&block)
+      self
+    end
+
+    # (see Weak::Map#empty?)
+    def empty?
+      @mutex.synchronize { @map.empty? }
+    end
+
+    # (see Weak::Map#include?)
+    def exist?(key)
+      @mutex.synchronize { @map.include?(key) }
+    end
+    alias_method :include?, :exist?
+    alias_method :key?, :exist?
+
+    # Fetches data from the cache, using the given `key`. If there is a value in
+    # the cache for the given key, that value is returned.
+    #
+    # If there is no value in the cache (a cache miss), then the given block
+    # will be passed the key and executed in the event of a cache miss. The
+    # return value of the block will be written to the cache under the given
+    # cache key, and that return value will be returned.
+    #
+    # @param key [Object] the key for the requested value
+    # @param skip_nil [Bool] prevents caching a `nil` value from the block
+    # @yield [key] if no value was set at `key`, we call the block, write its
+    #   returned value for the `key` in the cache and return the value
+    # @yieldparam key [String] the given `key`
+    # @return [Object] the value for the given `key` if present in the cache. If
+    #   the key was not found, we return the value of the given block.
+    # @raise [ArgumentError] if no block was provided
+    # @!macro weak_map_note_object_equality
+    def fetch(key, skip_nil: false)
+      raise ArgumentError, "must provide a block" unless block_given?
+
+      @mutex.synchronize {
+        @map.fetch(key) {
+          value = yield(key)
+          @map[key] = value unless skip_nil && value.nil?
+        }
+      }
+    end
+
+    # {Weak::Cache} objects can't be frozen since this is not enforced by the
+    # underlying {Weak::Map}, resp. its `ObjectSpace::WeakMap` implementation.
+    # Thus, we try to signal this by not actually setting the `frozen?` flag and
+    # ignoring attempts to freeze us with just a warning.
+    #
+    # @return [self]
+    def freeze
+      warn("Can't freeze #{self.class}")
+      self
+    end
+
+    def inspect
+      @mutex.synchronize { "#<#{self.class} #{@map._inspect}>" }
+    end
+
+    # (see Weak::Map#keys)
+    def keys
+      @mutex.synchronize { @map.keys }
+    end
+
+    # @!visibility private
+    def pretty_print(pp)
+      pp.group(1, "#<#{self.class}", ">") do
+        pp.breakable
+        pp.pp @mutex.synchronize {
+          @map.to_a.sort_by! { |k, _v| k.__id__ }.to_h
+        }
+      end
+    end
+
+    # @!visibility private
+    def pretty_print_cycle(pp)
+      pp.text "#<#{self.class} {#{"..." unless empty?}}>"
+    end
+
+    # @param key [Object] the key for the requested value
+    # @return [Object] the value associated with the given `key`, or `nil` if
+    #   no value was found for the `key`
+    # @!macro weak_map_note_object_equality
+    def read(key)
+      @mutex.synchronize { @map[key] }
+    end
+    alias_method :[], :read
+
+    def size
+      @mutex.synchronize { @map.size }
+    end
+    alias_method :length, :size
+
+    # (see Weak::Map#to_h)
+    def to_h(&block)
+      @mutex.synchronize { @map.to_h(&block) }
+    end
+
+    # (see Weak::Map#[]=)
+    def write(key, value)
+      @mutex.synchronize { @map[key] = value }
+    end
+    alias_method :[]=, :write
+
+    private
+
+    def initialize_copy(orig)
+      @map = @map.dup
+      @mutex = Mutex.new
+    end
+  end
+end

data/lib/weak/map/abstract_strong_keys.rb

@@ -5,7 +5,7 @@
 # This software may be modified and distributed under the terms
 # of the MIT license. See the LICENSE.txt file for details.
 
-require "weak/map/deletable"
+require_relative "deletable"
 
 ##
 module Weak
@@ -34,9 +34,9 @@ module Weak
       private
 
       # This method is called during {#_get}. It generally needs to be
-      # overwritten in a "sub"-mdule to automatically cleanup any internal data.
-      # The implemented `auto_prune` method should quickly check if a prune is
-      # necessary and then either call the `prune` method or return.
+      # overwritten in a "sub"-module to automatically cleanup any internal
+      # data. The implemented `auto_prune` method should quickly check if a
+      # prune is necessary and then either call the `prune` method or return.
       #
       # @return [void]
       def auto_prune

data/lib/weak/map/strong_keys.rb

@@ -7,7 +7,8 @@
 
 require "set"
 
-require "weak/map/abstract_strong_keys"
+require_relative "abstract_strong_keys"
+require_relative "../undefined"
 
 ##
 module Weak

data/lib/weak/map/strong_secondary_keys.rb

@@ -7,7 +7,8 @@
 
 require "set"
 
-require "weak/map/abstract_strong_keys"
+require_relative "abstract_strong_keys"
+require_relative "../undefined"
 
 ##
 module Weak
@@ -53,7 +54,7 @@ module Weak
 
       # Checks if this strategy is usable for the current Ruby version.
       #
-      # @return [Bool] always `true` to indicate that this stragegy should be
+      # @return [Bool] always `true` to indicate that this strategy should be
       #   usable with any Ruby implementation which provides an
       #   `ObjectSpace::WeakMap`.
       def self.usable?

data/lib/weak/map/weak_keys.rb

@@ -5,7 +5,8 @@
 # This software may be modified and distributed under the terms
 # of the MIT license. See the LICENSE.txt file for details.
 
-require "weak/map/deletable"
+require_relative "deletable"
+require_relative "../undefined"
 
 ##
 module Weak
@@ -65,7 +66,8 @@ module Weak
         return enum_for(__method__) { size } unless block_given?
 
         @map.keys.each do |key|
-          yield key unless missing?(@map[key])
+          raw_value = @map[key]
+          yield key unless missing?(raw_value)
         end
         self
       end

data/lib/weak/map/weak_keys_with_delete.rb

@@ -5,6 +5,8 @@
 # This software may be modified and distributed under the terms
 # of the MIT license. See the LICENSE.txt file for details.
 
+require_relative "../undefined"
+
 ##
 module Weak
   class Map
@@ -19,16 +21,14 @@ module Weak
     # either of them vanishes, the entry is removed.
     #
     # The `ObjectSpace::WeakMap` also allows to delete entries. This allows us
-    # to directly use the `ObjectSpace::WeakMap` as a storage the same way a
-    # `Set` uses a `Hash` object object as storage.
+    # to directly use the `ObjectSpace::WeakMap` as a storage object.
     module WeakKeysWithDelete
       # Checks if this strategy is usable for the current Ruby version.
       #
       # @return [Bool] truethy for Ruby (aka. MRI, aka. YARV) >= 3.3.0,
       #   falsey otherwise
       def self.usable?
-        RUBY_ENGINE == "ruby" &&
-          ObjectSpace::WeakMap.instance_methods.include?(:delete)
+        RUBY_ENGINE == "ruby" && ObjectSpace::WeakMap.method_defined?(:delete)
       end
 
       # @!macro weak_map_accessor_read

data/lib/weak/map.rb

@@ -9,6 +9,7 @@ require_relative "map/weak_keys_with_delete"
 require_relative "map/weak_keys"
 require_relative "map/strong_keys"
 require_relative "map/strong_secondary_keys"
+require_relative "undefined"
 
 ##
 module Weak
@@ -33,7 +34,8 @@ module Weak
   #
   # Note that {Weak::Map} is not inherently thread-safe. When accessing a
   # {Weak::Map} from multiple threads or fibers, you MUST use a mutex or another
-  # locking mechanism.
+  # locking mechanism. You can also use {Weak::Cache} as a thread-safe
+  # alternative.
   #
   # ## Implementation Details
   #
@@ -95,7 +97,7 @@ module Weak
     # Here follows the documentation of strategy-specific methods which are
     # implemented in one of the include modules depending on the current Ruby.
 
-    # @!macro _note_object_equality
+    # @!macro weak_map_note_object_equality
     #   @note {Weak::Map} does not test member equality with `==` or `eql?`.
     #     Instead, it always checks strict object equality, so that, e.g.,
     #     different String keys are not considered equal, even if they may
@@ -107,7 +109,7 @@ module Weak
     #     `key` is not found, returns the default value, i.e. the value returned
     #     by the default proc (if defined) or the `default` value (which is
     #     initially `nil`.)
-    #   @!macro _note_object_equality
+    #   @!macro weak_map_note_object_equality
 
     # @!macro weak_map_accessor_write
     #   Associates the given `value` with the given `key`; returns `value`. If
@@ -116,7 +118,7 @@ module Weak
     #   @param key [Object] the key for the set key-value pair
     #   @param value [Object] the value of the set key-value pair
     #   @return [Object] the given `value`
-    #   @!macro _note_object_equality
+    #   @!macro weak_map_note_object_equality
 
     # @!macro weak_map_method_clear
     #   Removes all elements and returns `self`
@@ -135,7 +137,7 @@ module Weak
     #     if the key was not found and no block was given.
     #   @yield [key]
     #   @yieldparam key [Object] the given `key` if it was not part of the map
-    #   @!macro _note_object_equality
+    #   @!macro weak_map_note_object_equality
 
     # @!macro weak_map_method_each_pair
     #   Calls the given block once for each live key in `self`, passing the key
@@ -190,13 +192,13 @@ module Weak
     #     the given block.
     #   @raise [KeyError] if the key can not be found and no block or `default`
     #     value was provided
-    #   @!macro _note_object_equality
+    #   @!macro weak_map_note_object_equality
 
     # @!macro weak_map_method_include_question
     #   @param key [Object] a possible key
     #   @return [Bool] `true` if the given key is included in `self` and has an
     #     associated live value, `false` otherwise
-    #   @!macro _note_object_equality
+    #   @!macro weak_map_note_object_equality
 
     # @!macro weak_map_method_keys
     #   @return [Array] an `Array` containing all keys of the map for which we
@@ -287,7 +289,7 @@ module Weak
     # The initial default value and initial default proc for the new hash depend
     # on which form above was used.
     #
-    # If neither an `default_value` nor a block is given, initializes both the
+    # If neither a `default_value` nor a block is given, initializes both the
     # default value and the default proc to nil:
     #
     #     map = Weak::Map.new
@@ -331,7 +333,7 @@ module Weak
     alias_method :key?, :include?
     alias_method :member?, :include?
     alias_method :length, :size
-    alias_method :store, :[]
+    alias_method :store, :[]=
 
     # {Weak::Map} objects can't be frozen since this is not enforced by the
     # underlying `ObjectSpace::WeakMap` implementation. Thus, we try to signal
@@ -340,7 +342,7 @@ module Weak
     #
     # @param freeze [Bool, nil] ignored; we always behave as if this is false.
     #   If this is set to a truethy value, we emit a warning.
-    # @return [Weak::Set] a new `Weak::Map` object containing the same elements
+    # @return [Weak::Map] a new `Weak::Map` object containing the same elements
     #   as `self`
     def clone(freeze: false)
       warn("Can't freeze #{self.class}") if freeze
@@ -398,7 +400,7 @@ module Weak
     # Sets the default proc for self to `proc` and clears the {#default} value.
     #
     # @param proc [Proc, #to_proc nil] a `Proc` which can be called with two
-    #   arguments: the map and the rquested non-exiting key. The proc is
+    #   arguments: the map and the requested non-exiting key. The proc is
     #   expected to return the default value for the key. Whe giving `nil`, the
     #   default proc is cleared.
     # @return [Proc, nil] the new default proc
@@ -456,7 +458,7 @@ module Weak
       size == 0
     end
 
-    # {Weak::Set} objects can't be frozen since this is not enforced by the
+    # {Weak::Map} objects can't be frozen since this is not enforced by the
     # underlying `ObjectSpace::WeakMap` implementation. Thus, we try to signal
     # this by not actually setting the `frozen?` flag and ignoring attempts to
     # freeze us with just a warning.
@@ -470,7 +472,7 @@ module Weak
     # @param value [Object] a value to check
     # @return [Bool] `true` if `value` is a value in `self`, `false` otherwise
     #
-    # @!macro _note_object_equality
+    # @!macro weak_map_note_object_equality
     def has_value?(value)
       id = value.__id__
       each_value.any? { |v| v.__id__ == id }
@@ -481,18 +483,25 @@ module Weak
     #   the weak set, e.g.,
     #   `"#<Weak::Map {key1 => value1, key2 => value2, ...}>"`
     def inspect
+      "#<#{self.class} #{_inspect}>"
+    end
+    alias_method :to_s, :inspect
+
+    # @return [String] a string containing a human-readable representation of
+    #   just the data of the weak set, e.g.,
+    #   `"{key1 => value1, key2 => value2, ...}"`
+    # @!visibility private
+    def _inspect
       object_ids = (Thread.current[INSPECT_KEY] ||= [])
-      return "#<#{self.class} {...}>" if object_ids.include?(object_id)
+      return "{...}" if object_ids.include?(__id__)
 
-      object_ids << object_id
+      object_ids << __id__
       begin
-        elements = to_a.sort_by! { |k, _v| k.__id__ }.to_h.inspect[1..-2]
-        "#<#{self.class} {#{elements}}>"
+        to_a.sort_by! { |k, _v| k.__id__ }.to_h.inspect
       ensure
         object_ids.pop
       end
     end
-    alias_method :to_s, :inspect
 
     # Deletes every key-value pair from `self` for which the given block
     # evaluates to a falsey value.
@@ -536,7 +545,7 @@ module Weak
     #     h1 = {baz: 3, bar: 4}
     #     h2 = {bam: 5, baz: 6}
     #     map.merge(h1, h2)
-    #     # => #<Weak::Map {:foo=>0, :bar=>4, :baz=>6, :bam=>5}
+    #     # => #<Weak::Map {:foo=>0, :bar=>4, :baz=>6, :bam=>5}>
     #
     # With arguments and a block:
     #
@@ -558,7 +567,7 @@ module Weak
     #     h1 = {baz: 3, bar: 4}
     #     h2 = {bam: 5, baz: 6}
     #     map.merge(h1, h2) { |key, old_value, new_value| old_value + new_value }
-    #     # => #<Weak::Map {:foo=>0, :bar=>5, :baz=>9, :bam=>5}
+    #     # => #<Weak::Map {:foo=>0, :bar=>5, :baz=>9, :bam=>5}>
     #
     # With no arguments:
     #
@@ -577,7 +586,7 @@ module Weak
     #   `other_maps`
     # @return [Weak::Map] a new weak map containing the merged pairs
     #
-    # @!macro _note_object_equality
+    # @!macro weak_map_note_object_equality
     def merge(*other_maps, &block)
       dup.merge!(*other_maps, &block)
     end
@@ -590,6 +599,11 @@ module Weak
       end
     end
 
+    # @!visibility private
+    def pretty_print_cycle(pp)
+      pp.text "#<#{self.class} {#{"..." unless empty?}}>"
+    end
+
     # Deletes every key-value pair from `self` for which the given block
     # evaluates to a truethy value.
     #
@@ -600,9 +614,9 @@ module Weak
     # @yield [key, value] calls the given block once for each key in the map
     # @yieldparam key [Object] a key
     # @return [Enumerator, self, nil] `self` if a block was given and some
-    #    element(s) were deleted, `nil` if a block was given but no keys were
+    #   element(s) were deleted, `nil` if a block was given but no keys were
     #   deleted, or an `Enumerator` if no block was given.
-    # #see #delete_if
+    # @see #delete_if
     def reject!(&block)
       return enum_for(__method__) { size } unless block_given?
 
@@ -644,8 +658,8 @@ module Weak
     # @yieldparam key [Object] a key
     # @yieldparam value [Object] the corresponding value
     # @return [Enumerator, self, nil] `self` if a block was given and some
-    #    element(s) were deleted, `nil` if a block was given but nothing was
-    #    deleted, or an `Enumerator` if no block was given.
+    #   element(s) were deleted, `nil` if a block was given but nothing was
+    #   deleted, or an `Enumerator` if no block was given.
     # @see keep_if
     def select!(&block)
       return enum_for(__method__) { size } unless block_given?
@@ -682,7 +696,7 @@ module Weak
     #     h1 = {baz: 3, bar: 4}
     #     h2 = {bam: 5, baz: 6}
     #     map.update(h1, h2)
-    #     # => #<Weak::Map {:foo=>0, :bar=>4, :baz=>6, :bam=>5}
+    #     # => #<Weak::Map {:foo=>0, :bar=>4, :baz=>6, :bam=>5}>
     #
     # With arguments and a block:
     #
@@ -704,7 +718,7 @@ module Weak
     #     h1 = {baz: 3, bar: 4}
     #     h2 = {bam: 5, baz: 6}
     #     map.update(h1, h2) { |key, old_value, new_value| old_value + new_value }
-    #     # => #<Weak::Map {:foo=>0, :bar=>5, :baz=>9, :bam=>5}
+    #     # => #<Weak::Map {:foo=>0, :bar=>5, :baz=>9, :bam=>5}>
     #
     # With no arguments:
     #
@@ -723,7 +737,7 @@ module Weak
     #   `other_maps`
     # @return [self]
     #
-    # @!macro _note_object_equality
+    # @!macro weak_map_note_object_equality
     def update(*other_maps)
       if block_given?
         missing = Object.new

data/lib/weak/set/strong_secondary_keys.rb

@@ -44,7 +44,7 @@ module Weak
 
       # Checks if this strategy is usable for the current Ruby version.
       #
-      # @return [Bool] always `true` to indicate that this stragegy should be
+      # @return [Bool] always `true` to indicate that this strategy should be
       #   usable with any Ruby implementation which provides an
       #   `ObjectSpace::WeakMap`.
       def self.usable?

data/lib/weak/set/weak_keys_with_delete.rb

@@ -19,16 +19,14 @@ module Weak
     # either of them vanishes, the entry is removed.
     #
     # The `ObjectSpace::WeakMap` also allows to delete entries. This allows us
-    # to directly use the `ObjectSpace::WeakMap` as a storage the same way a
-    # `::Set` uses a `Hash` object object as storage.
+    # to directly use the `ObjectSpace::WeakMap` as a storage object.
     module WeakKeysWithDelete
       # Checks if this strategy is usable for the current Ruby version.
       #
       # @return [Bool] truethy for Ruby (aka. MRI, aka. YARV) >= 3.3.0,
       #   falsey otherwise
       def self.usable?
-        RUBY_ENGINE == "ruby" &&
-          ObjectSpace::WeakMap.instance_methods.include?(:delete)
+        RUBY_ENGINE == "ruby" && ObjectSpace::WeakMap.method_defined?(:delete)
       end
 
       # @!macro weak_set_method_add

data/lib/weak/set.rb

@@ -71,11 +71,11 @@ module Weak
   # @example
   #   require "weak/set"
   #
-  #   s1 = Weak::Set[1, 2]                  #=> #<Weak::Set {1, 2}>
-  #   s2 = Weak::Set.new [1, 2]             #=> #<Weak::Set {1, 2}>
+  #   s1 = Weak::Set[1, 2]                  #=> Weak::Set[1, 2]
+  #   s2 = Weak::Set.new [1, 2]             #=> Weak::Set[1, 2]
   #   s1 == s2                              #=> true
-  #   s1.add(:foo)                          #=> #<Weak::Set {1, 2, :foo}>
-  #   s1.merge([2, 6])                      #=> #<Weak::Set {1, 2, :foo, 6}>
+  #   s1.add(:foo)                          #=> Weak::Set[1, 2, :foo]
+  #   s1.merge([2, 6])                      #=> Weak::Set[1, 2, 6, :foo]
   #   s1.subset?(s2)                        #=> false
   #   s2.subset?(s1)                        #=> true
   class Set
@@ -97,7 +97,7 @@ module Weak
     # Here follows the documentation of strategy-specific methods which are
     # implemented in one of the include modules depending on the current Ruby.
 
-    # @!macro _note_object_equality
+    # @!macro weak_set_note_object_equality
     #   @note {Weak::Set} does not test member equality with `==` or `eql?`.
     #     Instead, it always checks strict object equality, so that, e.g.,
     #     different strings are not considered equal, even if they may contain
@@ -115,9 +115,9 @@ module Weak
     #   @return [self]
     #
     #   @example
-    #       Weak::Set[1, 2].add(3)                #=> #<Weak::Set {1, 2, 3}>
-    #       Weak::Set[1, 2].add([3, 4])           #=> #<Weak::Set {1, 2, [3, 4]}>
-    #       Weak::Set[1, 2].add(2)                #=> #<Weak::Set {1, 2}>
+    #       Weak::Set[1, 2].add(3)                #=> Weak::Set[1, 2, 3]
+    #       Weak::Set[1, 2].add([3, 4])           #=> Weak::Set[1, 2, [3, 4]]
+    #       Weak::Set[1, 2].add(2)                #=> Weak::Set[1, 2]
 
     # @!macro weak_set_method_clear
     #   Removes all elements and returns `self`
@@ -131,7 +131,7 @@ module Weak
     #   @param obj [Object]
     #   @return [self, nil] `self` if the given object was deleted from the set
     #     or `nil` if the object was not part of the set
-    #   @!macro _note_object_equality
+    #   @!macro weak_set_note_object_equality
 
     # @!macro weak_set_method_each
     #   Calls the given block once for each live element in `self`, passing that
@@ -148,7 +148,7 @@ module Weak
     #   @param obj [Object] an object
     #   @return [Bool] `true` if the given object is included in `self`, `false`
     #     otherwise
-    #   @!macro _note_object_equality
+    #   @!macro weak_set_note_object_equality
 
     # @!macro weak_set_method_prune
     #   Cleanup data structures from the set to remove data associated with
@@ -164,9 +164,9 @@ module Weak
     #   @param enum (see #do_with_enum)
     #   @return [self]
     #   @example
-    #       set = Weak::Set[1, :c, :s]        #=> #<Weak::Set {1, :c, :s}>
-    #       set.replace([1, 2])               #=> #<Weak::Set {1, 2}>
-    #       set                               #=> #<Weak::Set {1, 2}>
+    #       set = Weak::Set[1, :c, :s]        #=> Weak::Set[1, :c, :s]
+    #       set.replace([1, 2])               #=> Weak::Set[1, 2]
+    #       set                               #=> Weak::Set[1, 2]
 
     # @!macro weak_set_method_size
     #   @return [Integer] the number of live elements in `self`
@@ -212,15 +212,16 @@ module Weak
     INSPECT_KEY = :__inspect_key__
     private_constant :INSPECT_KEY
 
-    # @param ary [Array<Object>] a list of objects
+    # @param objects [Array<Object>] a list of objects
     # @return [Weak::Set] a new weak set containing the given objects
+    # @see #initialize
     #
     # @example
-    #     Weak::Set[1, 2]                   # => #<Weak::Set {1, 2}>
-    #     Weak::Set[1, 2, 1]                # => #<Weak::Set {1, 2}>
-    #     Weak::Set[1, :c, :s]              # => #<Weak::Set {1, :c, :s}>
-    def self.[](*ary)
-      new(ary)
+    #     Weak::Set[1, 2]                   # => Weak::Set[1, 2]
+    #     Weak::Set[1, 2, 1]                # => Weak::Set[1, 2]
+    #     Weak::Set[1, :c, :s]              # => Weak::Set[1, :c, :s]
+    def self.[](*objects)
+      new(objects)
     end
 
     # @param enum (see #do_with_enum)
@@ -253,11 +254,11 @@ module Weak
     # @param enum (see #do_with_enum)
     # @return [Weak::Set] a new weak set built by merging `self` and the elements
     #   of the given enumerable object.
-    # @!macro _note_object_equality
+    # @!macro weak_set_note_object_equality
     #
     # @example
-    #     Weak::Set[1, 2, 3] | Weak::Set[2, 4, 5] # => #<Weak::Set {1, 2, 3, 4, 5}>
-    #     Weak::Set[1, 3, :z] | (1..4)            # => #<Weak::Set {1, 3, :z, 2, 4}>
+    #     Weak::Set[1, 2, 3] | Weak::Set[2, 4, 5] # => Weak::Set[1, 2, 3, 4, 5]
+    #     Weak::Set[1, 3, :z] | (1..4)            # => Weak::Set[1, 2, 3, 4, :z]
     def |(enum)
       new_set = dup
       do_with_enum(enum) do |obj|
@@ -271,11 +272,11 @@ module Weak
     # @param enum (see #do_with_enum)
     # @return [Weak::Set] a new weak set built by duplicating `self`, removing
     #   every element that appears in the given enumerable object from that.
-    # @!macro _note_object_equality
+    # @!macro weak_set_note_object_equality
     #
     # @example
-    #     Weak::Set[1, 3, 5] - Weak::Set[1, 5]        # => #<Weak::Set {3}>
-    #     Weak::Set['a', 'b', 'z'] - ['a', 'c']       # => #<Weak::Set {"b", "z"}>
+    #     Weak::Set[1, 3, 5] - Weak::Set[1, 5]        # => Weak::Set[3]
+    #     Weak::Set['a', 'b', 'z'] - ['a', 'c']       # => Weak::Set["b", "z"]
     def -(enum)
       dup.subtract(enum)
     end
@@ -284,11 +285,11 @@ module Weak
     # @param enum (see #do_with_enum g)
     # @return [Weak::Set] a new weak set containing elements common to `self`
     #   and the given enumerable object.
-    # @!macro _note_object_equality
+    # @!macro weak_set_note_object_equality
     #
     # @example
-    #     Weak::Set[1, 3, 5] & Weak::Set[3, 2, 1]    # => #<Weak::Set {3, 1}>
-    #     Weak::Set[1, 2, 9] & [2, 1, 3]             # => #<Weak::Set {1, 2}>
+    #     Weak::Set[1, 3, 5] & Weak::Set[3, 2, 1]    # => Weak::Set[1, 3]
+    #     Weak::Set[1, 2, 9] & [2, 1, 3]             # => Weak::Set[1, 2]
     def &(enum)
       new_set = self.class.new
       do_with_enum(enum) do |obj|
@@ -303,7 +304,7 @@ module Weak
     #   elements, `-1` / `+1` if `self` is a proper subset / superset of the
     #   given `set`, or `nil` if they both have unique elements or `set` is not
     #   a {Weak::Set}
-    # @!macro _note_object_equality
+    # @!macro weak_set_note_object_equality
     def <=>(other)
       return unless Weak::Set === other
       return 0 if equal?(other)
@@ -349,11 +350,11 @@ module Weak
     #
     # @param enum (see #do_with_enum)
     # @return [Weak::Set] a new weak set
-    # @!macro _note_object_equality
+    # @!macro weak_set_note_object_equality
     #
     # @example
-    #     Weak::Set[1, 2] ^ Set[2, 3]           #=> #<Weak::Set {3, 1}>
-    #     Weak::Set[1, :b, :c] ^ [:b, :d]       #=> #<Weak::Set {:d, 1, :c}>
+    #     Weak::Set[1, 2] ^ Set[2, 3]           #=> Weak::Set[1, 3]
+    #     Weak::Set[1, :b, :c] ^ [:b, :d]       #=> Weak::Set[1, :c, :d]
     def ^(enum)
       return dup if enum.nil?
 
@@ -368,7 +369,7 @@ module Weak
     # @return [Object, nil] the provided `obj` if it is included in `self`,
     #   `nil` otherwise
     # @see #include?
-    # @!macro _note_object_equality
+    # @!macro weak_set_note_object_equality
     def [](obj)
       obj if include?(obj)
     end
@@ -379,11 +380,11 @@ module Weak
     # @param obj [Object] an object to add to the weak set
     # @return [self, nil] `self` if the object was added, `nil` if it was part
     #   of the set already
-    # @!macro _note_object_equality
+    # @!macro weak_set_note_object_equality
     #
     # @example
-    #     Weak::Set[1, 2].add?(3)              #=> #<Weak::Set {1, 2, 3}>
-    #     Weak::Set[1, 2].add?([3, 4])         #=> #<Weak::Set {1, 2, [3, 4]}>
+    #     Weak::Set[1, 2].add?(3)              #=> Weak::Set[1, 2, 3]
+    #     Weak::Set[1, 2].add?([3, 4])         #=> Weak::Set[1, 2, [3, 4]]
     #     Weak::Set[1, 2].add?(2)              #=> nil
     def add?(obj)
       add(obj) unless include?(obj)
@@ -423,7 +424,7 @@ module Weak
     #
     # @param obj [Object] an object to delete from the weak set
     # @return [self] always returns self
-    # @!macro _note_object_equality
+    # @!macro weak_set_note_object_equality
     def delete(obj)
       delete?(obj)
       self
@@ -450,7 +451,7 @@ module Weak
     # @param enum (see #intersect)
     # @return [Bool] `true` if `self` and the given `enum` have no element in
     #   common. This method is the opposite of {#intersect?}.
-    # @!macro _note_object_equality
+    # @!macro weak_set_note_object_equality
     def disjoint?(enum)
       !intersect?(enum)
     end
@@ -472,15 +473,18 @@ module Weak
     end
 
     # @return [String] a string containing a human-readable representation of
-    #   the weak set, e.g., `"#<Weak::Set {element1, element2, ...}>"`
+    #   the weak set, e.g., `"Weak::Set[element1, element2, ...]"`
+    # @note The elements of the set are ordered by their object id in the
+    #   inspect output. If we detect a reference cycle (e.g. with a set
+    #   containing itself), we output `"Weak::Set[...]"`.
     def inspect
       object_ids = (Thread.current[INSPECT_KEY] ||= [])
-      return "#<#{self.class} {...}>" if object_ids.include?(object_id)
+      return "#{self.class}[...]" if object_ids.include?(object_id)
 
       object_ids << object_id
       begin
         elements = to_a.sort_by!(&:__id__).inspect[1..-2]
-        "#<#{self.class} {#{elements}}>"
+        "#{self.class}[#{elements}]"
       ensure
         object_ids.pop
       end
@@ -490,7 +494,7 @@ module Weak
     # @param enum (see #enumerable)
     # @return [Bool] `true` if `self` and the given enumerable object have at
     #   least one element in common, `false` otherwise
-    # @!macro _note_object_equality
+    # @!macro weak_set_note_object_equality
     #
     # @example
     #     Weak::Set[1, 2, 3].intersect? Weak::Set[4, 5]   #=> false
@@ -549,19 +553,16 @@ module Weak
 
     # @!visibility private
     def pretty_print(pp)
-      pp.group(1, "#<#{self.class}", ">") do
-        pp.breakable
-        pp.group(1, "{", "}") do
-          pp.seplist(to_a.sort_by!(&:__id__)) do |obj|
-            pp.pp obj
-          end
+      pp.group(1, "#{self.class}[", "]") do
+        pp.seplist(to_a.sort_by!(&:__id__)) do |obj|
+          pp.pp obj
         end
       end
     end
 
     # @!visibility private
     def pretty_print_cycle(pp)
-      pp.text "#<#{self.class} {#{empty? ? "" : "..."}}>"
+      pp.text "#{self.class}[#{"..." unless empty?}]"
     end
 
     # @param other [Weak::Set] a weak set
@@ -584,7 +585,7 @@ module Weak
     # @param other [Weak::Set] a weak set
     # @return [Bool] `true` if `self` is a proper superset of the given `set`,
     #   `false` otherwise
-    # @!macro _note_object_equality
+    # @!macro weak_set_note_object_equality
     # @see superset?
     def proper_superset?(other)
       if Weak::Set === other
@@ -609,9 +610,9 @@ module Weak
     # @yield [element] calls the given block once for each live object in `self`
     # @yieldparam element [Object] the element to check
     # @return [Enumerator, self, nil] `self` if a block was given and some
-    #    element(s) were deleted, `nil` if a block was given but no keys were
+    #   element(s) were deleted, `nil` if a block was given but no keys were
     #   deleted, or an `Enumerator` if no block was given.
-    # #see #delete_if
+    # @see #delete_if
     def reject!(&block)
       return enum_for(__method__) { size } unless block_given?
 
@@ -633,8 +634,8 @@ module Weak
     # @yield [element] calls the given block once for each element in the set
     # @yieldparam element [Object] the element to check
     # @return [Enumerator, self, nil] `self` if a block was given and some
-    #    element(s) were deleted, `nil` if a block was given but nothing was
-    #    deleted, or an `Enumerator` if no block was given.
+    #   element(s) were deleted, `nil` if a block was given but nothing was
+    #   deleted, or an `Enumerator` if no block was given.
     # @see keep_if
     def select!(&block)
       return enum_for(__method__) { size } unless block_given?
@@ -651,7 +652,7 @@ module Weak
     # @param other [Weak::Set] a weak set
     # @return [Bool] `true` if `self` is a subset of the given `set`, `false`
     #   otherwise
-    # @!macro _note_object_equality
+    # @!macro weak_set_note_object_equality
     # @see proper_subset?
     def subset?(other)
       if Weak::Set === other

data/lib/weak/undefined.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+# Copyright (c) Holger Just
+#
+# This software may be modified and distributed under the terms
+# of the MIT license. See the LICENSE.txt file for details.
+
+require "singleton"
+
+##
+module Weak
+  # A class for the {UNDEFINED} object. Being a singleton, there will only be
+  # exactly one object of this class: the {UNDEFINED} object.
+  #
+  # @private
+  class UndefinedClass
+    include Singleton
+
+    def initialize
+      freeze
+    end
+
+    # @return [String] the string `"UNDEFINED"`
+    def to_s
+      "UNDEFINED"
+    end
+    alias_method :inspect, :to_s
+  end
+
+  # The {UNDEFINED} object can be used as the default value for method arguments
+  # to distinguish it from `nil`.
+  #
+  # @see https://holgerjust.de/2016/detecting-default-arguments-in-ruby/#special-default-value
+  UNDEFINED = UndefinedClass.instance
+end

data/lib/weak/version.rb

@@ -7,8 +7,36 @@
 
 ##
 module Weak
-  # The {Weak} version as a `Gem::Version` string. We follow semantic
-  # versioning.
-  # @see https://semver.org/
-  VERSION = "0.2.0"
+  # Version information about {Weak}. We follow semantic versioning.
+  module Version
+    # MAJOR version. It is incremented after incompatible API changes
+    MAJOR = 0
+    # MINOR version. It is incremented after adding functionality in a
+    # backwards-compatible manner
+    MINOR = 3
+    # PATCH version. It is incremented when making backwards-compatible
+    # bug-fixes.
+    PATCH = 0
+    # PRERELEASE suffix. Set to a alphanumeric string on any pre-release
+    # versions like beta or RC releases; `nil` on regular releases
+    PRERELEASE = nil
+
+    # The {Weak} version as a `Gem::Version` string. We follow semantic
+    # versioning.
+    # @see https://semver.org/
+    STRING = [MAJOR, MINOR, PATCH, PRERELEASE].compact.join(".").freeze
+
+    # @return [Gem::Version] the {Weak} version as a `Gem::Version` object
+    def self.gem_version
+      Gem::Version.new STRING
+    end
+
+    # @return [String] the Weak version as a `Gem::Version` string
+    def self.to_s
+      STRING
+    end
+  end
+
+  # (see Version::STRING)
+  VERSION = Weak::Version::STRING
 end

data/lib/weak.rb

@@ -5,11 +5,10 @@
 # This software may be modified and distributed under the terms
 # of the MIT license. See the LICENSE.txt file for details.
 
-require "singleton"
-
 require_relative "weak/version"
 require_relative "weak/map"
 require_relative "weak/set"
+require_relative "weak/cache"
 
 # Weak is a Ruby library which implements collections of unordered values
 # without strong object references.
@@ -19,27 +18,4 @@ require_relative "weak/set"
 # elements can be garbage collected and silently removed from the collection
 # unless they are still referenced from some other live object.
 module Weak
-  # A class for the {UNDEFINED} object. Being a singleton, there will only be
-  # exactly one object of this class: the {UNDEFINED} object.
-  #
-  # @private
-  class UndefinedClass
-    include Singleton
-
-    def initialize
-      freeze
-    end
-
-    # @return [String] the string `"UNDEFINED"`
-    def to_s
-      "UNDEFINED"
-    end
-    alias_method :inspect, :to_s
-  end
-
-  # The {UNDEFINED} object can be used as the default value for method arguments
-  # to distinguish it from `nil`.
-  #
-  # @see https://holgerjust.de/2016/detecting-default-arguments-in-ruby/#special-default-value
-  UNDEFINED = UndefinedClass.instance
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: weak
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Holger Just
 bindir: bin
 cert_chain: []
-date: 2025-04-09 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
 description: |
   The Weak library provides a Weak::Set class to store an unordered list of
@@ -24,6 +24,7 @@ files:
 - LICENSE.txt
 - README.md
 - lib/weak.rb
+- lib/weak/cache.rb
 - lib/weak/map.rb
 - lib/weak/map/abstract_strong_keys.rb
 - lib/weak/map/deletable.rb
@@ -36,6 +37,7 @@ files:
 - lib/weak/set/strong_secondary_keys.rb
 - lib/weak/set/weak_keys.rb
 - lib/weak/set/weak_keys_with_delete.rb
+- lib/weak/undefined.rb
 - lib/weak/version.rb
 homepage: https://github.com/meineerde/weak
 licenses:
@@ -45,7 +47,7 @@ metadata:
   homepage_uri: https://github.com/meineerde/weak
   source_code_uri: https://github.com/meineerde/weak
   changelog_uri: https://github.com/meineerde/weak/blob/main/CHANGELOG.md
-  documentation_uri: https://www.rubydoc.info/gems/weak/0.2.0
+  documentation_uri: https://www.rubydoc.info/gems/weak/0.3.0
 rdoc_options: []
 require_paths:
 - lib
@@ -60,7 +62,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.3
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Tools to handle collections of weakly-referenced values
 test_files: []