defi 2.0.7 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 45f62cb331ea97335ed07945d26c22a25f3ee7c826ded161d1432018e2e1005c
-  data.tar.gz: 1067904cd927baeb4c4f5bb8a52260ff813b66f1987e774baaf5916dd10922fa
+  metadata.gz: bd965274ab9b7a6dd1303d7aa7b4c1da9c87551c6197a5075ea1f6a8c409df52
+  data.tar.gz: 2fc6a867f949feeb94e971347313fd1b734c5851bb1f770e77bc6b2c0d72e9d8
 SHA512:
-  metadata.gz: 7fbd50efbc1db138975db94ab8c5b876b203443719d780032ac97a2e9129366b85dec847fc8cff0655b3046b02b423f8f2717c8c36b6c11fe45ba03772fc674e
-  data.tar.gz: a6ee3bb73c8dbbca088d2df08239f31c3451b0bee4075d4f6499d1d45625daab3314ce954fcde3b354d3a564bcbee3557201f74fa7fce65640776ada36e9a214
+  metadata.gz: 99d0012c6768b9e38db3a149cb9021c3fdad056705748079e8e33ca6b7e05f55ec551ea1b784eb2cfba31dd3bae2f5454d75eeb8469fa5372321c192c42dcf99
+  data.tar.gz: 789d8cd29d0cb8d608980c88b995d5d188e93febf868715113a1b274fe35cb54f2cd01f5b7a0f57d3e5ba804099c3129ab824e7ecfc0b50cf6b903df926bd935

data/LICENSE.md

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2015-2022 Cyril Kato
+Copyright (c) 2015-2024 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,20 @@
 # 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)
+[![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)
 
-> 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 +38,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 +83,11 @@ __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).
 
-***
+---
 
 <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>
+    alt="Sashité" /></a>
 </p>

data/lib/defi/method.rb

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

@@ -1,15 +1,30 @@
 # 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 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.
   class Value
+    RAISE = "raise"
+    RETURN = "return"
+
     # @return [#object_id] The returned or the raised object.
     attr_reader :object
 
-    # Initialize the value class.
+    # 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
     #
-    # @yieldreturn [#object_id] The challenged code.
+    # @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
@@ -20,49 +35,61 @@ module Defi
     end
     # rubocop:enable Lint/RescueException
 
-    # Raise or return the value.
+    # Returns the object if no exception was raised, otherwise raises the exception.
+    #
+    # @example
+    #   value = Defi::Value.new { "Hello" }
+    #   value.call # => "Hello"
     #
-    # @return [#object_id] Raised exception or returned object.
+    # @return [#object_id] The returned object or raises the captured exception.
     def call
       raise object if raised?
 
       object
     end
 
-    # @return [Boolean] The value was raised (or returned)?
+    # 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.
     def raised?
       @raised
     end
 
-    # Properties of the value.
+    # Returns a hash containing the properties of the Value object.
     #
-    # @return [Hash] The properties of the value.
+    # @return [Hash] The properties of the Value object.
     def to_h
       {
         raised: raised?,
-        object: object
+        object:
       }
     end
 
-    # String of the value.
+    # Returns a string representation of the Value object.
     #
-    # @return [String] The string representation of the value.
+    # @return [String] The string representation of the Value object.
     def to_s
       "#{raise_or_return} #{object}"
     end
 
-    # A string containing a human-readable representation of the value.
+    # Returns a human-readable representation of the Value object.
     #
-    # @return [String] The human-readable representation of the value.
+    # @return [String] The human-readable representation of the Value object.
     def inspect
       "Value(object: #{object}, raised: #{raised?})"
     end
 
     private
 
+    # 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"
+      raised? ? RAISE : RETURN
     end
   end
 end

data/lib/defi.rb

@@ -2,21 +2,27 @@
 
 # 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
+#
 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")
+# Require additional components of the Defi library.
+require_relative "kernel"

data/lib/kernel.rb

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

metadata

@@ -1,141 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: defi
 version: !ruby/object:Gem::Version
-  version: 2.0.7
+  version: 3.0.0
 platform: ruby
 authors:
 - Cyril Kato
 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-01-25 00:00:00.000000000 Z
+dependencies: []
 description: Challenge library.
 email: contact@cyril.email
 executables: []
@@ -145,8 +19,9 @@ 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
@@ -160,14 +35,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.7.0
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.6
+rubygems_version: 3.4.19
 signing_key: 
 specification_version: 4
 summary: Challenge library.

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"