defi 3.0.1 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cbd2a5befa5ac9808bfe1c121549311dfed58c0a48070b9708ec46621a101255
-  data.tar.gz: b1f16e2e70d07e377e7f662a807afb1afbe9cc971535cb683d5000b19b0306de
+  metadata.gz: 147abcfe45309cf8e5e5df3cf02dbcaeaccd2c421841ab017844206dd1218ed1
+  data.tar.gz: 8d82cceb4e3e68f29ee6ae8632369cf9c4d2bdfdc3d3ba1a1cd3de5659cad8bc
 SHA512:
-  metadata.gz: a673ab6344aa7f6ebe0b04ff7556b0f3d5524cec97f26810613858afe874f96362081a293cabadcdcf8a09da1c10c75ef8fa0e5a3efc39fc3f075660febc6a9a
-  data.tar.gz: a8c78c9725743ba1efeb8e3ac12afb5dca6403d8a7d6b714142814db42d7d60b075b5a3d5431a2145b33319f2c6d08742e50fe91d4e7ea5916579a8185b4bcdd
+  metadata.gz: 9c0076455aa06379af57797aff1c160fce9bd1d930f45702a95eea4836b0c77270f9bcdac8cb4f00b4c5fe364766cb0a8a07b3f4c0800606366df9408debe882
+  data.tar.gz: '0379b004d430b65a97b2f56d2a968457ec37a41510a08f253899060e7645937b7c29e234e2d6a9bbca75b991edde71485ade15d64cb0f61a7b348fd750d2e092'

data/LICENSE.md

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2015-2025 Cyril Kato
+Copyright (c) 2015-2026 Cyril Kato
 
 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

@@ -4,78 +4,71 @@
 [![Yard documentation](https://img.shields.io/badge/Yard-documentation-blue.svg?logo=github)](https://rubydoc.info/github/fixrb/defi/main)
 [![License](https://img.shields.io/github/license/fixrb/defi?label=License&logo=github)](https://github.com/fixrb/defi/raw/main/LICENSE.md)
 
-**Defi** is a streamlined Ruby library designed for the specification of method arguments while respecting their signatures.
-Rather than representing method signatures themselves, Defi focuses on providing a way to furnish methods with appropriate arguments, thereby preparing them for invocation.
-
-This approach serves as an alternative to traditional methods like `Object#method` and `UnboundMethod`.
-Where `Object#method` is bound to a specific object and `UnboundMethod` requires compatibility with the method’s originating class, Defi offers a more flexible and universal way to prepare method calls.
-It allows method arguments to be specified in advance and then applied to any compatible object – those equipped with corresponding methods.
-
-Defi is particularly useful in scenarios where you need to apply a set of method arguments across different objects to observe the varying outcomes, whether they be returned values or exceptions.
-This makes it an ideal tool for testing, method comparison across different implementations, or any situation where method behavior needs to be assessed dynamically across various objects.
+Defi prepares a method call, a name with its arguments, and sends it to any object, keeping what came back: the value returned, or the exception raised. The same call can be sent to as many objects as you like, to compare what each one does with it.
 
 ## Installation
 
-Add this line to your application's Gemfile:
-
 ```ruby
+# Gemfile
 gem "defi"
 ```
 
-And then execute:
+Defi requires Ruby 3.3 or later, and depends on nothing.
 
-```sh
-bundle install
-```
+## Usage
 
-Or install it yourself as:
+A challenge is a method name, with positional arguments, keyword arguments and a block, as you would write them after a dot:
 
-```sh
-gem install defi
-```
+```ruby
+require "defi"
 
-## Usage
+challenge = Defi::Challenge.new(:fetch, :b, 0)
+challenge.to_s # => ".fetch(:b, 0)"
+```
 
-The `Defi` library simplifies the task of applying method signatures to various objects, regardless of their type (instances, modules, etc.).
-Below are some detailed examples to demonstrate its versatility and ease of use:
+Sent to an object with `to`, it brings back a value: what the method returned, or what it raised.
 
-### Example 1: Multiplying Numbers
+```ruby
+value = challenge.to({ b: 2 })
+value.raised? # => false
+value.object  # => 2
+value.call    # => 2
+
+value = Defi::Challenge.new(:fetch, :b).to({})
+value.raised? # => true
+value.object  # => #<KeyError: key not found: :b>
+value.call    # raises the KeyError again
+```
 
-Suppose you want to multiply the number `6` by `7`.
-With `Defi`, this can be elegantly done as follows:
+Keyword arguments and the block go through as they are:
 
 ```ruby
-result = Defi(:*, 7).to(6).call
-puts result # Output: 42
+Defi::Challenge.new(:encode, "US-ASCII", undef: :replace).to("café").object # => "caf?"
+Defi::Challenge.new(:map) { |n| n * 2 }.to([1, 2]).object # => [2, 4]
 ```
 
-Here, `Defi(:*, 7)` creates a challenge with the multiplication method (`:*`) and the argument `7`.
-The `.to(6)` method specifies that this challenge should be applied to the number `6`.
-Finally, `.call` executes the challenge, yielding the result `42`.
+## What comes back
 
-### Example 2: Invoking an Undefined Method
+The message is sent with `public_send`: a private method, or a `BasicObject`, which has no `public_send`, gives a `NoMethodError`. `public_send` protects the named method only: a challenge of `send` or `instance_eval`, which are public, reaches what they reach.
 
-`Defi` also elegantly handles cases where the method might not exist on the target object.
-For instance:
+A challenge keeps as its value the exceptions a method raises on its own: a `StandardError`, a `ScriptError` (such as `NotImplementedError`), a `SystemStackError`, or the `SystemExit` of an `exit` or an `abort`. What is not the method's doing goes through: an `Interrupt`, a `SignalException`, a `NoMemoryError`, the exception a `Timeout` uses to end its block (a `Timeout` given a class to raise, such as `RuntimeError`, is kept like any `StandardError`), and any other subclass of `Exception`. `Defi::Value::RAISED` lists the classes kept. `call` raises the exception again, the same object, with its own cause.
 
-```ruby
-begin
-  Defi(:boom).to("foo").call
-rescue NoMethodError => e
-  puts e.message # Output: undefined method `boom' for "foo":String
-end
-```
+`to_s` writes the call as `.name(1, key: 2, &block)`: the arguments and the keys by their `inspect`, which runs their code and can change from one Ruby to the next (a Hash in 3.4, a Set in 4.0), the block as `&block`.
+
+A challenge and a value are frozen. Their arguments are the objects given, not copies: a mutable argument stays shared with the caller.
 
-In this example, we attempt to call the non-existent method `boom` on the string `"foo"`.
-`Defi` correctly raises a `NoMethodError`, showing that the method `boom` is undefined for a `String` object.
+## Changes in 4.0
 
-## Contact
+Compared with 3.0.1:
 
-* Source code: https://github.com/fixrb/defi/issues
+- `Defi::Method` becomes `Defi::Challenge`, a plain class, no longer a `BasicObject`, in `defi/challenge.rb`: `require "defi/method"` becomes `require "defi"`. `Kernel#Defi`, which every object received as a public method, is gone: write `Defi::Challenge.new`.
+- `to` keeps the exceptions of the method only, where 3.0.1 caught every `Exception`, `Timeout` and `Interrupt` included. A name that is not a Symbol raises `ArgumentError`, as documented, with a new message; the `BasicObject` could not even `raise`. `call` keeps the cause of the exception it raises again.
+- `Challenge#to_s` writes keyword arguments as `key: value` and the block as `&block`. `args` and `opts` are frozen. `Value.new` takes the object and whether it was raised; `Value::RAISE` and `Value::RETURN` are gone, as are `to_h` on both classes, `to_s` on a value and the custom `inspect` methods.
+- Ruby 3.3 or later; tested on 3.3, 3.4, 4.0 and head.
 
 ## Versioning
 
-__Defi__ follows [Semantic Versioning 2.0](https://semver.org/).
+Defi follows [Semantic Versioning 2.0](https://semver.org/).
 
 ## License
 

data/lib/defi/challenge.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require_relative "value"
+
+module Defi
+  # A method call prepared in advance: a name, positional arguments, keyword
+  # arguments and a block, to send to any object with {#to}. A challenge is
+  # frozen, and sends its message as `public_send` does: a private method is
+  # a `NoMethodError`, while a public one that reaches further, such as
+  # `send` or `instance_eval`, does what it does.
+  class Challenge
+    # @return [Symbol] the name of the method
+    attr_reader :name
+
+    # @return [Array] the positional arguments, frozen
+    attr_reader :args
+
+    # @return [Hash] the keyword arguments, frozen
+    attr_reader :opts
+
+    # @return [Proc, nil] the block
+    attr_reader :block
+
+    # @param name [Symbol] the name of the method
+    # @param args [Array] the positional arguments
+    # @param opts [Hash] the keyword arguments
+    # @param block [Proc] the block
+    # @raise [ArgumentError] when the name is not a Symbol
+    def initialize(name, *args, **opts, &block)
+      raise ::ArgumentError, "the name of the method must be a Symbol" unless name.instance_of?(::Symbol)
+
+      @name = name
+      @args = args.freeze
+      @opts = opts.freeze
+      @block = block
+      freeze
+    end
+
+    # Sends the message to an object. What the method raises comes back as
+    # the value, as long as it is the method's own doing: a `StandardError`,
+    # a `ScriptError` (such as `NotImplementedError`), a `SystemStackError`
+    # or a `SystemExit`. An `Interrupt`, a signal, a `NoMemoryError` and the
+    # exception a `Timeout` uses to end the block go through.
+    #
+    # @param object [Object] the receiver; a `BasicObject` has no
+    #   `public_send`, so the value is a `NoMethodError`
+    # @return [Defi::Value] what came back
+    def to(object)
+      Value.new(object.public_send(name, *args, **opts, &block), false)
+    rescue *Value::RAISED => e
+      Value.new(e, true)
+    end
+
+    # @return [String] the call, as `.name(1, key: 2, &block)`: the arguments
+    #   and the keys as their `inspect` writes them (user code, which runs
+    #   here), the block as `&block`
+    def to_s
+      parts = args.map(&:inspect) + opts.map { |key, value| "#{keyword(key)} #{value.inspect}" }
+      parts << "&block" if block
+      parts.empty? ? ".#{name}" : ".#{name}(#{parts.join(", ")})"
+    end
+
+    private
+
+    # A keyword as Ruby writes it: `key:` for a Symbol, quoted when its
+    # inspect is, `"key" =>` otherwise.
+    def keyword(key)
+      key.instance_of?(::Symbol) ? "#{key.inspect[1..]}:" : "#{key.inspect} =>"
+    end
+  end
+end

data/lib/defi/value.rb

@@ -1,85 +1,37 @@
 # frozen_string_literal: true
 
 module Defi
-  # Represents a result of an operation, encapsulating both successful returns
-  # and exceptions. This class intentionally catches all exceptions (Exception)
-  # instead of StandardError to maintain complete control over method execution
-  # outcomes, particularly in testing contexts. This ensures that system-level
-  # exceptions like SystemExit cannot prematurely terminate test execution with
-  # potentially false positive results.
+  # What came back from a challenge: the object returned, or the exception
+  # raised. A value is frozen.
   class Value
-    RAISE = "raise"
-    RETURN = "return"
+    # The exceptions a method raises on its own, which a challenge keeps as
+    # its value. Anything else, an interruption or a signal, a shortage of
+    # memory, the end of a `Timeout`, goes through.
+    RAISED = [::StandardError, ::ScriptError, ::SystemStackError, ::SystemExit].freeze
 
-    # @return [#object_id] The returned value or caught exception
+    # @return [Object] the object returned, or the exception raised
     attr_reader :object
 
-    # Initializes a Value object by executing the provided block.
-    #
-    # @example Successful execution
-    #   value = Defi::Value.new { 1 + 1 }
-    #   value.call # => 2
-    #   value.raised? # => false
-    #
-    # @example Exception handling
-    #   value = Defi::Value.new { raise TypeError, "Invalid type" }
-    #   value.raised? # => true
-    #   value.object # => #<TypeError: Invalid type>
-    #
-    # @note This implementation catches Exception instead of StandardError
-    #   to provide complete control over method execution outcomes,
-    #   including system-level exceptions when needed.
-    #
-    # @yieldreturn [#object_id] Result or exception from block execution
-    def initialize
-      @object = yield
-      @raised = false
-    rescue ::Exception => e # rubocop:disable Lint/RescueException
-      @object = e
-      @raised = true
+    # @param object [Object] the object returned, or the exception raised
+    # @param raised [Boolean] whether the method raised: `true` or `false`,
+    #   as given
+    def initialize(object, raised)
+      @object = object
+      @raised = raised
+      freeze
     end
 
-    # Returns the result or raises the captured exception.
-    #
-    # @example With successful result
-    #   Value.new { "success" }.call # => "success"
-    #
-    # @example With exception
-    #   Value.new { raise "error" }.call # raises RuntimeError: error
-    #
-    # @return [#object_id] The operation result
-    # @raise [Exception] The captured exception if raised? is true
-    def call
-      raise object if raised?
-
-      object
-    end
-
-    # @return [Boolean] true if execution raised an exception
+    # @return [Boolean] whether the method raised
     def raised?
       @raised
     end
 
-    # @return [String] Human-readable representation
-    def inspect
-      "Value(object: #{object}, raised: #{raised?})"
-    end
-
-    # @return [Hash] Value properties
-    def to_h
-      { raised: raised?, object: }
-    end
-
-    # @return [String] String representation showing outcome type and value
-    def to_s
-      "#{raise_or_return} #{object}"
-    end
-
-    private
+    # @return [Object] the object returned
+    # @raise [Exception] the exception raised, again, with its own cause
+    def call
+      raise object, cause: object.cause if raised?
 
-    # @return [String] Execution outcome type
-    def raise_or_return
-      raised? ? RAISE : RETURN
+      object
     end
   end
 end

data/lib/defi.rb

@@ -1,34 +1,15 @@
 # frozen_string_literal: true
 
-# Namespace for the Defi library.
-#
-# Defi provides a flexible way to specify method calls with arguments
-# for later execution. It supports method chaining, exception handling,
-# and value inspection.
-#
-# @example Basic arithmetic operation
-#   addition = Defi(:+, 2)
-#   addition.to(1).call # => 3
-#
-# @example String manipulation
-#   upcase = Defi(:upcase)
-#   upcase.to("hello").call # => "HELLO"
-#
-# @example Method with keyword arguments
-#   format = Defi(:format, precision: 2)
-#   format.to(3.14159).call # => "3.14"
-#
-# @example Block usage
-#   map_double = Defi(:map) { |x| x * 2 }
-#   map_double.to([1, 2, 3]).call # => [2, 4, 6]
-#
-# @example Error handling
-#   result = Defi(:undefined_method).to(42)
-#   result.raised? # => true
-#   result.object # => #<NoMethodError: ...>
-#
+# Prepares a method call, a name with its arguments, and sends it to any
+# object, keeping what came back: the value returned, or the exception
+# raised.
+#
+# @example
+#   challenge = Defi::Challenge.new(:+, 2)
+#   challenge.to(40).object # => 42
+#   challenge.to("a").call  # raises TypeError: no implicit conversion of Integer into String
 module Defi
 end
 
-# Load core components
-require_relative "kernel"
+require_relative "defi/challenge"
+require_relative "defi/value"

metadata

@@ -1,16 +1,17 @@
 --- !ruby/object:Gem::Specification
 name: defi
 version: !ruby/object:Gem::Version
-  version: 3.0.1
+  version: 4.0.0
 platform: ruby
 authors:
 - Cyril Kato
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-12-31 00:00:00.000000000 Z
+date: 2026-10-24 00:00:00.000000000 Z
 dependencies: []
-description: Challenge library.
+description: 'Prepares a method call, a name with its arguments, and sends it to any
+  object, keeping what came back: the value returned, or the exception raised.'
 email: contact@cyril.email
 executables: []
 extensions: []
@@ -19,14 +20,17 @@ files:
 - LICENSE.md
 - README.md
 - lib/defi.rb
-- lib/defi/method.rb
+- lib/defi/challenge.rb
 - lib/defi/value.rb
-- lib/kernel.rb
-homepage: https://github.com/fixrb/defi
+homepage: https://fixrb.dev/gems/defi/
 licenses:
 - MIT
 metadata:
+  bug_tracker_uri: https://github.com/fixrb/defi/issues
+  changelog_uri: https://github.com/fixrb/defi#changes-in-40
+  documentation_uri: https://rubydoc.info/gems/defi
   rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/fixrb/defi
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -35,15 +39,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.1.0
+      version: 3.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.27
+rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
-summary: Challenge library.
+summary: A method call prepared in advance, to send to any object
 test_files: []

data/lib/defi/method.rb

@@ -1,105 +0,0 @@
-# frozen_string_literal: true
-
-module Defi
-  # Represents a method to be applied against an object.
-  # Encapsulates method name, arguments, keyword arguments and blocks
-  # for dynamic method invocation with proper error handling.
-  class Method < ::BasicObject
-    # Initialize a new Method object.
-    #
-    # @param name [Symbol] The method name
-    # @param args [Array] Positional arguments
-    # @param opts [Hash] Keyword arguments
-    # @param block [Proc] Optional block
-    #
-    # @raise [ArgumentError] If name is not a Symbol, raises with the actual class received
-    def initialize(name, *args, **opts, &block)
-      raise ::ArgumentError, "Method name must be a Symbol, got: #{name.class}" unless name.is_a?(::Symbol)
-
-      @name = name
-      @args = args
-      @opts = opts
-      @block = block
-    end
-
-    # Applies the method to the given object.
-    #
-    # @param object [#object_id] Target object for method invocation
-    # @return [Defi::Value] Result wrapper containing return value or exception
-    #
-    # @example Basic arithmetic
-    #   Defi::Method.new(:+, 1).to(2).call # => 3
-    #
-    # @example Block usage
-    #   Defi::Method.new(:map) { |x| x * 2 }.to([1, 2, 3]).call # => [2, 4, 6]
-    #
-    # @example Error handling
-    #   result = Defi::Method.new(:undefined).to(42)
-    #   result.raised? # => true
-    def to(object)
-      Value.new { object.public_send(@name, *@args, **@opts, &@block) }
-    end
-
-    # @return [Hash] Method properties
-    def to_h
-      {
-        name:  @name,
-        args:  @args,
-        opts:  @opts,
-        block: @block
-      }
-    end
-
-    # @return [String] Human-readable representation
-    #
-    # @example
-    #   Defi::Method.new(:+, 1).inspect
-    #   # => "Defi(name: :+, args: [1], opts: {}, block: nil)"
-    def inspect
-      "Defi(" \
-        "name: #{@name.inspect}, " \
-        "args: #{@args.inspect}, " \
-        "opts: #{@opts.inspect}, " \
-        "block: #{@block.nil? ? "nil" : "<Proc>"})"
-    end
-
-    # @return [String] String representation of the method call
-    #
-    # @example
-    #   Defi::Method.new(:+, 1).to_s # => ".+(1)"
-    #   Defi::Method.new(:map) { |x| x }.to_s # => ".map(<Proc>)"
-    def to_s
-      return ".#{@name}" if no_arguments?
-
-      ".#{@name}(#{stringified_arguments})"
-    end
-
-    private
-
-    def no_arguments?
-      @args.empty? && @opts.empty? && @block.nil?
-    end
-
-    def stringified_arguments
-      [
-        args_string,
-        opts_string,
-        block_string
-      ].compact.join(", ")
-    end
-
-    def args_string
-      @args.inspect[1..-2] unless @args.empty?
-    end
-
-    def opts_string
-      @opts.inspect[1..-2] unless @opts.empty?
-    end
-
-    def block_string
-      "<Proc>" if @block
-    end
-  end
-end
-
-require_relative "value"

data/lib/kernel.rb

@@ -1,45 +0,0 @@
-# frozen_string_literal: true
-
-require_relative File.join("defi", "method")
-
-# Core Ruby module extended to provide the Defi method globally.
-# This extension allows for convenient method encapsulation and
-# delayed execution through the Defi method, accessible anywhere
-# in the Ruby environment.
-module Kernel
-  # rubocop:disable Naming/MethodName
-
-  # Creates a new Defi::Method instance.
-  # This method provides a flexible way to encapsulate a method name along with its
-  # arguments, keyword arguments, and an optional block for later invocation.
-  #
-  # @param method_name [Symbol] The method name to be sent to an object
-  # @param args [Array] Positional arguments to be passed to the method
-  # @param opts [Hash] Keyword arguments to be passed to the method
-  # @param block [Proc] Optional block to be passed to the method
-  #
-  # @example Basic method without arguments
-  #   Defi(:to_s)
-  #
-  # @example Method with positional arguments
-  #   Defi(:+, 2)
-  #   Defi(:[], 0, 2)  # For array/string slicing
-  #
-  # @example Method with keyword arguments
-  #   Defi(:transform, x: 1, y: 2)
-  #
-  # @example Method with a block
-  #   Defi(:map) { |x| x * 2 }
-  #
-  # @example Complex method call
-  #   Defi(:reduce, 0, &:+)  # Sum an array
-  #
-  # @raise [ArgumentError] If method_name is not a Symbol
-  #
-  # @return [Defi::Method] An instance of Defi::Method encapsulating the method call
-  def Defi(method_name, *args, **opts, &block)
-    ::Defi::Method.new(method_name, *args, **opts, &block)
-  end
-
-  # rubocop:enable Naming/MethodName
-end