spectus 3.4.0 → 4.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2fea4a88991addc0a6b69ce46d6422e92df818447818975d6123848cbba9d5a7
-  data.tar.gz: 8dffb97e6e58cdf0c3e5661294238e42f5477f4e677a34868ce918156086cbdb
+  metadata.gz: 3d2dc0863871f3794105ca9de38893d86ca937fe09bc8f90772d22f23551db79
+  data.tar.gz: efda8aae27fb68317b3d450ede09c13e22c7d5c8e638ba8c8fd8169ce5b93f03
 SHA512:
-  metadata.gz: 9a4798a255dcf0097dcba1bac46af91552a11348513c0d4af77a00a748cb950e90b113c264404cc745af3c7dc730154ad81893d879a495450f6cda5ca4b07942
-  data.tar.gz: ba56345d554c0483ce27fd6c7d876e7837d59a53a37a9b9e6417df849e0a6047b522a2c00e7f5d4327a76c1ed3e60cea68cff5970e7dcc4718d31ed89e3e6fa4
+  metadata.gz: 07e371fdb35d33e5451ca8188be95e153d08e58b0e32791081ecfed6d42a7eb16917ed711cff89bcaca7e27b2b10a59ba6676e1896e7f6cd15eb255861c1f2d4
+  data.tar.gz: 777d8c69e1beede896cd074c3c839707497a6775fe2e4263f309d66128a25b914beeee4ae822fa43c58d0b6279215c0f8a39ffe08b595ced35cdf02714e15a4e

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,151 +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)
+For convenience, we will also instantiate some matchers from the [Matchi library](https://github.com/fixrb/matchi):
 
-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)
-
-t.test_c # => Spectus::Result::Pass(actual: 3, error: nil, expected: 42, got: false, matcher: :equal, negate: false, level: :SHOULD)
+```sh
+gem install matchi
 ```
 
 ```ruby
-t = Spec.new(4)
-
-t.test_a # => raises an exception:
-# Traceback (most recent call last):
-#         3: from ./bin/console:8:in `<main>'
-#         2: from (irb):23
-#         1: from (irb):11:in `test_a'
-# 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)
-
-t.test_c # => raises an exception:
-# Traceback (most recent call last):
-#         3: from ./bin/console:8:in `<main>'
-#         2: from (irb):25
-#         1: from (irb):19:in `test_c'
-# Spectus::Result::Fail (NoMethodError: undefined method `length' for 4:Integer.)
-```
-
-## More examples
-
-To make __Spectus__ available:
-
-```ruby
-require "spectus"
-
-include Spectus
+require "matchi"
 ```
 
 All examples here assume that this has been done.
 
 ### Absolute Requirement
 
-There's only one bat:
+There is exactly one bat:
 
 ```ruby
-it { "🦇".size }.MUST equal 1
-# => Spectus::Result::Pass(actual: 1, error: nil, expected: 1, got: true, matcher: :equal, negate: false, level: :MUST)
+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 test is passed.
+
 ### Absolute Prohibition
 
-The true from the false:
+Truth and lies:
 
 ```ruby
-it { false }.MUST_NOT be_true
-# => Spectus::Result::Pass(actual: false, error: nil, expected: nil, got: true, matcher: :be_true, negate: true, level: :MUST)
+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)
 ```
 
 ### Recommended
 
-A well-known joke. An addition of `0.1` and `0.2` is deadly precise:
+A well-known joke. The addition of `0.1` and `0.2` is deadly precise:
 
 ```ruby
-it { 0.1 + 0.2 }.SHOULD equal 0.3
-# => Spectus::Result::Pass(actual: 0.30000000000000004, error: nil, expected: 0.3, got: false, matcher: :equal, negate: false, level: :SHOULD)
+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)
 ```
 
 ### Not Recommended
 
-The situation should still be under control:
+This should not be wrong:
 
 ```ruby
-it { BOOM }.SHOULD_NOT raise_exception SystemExit
-```
+definition = Spectus.should_not Matchi::Match.new("123456")
 
-```txt
-Traceback (most recent call last):
-        2: from ./bin/console:8:in `<main>'
-        1: from (irb):8
-Spectus::Result::Fail (NameError: uninitialized constant BOOM.)
+definition.call do
+  require "securerandom"
+
+  SecureRandom.hex(3)
+end
+# => Expresenter::Pass(actual: "bb5716", definition: "match \"123456\"", error: nil, expected: "123456", got: true, negate: true, level: :SHOULD)
 ```
 
+In any case, as long as there are no exceptions, the test passes.
+
 ### Optional
 
 An empty array is blank, right?
 
 ```ruby
-it { [].blank? }.MAY be_true
-# => Spectus::Result::Pass(actual: nil, error: #<NoMethodError: undefined method `blank?' for []:Array>, expected: nil, got: nil, matcher: :be_true, negate: false, level: :MAY)
+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)
 ```
 
-Damn, I forgot to load activesupport. 🤦‍♂️
+My bad! ActiveSupport was not imported. 🤦‍♂️
 
-That said, the test is passing due to the _not-implemented-like_ raised exception: `NoMethodError`.
+Anyways, the test passes because the exception produced is `NoMethodError`, meaning that the functionality is not implemented.
 
 ## Code Isolation
 
@@ -185,8 +126,9 @@ Example of test without isolation:
 ```ruby
 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)
+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, Alice!"
 ```
@@ -196,8 +138,9 @@ Example of test in isolation:
 ```ruby
 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)
+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!"
 ```
@@ -206,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
 
@@ -213,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)
-#   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)
-#   t.test_c # => Spectus::Result::Pass(actual: 3, error: nil, expected: 42, got: false, matcher: :equal, negate: false, level: :SHOULD)
-#
-# Or even directly used like this.
-#
-# @example
-#   require 'spectus'
-#
-#   include Spectus
-#
-#   it { 42 }.MUST equal 42 # => Spectus::Result::Pass(actual: 42, error: nil, expected: 42, got: true, matcher: :equal, negate: false, level: :MUST
-#
-# 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(actual: 42, error: nil, expected: 42, got: true, matcher: :equal, negate: false, level: :MUST
+  # @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,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: spectus
 version: !ruby/object:Gem::Version
-  version: 3.4.0
+  version: 4.0.3
 platform: ruby
 authors:
 - Cyril Kato
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-06-19 00:00:00.000000000 Z
+date: 2021-07-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: expresenter
@@ -16,44 +16,44 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.3.0
+        version: 1.4.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.3.0
+        version: 1.4.0
 - !ruby/object:Gem::Dependency
-  name: matchi
+  name: test_tube
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.1.0
+        version: 2.1.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.1.0
+        version: 2.1.1
 - !ruby/object:Gem::Dependency
-  name: test_tube
+  name: brutal
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 1.0.0
-  type: :runtime
+        version: '0'
+  type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 1.0.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,14 +187,11 @@ files:
 - LICENSE.md
 - README.md
 - lib/spectus.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/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,70 +0,0 @@
-# frozen_string_literal: true
-
-require "test_tube"
-
-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]   Invert the matcher or not.
-      # @param matcher    [#matches?] The matcher.
-      def initialize(callable:, isolation:, matcher:, negate:)
-        @negate     = negate
-        @matcher    = matcher
-        @experiment = ::TestTube.invoke(
-          callable,
-          isolation:  isolation,
-          matcher:    matcher,
-          negate:     negate
-        )
-      end
-
-      # @return [TestTube::Base] The experiment.
-      attr_reader :experiment
-
-      # @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:   experiment.actual,
-          error:    experiment.error,
-          expected: matcher.expected,
-          got:      experiment.got,
-          level:    level,
-          matcher:  matcher.class.to_sym,
-          negate:   negate?
-        )
-      end
-
-      protected
-
-      # Some key words for use in RFCs to indicate requirement levels.
-      #
-      # @return [:MUST, :SHOULD, :MAY] 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] Invert the matcher or not.
-      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 || experiment.error.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?
-        experiment.got.equal?(true)
-      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 || experiment.error.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