qed 2.5.1 → 2.6.0

data/HISTORY.rdoc

@@ -0,0 +1,259 @@
+= RELEASE HISTORY
+
+== 2.6.0 / 2011-07-01
+
+Thie release fixes some issues with reporters, further refines
+their output and adds the start of a new reporter called dtrace.
+Also the Table and Data macros have been updated. Table can now
+handle a YAML stream with the :stream option, and Data no long runs
+the text through YAML.load whe the file name ends in .yml or .yaml,
+In other words it's for raw fixture data. Finally the documentation
+tool has been improved ot simplify HTML generation and also add a
+format option for creating a simple plain text merging instead.
+
+Changes:
+
+* Data is raw and no longer uses YAML.load.
+* Table can handle a YAML stream, via :stream option.
+* Better handling of code snippets.
+* Backtrace count defaults to 2 rather than 3.
+* Load ansi/core, rather than ansi/code.
+* Doc output setting takes a file name instead of directory.
+* Support for plain text format (by simple file merge).
+* HTML output is single file, jquery comes from CDNJ.
+
+
+== 2.5.2 / 2011-06-26
+
+This release focuses on reporter improvements. Better trace
+information is now displayed, and the max nmber of backtrace
+lines can be set with the -t option, or $trace environment
+variable.
+
+Changes:
+
+* Trace option takes a max count setting (0 for all).
+* Trace count can also be set via $trace environment variable.
+* Added TAP-Y reporter.
+
+
+== 2.5.1 / 2011-06-07
+
+This release makes a number adjustments and fixes one majort issue
+with the way the latest AE library counts assertions.
+
+Changes:
+
+* Fix references to AE assertion counts.
+* @_ stores the return value of last execution block.
+* Backtrace filter omits references to AE library.
+
+
+== 2.5.0 / 2010-11-04
+
+The latest release of QED improves on applique loading, such that each
+demonstrandum gets it's own localized set. The CLI has also been modified
+so that there is no longer a defualt location, the directory or files to run
+must be specified.
+
+Changes:
+
+* Better handling of Applique.
+* Remove Advice class --advice is now stored in Applique.
+* Each applique file is it's own module.
+* Advice from each applique is applied.
+* CLI requires files be specified.
+
+
+== 2.4.0 / 2010-09-02
+
+All engines go! QED has not been tested against 1.8.6, 1.8.7 and 1.9.2.
+Underthehood steps are not organized in doubely-linked lists, which makes
+them much more robust and flexible. This release also improves scoping,
+test counts, and inline documentation parsing.
+
+Changes:
+
+* Use new doubly-linked list step design.
+* Fix -r option on command line.
+* Provide #instance_exec core extension for Ruby 1.8.6.
+* Scope is extended by and includes applique.
+
+
+== 2.3.0 / 2010-07-14
+
+Bug to the scurry! QED has broken through the code/document ceiling and
+is cracking ectoskeletons all the way to the bank. A proverbal can of
+Roach-Be-Gone this is! What's that you say? I will exlpain. QED can now
+run directly against code comments. Simply slip the qed command the -c
+option and feed it some ruby scripts, and presto watch you commnets
+fail ;) I think you can figure out what to do next.
+
+In addition to this coolness QED has been improved under the floor
+boards as well. The parser, which is much faster, now blocks commentary
+paragraphs and code examples togeher in one-to-one pairings. Not only
+does this clean-up the code, but it opens up the potential for Around
+advice in a future version.
+
+Changes:
+
+* NEW! Ruby script comment run mode.
+* Better parsing system uses commentary-example pairs.
+* Colon can also be used to specify plain text (along with ellipsis).
+* Now distributed under the more permissive Apache 2.0 license.
+
+
+== 2.2.2 / 2010-06-21
+
+An issue was reported in which the a code block at the very
+top of a demo was being ignored. This release fixes this issue
+by rewriting the parser (much better now thanks!). At the same
+time the Data and Table methods have been polished, both of
+which can now pick up sample data relative to the current demo.
+
+Changes:
+
+* Rewrite parser and fix top code issue.
+* Data method cannot write data, instead executes block.
+* Data and Table methods look for file relative to demo first.
+* Added -R option to run demos relative to project root.
+
+
+== 2.2.1 / 2010-06-20
+
+Remove dependencies to Tilt and Nokogiri. Should have
+done this in last release but alas --there is so
+much to do.
+
+Changes:
+
+* Removed HTML parsing dependencies.
+* Reduce Advice to a single class.
+
+
+== 2.2.0 / 2010-06-19
+
+This release returns to a text-based evaluator, rather
+then use HTML. Processing HTML proved to have too many
+edge cases to be effective --both in implementation
+and in end-usage. So to remedy the situation QED has
+return to supportting simple markup formats such as
+RDoc and Markup.
+
+This release also adds multi-pattern advice. Instead of
+a single pattern, multiple patterns can be matched
+sequentially. This make it a easier to match large text
+descriptions without restoring to regular expressions.
+
+In addition QED now supports raw text blocks. By ending
+a description section in ellipsis (...), the subsequent
+code setion becomes a plain text section and is passed
+into the argument list of any matching When advice. This
+makes it easy to scaffold fixture files, for example.
+
+Finally, this release also refines the evaluation scopes.
+Where before, a new binding was being created, each was 
+attached to the TOPLEVEL, and therefore not truly isolated 
+on a per-dcoument basis. To correct, QED now mocks the
+TOPLEVEL providing a new instance of this mock object for
+each document.
+
+Changes:
+
+* No longer uses HTML for document processing.
+* Support for plain text blocks using ellipsis.
+* New sequential multi-pattern matches.
+* Mock TOPLEVEL at both the demo and applique levels.
+* Adjust color support for latest ANSI release.
+
+
+== 2.1.1 / 2010-04-08
+
+Fixed bug introduced in the last version that executed all
+scripts in a single binding. There needed to be a binding
+for each script.
+
+Changes:
+
+* Fixed cross-script bug by moving binding instantiation into Script class.
+
+
+== 2.1.0 / 2010-04-07
+
+QED documents are now run in the TOPLEVEL context, rather
+than in a subclass of Scope. This ensures code runs as
+one would expect it too in the wild.
+
+Changes:
+
+* Scope.new redirect to TOPLEVEL.
+* DomainLanguage module is added to include into TOPLEVEL.
+
+
+== 2.0.0 / 2010-03-04
+
+This is a major new release of QED. All demonstration documents
+are now converted to HTML via Tilt (http://github.com/tilt) before
+being run through the test runner. So QED now supports any markup
+format supported by Tilt, as well as ordinary HTML. Simply
+stated, QED process <tt>pre</tt> tags as code and everything else
+as comments. Nokogiri is used to parse the HTML.
+
+Changes:
+
+* HTML serves as a common format.
+* New dependencies: Tilt and Nokogiri.
+* New system of version numbers.
+
+
+== 1.2.0 / 2009-12-07
+
+This release adds a significant new feature, Comment Matchers.
+These work like Cucumber allowing for background code to
+be run when matching comments occur --a much better solution
+for setup and teardown.
+
+Changes:
+
+* 2 Major Enhancements
+
+  * Added command matchers via #When method.
+  * All QED methods are now capitalized.
+
+* 2 Minor Enhancements
+
+  * Use OptionParser for qed exectuable.
+  * Verbatim reporter is literally verbatim.
+
+
+== 1.1.1 / 2009-09-05
+
+This release 
+
+Changes:
+
+* 2 Major Enhancements
+
+  * Helpers are provided by bottom code.
+  * Added Markdown header support.
+
+* 2 Minor Enhancements
+
+  * Use Ansi project for color output.
+  * Use latest RDoc version.
+
+
+== 1.0.0 / 2009-06-30
+
+QED has found itself. It took some time to really figure out
+what this project "was" and how it should best be utilized.
+This release is the initial release that puts QED in proper
+perpective.
+
+Changes:
+
+* 2 Major Enhancement
+
+    * Partial rewrite of a project that was once called "Quarry".
+    * Now uese AE for assertions.
+

data/LICENSE.rdoc

@@ -0,0 +1,35 @@
+= COPYRIGHT NOTICES
+
+== YES
+
+Copyright:: (c) 2011 Rubyworks, Thomas Sawyer
+License:: BSD-2-Clause
+Website:: http://rubyworks.github.com/yes
+
+    Copyright 2011 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:
+
+    * Redistributions of source code must retain the above copyright notice,
+      this list of conditions and the following disclaimer.
+
+    * 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 BY Thomas Sawyer ``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 Thomas Sawyer 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.
+
+    The views and conclusions contained in the software and documentation are
+    those of the authors and should not be interpreted as representing official
+    policies, either expressed or implied, of Thomas Sawyer.
+

data/README.rdoc

@@ -5,32 +5,32 @@
 
 Q.E.D. is an abbreviation for the well known Latin phrase "Quod Erat Demonstrandum",
 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 the
+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". 
 
 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 grand requirement specifications tools like Cucumber. In practice it works
-exceptionally well for <i>API-Driven Design</i>, which is especially useful when
-designing reusable libraries, but it can be used to test code at any level
-of abstract, from unit test to systems tests.
+and grandiose requirement specifications systems like Cucumber. In practice it
+works exceptionally well for <i>API-Driven Design</i>, 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.
 
 
 == Features
 
 * Write tests and documentation in the same breath!
 * Demos can be RDoc, Markdown or any other conforming text format.
-* Uses the excellent Assertive Expressive library for assertions.
-* Table macro allows large sets of data to be run by the same code.
+* Uses the excellent AE (Assertive Expressive) library for assertions.
+* Table macro allows large sets of data to be tested by the same code.
 * Documentation tool provides nice output with jQuery-based TOC.
 
 
 == Resources
 
-* homepage: http://rubyworks.github.com/qed
-* mailing list: http://groups.google.com/group/rubyworks
-* development: http://github.com/rubyworks/qed
+* {Homepage}[http://rubyworks.github.com/qed]
+* {Mailing list}[http://groups.google.com/group/rubyworks-mailinglist]
+* {Development}[http://github.com/rubyworks/qed]
 
 
 == Synopsis
@@ -90,15 +90,16 @@ To run a document through QED, simply use the +qed+ command.
 The <code>-v</code> option specifies verbatim mode, which outputs the entire
 document.
 
-Notice we placed the QED document in the <code>demo/</code> or <code>demos/</code>
-directory, this is the conical place that has been designated for them, though you
-can of course put them elsewhere in your project if you prefer. Also notice the
-<code>01_</code> prefix in front of the name. While this is not strictly necessary,
-it helps order the documents properly when generating QED documentation (QEDocs).
+Notice we placed the QED document in a <code>demo/</code> directory, this is no
+standard place that demonstrations have to go. They can be placed anywhere
+in a project that is preferred (lately I've been use qed/). Also notice the
+`<code>01_</code>` prefix in front of the name. While this is not strictly
+necessary, it helps order the documents nicely in particular when generating
+QED documentation ("QEDocs").
 
-=== Utilizeing Applique
+=== Utilizing Applique
 
-QED demonstrandum descriptive text is not stricty passive explination. Using
+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*.
 
@@ -156,15 +157,6 @@ Q.E.D.
 
 Copyright (c) 2007 Thomas Sawyer
 
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-   http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
+BSD 2-Clause License
 
+See LICENSE.rdoc for details.

data/bin/qedoc

@@ -1,3 +1,3 @@
 #!/usr/bin/env ruby
-require 'qedoc/command'
-QEDoc::Command.run
+require 'qed/cli/qedoc'
+QED::Document.cli(*ARGV)

data/lib/{qedoc/command.rb → qed/cli/qedoc.rb}

@@ -1,29 +1,16 @@
-#!/usr/bin/env ruby
-
-module QEDoc
+module QED
 
   require 'optparse'
-  require 'qedoc/document'
-
-  class Command
+  require 'qed/document'
 
-    #
-    def self.run
-      new.run
-    end
+  class Document
 
-    #
-    attr :options
+    # Command line interface for generating qedocs.
+    def self.cli(*argv)
 
-    #
-    def initialize
-      @options = {}
-    end
-
-    #
-    def parser
-      OptionParser.new do |usage|
+      options = {}
 
+      parser = OptionParser.new do |usage|
         usage.banner = "Usage: qedoc [OPTIONS] <QEDFile1> [ <QEDFile2> ... ]"
 
         usage.on("-o", "--output [DIR]", "Output directory") do |dir|
@@ -50,15 +37,11 @@ module QEDoc
           puts usage
           exit
         end
-
       end
-    end
 
-    #
-    def run
-      parser.parse!
+      parser.parse!(argv)
 
-      options[:paths] = ARGV.dup
+      options[:paths] = argv.dup
 
       #opts[:output] = cli.options[:file]
       #opts[:dryrun] = cli.options[:dryrun]

data/lib/qed/demo.rb

@@ -85,11 +85,23 @@ module QED
       )
     end
 
-    # Parse demonstration script.
+    # Demo steps, cached from parsing.
     #
-    # Returns an abstract syntax tree.
-    def parse
-      Parser.new(file, :mode=>mode).parse
+    # @return [Array] parsed steps
+    def steps
+      @steps ||= parser.parse
+    end
+
+    # Parse and cache demonstration script.
+    #
+    # @return [Array] abstract syntax tree
+    alias_method :parse, :steps
+
+    # Get a new Parser instance for this demo.
+    #
+    # @return [Parser] parser for this demo
+    def parser
+      Parser.new(file, :mode=>mode)
     end
 
     #