defi 2.0.7 → 3.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 45f62cb331ea97335ed07945d26c22a25f3ee7c826ded161d1432018e2e1005c
-  data.tar.gz: 1067904cd927baeb4c4f5bb8a52260ff813b66f1987e774baaf5916dd10922fa
+  metadata.gz: cbd2a5befa5ac9808bfe1c121549311dfed58c0a48070b9708ec46621a101255
+  data.tar.gz: b1f16e2e70d07e377e7f662a807afb1afbe9cc971535cb683d5000b19b0306de
 SHA512:
-  metadata.gz: 7fbd50efbc1db138975db94ab8c5b876b203443719d780032ac97a2e9129366b85dec847fc8cff0655b3046b02b423f8f2717c8c36b6c11fe45ba03772fc674e
-  data.tar.gz: a6ee3bb73c8dbbca088d2df08239f31c3451b0bee4075d4f6499d1d45625daab3314ce954fcde3b354d3a564bcbee3557201f74fa7fce65640776ada36e9a214
+  metadata.gz: a673ab6344aa7f6ebe0b04ff7556b0f3d5524cec97f26810613858afe874f96362081a293cabadcdcf8a09da1c10c75ef8fa0e5a3efc39fc3f075660febc6a9a
+  data.tar.gz: a8c78c9725743ba1efeb8e3ac12afb5dca6403d8a7d6b714142814db42d7d60b075b5a3d5431a2145b33319f2c6d08742e50fe91d4e7ea5916579a8185b4bcdd

data/LICENSE.md

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

@@ -1,12 +1,18 @@
 # Defi
 
-[![Version](https://img.shields.io/github/v/tag/fixrb/defi?label=Version&logo=github)](https://github.com/fixrb/defi/releases)
+[![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)
-[![CI](https://github.com/fixrb/defi/workflows/CI/badge.svg?branch=main)](https://github.com/fixrb/defi/actions?query=workflow%3Aci+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)
 
-> Challenge library.
+**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.
 
 ## Installation
 
@@ -30,26 +36,39 @@ gem install defi
 
 ## Usage
 
-Let's multiply by `7` the number `6`:
+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:
 
-```ruby
-Defi.send(:*, 7).to(6).call # => 42
-```
+### Example 1: Multiplying Numbers
 
-Now, let's challenge "`foo`" with `boom` method:
+Suppose you want to multiply the number `6` by `7`.
+With `Defi`, this can be elegantly done as follows:
 
 ```ruby
-Defi.send(:boom).to("foo").call # NoMethodError: undefined method `boom' for "foo":String
+result = Defi(:*, 7).to(6).call
+puts result # Output: 42
 ```
 
-Let's challenge "`hello world`" with `gsub!` in isolation:
+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`.
+
+### Example 2: Invoking an Undefined Method
+
+`Defi` also elegantly handles cases where the method might not exist on the target object.
+For instance:
 
 ```ruby
-some_text = "hello world"
-Defi.send(:gsub!, "world", "Alice").to!(some_text).call # => "hello Alice"
-some_text # => "hello world"
+begin
+  Defi(:boom).to("foo").call
+rescue NoMethodError => e
+  puts e.message # Output: undefined method `boom' for "foo":String
+end
 ```
 
+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.
+
 ## Contact
 
 * Source code: https://github.com/fixrb/defi/issues
@@ -62,11 +81,6 @@ __Defi__ follows [Semantic Versioning 2.0](https://semver.org/).
 
 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="Sashite" /></a>
-</p>
+This project is sponsored by [Sashité](https://sashite.com/)

data/lib/defi/method.rb

@@ -0,0 +1,105 @@
+# 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/defi/value.rb

@@ -1,68 +1,85 @@
 # frozen_string_literal: true
 
 module Defi
-  # This class contains an object that returned or raised during the initialize.
-  #
+  # 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.
   class Value
-    # @return [#object_id] The returned or the raised object.
+    RAISE = "raise"
+    RETURN = "return"
+
+    # @return [#object_id] The returned value or caught exception
     attr_reader :object
 
-    # Initialize the value class.
+    # 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>
     #
-    # @yieldreturn [#object_id] The challenged code.
-    # rubocop:disable Lint/RescueException
+    # @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
+    rescue ::Exception => e # rubocop:disable Lint/RescueException
       @object = e
       @raised = true
     end
-    # rubocop:enable Lint/RescueException
 
-    # Raise or return the value.
+    # Returns the result or raises the captured exception.
+    #
+    # @example With successful result
+    #   Value.new { "success" }.call # => "success"
     #
-    # @return [#object_id] Raised exception or returned object.
+    # @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] The value was raised (or returned)?
+    # @return [Boolean] true if execution raised an exception
     def raised?
       @raised
     end
 
-    # Properties of the value.
-    #
-    # @return [Hash] The properties of the value.
+    # @return [String] Human-readable representation
+    def inspect
+      "Value(object: #{object}, raised: #{raised?})"
+    end
+
+    # @return [Hash] Value properties
     def to_h
-      {
-        raised: raised?,
-        object: object
-      }
+      { raised: raised?, object: }
     end
 
-    # String of the value.
-    #
-    # @return [String] The string representation of the value.
+    # @return [String] String representation showing outcome type and value
     def to_s
       "#{raise_or_return} #{object}"
     end
 
-    # A string containing a human-readable representation of the value.
-    #
-    # @return [String] The human-readable representation of the value.
-    def inspect
-      "Value(object: #{object}, raised: #{raised?})"
-    end
-
     private
 
-    # @return [String] A "raise" or "return" string.
+    # @return [String] Execution outcome type
     def raise_or_return
-      raised? ? "raise" : "return"
+      raised? ? RAISE : RETURN
     end
   end
 end

data/lib/defi.rb

@@ -2,21 +2,33 @@
 
 # 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: ...>
+#
 module Defi
-  # Expectations are built with this method.
-  #
-  # @example A :foo challenge
-  #   send(:foo) # => #<Defi::Challenge:0x007f96a40925f8 @method=:foo, @args=[]>
-  #
-  # @param method [#to_sym] The method to send to an object.
-  # @param args   [Array]   Any arguments of the method.
-  # @param kwargs [Hash]    Any keyword arguments of the method.
-  # @param block  [Proc]    Any block argument of the method.
-  #
-  # @return [Challenge] The challenge instance.
-  def self.send(method, *args, **kwargs, &block)
-    Challenge.new(method, *args, **kwargs, &block)
-  end
 end
 
-require_relative File.join("defi", "challenge")
+# Load core components
+require_relative "kernel"

data/lib/kernel.rb

@@ -0,0 +1,45 @@
+# 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

metadata

@@ -1,141 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: defi
 version: !ruby/object:Gem::Version
-  version: 2.0.7
+  version: 3.0.1
 platform: ruby
 authors:
 - Cyril Kato
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-04-02 00:00:00.000000000 Z
-dependencies:
-- !ruby/object:Gem::Dependency
-  name: aw
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.2.0
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.2.0
-- !ruby/object:Gem::Dependency
-  name: bundler
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: rake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: rubocop-md
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: rubocop-performance
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: rubocop-rake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: rubocop-thread_safety
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: simplecov
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: yard
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
+date: 2024-12-31 00:00:00.000000000 Z
+dependencies: []
 description: Challenge library.
 email: contact@cyril.email
 executables: []
@@ -145,14 +19,15 @@ files:
 - LICENSE.md
 - README.md
 - lib/defi.rb
-- lib/defi/challenge.rb
+- lib/defi/method.rb
 - lib/defi/value.rb
+- lib/kernel.rb
 homepage: https://github.com/fixrb/defi
 licenses:
 - MIT
 metadata:
   rubygems_mfa_required: 'true'
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -160,15 +35,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.7.0
+      version: 3.1.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.6
-signing_key: 
+rubygems_version: 3.3.27
+signing_key:
 specification_version: 4
 summary: Challenge library.
 test_files: []

data/lib/defi/challenge.rb

@@ -1,99 +0,0 @@
-# frozen_string_literal: true
-
-require "aw"
-
-module Defi
-  # This class contains a challenge to apply against an object.
-  class Challenge < ::BasicObject
-    # Initialize the challenge class.
-    #
-    # @param method [#to_sym] The method to send to an object.
-    # @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.
-    def initialize(method, *args, **opts, &block)
-      @method = method.to_sym
-      @args   = args
-      @opts   = opts
-      @block  = block
-    end
-
-    # @param object [#object_id] The object to challenge.
-    #
-    # @return [Defi::Value] The actual value, to raise or to return.
-    def to(object)
-      Value.new { object.public_send(@method, *@args, **@opts, &@block) }
-    end
-
-    # @param object [#object_id] The object to challenge in code isolation.
-    #
-    # @return [Defi::Value] The actual value, to raise or to return.
-    #
-    # @see to
-    def to!(object)
-      ::Aw.fork! { to(object) }
-    end
-
-    # Properties of the challenge.
-    #
-    # @return [Hash] The properties of the challenge.
-    def to_h
-      {
-        method: @method,
-        args:   @args,
-        opts:   @opts,
-        block:  @block
-      }
-    end
-
-    # rubocop:disable Metrics/AbcSize
-    # rubocop:disable Metrics/CyclomaticComplexity
-    # rubocop:disable Metrics/MethodLength
-
-    # String of the challenge.
-    #
-    # @return [String] The string representation of the challenge.
-    def to_s
-      string = ".#{@method}"
-
-      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?
-
-      string += "("
-
-      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
-    # rubocop:enable Metrics/MethodLength
-
-    # A string containing a human-readable representation of the challenge.
-    #
-    # @return [String] The human-readable representation of the challenge.
-    def inspect
-      inspected_method  = @method.inspect
-      inspected_args    = @args.inspect
-      inspected_opts    = @opts.inspect
-      inspected_block   = @block.nil? ? "nil" : "<Proc>"
-
-      "Defi(" \
-        "method: #{inspected_method}, " \
-        "args: #{inspected_args}, " \
-        "opts: #{inspected_opts}, " \
-        "block: #{inspected_block}" \
-        ")"
-    end
-  end
-end
-
-require_relative "value"