spectus 1.1.1 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3b29a968ab4babf3a903050203e7deb144040793
-  data.tar.gz: 88bceace4526d5b32086d8cffc4b0bafe0a63eea
+  metadata.gz: 867183006b16f6ab6f0d641efbfd37380a4612b8
+  data.tar.gz: a478b86f508003282d7544cfd660a6b811b71cb2
 SHA512:
-  metadata.gz: 33c4154ad5a8df2a17a18c150f8f08415cde517314b3b108ae25eb5e2150016d88653ff7a20e0bb0f6dd90e4daa4cdf4d443ec6e96da003cc8d0b5a3874ad506
-  data.tar.gz: 044277ab6398d8d44b2566b858cb394f22e75c6f8dcd09eae299e3beb3245c7c1304f2fb6966d925feb20f0f119e480b3d1635d5011688fc046c6142176ad660
+  metadata.gz: 252c54bd2591df3ff5eb38b27ae5482855d08346c9679901bea0d6fba059134a678d9d79235a621c94de6d970eaf195f96144d52034f42379ce903ce46de92f7
+  data.tar.gz: 9576c89c47fa07424278f9bcff57e5fd26cf9075a239fc2e3db2e367eedb696e656296a6a07a4ced7ea923a1fc156f493f62410211970ae10262b69d943ad90c

data/.gitignore

@@ -7,8 +7,3 @@
 /pkg/
 /spec/reports/
 /tmp/
-*.bundle
-*.so
-*.o
-*.a
-mkmf.log

data/.travis.yml

@@ -1,6 +1,15 @@
 language: ruby
-script: 'bundle exec rake test:coverage'
+sudo: false
+cache: bundler
+script: 'bundle exec rake test:coverage --trace'
+before_install:
+  - gem install bundler
 rvm:
-  - 2.0.0
-  - 2.1.3
+  - 1.9.3
+  - 2.0
+  - 2.1
+  - 2.2
   - ruby-head
+  - jruby
+  - jruby-head
+  - rbx-2

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,13 @@
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, age, or religion.
+
+Examples of unacceptable behavior by participants include the use of sexual language or imagery, derogatory comments or personal attacks, trolling, public or private harassment, insults, or other unprofessional conduct.
+
+Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct. Project maintainers who do not follow the Code of Conduct may be removed from the project team.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting one or more of the project maintainers.
+
+This Code of Conduct is adapted from the [Contributor Covenant](http:contributor-covenant.org), version 1.0.0, available at [http://contributor-covenant.org/version/1/0/0/](http://contributor-covenant.org/version/1/0/0/)

data/Gemfile

@@ -1,2 +1,5 @@
 source 'https://rubygems.org'
+
 gemspec
+
+gem 'rubysl-irb' if RUBY_ENGINE.eql?('rbx')

data/LICENSE.md

@@ -1,22 +1,21 @@
-Copyright (c) 2014 Cyril Wack
+The MIT License (MIT)
 
-MIT License
+Copyright (c) 2014 Cyril Wack
 
-Permission is hereby granted, free of charge, to any person obtaining
-a copy of this software and associated documentation files (the
-"Software"), to deal in the Software without restriction, including
-without limitation the rights to use, copy, modify, merge, publish,
-distribute, sublicense, and/or sell copies of the Software, and to
-permit persons to whom the Software is furnished to do so, subject to
-the following conditions:
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
 
-The above copyright notice and this permission notice shall be
-included in all copies or substantial portions of the Software.
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
-NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
-LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
-OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
-WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -1,13 +1,12 @@
 # Spectus
 
 [![Build Status](https://travis-ci.org/fixrb/spectus.svg?branch=master)](https://travis-ci.org/fixrb/spectus)
-[![Coverage Status](http://img.shields.io/coveralls/fixrb/spectus.svg?branch=master)](https://coveralls.io/r/fixrb/spectus)
 [![Dependency Status](https://gemnasium.com/fixrb/spectus.svg)](https://gemnasium.com/fixrb/spectus)
 [![Gem Version](http://img.shields.io/gem/v/spectus.svg)](https://rubygems.org/gems/spectus)
 [![Inline docs](http://inch-ci.org/github/fixrb/spectus.svg?branch=master)](http://inch-ci.org/github/fixrb/spectus)
 [![Documentation](http://img.shields.io/:yard-docs-38c800.svg)](http://rubydoc.info/gems/spectus/frames)
 
-> Expectation library with some built-in matchers for Ruby.
+> Expectation library with [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt)'s requirement levels, and some matchers for Ruby.
 
 ## Contact
 
@@ -17,7 +16,9 @@
 
 ## Rubies
 
-__Spectus__ is supported by Ruby (MRI) 2+.
+* [MRI](https://www.ruby-lang.org/)
+* [Rubinius](http://rubini.us/)
+* [JRuby](http://jruby.org/)
 
 ## Installation
 
@@ -29,221 +30,47 @@ gem 'spectus'
 
 And then execute:
 
-```shell
-$ bundle
-```
+    $ bundle
 
 Or install it yourself as:
 
-```shell
-$ gem install spectus
-```
-
-## Why would I want this library?
-
-* It's 143 lines of fast and KISS code.
-* Atomic state transitions, unmutated objects, thread-safe.
-* Provides a generic and consistent DSL for assertions.
-
-## API
-
-The [Spectus DSL](lib/spectus/dsl.rb) provides the `expect` method.
-It takes a block parameter and responds to:
-
-* `to(definition)`
-* `not_to(definition)`
-
-Then, it returns `true` or `false`; or it raises an exception.
+    $ gem install spectus
 
 ## Usage
 
-```ruby
-class Duck
-  def walks
-    "Klop klop!"
-  end
-
-  def swims
-    "Swoosh..."
-  end
-
-  def quacks
-    puts "Quaaaaaack!"
-  end
-end
-
-@bird = Duck.new
-```
-
-> When I see a `#<Duck:0x007f96b285d6d0>` that ...
+**Absolute requirement** definition:
 
 ```ruby
-require 'spectus'
-extend Spectus::DSL
-
-# Let's define the custom matcher `capture_stdout`.
-require 'stringio'
-module Spectus
-  module Matcher
-    class CaptureStdout
-      def initialize expected
-        @expected = expected
-      end
-
-      def matches?
-        begin
-          orig_std  = $stdout
-          $stdout   = StringIO.new
-          yield
-          $stdout.string.eql? @expected
-        ensure
-          $stdout   = orig_std
-        end
-      end
-    end
-  end
-end
-
-expectation_1 = expect { @bird.walks  }.to eql: "Klop klop!"
-expectation_2 = expect { @bird.swims  }.to eql: "Swoosh..."
-expectation_3 = expect { @bird.quacks }.to capture_stdout: "Quaaaaaack!\n"
-expectation_4 = expect { @bird.speaks }.to raise_exception: NoMethodError
-
-case (expectation_1 == true &&
-      expectation_2 == true &&
-      expectation_3 == true &&
-      expectation_4 == true)
-  when true then puts "I call that #{@bird} a duck."
-  else abort 'WAT?'
-end
+Spectus.this { 'foo'.upcase }.MUST eql: 'FOO' # => true
 ```
 
-> I call that `#<Duck:0x007f96b285d6d0>` a duck.
-
-## Built-in matchers
-
-### Equivalence
+**Absolute prohibition** definition:
 
 ```ruby
-expect { 'foo' }.to eql: 'foo' # => true
+Spectus.this { 'foo'.length }.MUST_NOT equal: 42 # => true
 ```
 
-### Identity
+**Recommended** definition:
 
 ```ruby
-expect { :foo }.to equal: :foo # => true
+Spectus.this { 'foo'.valid_encoding? }.SHOULD equal: true # => true
 ```
 
-### Regular expressions
+**Not recommended** definition:
 
 ```ruby
-expect { 'foo' }.to({match: /^foo$/}) # => true
+Spectus.this { ''.blank? }.SHOULD_NOT raise_exception: NoMethodError # => false
 ```
 
-### Expecting errors
-
-```ruby
-expect { Foo }.to raise_exception: NameError # => true
-```
-
-## Custom matchers
-
-Custom matchers can also be defined for expressing expectations.
-
-### Be prime
-
-The following expression...
+**Optional** definition:
 
 ```ruby
-require 'prime'
-expect { Prime.prime? 42 }.to equal: false # => true
+Spectus.this { 'foo'.bar }.MAY match: /^foo$/ # => true
 ```
 
-...could be refactored into:
-
-```ruby
-expect { 42 }.not_to :be_prime # => true
-```
-
-It can be done with this custom matcher:
-
-```ruby
-require 'prime'
-
-module Spectus
-  module Matcher
-    class BePrime
-      def matches?
-        Prime.prime? yield
-      end
-    end
-  end
-end
-```
-
-### Be the answer
-
-The following expression...
-
-```ruby
-expect { 42 }.to equal: 42 # => true
-```
-
-...could be refactored into:
-
-```ruby
-expect { 42 }.to :be_the_answer # => true
-```
-
-It can be done with this custom matcher:
-
-```ruby
-module Spectus
-  module Matcher
-    class BeTheAnswer
-      def matches?
-        42.equal? yield
-      end
-    end
-  end
-end
-```
-
-### Start with
-
-The following expression...
-
-```ruby
-expect { 'foobar' }.to match: /^foo/ # => true
-```
-
-...could be refactored into:
-
-```ruby
-expect { 'foobar' }.to start_with: 'foo' # => true
-```
-
-It can be done with this custom matcher:
-
-```ruby
-module Spectus
-  module Matcher
-    class StartWith
-      def initialize expected
-        @expected = expected
-      end
-
-      def matches?
-        !Regexp.new("^#{@expected}").match(yield).nil?
-      end
-    end
-  end
-end
-```
-
-## Presentations
+## Versioning
 
-* [こんばんは、条件やビヘイビアテスト](https://speakerdeck.com/cyril/konbanha-tiao-jian-yabiheibiatesuto)
+__Spectus__ follows [Semantic Versioning 2.0](http://semver.org/).
 
 ## Contributing
 
@@ -252,11 +79,3 @@ end
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)
 5. Create a new Pull Request
-
-## Versioning
-
-__Spectus__ follows [Semantic Versioning 2.0](http://semver.org/)
-
-## Copyright
-
-&copy; 2014 [Cyril Wack](https://plus.google.com/+CyrilWack?rel=author)

data/VERSION.semver

@@ -1 +1 @@
-1.1.1
+2.0.0

data/bin/console

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'spectus'
+
+require 'irb'
+IRB.start

data/bin/setup

@@ -0,0 +1,5 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install

data/lib/spectus.rb

@@ -1,8 +1,18 @@
-require_relative File.join 'spectus', 'dsl'
-require_relative File.join 'spectus', 'version'
+require_relative File.join 'spectus', 'expectation_target'
 
 # Namespace for the Spectus library.
 #
 # @api private
 module Spectus
+  # Expectations are built with this method.
+  #
+  # @api public
+  #
+  # @example Absolute requirement definition
+  #   this { 42 }.MUST equal: 42 # => true
+  #
+  # @return [ExpectationTarget] the expectation target.
+  def self.this(&input)
+    ExpectationTarget.new(&input)
+  end
 end

data/lib/spectus/expectation_target.rb

@@ -1,32 +1,106 @@
-require_relative 'matcher'
+require_relative File.join 'requirement_level', 'high'
+require_relative File.join 'requirement_level', 'medium'
+require_relative File.join 'requirement_level', 'low'
 
 module Spectus
-
   # Wraps the target of an expectation.
   #
   # @example
-  #   expect { do_something } # => ExpectationTarget wrapping the block
+  #   this { stuff } # => ExpectationTarget wrapping the block
   class ExpectationTarget < BasicObject
-    def initialize &actual
+    # Create a new expection target
+    #
+    def initialize(&actual)
       @actual = actual
     end
 
-    # Evaluate to a positive assertion.
+    # This word, or the terms "REQUIRED" or "SHALL", mean that the
+    # definition is an absolute requirement of the specification.
+    #
+    # @api public
+    #
+    # @example _Absolute requirement_ definition
+    #   this { 'foo'.upcase }.MUST eql: 'FOO' # => true
+    #
+    # @param [Hash] definition
+    #
+    # @return [Boolean] report if the expectation is true or false.
+    def MUST(definition)
+      RequirementLevel::High.new(definition).pass?(&@actual)
+    end
+
+    # This phrase, or the phrase "SHALL NOT", mean that the
+    # definition is an absolute prohibition of the specification.
     #
     # @api public
     #
-    # @see Matcher#pass?
-    def to definition
-      Matcher.pass? false, definition, &@actual
+    # @example _Absolute prohibition_ definition
+    #   this { 'foo'.length }.MUST_NOT equal: 42 # => true
+    #
+    # @param [Hash] definition
+    #
+    # @return [Boolean] report if the expectation is true or false.
+    def MUST_NOT(definition)
+      RequirementLevel::High.new(definition, true).pass?(&@actual)
     end
 
-    # Evaluate to a negative assertion.
+    # 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.
     #
     # @api public
     #
-    # @see Matcher#pass?
-    def not_to definition
-      Matcher.pass? true, definition, &@actual
+    # @example _Recommended_ definition
+    #   this { 'foo'.valid_encoding? }.SHOULD equal: true # => true
+    #
+    # @param [Hash] definition
+    #
+    # @return [Boolean] report if the expectation is true or false.
+    def SHOULD(definition)
+      RequirementLevel::Medium.new(definition).pass?(&@actual)
+    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.
+    #
+    # @api public
+    #
+    # @example _Not recommended_ definition
+    #   this { ''.blank? }.SHOULD_NOT raise_exception: NoMethodError # => false
+    #
+    # @param [Hash] definition
+    #
+    # @return [Boolean] report if the expectation is true or false.
+    def SHOULD_NOT(definition)
+      RequirementLevel::Medium.new(definition, true).pass?(&@actual)
+    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.)
+    #
+    # @api public
+    #
+    # @example _Optional_ definition
+    #   this { 'foo'.bar }.MAY match: /^foo$/ # => true
+    #
+    # @param [Hash] definition
+    #
+    # @return [Boolean] report if the expectation is true or false.
+    def MAY(definition)
+      RequirementLevel::Low.new(definition).pass?(&@actual)
     end
   end
 end