qed 2.9.1 → 3.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0641d46bfe700cfdd8b44f9e6e50242fa08dd47950ead38b785b1c8bd2d99008
+  data.tar.gz: 658fbcd892cbed202703946fb8745fcbd7b3a06b938bdaf62c525961418e7cc3
+SHA512:
+  metadata.gz: 9a65c7101c15ed6d98ccd4353a388497f6dacb45bb96f71bf8ed03002ce6e8f1c9acc9b5b4cbe7a5bce9b182507ac2715332ae67ce0b270271c8ddbc0bec7885
+  data.tar.gz: 6a37486a0384159148eef66931d25fba51e57ce7352d8f88b73d506f0fd7fe363da709cb247b6d3b56ad2654693d5e8b0a6d70a15384cdf08dad8a356ce176c4

data/Gemfile

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+
+gemspec

data/HISTORY.md

@@ -1,5 +1,53 @@
 # RELEASE HISTORY
 
+## 3.0.0 | 2026-03-31
+
+Major modernization release after a long hiatus.
+
+Breaking Changes:
+
+* Requires Ruby 3.1 or later (dropped Ruby 1.8/1.9/2.x support).
+* Removed Indexer gemspec system; uses standard gemspec.
+* Removed Detroit Assembly; uses standard Rakefile.
+
+New Features:
+
+* Fenced code block support in parser (#23).
+  Bare and ```ruby blocks are executed; other languages are skipped.
+* Restored and modernized HTML reporter with --html flag (#13).
+* GitHub Actions CI replacing Travis CI.
+* Website moved from gh-pages branch to docs/ directory.
+
+Bug Fixes:
+
+* Fix --version crash due to VERSION not being loaded (#26).
+* Fix --help crash from undefined `settings` in cli_parse (#22, #26).
+* Fix --copyright showing wrong license (Apache 2.0 -> BSD-2-Clause) (#26).
+* Fix --rooted flag not actually running from project root (#21).
+* Fix TapY reporter crash referencing `assertion` instead of `exception` (#24).
+
+Dependencies:
+
+* Switch markdown processing from rdiscount to kramdown (#20).
+* Remove instance_exec polyfill for Ruby 1.8.
+* Remove old RubyGems compatibility checks from gemspec.
+* Drop rulebow, RC, and Facets dependencies.
+* Require ansi ~> 1.6, brass ~> 1.3, ae ~> 1.9 (dev).
+
+
+## 2.9.2 | 2014-02-24
+
+This release removes the dependency on Facets. There were only two important
+facets being used, String#tabto and String#indent. These have been copied over
+so the dependency is no longer required. Minimaizing dependencies is especailly
+important for a testing tool as it helps maximize robustness.
+
+Changes:
+
+* Remove dependency on Facets.
+* After and Before types are :demo/:all or :test/:each.
+
+
 ## 2.9.1 | 2013-02-20
 
 The RC gem is optional now and old school `etc/qed.rb`, `config/qed.rb` and

data/README.md

@@ -1,12 +1,9 @@
 # Ruby Q.E.D.
 
-[Homepage](http://rubyworks.github.com/qed) /
-[Documentation](http://rubydoc.info/gems/qed/frames) /
-[Report Issue](http://github.com/rubyworks/qed/issues) /
-[Development](http://github.com/rubyworks/qed) /
-[Mailing list](http://groups.google.com/group/rubyworks-mailinglist)    
-[![Build Status](https://secure.travis-ci.org/rubyworks/qed.png)](http://travis-ci.org/rubyworks/qed)
-[![Gem Version](https://badge.fury.io/rb/qed.png)](http://badge.fury.io/rb/qed)
+[Homepage](https://rubyworks.github.io/qed) /
+[Documentation](https://rubydoc.info/gems/qed/frames) /
+[Report Issue](https://github.com/rubyworks/qed/issues) /
+[Development](https://github.com/rubyworks/qed)
 
 
 ## Introduction
@@ -15,12 +12,12 @@ Q.E.D. is an abbreviation for the well known Latin phrase "Quod Erat Demonstrand
 literally "which was to be demonstrated", which is oft written in its abbreviated
 form at the end of a mathematical proof or philosophical argument to signify
 a successful conclusion. And so it is too for Ruby Q.E.D., though it might as easily
-be taken to stand for "Quality Ensured Documentation". 
+be taken to stand for "Quality Ensured Documentation".
 
 QED is in fact both a test framework and a documentation system for Ruby
 developers. QED sits somewhere between lower-level testing tools like Test::Unit
 and grandiose requirement specifications systems like Cucumber. In practice it
-works exceptionally well for <i>API-Driven Design</i>, which is especially
+works exceptionally well for *API-Driven Design*, which is especially
 useful when designing reusable libraries, but it can be used to test code at
 any level of abstraction, from unit test to systems tests.
 
@@ -28,10 +25,12 @@ any level of abstraction, from unit test to systems tests.
 ## Features
 
 * Write tests and documentation in the same breath!
-* Demos can be RDoc, Markdown or any other conforming text format.
-* Can use any BRASS compliant assertion framework, such as the the excellent AE (Assertive Expressive) library.
-* Data and Table macros allows large sets of data to be tested by the same code.
-* Documentation tool provides nice output with jQuery-based TOC.
+* Demos can be Markdown or RDoc format.
+* Supports fenced code blocks — non-Ruby blocks (e.g. ` ```elixir `) are automatically skipped.
+* Can use any BRASS compliant assertion framework, such as the excellent AE (Assertive Expressive) library.
+* Data and Table macros allow large sets of data to be tested by the same code.
+* HTML report generation via `--html` flag.
+* Documentation tool (`qedoc`) generates browsable HTML from demos.
 
 
 ## Synopsis
@@ -40,7 +39,7 @@ any level of abstraction, from unit test to systems tests.
 
 QED can use any BRASS compliant assertions framework. Simply require the library in
 ones applique (see below). Traditionally this has been the AE (Assertive Expressive) library,
-which provides an elegant means to make assertions. To give a quick overview, assertion
+which provides an elegant means to make assertions. To give a quick overview, assertions
 can be written as:
 
     4.assert == 5
@@ -49,16 +48,16 @@ In this example, because 4 != 5, this expression will raise an Assertion
 exception. QED's Runner class is thus just a means of running and capturing
 code blocks containing such assertions.
 
-You can learn more about BRASS and AE at http://rubyworks.github.com/brass and
-http://rubyworks.github.com/ae, repectively.
+You can learn more about BRASS and AE at https://github.com/rubyworks/brass and
+https://github.com/rubyworks/ae, respectively.
 
 ### Document Structure
 
 QED documents are simply text files called *demonstrandum* (demos for short).
 Because they largely consist of free-form descriptive text, they are a practice
-pure Literate Programming. For example:
+of pure Literate Programming. For example:
 
-    = Example
+    # Example
 
     Shows that the number 5 does not equal 4.
 
@@ -68,18 +67,24 @@ pure Literate Programming. For example:
 
         5.assert == 5
 
-In this example RDoc was chosen for the document format. However, almost any
-text format can be used. The only necessary distinction is that description text
-align to the left margin and all code be indented, although QED does recognize
-RDoc and Markdown single-line style headers, so any format that supports
-those (which covers many markup formats in use today) will have mildly
-improved console output. In any case, the essential take away here is that
-QED *demonstrandum* are simply descriptive documents with interspersed 
-blocks of example code.
+Description text aligns to the left margin and all code is indented. QED also
+supports fenced code blocks:
 
-Give this design some thought. It should become clear that this approach is
-especially fruitful in that it allows *documentation* and *specification*
-to seamlessly merge into a unified *demonstration*. 
+    ```ruby
+    5.assert == 5
+    ```
+
+Blocks tagged with a non-Ruby language are skipped during execution, which is
+useful for multi-language documentation:
+
+    ```javascript
+    // This is not executed
+    console.log("hello");
+    ```
+
+QED recognizes Markdown and RDoc headers for improved console output. The
+essential take away is that QED *demonstrandum* are simply descriptive
+documents with interspersed blocks of example code.
 
 ### Running Demonstrations
 
@@ -87,22 +92,22 @@ If we were to run the above document through QED in verbatim mode the output
 would be identical (assuming we did not make a typo and the assertions passed).
 If there were errors or failures, we would see information detailing each.
 
-To run a document through QED, simply use the +qed+ command.
+To run a document through QED, simply use the `qed` command.
 
-  $ qed -v demo/01_example.rdoc
+    $ qed -v demo/01_example.md
 
-The `-v` option specifies verbatim mode, which outputs the entire
-document.
+The `-v` option specifies verbatim mode, which outputs the entire document.
 
 Notice we placed the QED document in a `demo/` directory. This is the
-canonical location, but there is no place that demonstrations have to go. They
-can be placed anywhere that is preferred. However, the `qed` command
-will look for `qed/`, `demo/`, `demos/` and `spec/`, in that order, if no
-path is given.
+canonical location, but demonstrations can be placed anywhere. The `qed`
+command will look for `qed/`, `demo/`, `demos/` and `spec/`, in that order,
+if no path is given.
+
+The `01_` prefix helps order documents when generating QED documentation.
+
+To generate an HTML test report:
 
-Also notice the use of ``01_`` prefix in front of the file name.
-While this is not strictly necessary, QED sorts the documents, so it helps order
-the documents nicely, in particular when generating QED documentation ("QEDocs").
+    $ qed --html > report.html
 
 ### Utilizing Applique
 
@@ -110,9 +115,9 @@ QED demonstrandum descriptive text is not strictly passive explanation. Using
 pattern matching techniques, document phrases can trigger underlying actions.
 These actions provide a support structure for running tests called the *applique*.
 
-Creating an applique is easy. Along with your QED scripts, to which the 
+Creating an applique is easy. Along with your QED scripts, to which the
 applique will apply, create an `applique/` directory. In this
-directory add Ruby scripts. When you run your demos every Ruby script in 
+directory add Ruby scripts. When you run your demos every Ruby script in
 the directory will be automatically loaded.
 
 Within these applique scripts *advice* can be defined. Advice can be
@@ -126,11 +131,11 @@ phrases in the QED demos. An example would be:
     end
 
 So that whenever the phrase "a new round is started" appears in a demo,
-the @round instance variable with be reset to an empty array.
+the @round instance variable will be reset to an empty array.
 
-It is rather amazing what can be accomplished with such a system,
-be sure to look at QED's own demonstrandum to get a better notion of
-how you can put the the system to use.
+It is rather amazing what can be accomplished with such a system.
+Be sure to look at QED's own demonstrandum to get a better notion of
+how you can put the system to use.
 
 ### Configuration
 
@@ -154,63 +159,53 @@ Or by setting the `profile` environment variable.
 
     $ profile=coverage qed
 
-QED can also use the [RC](http://rubyworks.github.com/rc) gem to handle
-configuration. Be sure to `gem install rc` and then add this to `.rubyrc`
-or `Config.rb` file of the same effect as given above.
-
-    config :qed, :profile=>:coverage do
-      require 'simplecov'
-      SimpleCov.start do
-        coverage_dir 'log/coverage'
-      end
-    end
-
 ### Generating Documentation
 
-To generate documentation from QED documents, use the +qedoc+ command.
+To generate documentation from QED documents, use the `qedoc` command.
 
-    $ qedoc --output doc/qedoc --title "Example" demo/*.rdoc
+    $ qedoc --output doc/demo.html --title "Example" demo/
 
-When documenting, QED recognizes the format by the file extension and 
-treats it accordingly. An extension of `.qed` is treated the same
-as `.rdoc`.
+When documenting, QED recognizes the format by the file extension and
+treats it accordingly.
 
-Use the `--help` options on each command to get more information
+Use the `--help` option on each command to get more information
 on the use of these commands.
 
 
 ## Requirements
 
-QED depends on the following external libraries:
+QED depends on the following libraries:
+
+* [BRASS](https://github.com/rubyworks/brass) - Assertions System
+* [ANSI](https://github.com/rubyworks/ansi) - ANSI Color Codes
+* [kramdown](https://kramdown.gettalong.org/) - Markdown Processing
 
-* [BRASS](http://rubyworks.github.com/brass) - Assertions System
-* [ANSI](http://rubyworks.github.com/ansi) - ANSI Color Codes
-* [RC](http://rubyworks.github.com/rc) - Runtime Configuration
-* [Facets](http://rubyworks.github.com/facets) - Core Extensions
+These will be automatically installed when installing QED via RubyGems.
 
-These will be automatically installed when installing QED via RubyGems,
-if they are not already installed.
+Optional libraries that are generally useful with QED:
 
-Optional libraries that are generally useful with QED.
+* [AE](https://github.com/rubyworks/ae) - Assertions Framework
 
-* [AE](http://rubyworks.github.com/ae) - Assertions Framework
+Install AE and require it in your applique to use.
 
-Install these individually and require them in your applique to use.
+Requires Ruby 3.1 or later.
 
 
 ## Development
 
 ### Testing
 
-QED uses itself for testing, which can be a bit tricky. But works fine for
-the most part. In the future we may add some addition tests via another
-test framework to ensure full coverage. But for now QED is proving sufficient.
+QED uses itself for testing. To run the tests:
 
-To run the tests, use `qed` command line tool --ideally use `$ ruby -Ilib bin/qed`
-to ensure the current version of QED is being used.
+    $ rake demo
 
-For convenience, use `$ fire spec` to run the test specifications. To also 
-generate a test coverage report use `$ fire spec:cov`.
+Or directly:
+
+    $ ruby -Ilib bin/qed
+
+To generate a test coverage report:
+
+    $ rake demo:cov
 
 
 ## Copyrights
@@ -220,4 +215,3 @@ generate a test coverage report use `$ fire spec:cov`.
 Copyright (c) 2009 Rubyworks. All rights reserved.
 
 See LICENSE.txt for details.
-

data/demo/13_fenced_code_blocks.md

@@ -0,0 +1,60 @@
+# Fenced Code Blocks
+
+QED supports fenced code blocks using triple backticks in addition
+to the traditional indented code blocks.
+
+## Bare fenced blocks
+
+A bare fenced block (no language tag) is treated as Ruby.
+
+```
+x = 1 + 1
+x.assert == 2
+```
+
+## Ruby-tagged fenced blocks
+
+A block explicitly tagged as `ruby` is also executed.
+
+```ruby
+y = "hello"
+y.assert == "hello"
+```
+
+## Foreign language blocks are skipped
+
+Code blocks tagged with any language other than Ruby are ignored.
+This is useful for documentation that includes examples in other
+languages.
+
+```elixir
+# This Elixir code is NOT executed.
+# If it were, QED would raise an error.
+IO.puts "hello from elixir"
+```
+
+```javascript
+// This JavaScript is also skipped.
+console.log("hello from js");
+```
+
+We can verify that Ruby execution continues normally after
+skipping foreign blocks.
+
+    z = 42
+    z.assert == 42
+
+## Mixed usage
+
+Traditional indented blocks and fenced blocks can be used
+together in the same document.
+
+    a = 10
+
+```ruby
+b = 20
+```
+
+And the results carry across.
+
+    (a + b).assert == 30

data/lib/qed/applique.rb

@@ -98,10 +98,13 @@ module QED
     # Before advice.
     #
     # @param [Symbol] type
-    #   Event signal (`:eval`).
+    #   Event signal (`:demo`).
     #
     # @yield Procedure to run on event.
-    def Before(type=:eval, &procedure)
+    def Before(type=:demo, &procedure)
+      type = type.to_sym
+      type = :demo if type == :all
+      type = :test if type == :each
       type = "before_#{type}".to_sym
       @__signals__[type] = procedure
       #define_method(type, &procedure)
@@ -110,10 +113,13 @@ module QED
     # After advice.
     #
     # @param [Symbol] type
-    #   Event signal (`:eval`).
+    #   Event signal (`:demo`).
     #
     # @yield Procedure to run on event.
-    def After(type=:eval, &procedure)
+    def After(type=:demo, &procedure)
+      type = type.to_sym
+      type = :demo if type == :all
+      type = :test if type == :each
       type = "after_#{type}".to_sym
       @__signals__[type] = procedure
       #define_method(type, &procedure)

data/lib/qed/cli/qed.rb

@@ -10,9 +10,9 @@ module QED
     #
     # Session settings are passed to `Session.new`.
     #
-    #def self.settings
-    #  @settings ||= Settings.new
-    #end
+    def self.settings
+      @settings ||= Settings.new
+    end
 
     #
     # Command line interface for running demos.
@@ -56,8 +56,8 @@ module QED
 
       options = cli_parse(argv)
 
-      settings = Settings.new(options)
-      session  = Session.new(settings)
+      @settings = Settings.new(options)
+      session  = Session.new(@settings)
       success  = session.run
 
       exit -1 unless success
@@ -86,9 +86,9 @@ module QED
         #opt.on('--bullet', '-b', "use bullet-point reporter") do
         #  options[:format] = :bullet
         #end
-        #opt.on('--html', '-h', "use underlying HTML reporter") do
-        #  options[:format] = :html
-        #end
+        opt.on('--html', "generate HTML report") do
+          options[:format] = :html
+        end
         #opt.on('--script', "psuedo-reporter") do
         #  options[:format] = :script  # psuedo-reporter
         #end
@@ -134,7 +134,7 @@ module QED
           exit
         end
         opt.on_tail('--copyright', "display copyrights") do
-          puts "Copyright (c) 2008 Thomas Sawyer, Apache 2.0 License"
+          puts "Copyright (c) 2008 Thomas Sawyer, BSD-2-Clause License"
           exit
         end
         opt.on_tail('--help', '-h', "display this help message") do
@@ -142,8 +142,7 @@ module QED
 
           unless settings.profiles.empty?
             puts "Available Profiles:"
-            #require 'confection'
-            QED.profiles.each do |name|
+            settings.profiles.each do |name|
               next if name.strip == ''
               puts "    -p #{name}"
             end

data/lib/qed/cli.rb

@@ -1,10 +1,5 @@
-if RUBY_VERSION < '1.9'
-  require 'qed/configure'
-  require 'qed/cli/qed'
-  require 'qed/cli/qedoc'
-else
-  require_relative 'configure'
-  require_relative 'cli/qed'
-  require_relative 'cli/qedoc'
-end
+require_relative 'version'
+require_relative 'configure'
+require_relative 'cli/qed'
+require_relative 'cli/qedoc'
 

data/lib/qed/core_ext.rb

@@ -1,47 +1,49 @@
 require 'brass'
 
-require 'facets/dir/ascend'
-
 class Object
 
-  unless method_defined?(:instance_exec) # 1.9
-    require 'thread'
+  #
+  # This is used by the `#=>` notation.
+  #
+  def must_return(value)
+    assert(self == value, "#{self.inspect} #=> #{value.inspect}")
+  end
 
-    module InstanceExecMethods #:nodoc:
-    end
+end
 
-    include InstanceExecMethods
-
-    # Evaluate the block with the given arguments within the context of
-    # this object, so self is set to the method receiver.
-    #
-    # From Mauricio's http://eigenclass.org/hiki/bounded+space+instance_exec
-    #
-    # This version has been borrowed from Rails for compatibility sake.
-    def instance_exec(*args, &block)
-      begin
-        old_critical, Thread.critical = Thread.critical, true
-        n = 0
-        n += 1 while respond_to?(method_name = "__instance_exec#{n}")
-        InstanceExecMethods.module_eval { define_method(method_name, &block) }
-      ensure
-        Thread.critical = old_critical
-      end
+class String
 
-      begin
-        send(method_name, *args)
-      ensure
-        InstanceExecMethods.module_eval { remove_method(method_name) } rescue nil
+  # from facets
+  def tabto(num=nil, opts={})
+    raise ArgumentError, "String#margin has been renamed to #trim." unless num
+
+    tab = opts[:tab] || 2
+    str = gsub("\t", " " * tab)  # TODO: only leading tabs ?
+
+    if opts[:lead]
+      if self =~ /^( *)\S/
+        indent(num - $1.length)
+      else
+        self
+      end
+    else
+      min = []
+      str.each_line do |line|
+        next if line.strip.empty?
+        min << line.index(/\S/)
       end
+      min = min.min
+      str.indent(num - min)
     end
   end
 
-  #
-  # This is used by the `#=>` notation.
-  #
-  def must_return(value)
-    assert(self == value, "#{self.inspect} #=> #{value.inspect}")
+  # from facets
+  def indent(n, c=' ')
+    if n >= 0
+      gsub(/^/, c * n)
+    else
+      gsub(/^#{Regexp.escape(c)}{0,#{-n}}/, "")
+    end
   end
 
 end
-

data/lib/qed/demo.rb

@@ -1,6 +1,7 @@
 module QED
 
   require 'yaml'
+  require 'pathname'
 
   require 'qed/core_ext'
   require 'qed/parser'
@@ -78,7 +79,8 @@ module QED
     def applique_locations
       @applique_locations ||= (
         locations = []
-        Dir.ascend(File.dirname(file)) do |path|
+        dirpath = Pathname.new(File.dirname(file))
+        dirpath.ascend do |path|
           break if path == Dir.pwd
           dir = File.join(path, 'applique')
           if File.directory?(dir)

data/lib/qed/document.rb

@@ -147,10 +147,9 @@ module QED
             text << txt
           end        
         when '.md', '.markdown'
-          require_rdiscount
+          require_kramdown
           if html?
-            markdown = RDiscount.new(txt)
-            text << markdown.to_html
+            text << Kramdown::Document.new(txt).to_html
           else
             text << txt
           end
@@ -251,9 +250,9 @@ module QED
     end
 
     #
-    def require_rdiscount
-      @require_rdiscount ||= (
-        require 'rdiscount'
+    def require_kramdown
+      @require_kramdown ||= (
+        require 'kramdown'
         true
       )
     end

data/lib/qed/evaluator.rb

@@ -159,7 +159,7 @@ module QED
     # Exceptions to always raise regardless.
     FORCED_EXCEPTIONS = [NoMemoryError, SignalException, Interrupt] #, SystemExit]
 
-    # Evaluate the step's matchaters and code sample, wrapped in a begin-rescue
+    # Evaluate the step's matchers and code sample, wrapped in a begin-rescue
     # clause.
     #
     # @macro step