ae 1.8.2 → 1.9.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 23a2b354470346c0cce0e01593887716f750919349cac99c6ec35bdb079a56d7
+  data.tar.gz: '013992a3d412b79836902cf8234c3acb6629cfbcf3654e1da51d51144bc43990'
+SHA512:
+  metadata.gz: ccfba2d7d7d331f1531810b953c9cf38663f81a3dac682179288c09a8472b510de405034d4bd9334a6872f9a46c96b8e8e94c526b7744c1f20b124b98162aa00
+  data.tar.gz: bdfe778a71801e72f005f8f467d3a0cf1f8f0dac106d43fd0c6a146d3ac176d7c6b249dfe3ee437983b733419371d0861e6c6159c2c9e9824600e5bb477ddb36

data/HISTORY.md

@@ -1,5 +1,24 @@
 # RELEASE HISTORY
 
+## 1.9.0 / 2026-03-30
+
+Maintenance release. Modernized project tooling and cleaned up documentation.
+
+Changes:
+
+* Replace custom Indexer system with standard gemspec.
+* Replace Travis CI with GitHub Actions.
+* Replace Assembly/detroit with Rakefile.
+* Simplify version.rb to use a plain constant.
+* Update minitest adapter for minitest 5+.
+* Update testunit adapter for modern test-unit gem.
+* Fix typos and update URLs to HTTPS.
+* Add LICENSE.txt.
+* Move site from gh-pages to docs/.
+* Remove obsolete files (var/, etc/, MANIFEST, DEMO.rdoc).
+* Clean up .gitignore.
+
+
 ## 1.8.2 / 2013-02-18
 
 This release primarily fixes one bug --the assertions count

data/LICENSE.txt

@@ -0,0 +1,24 @@
+(BSD-2-Clause License)
+
+Copyright (c) 2008 Thomas Sawyer. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+   1. Redistributions of source code must retain the above copyright notice,
+      this list of conditions and the following disclaimer.
+
+   2. Redistributions in binary form must reproduce the above copyright
+      notice, this list of conditions and the following disclaimer in the
+      documentation and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
+INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
+COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
+INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
+OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
+EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -1,14 +1,12 @@
 # Assertive Expressive
 
-[Homepage](http://rubyworks.github.com/ae) /
-[Source Code](http://github.com/rubyworks/ae) /
-[Documentation](http://rubydoc.info/gems/ae) /
-[User Manual](http://wiki.github.com/rubyworks/ae) /
-[Report Issue](http://github.com/rubyworks/ae/issues) /
-[Mailing List](http://googlegroups.com/group/rubyworks-mailinglist) /
-[IRC Channel](irc://irc.freenode.net/rubyworks)    
-[![Build Status](https://secure.travis-ci.org/rubyworks/qed.png)](http://travis-ci.org/rubyworks/ae)
-[![Gem Version](https://badge.fury.io/rb/qed.png)](http://badge.fury.io/rb/ae)
+[Website](https://rubyworks.github.io/ae) /
+[API](https://rubydoc.info/gems/ae) /
+[Report Issue](https://github.com/rubyworks/ae/issues) /
+[Source Code](https://github.com/rubyworks/ae)
+
+[![Gem Version](https://img.shields.io/gem/v/ae.svg?style=flat)](https://rubygems.org/gems/ae)
+[![Build Status](https://github.com/rubyworks/ae/actions/workflows/test.yml/badge.svg)](https://github.com/rubyworks/ae/actions/workflows/test.yml)
 
 
 ## About
@@ -25,12 +23,12 @@ intended for reuse by any TDD, BDD or similar system.
 * Core extensions are standardized around Ruby Facets.
 * But Facets is not a dependency; the extensions are built-in.
 * Easily extensible allowing for alternate notations.
-* Eats it's own dog food.
+* Eats its own dog food.
 
 
 ## Synopsis
 
-AE defines the method `assert`. It's is compatible with the method
+AE defines the method `assert`. It is compatible with the method
 as defined by Test::Unit and MiniTest, which verifies truth of a
 single argument (and can accept an optional failure message).
 
@@ -154,6 +152,20 @@ and do:
 Windows users use 'ruby setup.rb all'.
 
 
+## Contributing
+
+If you would like to contribute code to the AE project, for the upstream
+repository and create a branch for you changes. When your changes are ready
+for review (and no, they do not have to 100% perfect if you still have some issues
+you need help working out).
+
+It you need to personally discuss some ideas or issue you try to get up with us
+via the mailing list or the IRC channel.
+
+* [Source Code](https://github.com/rubyworks/ae) /
+* [Mailing List](https://groups.google.com/group/rubyworks-mailinglist)
+
+
 ## Copyrights & License
 
 Copyright (c) 2008 Rubyworks. All rights reserved.
@@ -162,7 +174,7 @@ Unless otherwise provided for by the originating author, this
 program is distributed under the terms of the *BSD-2-Clause* license.
 Portions of this program may be copyrighted by others.
 
-See the NOTICE.rdoc file for details.
+See the NOTICE.md file for details.
 
-AE is a [Rubyworks](http://rubyworks.github.com) project.
+AE is a [Rubyworks](https://rubyworks.github.io) project.
 

data/demo/01_overview.md

@@ -0,0 +1,92 @@
+# Introduction
+
+AE is an assertions framework for Ruby. It's designed
+around the concept of an Assertor. The Assertor is an
+Assertion Functor, or Higher-Order Function, which 
+reroutes method calls while monitoring them for failing
+conditions.
+
+
+## What AE Provides
+
+Requiring the AE library.
+
+    require 'ae'
+
+Loads two classes, +Assertion+ and +Assertor+, the Kernel
+method +assert+ and it's antonyms +assert!+ and +refute+
+and a set of core extensions that make writing certain types
+of assertions easier.
+
+
+## Assertion and Assertor Classes
+
+The +Assertion+ class is at the heart of AE. All other AE
+methods depend on it. The +Assertion+ class is a subclass
+of Exception. When an assertion is made and fails, it is
+an instance of Assertion that is raised.
+
+    expect Assertion do
+      msg = "my failure message"
+      assert false, msg
+    end
+
+Like any raised exception, the last Assertion message is available
+via `$!`.
+
+(FYI, in Test::Unit the equivalent class was called +AssertionFailedError+.)
+
+Assertions themselves are not generally used in creating tests or
+behavior specifications. Rather they are used to create additional
+types of assertion methods.
+
+As mentioned above the +Assertor+ class is a type of Higher-Order
+function, or Functor, which intercedes with a normal message
+invocation to monitor for failed conditions, upon which is raises
+Assertion exceptions.
+
+
+## Assertion Methods
+
+The three methods, +assert+, <tt>assert!</tt> and +refute+ all
+return an Assertor instance when used fluidly, i.e. magic-dot
+notation, higher-order notation, functor notation, whatever you
+prefer to call it.
+
+    assert(AE::Assertor === assert)
+
+Through the use of +method_missing+, the Assertor allows us to write
+statements like:
+
+    1.assert == 1
+
+If the operation evaluates to false or nil, then an Assertion error
+is raised.
+
+    expect Assertion do
+      1.assert == 2
+    end
+
+The methods <tt>assert!</tt> and +refute+ are just like +assert+
+expect they purport the negative condition. Patterned after Ruby's
+own use of "<tt>!</tt>" as meaning +not+, <tt>assert!</tt> should be
+read "assert not". While +refute+ exists for the sake of those who
+find the use of a bang method for this purpose unsuited to them.
+
+
+## How It Works
+
+An Assertor essentially sits in wait for a method call (via
+method_missing). When that happens it applies the method to the
+original receiver, but wrapped in a clause that raises an
+Assertion should the statement fail. If we wanted to be 
+pedantic, we could write our assertions like:
+
+    raise Assertion.new("1 != 1") unless 1 == 1
+
+Instead of 
+
+    1.assert == 1
+
+Obviously using Assertor methods are whole lot more concise.
+

data/demo/02_assertion.md

@@ -0,0 +1,4 @@
+# Assertion Class
+
+The Assertion class is a subclass of Exception and is the error raised when
+and assertion fails.

data/demo/03_assert.md

@@ -0,0 +1,300 @@
+# Assert Method
+
+## Compatible with Test::Unit
+
+The `assert` method is designed to be backward compatible
+with the same method in `Test::Unit`.
+
+Using an argument, `assert` will check that an argument evaluates
+to true. Optionally one can send along a meaningful message should
+the assertion fail.
+
+    assert(true, "Not true!")
+
+    expect Assertion do
+      assert(false, "Not true!")
+    end
+
+
+## Assert with a Block
+
+In addition +assert+ has been extended to accept a block. Like the case of the
+argument, the block is expected to return something that evaluates as true.
+
+    assert do
+      true
+    end
+
+    Assertion.assert.raised? do
+      assert do
+        false
+      end
+    end
+
+We should also mention that, while probably not very useful, since
+the arity of a block can be checked, one can also pass the receiver
+into the block as a block argument.
+
+    "hi".assert do |s|
+      /h/ =~ s
+    end
+
+
+## Antonyms for Assert
+
+We can state the opposite assertion using `assert!`.
+
+    10.assert! == 9
+
+Or, because some people do not like the use of a bang method, +refute+.
+
+    10.refute == 9
+
+These terms can be used just as +assert+ is used in all examples,
+but with the opposite inference.
+
+Another way to get the opposite inference, is to use +not+.
+
+    10.assert.not == 9
+
+## Lambda Assertions
+
+Passing  +assert+ a `Proc` object, or any object that responds to `#call`,
+will be used as if it were a block. This allows for a simple way to quickly
+create reusable assertions.
+
+    palindrome = lambda{ |word| word == word.reverse }
+
+    "abracarba".assert palindrome
+
+The message for a failed assertion will come from calling `#to_s` on the
+object.
+
+## RSpec-style Assertion Matchers
+
+If an object passed to assert responds to `#matches?` then AE will handle
+the object as an RSpec-style mather, the receiver will be passed to the
+`#matches?` method to determine if the assertion passes and RSpec matcher
+message methods will be used if they are defined.
+
+    palindrome = Object.new
+
+    def palindrome.matches?(word)
+      word == word.reverse
+    end
+
+    "abracarba".assert palindrome
+
+
+## Identity Assertions
+
+Rather then the general form.
+
+    x = 10
+    x.assert.object_id == x.object_id
+
+We can use Ruby's own `equal?`> method.
+
+    x.assert.equal?(x)
+
+AE provides `identical?`> method as an alternative
+to make it a bit more clear.
+
+    x.assert.identical?(x)
+
+
+## Equality Assertions
+
+The most common assertion is that of value equality (`==`),
+as we have seen throughout this document. But other forms of
+equality can be verified as easily. We have already mentioned 
+identity. In addition there is *type equality*.
+
+    17.assert.eql? 17
+
+    Assertion.assert.raised? do
+      17.assert.eql? 17.0
+    end
+
+And there is *case equality*.
+
+    Numeric.assert === 3
+
+
+## Checking Equality with a Block
+
+Because operators can not take blocks, and at times blocks can
+be convenient means of supplying a value to an assertion,
+AE has defined alternate renditions of the equality methods.
+For equal? and eql?, the method names are the same, they simply
+can take a block in place of an argument if need be.
+
+For *value equality* (`==`), the method is called *eq?*.
+
+    10.assert.eq? do
+      10.0
+    end
+
+And should it fail,
+
+    Assertion.assert.raised? do
+      10.assert.eq? do
+        20
+      end
+    end
+
+
+## Case Equality
+
+For *case equality* (`===`), it is `case?`.
+
+    Numeric.assert.case? do
+      "3".to_i
+    end
+
+    Assertion.assert.raised? do
+      Numeric.assert.case? do
+        "3"
+      end
+    end
+
+
+## Regular Expressions
+
+Regular Expressions can be used to make assertions in much the same way as equality.
+
+    /i/.assert =~ "i"
+
+    Assertion.assert.raised? do
+      /i/.assert =~ "g"
+    end
+
+Conversely the String class recognizes the #=~ method as well.
+
+    "i".assert =~ /i/
+
+    Assertion.assert.raised? do
+      "i".assert =~ /g/
+    end
+
+
+## Exception Assertions
+
+Validating errors is easy too, as has already been shown
+in the document to verify assertion failures.
+
+    StandardError.assert.raised? do
+      unknown_method
+    end
+
+
+## Assertions on Object State
+
+While testing or specifying the internal state of an object is
+generally considered poor form, there are times when it is 
+necessary. Assert combined with +instance_eval+ makes it easy too.
+
+    class X
+      attr :a
+      def initialize(a); @a = a; end
+    end
+
+    x = X.new(1)
+
+    x.assert.instance_eval do
+      @a == 1
+    end
+
+
+## Catch/Try Assertions
+
+Catch/Try throws can be tested via `Symbol#thrown?`.
+
+    :hookme.assert.thrown? do
+      throw :hookme
+    end
+
+Alternatively, a lambda containing the potential throw
+can be the receiver using `throws?`.
+
+    hook = lambda{ throw :hookme }
+  
+    hook.assert.throws?(:hookme)
+
+
+## Assertions on Proc Changes
+
+I have to admit I'm not sure how this is useful,
+but I found it in the Bacon API and ported it over
+just for sake of thoroughness.
+
+    a = 0
+
+    l = lambda{ a }
+
+    l.assert.change?{ a +=1 }
+
+
+## Assertion on literal True, False and Nil
+
+Ruby already provides the #nil? method.
+
+    nil.assert.nil?
+
+AE adds `true?` and `false?` which acts accordingly.
+
+    true.assert.true?
+    false.assert.false?
+
+
+## Send Assertions
+
+Assert that a method can be successfully called.
+
+    "STRING".assert.send?(:upcase)
+
+
+## Numeric Delta and Epsilon
+
+You may wish to assert that a numeric value is with some
+range.
+
+    3.in_delta?(1,5)
+
+Or minimum range.
+
+    3.in_epsilon?(3,5)
+
+
+## Verifying Object State
+
+Not surprisingly if underlying object state needs to be verified, +instance_eval+
+can be used in conjunction with +assert+.
+
+    class X
+      attr :a
+      def initialize(a); @a = a; end
+    end
+
+    x = X.new(4)
+
+    x.instance_eval do
+      @a.assert == 4
+    end
+
+However #instance_eval is a reserved method for the underlying Assertor class,
+so it cannot be used on #assert, e.g.
+
+    x.assert.instance_eval do
+      @a == "obvisouly wrong"
+    end
+
+AE offers an optional helper method for times when testing underlying private
+or protected methods is important, called #pry. See the QED on pry for more
+information.
+
+For some testing underlying implementation might be considered poor
+form. You will get no argument here. It should be used thoughtfully,
+but I would not bet against there being occasions when such validations
+might be needed.
+

data/demo/04_subjunctive.md

@@ -0,0 +1,100 @@
+# Subjunctives
+
+Okay. I can hear the BDDers rumbling, "where's the *should?*"
+AE has nothing against "should", but there are different
+approaches for utilizing should nomenclature in specifications,
+and AE wants to be open to these techniques. One of which
+is how Shoulda (http://shoulda.rubyforge.org) utilizes
+`should` in a way analogous to RSpec's use of `it`.
+
+Even so, AE provides an optional mixin called `Subjunctive` which
+can be used to create assertor methods with English subjunctive
+terms, such as `should`, or `must`, `shall` and `will`.
+To load this library use:
+
+    require 'ae/subjunctive'
+
+Then all that is required it to define a subjunctive method for all
+objects. For example:
+
+    def will(*args, &block)
+      Assertor.new(self, :backtrace=>caller).be(*args,&block)
+    end
+
+It's that easy. Because of their commonality AE provides two such terms,
+`should` and +must+ as optional add-ons out-of-the-box.
+
+    require 'ae/should'
+    require 'ae/must'
+
+We will use these two methods interchangeable for the rest of this
+demonstration, but to be clear they both work exactly the same way,
+and almost exactly like `assert`.
+
+Keep in mind, AE "conical" functionality does not entail the subjunctive
+forms. These are simply options you can load via your `test_helper.rb`,
+or similar script, if you prefer these nomenclatures.
+
+
+## Fluent Notation and Antonyms
+
+Like `assert`, `should` and `must` can be used as higher order functions.
+
+    4.should == 4
+    4.must   == 4
+
+Antonyms provided for +should+ as `should!` (read "should not") and `shouldnt`.
+For `must`, they are `must!` and +wont+.
+
+    4.should!  == 5
+    4.shouldnt == 5
+
+    4.must! == 5
+    4.wont  == 5
+
+
+## To Be
+
+On occasions where the English readability of a specification is hindered,
+`be` can be used.
+
+    StandardError.must.be.raised? do
+      unknown_method
+    end
+
+The `be` method is the same as `assert` with the single exception
+that it will compare a lone argument to the receiver using `equate?`,
+unlike `assert` which simply checks to see that the argument evaluates
+as true.
+
+    10.should.be 10
+    10.should.be 10.0
+    10.should.be Numeric
+
+    Assertion.assert.raised? do
+      10.should.be "40"
+    end
+
+
+## Indefinite Articles
+
+Additional English forms are `a` and `an`, equivalent to `be` except
+that they use `case?` (same as `#===`) instead of `equate?` when
+acting on a single argument.
+
+    "hi".must.be.a String
+
+    Assertion.assert.raised? do
+      /x/.must.be.a /x/
+    end
+
+Otherwise they are interchangeable.
+
+    "hi".must.be.an.instance_of?(String)
+
+The indefinite articles work well when a noun follows as an arguments.
+
+    palindrome = lambda{ |x| x == x.reverse }
+
+    "abracarba".must.be.a palindrome
+