spectus 3.3.4 → 4.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8767313f403c0f015d1316eabbf06f124ef4ecb136f8edf3529d533602622a8c
-  data.tar.gz: 419a5c0e93edac33135d305e9e384fea7d6ca305d68f9bd268f89d4ead020d3c
+  metadata.gz: 45d1a638f042621d43b991c15aea5311a0b370c82f63d37c8fefa6e0a29dba8b
+  data.tar.gz: 5bc2409a8d4daeb2e69ca70ac3c6e7d209f4c47a40088c859b545929a2841018
 SHA512:
-  metadata.gz: 368fb8f488627e6c5b225bd66416ce4a3c8f61aaab0ce0a68ec6d2f354978393299399ccc4f9ea2c8e719b336764b9b7cededa4f6f237a7e5ad9a1495deb47ef
-  data.tar.gz: a5e56d1e3c6058f6df75bea0b5d564b0eb2cb6eea620ac9d445bea29a0a45e17302cdddf7cb9b5f7d18609c0b1334527f2495eef264bfb5d9041da453ec1055e
+  metadata.gz: 8a5cea6a4c057897592889e4215963176011906d940367e2e62404302ba87bc2fa1550716aba9fe00b8896375f3cb6b4785b2c7d74338c17c3df745c3da4ffb6
+  data.tar.gz: 5ad609a281efbde26dacc5e57c3ec0955ce431755bd206aa2617a2bbbba7740bb6730bd22603dfc2ac3159c60f8fea003e9bb0a097ac5755bd01fbb88ac47648

data/README.md

@@ -1,8 +1,10 @@
 # Spectus
 
-[![Build Status](https://api.travis-ci.org/fixrb/spectus.svg?branch=main)](https://travis-ci.org/fixrb/spectus)
-[![Gem Version](https://badge.fury.io/rb/spectus.svg)](https://rubygems.org/gems/spectus)
-[![Documentation](https://img.shields.io/:yard-docs-38c800.svg)](https://rubydoc.info/gems/spectus/frames)
+[![Version](https://img.shields.io/github/v/tag/fixrb/spectus?label=Version&logo=github)](https://github.com/fixrb/spectus/releases)
+[![Yard documentation](https://img.shields.io/badge/Yard-documentation-blue.svg?logo=github)](https://rubydoc.info/github/fixrb/spectus/main)
+[![CI](https://github.com/fixrb/spectus/workflows/CI/badge.svg?branch=main)](https://github.com/fixrb/spectus/actions?query=workflow%3Aci+branch%3Amain)
+[![RuboCop](https://github.com/fixrb/spectus/workflows/RuboCop/badge.svg?branch=main)](https://github.com/fixrb/spectus/actions?query=workflow%3Arubocop+branch%3Amain)
+[![License](https://img.shields.io/github/license/fixrb/spectus?label=License&logo=github)](https://github.com/fixrb/spectus/raw/main/LICENSE.md)
 
 > Expectation library with [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) requirement levels 🚥
 
@@ -26,168 +28,90 @@ Or install it yourself as:
 gem install spectus
 ```
 
-## Overview
-
-Assuming that an expectation is an assertion that is either `true` or `false`,
-qualifying it with `MUST`, `SHOULD` and `MAY`, we can draw up several scenarios:
-
-| Requirement levels        | **MUST** | **SHOULD** | **MAY** |
-| ------------------------- | -------- | ---------- | ------- |
-| Implemented & Matched     | `true`   | `true`     | `true`  |
-| Implemented & Not matched | `false`  | `true`     | `false` |
-| Implemented & Exception   | `false`  | `false`    | `false` |
-| Not implemented           | `false`  | `false`    | `true`  |
-
-When an expectation is evaluated by Spectus,
-
-* in case of a _passed_ expectation, a `Spectus::Result::Pass` instance is _returned_;
-* in case of a _failed_ expectation, a `Spectus::Result::Fail` exception is _raised_.
-
 ## Usage
 
-The __Spectus__ library is basically a module containing an `it` instance method that accept a block representing the actual value to be evaluated through an expectation.
+The __Spectus__ library is basically a module defining methods that can be used to qualify expectations in specifications.
 
-The `Spectus` module can be included inside a class and used as follows:
+To make __Spectus__ available:
 
 ```ruby
 require "spectus"
-
-class Spec
-  include ::Spectus
-
-  attr_reader :subject
-
-  def initialize(subject)
-    @subject = subject
-  end
-
-  def test_a
-    it { subject.upcase }.MUST eql "FOO"
-  end
-
-  def test_b
-    it { subject.blank? }.MAY be_true
-  end
-
-  def test_c
-    it { subject.length }.SHOULD equal 42
-  end
-end
 ```
 
-```ruby
-t = Spec.new("foo")
-
-t.test_a # => Spectus::Result::Pass(actual: "FOO", error: nil, expected: "FOO", got: true, matcher: :eql, negate: false, level: :MUST, valid: true)
-
-t.test_b # => Spectus::Result::Pass(actual: nil, error: #<NoMethodError: undefined method `blank?' for "foo":String>, expected: nil, got: nil, matcher: :be_true, negate: false, level: :MAY, valid: false)
+For convenience, we will also instantiate some matchers from the [Matchi library](https://github.com/fixrb/matchi):
 
-t.test_c # => Spectus::Result::Pass(actual: 3, error: nil, expected: 42, got: false, matcher: :equal, negate: false, level: :SHOULD, valid: false)
+```sh
+gem install matchi
 ```
 
 ```ruby
-t = Spec.new(4)
-
-t.test_a # => raises an exception:
-# Traceback (most recent call last):
-#         6: from ./bin/console:8:in `<main>'
-#         5: from (irb):23
-#         4: from (irb):11:in `test_a'
-#         3: from /Users/cyril/github/fixrb/spectus/lib/spectus/expectation_target.rb:34:in `MUST'
-#         2: from /Users/cyril/github/fixrb/spectus/lib/spectus/requirement_level/base.rb:38:in `call'
-#         1: from /Users/cyril/.rbenv/versions/2.7.3/lib/ruby/gems/2.7.0/gems/expresenter-1.2.1/lib/expresenter/fail.rb:19:in `with'
-# Spectus::Result::Fail (NoMethodError: undefined method `upcase' for 4:Integer)
-
-t.test_b # => Spectus::Result::Pass(actual: nil, error: #<NoMethodError: undefined method `blank?' for 4:Integer>, expected: nil, got: nil, matcher: :be_true, negate: false, level: :MAY, valid: false)
-
-t.test_c # => raises an exception:
-# Traceback (most recent call last):
-#         6: from ./bin/console:8:in `<main>'
-#         5: from (irb):25
-#         4: from (irb):19:in `test_c'
-#         3: from /Users/cyril/github/fixrb/spectus/lib/spectus/expectation_target.rb:100:in `SHOULD'
-#         2: from /Users/cyril/github/fixrb/spectus/lib/spectus/requirement_level/base.rb:38:in `call'
-#         1: from /Users/cyril/.rbenv/versions/2.7.3/lib/ruby/gems/2.7.0/gems/expresenter-1.2.1/lib/expresenter/fail.rb:19:in `with'
-# Spectus::Result::Fail (NoMethodError: undefined method `length' for 4:Integer.)
+require "matchi"
 ```
 
-## More examples
+All examples here assume that this has been done.
 
 ### Absolute Requirement
 
-Given the "`ルビー`" object, when it receives `valid_encoding?` method, then it **MUST** be `true`:
+There is exactly one bat:
 
 ```ruby
-require "spectus"
-
-include Spectus
-
-it { "ルビー".valid_encoding? }.MUST be_true
-# => Spectus::Result::Pass(actual: true, error: nil, expected: nil, got: true, matcher: :be_true, negate: false, level: :MUST, valid: true)
+definition = Spectus.must Matchi::Be.new(1)
+definition.call { "🦇".size }
+# => Expresenter::Pass(actual: 1, definition: "be 1", error: nil, expected: 1, got: true, negate: false, level: :MUST)
 ```
 
-The result of the test shows that the spec passed.
+The test is passed.
 
 ### Absolute Prohibition
 
-Given the "`foo`" object, when it receives `length` method, then it **MUST NOT** raise the `NoMethodError` exception:
+Truth and lies:
 
 ```ruby
-require "spectus"
-
-include Spectus
-
-it { "foo".length }.MUST_NOT raise_exception NoMethodError
-# => Spectus::Result::Pass(actual: 3, error: nil, expected: NoMethodError, got: true, matcher: :raise_exception, negate: true, level: :MUST, valid: true)
+definition = Spectus.must_not Matchi::Be.new(true)
+definition.call { false }
+# => Expresenter::Pass(actual: false, definition: "be true", error: nil, expected: true, got: true, negate: true, level: :MUST)
 ```
 
-The result of the test shows that the spec passed.
-
 ### Recommended
 
-Given the `BasicObject` object, when it receives `superclass` method, then it **SHOULD** return the explicit blank class `NilClass`:
+A well-known joke. The addition of `0.1` and `0.2` is deadly precise:
 
 ```ruby
-require "spectus"
-
-include Spectus
-
-it { BasicObject.superclass }.SHOULD equal NilClass
-# => Spectus::Result::Pass(actual: nil, error: nil, expected: NilClass, got: false, matcher: :equal, negate: false, level: :SHOULD, valid: false)
+definition = Spectus.should Matchi::Be.new(0.3)
+definition.call { 0.1 + 0.2 }
+# => Expresenter::Pass(actual: 0.30000000000000004, definition: "be 0.3", error: nil, expected: 0.3, got: false, negate: false, level: :SHOULD)
 ```
 
-Instead of the expected `NilClass` class, its sole instance (which is `nil`) was returned.
-However, because there isn't any exception, the result of the test shows that the spec passed.
-
 ### Not Recommended
 
-Given the "`1`" object, when it receives `+(1)` method, then it **SHOULD NOT** return the "`11`" value:
+This should not be wrong:
 
 ```ruby
-require "spectus"
+definition = Spectus.should_not Matchi::Match.new("123456")
 
-include Spectus
+definition.call do
+  require "securerandom"
 
-it { "1" + 1 }.SHOULD_NOT eql "11"
-# raise Spectus::Result::Fail(actual: nil, error: #<TypeError: no implicit conversion of Integer into String>, expected: "11", got: nil, matcher: :eql, negate: true, level: :SHOULD, valid: false)
+  SecureRandom.hex(3)
+end
+# => Expresenter::Pass(actual: "bb5716", definition: "match \"123456\"", error: nil, expected: "123456", got: true, negate: true, level: :SHOULD)
 ```
 
-There was a `TypeError` exception, the result of the test shows that the spec failed.
+In any case, as long as there are no exceptions, the test passes.
 
 ### Optional
 
-Given the "`foo`" object, when it receives `blank?` method, then it **MAY** be `false`:
+An empty array is blank, right?
 
 ```ruby
-require "spectus"
-
-include Spectus
-
-it { "foo".blank? }.MAY be_false
-# => Spectus::Result::Pass(actual: nil, error: #<NoMethodError: undefined method `blank?' for "foo":String>, expected: nil, got: nil, matcher: :be_false, negate: false, level: :MAY, valid: false)
+definition = Spectus.may Matchi::Be.new(true)
+definition.call { [].blank? }
+# => Expresenter::Pass(actual: nil, definition: "be true", error: #<NoMethodError: undefined method `blank?' for []:Array>, expected: true, got: nil, negate: false, level: :MAY)
 ```
 
-The optional `blank?` method is not implemented (unlike in [Ruby on Rails](https://api.rubyonrails.org/classes/Object.html#method-i-blank-3F), for instance), so the result of the test shows that the spec passed.
+My bad! ActiveSupport was not imported. 🤦‍♂️
+
+Anyways, the test passes because the exception produced is `NoMethodError`, meaning that the functionality is not implemented.
 
 ## Code Isolation
 
@@ -200,26 +124,24 @@ Because they may or may not be desired, each requirement level has 2 versions:
 Example of test without isolation:
 
 ```ruby
-require "spectus"
+greeting = "Hello, world!"
 
-include Spectus
+definition = Spectus.must Matchi::Eq.new("Hello, Alice!")
+definition.call { greeting.gsub!("world", "Alice") }
+# => Expresenter::Pass(actual: "Hello, Alice!", definition: "eq \"Hello, Alice!\"", error: nil, expected: "Hello, Alice!", got: true, negate: false, level: :MUST)
 
-greeting = "Hello, world!"
-it { greeting.gsub!("world", "Alice") }.MUST eql "Hello, Alice!"
-# => Spectus::Result::Pass(actual: "Hello, Alice!", error: nil, expected: "Hello, Alice!", got: true, matcher: :eql, negate: false, level: :MUST, valid: true)
 greeting # => "Hello, Alice!"
 ```
 
 Example of test in isolation:
 
 ```ruby
-require "spectus"
+greeting = "Hello, world!"
 
-include Spectus
+definition = Spectus.must! Matchi::Eq.new("Hello, Alice!")
+definition.call { greeting.gsub!("world", "Alice") }
+# => Expresenter::Pass(actual: "Hello, Alice!", definition: "eq \"Hello, Alice!\"", error: nil, expected: "Hello, Alice!", got: true, negate: false, level: :MUST)
 
-greeting = "Hello, world!"
-it { greeting.gsub!("world", "Alice") }.MUST! eql "Hello, Alice!"
-# => Spectus::Result::Pass(actual: "Hello, Alice!", error: nil, expected: "Hello, Alice!", got: true, matcher: :eql, negate: false, level: :MUST, valid: true)
 greeting # => "Hello, world!"
 ```
 
@@ -227,6 +149,7 @@ greeting # => "Hello, world!"
 
 * Home page: https://github.com/fixrb/spectus
 * Bugs/issues: https://github.com/fixrb/spectus/issues
+* Blog post: https://batman.buzz/a-spectus-tutorial-expectations-with-rfc-2119-compliance-1fc769861c1
 
 ## Versioning
 
@@ -234,7 +157,7 @@ __Spectus__ follows [Semantic Versioning 2.0](https://semver.org/).
 
 ## License
 
-The [gem](https://rubygems.org/gems/spectus) is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+The [gem](https://rubygems.org/gems/spectus) is available as open source under the terms of the [MIT License](https://github.com/fixrb/spectus/raw/main/LICENSE.md).
 
 ***
 

data/lib/spectus.rb

@@ -1,114 +1,207 @@
 # frozen_string_literal: true
 
-require "matchi/helper"
-
-require_relative File.join("spectus", "expectation_target")
+require_relative File.join("spectus", "requirement")
 
 # Namespace for the Spectus library.
 #
-# This module defines the {#it} method to create expectations, which can be
-# automatically included into classes.
-#
-# @example
-#   class Spec
-#     include ::Spectus
-#
-#     attr_reader :subject
-#
-#     def initialize(subject)
-#       @subject = subject
-#     end
-#
-#     def test_a
-#       it { subject.upcase }.MUST eql "FOO"
-#     end
-#
-#     def test_b
-#       it { subject.blank? }.MAY be_true
-#     end
-#
-#     def test_c
-#       it { subject.length }.SHOULD equal 42
-#     end
-#   end
-#
-#   t = Spec.new("foo")
-#   t.test_a # => Spectus::Result::Pass(actual: "FOO", error: nil, expected: "FOO", got: true, matcher: :eql, negate: false, level: :MUST, valid: true)
-#   t.test_b # => Spectus::Result::Pass(actual: nil, error: #<NoMethodError: undefined method `blank?' for "foo":String>, expected: nil, got: nil, matcher: :be_true, negate: false, level: :MAY, valid: false)
-#   t.test_c # => Spectus::Result::Pass(actual: 3, error: nil, expected: 42, got: false, matcher: :equal, negate: false, level: :SHOULD, valid: false)
-#
-# Or even directly used like this.
-#
-# @example
-#   require 'spectus'
-#
-#   include Spectus
-#
-#   it { 42 }.MUST equal 42 # => #<Spectus::Result::Pass...>
-#
-# It also includes a collection of expectation matchers 🤹
-#
-# @example Equivalence matcher
-#   matcher = eql("foo") # => Matchi::Matcher::Eql.new("foo")
-#   matcher.matches? { "foo" } # => true
-#   matcher.matches? { "bar" } # => false
-#
-# @example Identity matcher
-#   object = "foo"
-#
-#   matcher = equal(object) # => Matchi::Matcher::Equal.new(object)
-#   matcher.matches? { object } # => true
-#   matcher.matches? { "foo" } # => false
-#
-# @example Regular expressions matcher
-#   matcher = match(/^foo$/) # => Matchi::Matcher::Match.new(/^foo$/)
-#   matcher.matches? { "foo" } # => true
-#   matcher.matches? { "bar" } # => false
-#
-# @example Expecting errors matcher
-#   matcher = raise_exception(NameError) # => Matchi::Matcher::RaiseException.new(NameError)
-#   matcher.matches? { Boom } # => true
-#   matcher.matches? { true } # => false
-#
-# @example Truth matcher
-#   matcher = be_true # => Matchi::Matcher::BeTrue.new
-#   matcher.matches? { true } # => true
-#   matcher.matches? { false } # => false
-#   matcher.matches? { nil } # => false
-#   matcher.matches? { 4 } # => false
-#
-# @example Untruth matcher
-#   matcher = be_false # => Matchi::Matcher::BeFalse.new
-#   matcher.matches? { false } # => true
-#   matcher.matches? { true } # => false
-#   matcher.matches? { nil } # => false
-#   matcher.matches? { 4 } # => false
-#
-# @example Nil matcher
-#   matcher = be_nil # => Matchi::Matcher::BeNil.new
-#   matcher.matches? { nil } # => true
-#   matcher.matches? { false } # => false
-#   matcher.matches? { true } # => false
-#   matcher.matches? { 4 } # => false
-#
-# @example Type/class matcher
-#   matcher = be_an_instance_of(String) # => Matchi::Matcher::BeAnInstanceOf.new(String)
-#   matcher.matches? { "foo" } # => true
-#   matcher.matches? { 4 } # => false
-#
-# @see https://github.com/fixrb/matchi
+# This module defines methods that can be used to qualify expectations in
+# specifications.
 module Spectus
-  include ::Matchi::Helper
+  # This method mean that the definition is an absolute requirement of the
+  # specification.
+  #
+  # @example An absolute requirement definition
+  #   require "spectus"
+  #   require "matchi/eq"
+  #
+  #   Spectus.must Matchi::Eq.new("FOO")
+  #   # => #<MUST Matchi::Eq("FOO") isolate=false negate=false>
+  #
+  # @param matcher [#matches?] The matcher.
+  #
+  # @return [Requirement::Required] An absolute requirement level instance.
+  #
+  # @api public
+  def self.must(matcher)
+    Requirement::Required.new(
+      isolate: false,
+      negate:  false,
+      matcher: matcher
+    )
+  end
+
+  # @example An absolute requirement definition with isolation
+  #   require "spectus"
+  #   require "matchi/eq"
+  #
+  #   Spectus.must! Matchi::Eq.new("FOO")
+  #   # => #<MUST Matchi::Eq("FOO") isolate=true negate=false>
+  #
+  # @see must
+  def self.must!(matcher)
+    Requirement::Required.new(
+      isolate: true,
+      negate:  false,
+      matcher: matcher
+    )
+  end
+
+  # This method mean that the definition is an absolute prohibition of the specification.
+  #
+  # @example An absolute prohibition definition
+  #   require "spectus"
+  #   require "matchi/be"
+  #
+  #   Spectus.must_not Matchi::Be.new(42)
+  #   # => #<MUST Matchi::Be(42) isolate=false negate=true>
+  #
+  # @param matcher [#matches?] The matcher.
+  #
+  # @return [Requirement::Required] An absolute prohibition level instance.
+  def self.must_not(matcher)
+    Requirement::Required.new(
+      isolate: false,
+      negate:  true,
+      matcher: matcher
+    )
+  end
+
+  # @example An absolute prohibition definition with isolation
+  #   require "spectus"
+  #   require "matchi/be"
+  #
+  #   Spectus.must_not! Matchi::Be.new(42)
+  #   # => #<MUST Matchi::Be(42) isolate=true negate=true>
+  #
+  # @see must_not
+  def self.must_not!(matcher)
+    Requirement::Required.new(
+      isolate: true,
+      negate:  true,
+      matcher: matcher
+    )
+  end
+
+  # This method mean that there may exist valid reasons in particular
+  # circumstances to ignore a particular item, but the full implications must be
+  # understood and carefully weighed before choosing a different course.
+  #
+  # @example A recommended definition
+  #   require "spectus"
+  #   require "matchi/be"
+  #
+  #   Spectus.should Matchi::Be.new(true)
+  #   # => #<SHOULD Matchi::Be(true) isolate=false negate=false>
+  #
+  # @param matcher [#matches?] The matcher.
+  #
+  # @return [Requirement::Recommended] A recommended requirement level instance.
+  def self.should(matcher)
+    Requirement::Recommended.new(
+      isolate: false,
+      negate:  false,
+      matcher: matcher
+    )
+  end
+
+  # @example A recommended definition with isolation
+  #   require "spectus"
+  #   require "matchi/be"
+  #
+  #   Spectus.should! Matchi::Be.new(true)
+  #   # => #<SHOULD Matchi::Be(true) isolate=true negate=false>
+  #
+  # @see should
+  def self.should!(matcher)
+    Requirement::Recommended.new(
+      isolate: true,
+      negate:  false,
+      matcher: matcher
+    )
+  end
 
-  # Expectations are built with this method.
+  # This method mean that there may exist valid reasons in particular
+  # circumstances when the particular behavior is acceptable or even useful, but
+  # the full implications should be understood and the case carefully weighed
+  # before implementing any behavior described with this label.
+  #
+  # @example A not recommended definition
+  #   require "spectus"
+  #   require "matchi/raise_exception"
+  #
+  #   Spectus.should_not Matchi::RaiseException.new(NoMethodError)
+  #   # => #<SHOULD Matchi::RaiseException(NoMethodError) isolate=false negate=true>
+  #
+  # @param matcher [#matches?] The matcher.
+  #
+  # @return [Requirement::Recommended] A not recommended requirement level
+  #   instance.
+  def self.should_not(matcher)
+    Requirement::Recommended.new(
+      isolate: false,
+      negate:  true,
+      matcher: matcher
+    )
+  end
+
+  # @example A not recommended definition with isolation
+  #   require "spectus"
+  #   require "matchi/raise_exception"
+  #
+  #   Spectus.should_not! Matchi::RaiseException.new(NoMethodError)
+  #   # => #<SHOULD Matchi::RaiseException(NoMethodError) isolate=true negate=true>
   #
-  # @example An _absolute requirement_ definition.
-  #   it { 42 }.MUST equal 42 # => #<Spectus::Result::Pass...>
+  # @see should_not
+  def self.should_not!(matcher)
+    Requirement::Recommended.new(
+      isolate: true,
+      negate:  true,
+      matcher: matcher
+    )
+  end
+
+  # This method mean that an item is truly optional.
+  # One vendor may choose to include the item because a particular marketplace
+  # requires it or because the vendor feels that it enhances the product while
+  # another vendor may omit the same item. An implementation which does not
+  # include a particular option must be prepared to interoperate with another
+  # implementation which does include the option, though perhaps with reduced
+  # functionality. In the same vein an implementation which does include a
+  # particular option must be prepared to interoperate with another
+  # implementation which does not include the option (except, of course, for the
+  # feature the option provides).
+  #
+  # @example An optional definition
+  #   require "spectus"
+  #   require "matchi/match"
+  #
+  #   Spectus.may Matchi::Match.new(/^foo$/)
+  #   # => #<MAY Matchi::Match(/^foo$/) isolate=false negate=false>
+  #
+  # @param matcher [#matches?] The matcher.
+  #
+  # @return [Requirement::Optional] An optional requirement level instance.
+  def self.may(matcher)
+    Requirement::Optional.new(
+      isolate: false,
+      negate:  false,
+      matcher: matcher
+    )
+  end
+
+  # @example An optional definition with isolation
+  #   require "spectus"
+  #   require "matchi/match"
   #
-  # @param input [Proc] The code to test.
+  #   Spectus.may! Matchi::Match.new(/^foo$/)
+  #   # => #<MAY Matchi::Match(/^foo$/) isolate=true negate=false>
   #
-  # @return [ExpectationTarget] The expectation target.
-  def it(&input)
-    ExpectationTarget.new(&input)
+  # @see may
+  def self.may!(matcher)
+    Requirement::Optional.new(
+      isolate: true,
+      negate:  false,
+      matcher: matcher
+    )
   end
 end

data/lib/spectus/requirement.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Spectus
+  # Namespace for the results.
+  #
+  # @api private
+  module Requirement
+  end
+end
+
+require_relative File.join("requirement", "required")
+require_relative File.join("requirement", "recommended")
+require_relative File.join("requirement", "optional")

data/lib/spectus/requirement/base.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "expresenter"
+require "test_tube"
+
+module Spectus
+  # Namespace for the requirement levels.
+  module Requirement
+    # Requirement level's base class.
+    class Base
+      # Initialize the requirement level class.
+      #
+      # @param isolate  [Boolean]   Compute actual in a subprocess.
+      # @param matcher  [#matches?] The matcher.
+      # @param negate   [Boolean]   Invert the matcher or not.
+      def initialize(isolate:, matcher:, negate:)
+        @isolate  = isolate
+        @matcher  = matcher
+        @negate   = negate
+      end
+
+      # Test result.
+      #
+      # @raise [::Expresenter::Fail] A failed spec exception.
+      # @return [::Expresenter::Pass] A passed spec instance.
+      #
+      # @see https://github.com/fixrb/expresenter
+      #
+      # @api public
+      def call(&block)
+        test = ::TestTube.invoke(isolate: @isolate, matcher: @matcher, negate: @negate, &block)
+
+        ::Expresenter.call(passed?(test)).with(
+          actual:     test.actual,
+          definition: @matcher.to_s,
+          error:      test.error,
+          expected:   @matcher.expected,
+          got:        test.got,
+          level:      self.class.level,
+          negate:     @negate
+        )
+      end
+
+      # :nocov:
+
+      # A string containing a human-readable representation of the definition.
+      #
+      # @example The human-readable representation of an absolute requirement.
+      #   require "spectus"
+      #   require "matchi/be"
+      #
+      #   definition = Spectus.must Matchi::Be.new(1)
+      #   definition.inspect
+      #   # => "#<MUST Matchi::Be(1) isolate=false negate=false>"
+      #
+      # @return [String] The human-readable representation of the definition.
+      #
+      # @api public
+      def inspect
+        "#<#{self.class.level} #{@matcher.inspect} isolate=#{@isolate} negate=#{@negate}>"
+      end
+
+      # :nocov:
+
+      private
+
+      # Code experiment result.
+      #
+      # @param test [::TestTube::Base] The state of the experiment.
+      #
+      # @see https://github.com/fixrb/test_tube
+      #
+      # @return [Boolean] The result of the test (passed or failed).
+      def passed?(test)
+        test.got.equal?(true)
+      end
+    end
+  end
+end

data/lib/spectus/requirement/optional.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Spectus
+  module Requirement
+    # Optional requirement level.
+    class Optional < Base
+      # Key word for use in RFCs to indicate requirement levels.
+      #
+      # @return [Symbol] The requirement level.
+      def self.level
+        :MAY
+      end
+
+      private
+
+      # Code experiment result.
+      #
+      # @param (see Base#passed?)
+      #
+      # @return (see Base#passed?)
+      def passed?(test)
+        super || test.error.is_a?(::NoMethodError)
+      end
+    end
+  end
+end

data/lib/spectus/requirement/recommended.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Spectus
+  module Requirement
+    # Recommended and not recommended requirement levels.
+    class Recommended < Base
+      # Key word for use in RFCs to indicate requirement levels.
+      #
+      # @return [Symbol] The requirement level.
+      def self.level
+        :SHOULD
+      end
+
+      private
+
+      # Code experiment result.
+      #
+      # @param (see Base#passed?)
+      #
+      # @return (see Base#passed?)
+      def passed?(test)
+        super || test.error.nil?
+      end
+    end
+  end
+end

data/lib/spectus/requirement/required.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Spectus
+  module Requirement
+    # Absolute requirement and absolute prohibition levels.
+    class Required < Base
+      # Key word for use in RFCs to indicate requirement levels.
+      #
+      # @return [Symbol] The requirement level.
+      def self.level
+        :MUST
+      end
+    end
+  end
+end

metadata

@@ -1,59 +1,59 @@
 --- !ruby/object:Gem::Specification
 name: spectus
 version: !ruby/object:Gem::Version
-  version: 3.3.4
+  version: 4.0.2
 platform: ruby
 authors:
 - Cyril Kato
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-06-16 00:00:00.000000000 Z
+date: 2021-07-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: defi
+  name: expresenter
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.0.5
+        version: 1.4.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.0.5
+        version: 1.4.0
 - !ruby/object:Gem::Dependency
-  name: expresenter
+  name: test_tube
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.2.1
+        version: 2.1.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.2.1
+        version: 2.1.0
 - !ruby/object:Gem::Dependency
-  name: matchi
+  name: brutal
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 2.1.0
-  type: :runtime
+        version: '0'
+  type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 2.1.0
+        version: '0'
 - !ruby/object:Gem::Dependency
-  name: brutal
+  name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -67,7 +67,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: bundler
+  name: matchi
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -187,15 +187,11 @@ files:
 - LICENSE.md
 - README.md
 - lib/spectus.rb
-- lib/spectus/exam.rb
-- lib/spectus/expectation_target.rb
-- lib/spectus/requirement_level/base.rb
-- lib/spectus/requirement_level/may.rb
-- lib/spectus/requirement_level/must.rb
-- lib/spectus/requirement_level/should.rb
-- lib/spectus/result.rb
-- lib/spectus/result/fail.rb
-- lib/spectus/result/pass.rb
+- lib/spectus/requirement.rb
+- lib/spectus/requirement/base.rb
+- lib/spectus/requirement/optional.rb
+- lib/spectus/requirement/recommended.rb
+- lib/spectus/requirement/required.rb
 homepage: https://github.com/fixrb/spectus
 licenses:
 - MIT

data/lib/spectus/exam.rb

@@ -1,56 +0,0 @@
-# frozen_string_literal: true
-
-require "defi"
-
-module Spectus
-  # This class evaluate the expectation with the passed block.
-  class Exam
-    # Execute the untested code from the passed block against the matcher.
-    #
-    # rubocop:disable Lint/RescueException
-    #
-    # @param callable   [#call]     The callable object to test.
-    # @param isolation  [Boolean]   Compute actual in isolation?
-    # @param negate     [Boolean]   Positive or negative assertion?
-    # @param matcher    [#matches?] The matcher.
-    def initialize(callable:, isolation:, negate:, matcher:)
-      @got = negate ^ matcher.matches? do
-        value = if isolation
-                  send_call.to!(callable)
-                else
-                  send_call.to(callable)
-                end
-
-        @actual = value.object
-
-        value.call
-      end
-    rescue ::Exception => e
-      @actual     = nil
-      @exception  = e
-    end
-    # rubocop:enable Lint/RescueException
-
-    # @return [#object_id] The actual value.
-    attr_reader :actual
-
-    # @return [Exception, nil] An exception.
-    attr_reader :exception
-
-    # @return [Boolean, nil] Report to the spec requirement level if the
-    #   expectation is true or false.
-    attr_reader :got
-
-    # @return [Defi::Challenge] The challenge for the callable object.
-    def send_call
-      ::Defi.send(:call)
-    end
-
-    # Report to the spec requirement level if the test pass or fail.
-    #
-    # @return [Boolean] Report if the test pass or fail?
-    def valid?
-      exception.nil? ? got : false
-    end
-  end
-end

data/lib/spectus/expectation_target.rb

@@ -1,202 +0,0 @@
-# frozen_string_literal: true
-
-require_relative File.join("requirement_level", "must")
-require_relative File.join("requirement_level", "should")
-require_relative File.join("requirement_level", "may")
-
-module Spectus
-  # Wraps the target of an expectation.
-  #
-  # @example
-  #   it { actual value } # => ExpectationTarget wrapping the block
-  class ExpectationTarget
-    # Create a new expectation target
-    #
-    # @param callable [Proc] The object to test.
-    def initialize(&callable)
-      @callable = callable
-    end
-
-    # rubocop:disable Naming/MethodName
-
-    # This word, or the terms "REQUIRED" or "SHALL", mean that the
-    # definition is an absolute requirement of the specification.
-    #
-    # @example _Absolute requirement_ definition
-    #   it { "foo".upcase }.MUST eql 'FOO'
-    #
-    # @param matcher [#matches?] The matcher.
-    #
-    # @return [Spectus::Result::Fail, Spectus::Result::Pass] Report if the spec
-    #   pass or fail.
-    def MUST(matcher)
-      RequirementLevel::Must.new(
-        callable:   callable,
-        isolation:  false,
-        negate:     false,
-        matcher:    matcher
-      ).call
-    end
-
-    # @example _Absolute requirement_ definition with isolation
-    #   it { "foo".upcase }.MUST! eql 'FOO'
-    #
-    # @see MUST
-    def MUST!(matcher)
-      RequirementLevel::Must.new(
-        callable:   callable,
-        isolation:  true,
-        negate:     false,
-        matcher:    matcher
-      ).call
-    end
-
-    # This phrase, or the phrase "SHALL NOT", mean that the
-    # definition is an absolute prohibition of the specification.
-    #
-    # @example _Absolute prohibition_ definition
-    #   it { "foo".size }.MUST_NOT equal 42
-    #
-    # @param matcher [#matches?] The matcher.
-    #
-    # @return [Spectus::Result::Fail, Spectus::Result::Pass] Report if the spec
-    #   pass or fail.
-    def MUST_NOT(matcher)
-      RequirementLevel::Must.new(
-        callable:   callable,
-        isolation:  false,
-        negate:     true,
-        matcher:    matcher
-      ).call
-    end
-
-    # @example _Absolute prohibition_ definition with isolation
-    #   it { "foo".size }.MUST_NOT! equal 42
-    #
-    # @see MUST_NOT
-    def MUST_NOT!(matcher)
-      RequirementLevel::Must.new(
-        callable:   callable,
-        isolation:  true,
-        negate:     true,
-        matcher:    matcher
-      ).call
-    end
-
-    # This word, or the adjective "RECOMMENDED", mean that there
-    # may exist valid reasons in particular circumstances to ignore a
-    # particular item, but the full implications must be understood and
-    # carefully weighed before choosing a different course.
-    #
-    # @example _Recommended_ definition
-    #   it { "foo".valid_encoding? }.SHOULD equal true
-    #
-    # @param matcher [#matches?] The matcher.
-    #
-    # @return [Spectus::Result::Fail, Spectus::Result::Pass] Report if the spec
-    #   pass or fail.
-    def SHOULD(matcher)
-      RequirementLevel::Should.new(
-        callable:   callable,
-        isolation:  false,
-        negate:     false,
-        matcher:    matcher
-      ).call
-    end
-
-    # @example _Recommended_ definition with isolation
-    #   it { "foo".valid_encoding? }.SHOULD! equal true
-    #
-    # @see SHOULD
-    def SHOULD!(matcher)
-      RequirementLevel::Should.new(
-        callable:   callable,
-        isolation:  true,
-        negate:     false,
-        matcher:    matcher
-      ).call
-    end
-
-    # This phrase, or the phrase "NOT RECOMMENDED" mean that
-    # there may exist valid reasons in particular circumstances when the
-    # particular behavior is acceptable or even useful, but the full
-    # implications should be understood and the case carefully weighed
-    # before implementing any behavior described with this label.
-    #
-    # @example _Not recommended_ definition
-    #   it { "".blank? }.SHOULD_NOT raise_exception NoMethodError
-    #
-    # @param matcher [#matches?] The matcher.
-    #
-    # @return [Spectus::Result::Fail, Spectus::Result::Pass] Report if the spec
-    #   pass or fail.
-    def SHOULD_NOT(matcher)
-      RequirementLevel::Should.new(
-        callable:   callable,
-        isolation:  false,
-        negate:     true,
-        matcher:    matcher
-      ).call
-    end
-
-    # @example _Not recommended_ definition with isolation
-    #   it { "".blank? }.SHOULD_NOT! raise_exception NoMethodError
-    #
-    # @see SHOULD_NOT
-    def SHOULD_NOT!(matcher)
-      RequirementLevel::Should.new(
-        callable:   callable,
-        isolation:  true,
-        negate:     true,
-        matcher:    matcher
-      ).call
-    end
-
-    # This word, or the adjective "OPTIONAL", mean that an item is
-    # truly optional.  One vendor may choose to include the item because a
-    # particular marketplace requires it or because the vendor feels that
-    # it enhances the product while another vendor may omit the same item.
-    # An implementation which does not include a particular option MUST be
-    # prepared to interoperate with another implementation which does
-    # include the option, though perhaps with reduced functionality. In the
-    # same vein an implementation which does include a particular option
-    # MUST be prepared to interoperate with another implementation which
-    # does not include the option (except, of course, for the feature the
-    # option provides.)
-    #
-    # @example _Optional_ definition
-    #   it { "foo".bar }.MAY match /^foo$/
-    #
-    # @param matcher [#matches?] The matcher.
-    #
-    # @return [Spectus::Result::Fail, Spectus::Result::Pass] Report if the spec pass or fail.
-    def MAY(matcher)
-      RequirementLevel::May.new(
-        callable:   callable,
-        isolation:  false,
-        negate:     false,
-        matcher:    matcher
-      ).call
-    end
-
-    # @example _Optional_ definition with isolation
-    #   it { "foo".bar }.MAY! match /^foo$/
-    #
-    # @see MAY
-    def MAY!(matcher)
-      RequirementLevel::May.new(
-        callable:   callable,
-        isolation:  true,
-        negate:     false,
-        matcher:    matcher
-      ).call
-    end
-
-    # rubocop:enable Naming/MethodName
-
-    protected
-
-    # @return [#call] The callable object to test.
-    attr_reader :callable
-  end
-end

data/lib/spectus/requirement_level/base.rb

@@ -1,69 +0,0 @@
-# frozen_string_literal: true
-
-require_relative File.join("..", "exam")
-require_relative File.join("..", "result")
-
-module Spectus
-  # Namespace for the requirement levels.
-  module RequirementLevel
-    # Requirement level's base class.
-    class Base
-      # Initialize the requirement level class.
-      #
-      # @param callable   [#call]     The callable object to test.
-      # @param isolation  [Boolean]   Compute actual in isolation?
-      # @param negate     [Boolean]   Positive or negative assertion?
-      # @param matcher    [#matches?] The matcher.
-      def initialize(callable:, isolation:, negate:, matcher:)
-        @negate   = negate
-        @matcher  = matcher
-
-        @exam = Exam.new(
-          callable:   callable,
-          isolation:  isolation,
-          negate:     negate,
-          matcher:    matcher
-        )
-      end
-
-      # @return [#Exam] The exam.
-      attr_reader :exam
-
-      # @return [#matches?] The matcher that performed a boolean comparison
-      #   between the actual value and the expected value.
-      attr_reader :matcher
-
-      # The result of the expectation.
-      #
-      # @raise [Spectus::Result::Fail] The expectation failed.
-      # @return [Spectus::Result::Pass] The expectation passed.
-      def call
-        Result.call(pass?).with(
-          actual:   exam.actual,
-          error:    exam.exception,
-          expected: matcher.expected,
-          got:      exam.got,
-          negate:   negate?,
-          valid:    exam.valid?,
-          matcher:  matcher.class.to_sym,
-          level:    level
-        )
-      end
-
-      protected
-
-      # @return [Symbol] The requirement level.
-      def level
-        self.class.name.split("::").fetch(-1).upcase.to_sym
-      end
-
-      # @note The boolean comparison between the actual value and the expected
-      #   value can be evaluated to a negative assertion.
-      #
-      # @return [Boolean] Positive or negative assertion?
-      def negate?
-        @negate
-      end
-    end
-  end
-end

data/lib/spectus/requirement_level/may.rb

@@ -1,17 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "must"
-
-module Spectus
-  module RequirementLevel
-    # May requirement level's class.
-    class May < Must
-      # Evaluate the expectation.
-      #
-      # @return [Boolean] Report if the low expectation pass or fail?
-      def pass?
-        super || exam.exception.is_a?(::NoMethodError)
-      end
-    end
-  end
-end

data/lib/spectus/requirement_level/must.rb

@@ -1,17 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "base"
-
-module Spectus
-  module RequirementLevel
-    # Must requirement level's class.
-    class Must < Base
-      # Evaluate the expectation.
-      #
-      # @return [Boolean] Report if the high expectation pass or fail?
-      def pass?
-        exam.valid?
-      end
-    end
-  end
-end

data/lib/spectus/requirement_level/should.rb

@@ -1,17 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "must"
-
-module Spectus
-  module RequirementLevel
-    # Should requirement level's class.
-    class Should < Must
-      # Evaluate the expectation.
-      #
-      # @return [Boolean] Report if the medium expectation pass or fail?
-      def pass?
-        super || exam.exception.nil?
-      end
-    end
-  end
-end

data/lib/spectus/result.rb

@@ -1,18 +0,0 @@
-# frozen_string_literal: true
-
-require_relative File.join("result", "fail")
-require_relative File.join("result", "pass")
-
-module Spectus
-  # Namespace for the results.
-  module Result
-    # @param is_passed [Boolean] The value of an assertion.
-    # @return [Class<Spectus::Result::Pass>, Class<Spectus::Result::Fail>] The
-    #   class of the result.
-    # @example Get the pass class result.
-    #   call(true) # => Pass
-    def self.call(is_passed)
-      is_passed ? Pass : Fail
-    end
-  end
-end

data/lib/spectus/result/fail.rb

@@ -1,13 +0,0 @@
-# frozen_string_literal: true
-
-require "expresenter/fail"
-
-module Spectus
-  module Result
-    # The class that is responsible for reporting that the expectation is false.
-    #
-    # @see https://github.com/fixrb/expresenter/blob/v1.2.1/lib/expresenter/fail.rb
-    class Fail < ::Expresenter::Fail
-    end
-  end
-end

data/lib/spectus/result/pass.rb

@@ -1,13 +0,0 @@
-# frozen_string_literal: true
-
-require "expresenter/pass"
-
-module Spectus
-  module Result
-    # The class that is responsible for reporting that the expectation is true.
-    #
-    # @see https://github.com/fixrb/expresenter/blob/v1.2.1/lib/expresenter/pass.rb
-    class Pass < ::Expresenter::Pass
-    end
-  end
-end