defi 3.0.0 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bd965274ab9b7a6dd1303d7aa7b4c1da9c87551c6197a5075ea1f6a8c409df52
-  data.tar.gz: 2fc6a867f949feeb94e971347313fd1b734c5851bb1f770e77bc6b2c0d72e9d8
+  metadata.gz: 147abcfe45309cf8e5e5df3cf02dbcaeaccd2c421841ab017844206dd1218ed1
+  data.tar.gz: 8d82cceb4e3e68f29ee6ae8632369cf9c4d2bdfdc3d3ba1a1cd3de5659cad8bc
 SHA512:
-  metadata.gz: 99d0012c6768b9e38db3a149cb9021c3fdad056705748079e8e33ca6b7e05f55ec551ea1b784eb2cfba31dd3bae2f5454d75eeb8469fa5372321c192c42dcf99
-  data.tar.gz: 789d8cd29d0cb8d608980c88b995d5d188e93febf868715113a1b274fe35cb54f2cd01f5b7a0f57d3e5ba804099c3129ab824e7ecfc0b50cf6b903df926bd935
+  metadata.gz: 9c0076455aa06379af57797aff1c160fce9bd1d930f45702a95eea4836b0c77270f9bcdac8cb4f00b4c5fe364766cb0a8a07b3f4c0800606366df9408debe882
+  data.tar.gz: '0379b004d430b65a97b2f56d2a968457ec37a41510a08f253899060e7645937b7c29e234e2d6a9bbca75b991edde71485ade15d64cb0f61a7b348fd750d2e092'

data/LICENSE.md

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

@@ -2,92 +2,78 @@
 
 [![Version](https://img.shields.io/github/v/tag/fixrb/defi?label=Version&logo=github)](https://github.com/fixrb/defi/tags)
 [![Yard documentation](https://img.shields.io/badge/Yard-documentation-blue.svg?logo=github)](https://rubydoc.info/github/fixrb/defi/main)
-[![Ruby](https://github.com/fixrb/defi/workflows/Ruby/badge.svg?branch=main)](https://github.com/fixrb/defi/actions?query=workflow%3Aruby+branch%3Amain)
-[![RuboCop](https://github.com/fixrb/defi/workflows/RuboCop/badge.svg?branch=main)](https://github.com/fixrb/defi/actions?query=workflow%3Arubocop+branch%3Amain)
 [![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
 
 The [gem](https://rubygems.org/gems/defi) is available as open source under the terms of the [MIT License](https://github.com/fixrb/defi/raw/main/LICENSE.md).
 
----
+## Sponsors
 
-<p>
-  This project is sponsored by:<br />
-  <a href="https://sashite.com/"><img
-    src="https://github.com/fixrb/defi/raw/main/img/sashite.png"
-    alt="Sashité" /></a>
-</p>
+This project is sponsored by [Sashité](https://sashite.com/)

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,95 +1,37 @@
 # frozen_string_literal: true
 
 module Defi
-  # Represents a result of an operation, encapsulating either the returned value
-  # or an exception raised during the execution.
-  #
-  # This class is used to handle the outcome of a method invocation, allowing
-  # to distinguish between successful results and exceptions.
+  # 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 or the raised object.
+    # @return [Object] the object returned, or the exception raised
     attr_reader :object
 
-    # Initializes a Value object with the result of the provided block.
-    # Captures any exception raised during the block execution.
-    #
-    # @example
-    #   value = Defi::Value.new { 1 + 1 }
-    #   value.call # => 2
-    #
-    # @example Handling an exception
-    #   value = Defi::Value.new { raise 'Error' }
-    #   value.call # raises 'Error'
-    #
-    # @yieldreturn [#object_id] The result of the block or the exception raised.
-    # rubocop:disable Lint/RescueException
-    def initialize
-      @object = yield
-      @raised = false
-    rescue ::Exception => e
-      @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
-    # rubocop:enable Lint/RescueException
 
-    # Returns the object if no exception was raised, otherwise raises the exception.
-    #
-    # @example
-    #   value = Defi::Value.new { "Hello" }
-    #   value.call # => "Hello"
-    #
-    # @return [#object_id] The returned object or raises the captured exception.
-    def call
-      raise object if raised?
-
-      object
-    end
-
-    # Checks if an exception was raised during the execution.
-    #
-    # @example
-    #   value = Defi::Value.new { raise 'Error' }
-    #   value.raised? # => true
-    #
-    # @return [Boolean] True if an exception was raised, otherwise false.
+    # @return [Boolean] whether the method raised
     def raised?
       @raised
     end
 
-    # Returns a hash containing the properties of the Value object.
-    #
-    # @return [Hash] The properties of the Value object.
-    def to_h
-      {
-        raised: raised?,
-        object:
-      }
-    end
-
-    # Returns a string representation of the Value object.
-    #
-    # @return [String] The string representation of the Value object.
-    def to_s
-      "#{raise_or_return} #{object}"
-    end
-
-    # Returns a human-readable representation of the Value object.
-    #
-    # @return [String] The human-readable representation of the Value object.
-    def inspect
-      "Value(object: #{object}, raised: #{raised?})"
-    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?
 
-    # Returns a string indicating whether the object was raised or returned.
-    #
-    # @return [String] A "raise" or "return" string.
-    def raise_or_return
-      raised? ? RAISE : RETURN
+      object
     end
   end
 end

data/lib/defi.rb

@@ -1,28 +1,15 @@
 # frozen_string_literal: true
 
-# Namespace for the Defi library.
-#
-# This file serves as the entry point for the Defi library, establishing the
-# Defi namespace and requiring necessary components.  It is typically required
-# at the beginning of using the Defi library in an application.
-#
-# @example Requiring the Defi library in a Ruby application
-#   require "defi"
-#
-# @example Adding 2 to 1
-#   # Create a Defi method object for addition with an argument of 2
-#   addition = Defi(:+, 2)
-#   addition.inspect # => "Defi(name: :+, args: [2], opts: {}, block: nil)"
-#
-#   # Apply the addition to the number 1
-#   result = addition.to(1)
-#   result # => Value(object: 3, raised: false)
-#
-#   # Execute the addition and get the result
-#   result.call # => 3
-#
+# 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
 
-# Require additional components of the Defi library.
-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.0
+  version: 4.0.0
 platform: ruby
 authors:
 - Cyril Kato
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-01-25 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,15 +20,18 @@ 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'
-post_install_message: 
+  source_code_uri: https://github.com/fixrb/defi
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -35,15 +39,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.2.0
+      version: 3.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.19
-signing_key: 
+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,99 +0,0 @@
-# frozen_string_literal: true
-
-module Defi
-  # Represents a method to be applied against an object.
-  # This class encapsulates the method name, its arguments, keyword arguments,
-  # and an optional block, enabling dynamic method invocation.
-  class Method < ::BasicObject
-    # Initialize a new Method object.
-    #
-    # @param name  [Symbol] The name of the method.
-    # @param args  [Array]  Any arguments of the method.
-    # @param opts  [Hash]   Any keyword arguments of the method.
-    # @param block [Proc]   Any block argument of the method.
-    # @raise [ArgumentError] If the name is not a symbol.
-    def initialize(name, *args, **opts, &block)
-      raise ::ArgumentError, name.class.inspect unless name.is_a?(::Symbol)
-
-      @name = name
-      @args = args
-      @opts = opts
-      @block = block
-    end
-
-    # Applies the method to the given object.
-    #
-    # @example
-    #   add = Defi::Method.new(:+, 1)
-    #   add.to(2).call # => 3
-    #
-    # @param object [#object_id] The object to method.
-    # @return [Defi::Value] The actual value, to raise or to return.
-    def to(object)
-      Value.new { object.public_send(@name, *@args, **@opts, &@block) }
-    end
-
-    # Returns a hash containing the method's properties.
-    #
-    # @return [Hash] The properties of the method.
-    def to_h
-      {
-        name:  @name,
-        args:  @args,
-        opts:  @opts,
-        block: @block
-      }
-    end
-
-    # rubocop:disable Metrics/AbcSize
-    # rubocop:disable Metrics/CyclomaticComplexity
-
-    # Returns a string representation of the method.
-    #
-    # @example
-    #   add = Defi::Method.new(:+, 1)
-    #   add.to_s # => ".+(1)"
-    #
-    # @return [String] The string representation of the method.
-    def to_s
-      string = ".#{@name}"
-      return string if @args.empty? && @opts.empty? && @block.nil?
-
-      stringified_args  = @args.inspect[1..-2]
-      stringified_opts  = @opts.inspect[1..-2]
-      stringified_block = "<Proc>" unless @block.nil?
-
-      stringified_items = []
-      stringified_items << stringified_args   unless @args.empty?
-      stringified_items << stringified_opts   unless @opts.empty?
-      stringified_items << stringified_block  unless @block.nil?
-
-      "#{string}(#{stringified_items.join(", ")})"
-    end
-
-    # rubocop:enable Metrics/AbcSize
-    # rubocop:enable Metrics/CyclomaticComplexity
-
-    # Returns a human-readable representation of the method.
-    #
-    # @example
-    #   add = Defi::Method.new(:+, 1)
-    #   add.inspect # => "Defi(name: :+, args: [1], opts: {}, block: nil)"
-    #
-    # @return [String] The human-readable representation of the method.
-    def inspect
-      inspected_name  = @name.inspect
-      inspected_args  = @args.inspect
-      inspected_opts  = @opts.inspect
-      inspected_block = @block.nil? ? "nil" : "<Proc>"
-
-      "Defi(" \
-        "name: #{inspected_name}, " \
-        "args: #{inspected_args}, " \
-        "opts: #{inspected_opts}, " \
-        "block: #{inspected_block})"
-    end
-  end
-end
-
-require_relative "value"

data/lib/kernel.rb

@@ -1,42 +0,0 @@
-# frozen_string_literal: true
-
-require_relative File.join("defi", "method")
-
-# Extension of the Kernel module to include the Defi method.
-# The Defi method is a convenient way to create Method objects
-# that encapsulate a method name and its arguments, offering a
-# dynamic approach to method invocation.
-module Kernel
-  # Disabling the RuboCop rule for method naming conventions
-  # to define a method with an uppercase name for stylistic reasons.
-  # rubocop:disable Naming/MethodName
-
-  # Creates a new Defi::Method instance.
-  # This method provides a simple and elegant way to encapsulate
-  # a method name and its arguments for later invocation.
-  #
-  # @example Creating a Defi method without arguments
-  #   Defi(:foo).inspect # => "Defi(name: :foo, args: [], opts: {}, block: nil)"
-  #
-  # @example Adding 2 to 1
-  #   # Create a Defi method object for addition with an argument of 2
-  #   addition = Defi(:+, 2)
-  #   addition.inspect # => "Defi(name: :+, args: [2], opts: {}, block: nil)"
-  #
-  #   # Apply the addition to the number 1
-  #   result = addition.to(1)
-  #   result # => Value(object: 3, raised: false)
-  #
-  #   # Execute the addition and get the result
-  #   result.call # => 3
-  #
-  # @param method_name [Symbol] The method name to be sent to an object.
-  #
-  # @return [Defi::Method] An instance of Defi::Method encapsulating the method name and provided arguments.
-  def Defi(method_name, ...)
-    ::Defi::Method.new(method_name, ...)
-  end
-
-  # Re-enabling the RuboCop rule for method naming conventions.
-  # rubocop:enable Naming/MethodName
-end