qed 1.1.0 → 1.2

data/HISTORY

@@ -1,6 +1,43 @@
 = RELEASE HISTORY
 
-== 1.0.0 / 2009-06-18
+== 1.2 / 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 / 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 / 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.
@@ -9,7 +46,8 @@ perpective.
 
 Changes:
 
-* 1 Major Enhancement
+* 2 Major Enhancement
 
     * Partial rewrite of a project that was once called "Quarry".
+    * Now uese AE for assertions.
 

data/MANIFEST

@@ -1,23 +1,18 @@
 #!mast bin demo doc/qedoc lib meta [A-Z]*
-bin
 bin/qed
 bin/qedoc
-demo
 demo/01_spec.qed
-demo/01_spec.yaml
-demo/qed_helper.rb
-doc/qedoc
+demo/data.txt
+demo/helper.rb
+demo/table.yml
 doc/qedoc/index.html
 doc/qedoc/jquery.js
-lib
-lib/qed
-lib/qed/document
+lib/qed/command.rb
 lib/qed/document/jquery.js
 lib/qed/document/markup.rb
 lib/qed/document/template.rhtml
 lib/qed/document.rb
 lib/qed/extract.rb
-lib/qed/reporter
 lib/qed/reporter/base.rb
 lib/qed/reporter/dotprogress.rb
 lib/qed/reporter/summary.rb
@@ -25,15 +20,15 @@ lib/qed/reporter/verbatim.rb
 lib/qed/runner.rb
 lib/qed/script.rb
 lib/qed.rb
-meta
 meta/authors
 meta/created
 meta/description
 meta/homepage
-meta/package
-meta/project
+meta/name
+meta/repository
 meta/requires
 meta/ruby
+meta/suite
 meta/summary
 meta/title
 meta/version

data/README.rdoc

@@ -7,18 +7,25 @@
 
 == Introduction
 
-Q.E.D. stands for Quality Enhanced Demos. QED is an easy to use
-quality assurance and documentation system for Ruby Developers.
-QED sits between lower-level testing tools like Test Unit and 
-grand requirements specifications tools like Cucumber. It is
-designed to address <i>API-Driven Devleopment</i>, which
-is especailly useful when designing reusble libraries.
+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
+successful completion of a proof.
+
+And so it for Ruby Q.E.D., which might also be taken to stand for
+Quality Ensured Documentation. 
+
+Q.E.D. is in fact both a test framwork and a documentation system for Ruby
+developers. QED sits somehwere between lower-level testing tools like Test::Unit
+and grand requirement specifications tools like Cucumber. In pratice it works
+best addressing <i>API-Driven Development</i>, which is especially useful when
+designing reusable libraries.
 
 
 == Features
 
 * Demos can be RDoc, Markdown or any other conforming text format. 
-* Uses excellent Assertive Expressive library for assertion system.
+* Uses the excellent Assertive Expressive library for assertion system.
 * Helpers are easily loaded relative to running document.
 * Table macro allows large sets of data to be run by the same code.
 * Documentation tool provides nice output with jQuery-based TOC.
@@ -28,8 +35,8 @@ is especailly useful when designing reusble libraries.
 
 === Assertion Syntax
 
-QED uses AE (Assertive Expressions) libary to provide an elegant means of
-express behaviors. To give a quck overview, you can use code such as:
+QED uses AE (Assertive Expressive) library to provide an elegant means to
+express behaviors. To give a quick overview, you can use code such as:
 
     4.assert == 5
 
@@ -55,22 +62,22 @@ For example:
         5.assert == 5
 
 As you can see, we used RDoc for this document. Almost any text format
-can be used. The only neccesary distinction is that desciption text be
+can be used. The only necessary distinction is that description text
 align to the left margin and all code be indented. However QED recognizes
-RDoc and Markdown style headers, so any format that supports this style
-(which covers many markup formats in use today) will work a bit better.
-While strictly speaking QED does not need to recognize headers, it does
-improve console output.
+RDoc and Markdown single-line style headers, so any format that supports
+this style (which covers many markup formats in use today) will work a bit
+better. While strictly speaking QED does not need to recognize headers,
+it does improve console output.
 
 Give this design some thought. It should become clear that this approach is
 especially fruitful in that it allows *documentation* and *specification*
-to seemlessly merge into a unified *demonstration*. 
+to seamlessly merge into a unified *demonstration*. 
 
 === Running Demonstrations
 
 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 detaling each.
+If there were errors or failures, we would see information detailing each.
 
 To run a document through QED, simply use the +qed+ command.
 
@@ -79,21 +86,21 @@ To run a document through QED, simply use the +qed+ command.
 The <tt>-v</tt> option specifies verbatim mode, which outputs the entire
 document.
 
-Notice we placed the QED document in the demo directory, this is the
-concial place that has been designated for them, though you can put them
-elsewhre in your project if you prefer. Also notice the 01_ in front
-of the name. While this is not necessary, it helps order the documents
-properly with generating QED documentation (QEDocs).
+Notice we placed the QED document in the <tt>demo</tt> directory, this is
+one of two conical place that has been designated for them (the other is test/demos),
+though you can put them elsewhere in your project if you prefer. Also notice the
+<tt>01_</tt> in front of the name. While this is not necessary, it helps order
+the documents properly with generating QED documentation (QEDocs).
 
 To generate documentation from QED documents, use the +qedoc+ command.
 
-  $ qed --output doc/qedoc --title "Example" demo/*.rdoc
+  $ qedoc --output doc/qedoc --title "Example" demo/*.rdoc
 
 When documenting QED recognizes the format by the file extension and 
 treats it accordingly. An extension of <tt>.qed</tt> is treated the same
 as <tt>.rdoc</tt>.
 
-Use the <tt>--help</tt> options on each command to get more inforamtion on
+Use the <tt>--help</tt> options on each command to get more information on
 the use of these commands.
 
 

data/bin/qed

@@ -1,150 +1,4 @@
 #!/usr/bin/env ruby
-
-require 'qed'
-require 'getoptlong'
-
-module QED
-
-  # = QED Commandline Tool
-  #
-  class Command
-    def self.execute
-      new.execute
-    end
-
-    attr :reporter
-
-    def initialize
-      @reporter = nil
-    end
-
-    def opts
-      @opts ||= GetoptLong.new(
-        [ '--version',        GetoptLong::NO_ARGUMENT ],
-        [ '--help',     '-h', GetoptLong::NO_ARGUMENT ],
-        [ '--debug',    '-D', GetoptLong::NO_ARGUMENT ],
-        [ '--verbose',  '-V', GetoptLong::NO_ARGUMENT ],
-        [ '--verbatim', '-v', GetoptLong::NO_ARGUMENT ],
-        [ '--summary',  '-s', GetoptLong::NO_ARGUMENT ],
-        [ '--script',         GetoptLong::NO_ARGUMENT ],
-        [ '--loadpath', '-I', GetoptLong::REQUIRED_ARGUMENT ]
-      )
-    end
-
-    #
-    def parse_options
-      opts.each do |opt, arg|
-        case opt
-        when '--help'
-          puts HELP
-          exit
-        when '--debug'
-          $RESPECT_DEBUG = true
-        when '--verbose'
-          $VERBOSE = true
-        when '--verbatim'
-          @reporter = :verbatim
-        when '--summary'
-          @reporter = :summary
-        when '--script'
-          @reporter = :script  # psuedo-reporter
-        when '--loadpath'
-          libs = arg.split(/[:;]/).map{ |dir| File.expand_path(dir) }
-          libs.each{|dir| $LOAD_PATH.unshift(dir)}
-        end
-      end
-    end
-
-    #
-    #def load_rc
-    #  if rcfile = Dir['.config/qed{,rc}{,.rb}'].first
-    #    load(rcfile)
-    #  end
-    #end
-
-    # TODO: Better way to load helpers?
-    #
-    #def load_helpers
-    #  dirs = spec_files.map{ |file| File.join(Dir.pwd, File.dirname(file)) }
-    #  dirs = dirs.select{ |dir| File.directory?(dir) }
-    #  dirs.each do |dir|
-    #    while dir != '/' do
-    #      helper = File.join(dir, 'qed_helper.rb')
-    #      load(helper) if File.exist?(helper)
-    #      break if Dir.pwd == dir
-    #      dir = File.dirname(dir)
-    #    end
-    #  end
-    #end
-
-    #
-    def specs
-      spec_files
-    end
-
-    #
-    def spec_files
-      files = ARGV.map do |pattern|
-        Dir[pattern]
-      end.flatten.uniq
-
-      files = files.map do |file|
-        File.directory?(file) ? Dir[File.join(file,'**','*')] : file
-      end.flatten.uniq
-
-      files = files.reject do |file| 
-        %w{.yml .yaml .rb}.include?(File.extname(file))
-      end
-
-      files
-    end
-
-    #
-    def output
-      case reporter
-      when :verbatim
-        Reporter::Verbatim.new
-      when :summary
-        Reporter::Summary.new
-      else
-        nil
-      end
-    end
-
-    #
-    def runner
-      Runner.new(specs, output)
-    end
-
-    #
-    def execute
-      parse_options
-      #load_rc
-      #load_helpers
-      case reporter
-      when :script
-        specs.each do |spec|
-          puts spec.to_script
-        end
-      else
-        runner.check
-      end
-    end
-
-    HELP = <<-END
-qed [--options] [spec/tests...]
-
-Options:
--v --verbatim   use verbatim reporter
--s --summary    use summary reporter
--V --verbose    extra verbose output
--D --debug      spec/tests will exit on error
--h --help       show this help information
-   --version    show quarry version
-    END
-
-  end
-end
-
+require 'qed/command'
 QED::Command.execute
 

data/demo/01_spec.qed

@@ -12,21 +12,20 @@ a failure or error occur then the code gets a "pass".
 
 For example, the following passes:
 
-  (2 + 2).assert == 4
+    (2 + 2).assert == 4
 
 While the following would "fail", as indicated by the raising of 
 an Assertion error:
 
-  expect Assertion do
-    (2 + 2).assert == 5
-  end
+    expect Assertion do
+      (2 + 2).assert == 5
+    end
 
 And this would have raised a NameError:
 
-  expect NameError do
-    nobody_knows_method
-  end
-
+    expect NameError do
+      nobody_knows_method
+    end
 
 = Neutral Code
 
@@ -34,34 +33,32 @@ There is no means of specifying that a code clause is neutral code,
 i.e. that it should be executed but not tested. Thus far, such a
 feature has proven to be a YAGNI.
 
-
 = Defining Custom Assertions
 
 The context in which the QED code is run is a self-extended module, thus
 reusable macros can be created simply by defining a method.
 
-  def assert_integer(x)
-    x.assert.is_a? Integer
-  end
+    def assert_integer(x)
+      x.assert.is_a? Integer
+    end
 
 Now lets try out our new macro definition.
 
-  assert_integer(4)
+    assert_integer(4)
 
 Let's prove that it can also fail:
 
-  expect Assertion do
-    assert_integer("IV")
-  end
-
+    expect Assertion do
+      assert_integer("IV")
+    end
 
 = Helper File
 
-If you create a file called `qed_helper.rb` located in the directory with the
-QED documents you are running via the `qed` command, it will be loaded first.
-You can use that to load optional AE features, or define your own specialized
-assertion methods.
-
+Helpers can be defined at the bottom of any QED document by placing the code
+after a triple-dash divider (ie. "---"). You can use that to load optional
+AE features, or define your own specialized assertion methods. Helpers
+can be defined in a separate files using +require+ or +load+ in the bottom
+section to import them. The bottom section is run first, before any the steps.
 
 = Before and After Clauses
 
@@ -73,30 +70,30 @@ subsequent step.
 We use a *before* clause if we want to setup some code at the
 start of each step.
 
-  a, z = nil, nil
+    a, z = nil, nil
 
-  before do
-    a = "BEFORE"
-  end
+    Before do
+      a = "BEFORE"
+    end
 
-And an *after* clause to tear down objects after a step.
+And an *after* clause to teardown objects after a step.
 
-  after do
-    z = "AFTER"
-  end
+    After do
+      z = "AFTER"
+    end
 
 Notice we assigned +a+ and +z+ before the block. This was to ensure
-their visibility in the scope later. Now, lets verify this the *before*
-and *after* clause work.
+their visibility in the scope later. Now, lets verify that the *before*
+and *after* clauses work.
 
-  a.assert == "BEFORE"
+    a.assert == "BEFORE"
 
-  a = "A"
-  z = "Z"
+    a = "A"
+    z = "Z"
 
 And now.
 
-  z.assert == "AFTER"
+    z.assert == "AFTER"
 
 There can only be one before or after clause at a time. So if we
 define a new *before* or *after* clause later in the document,
@@ -104,43 +101,75 @@ it will replace the current clause(s) in use.
 
 As a demonstration of this:
 
-  before do
-    a = "BEFORE AGAIN"
-  end
+    Before do
+      a = "BEFORE AGAIN"
+    end
 
 We will see it is the case.
 
-  a.assert == "BEFORE AGAIN"
+    a.assert == "BEFORE AGAIN"
 
 Only use *before* and *after* clauses when necessary --specifications
 are generally more readable without them. Indeed, some developers
 make a policy of avoiding them altogether. YMMV.
 
+= External Data
+
+When creating testable demonstrations, there are times when sizable
+chunks of data are needed. It is convenient to store such data in
+a separate file. The +Data+ method makes is easy to load such files.
+
+    Data('data.txt').assert =~ /dolor/
+
+All files are looked for relative to the location of current document.
 
 = Tabular Steps
 
-Finally we will demonstrate a tabular step. +table+ method is used
-for this. We supply a file name to the method telling QED where to
-find the table data to be used in the test. All table files are looked
-for relative to the location of the document. If no name is given the
-'<doc-name>.yaml' is assumed.
+The +Table+ method is similar to the +Data+ method except that it
+expects a YAML file, and it can take a block to iterate the data over.
+This makes it easy to test tables of examples.
 
 The arity of the table block determines the number of columns each row
 in the table should have. Each row is assigned in turn and run
 through the coded step. Consider the following example:
 
-Every row in 'table.yaml' will be assigned to the block parameters
-and run through the following assertion.
+Every row in the {table.yml table}[table.yml] will be assigned to
+the block parameters and run through the subsequent assertion.
+
+    Table 'table.yml' do |x, y|
+      x.upcase.assert == y
+    end
 
-  table do |x,y|
-    x.upcase.assert == y
-  end
+= Comment Triggers
+
+QED also supports comment match triggers. With the +When+ method one can
+define setup and teardown procedures by matching against comment text.
+For example:
+
+    When 'given a setting @a equal to (((\d+)))' do |n|
+      @a = n.to_i
+    end
+
+Now, @a will be set to 1 whenever a comment like this one contains,
+"given a setting @a equal to 1".
+
+    @a.assert == 1
+
+A string pattern is translated into a regular expression. In fact, you can
+use a regular expression if you need more control over the match. When
+using a string all spaces are converted to <tt>\s+</tt> and anything within
+double-parenthesis is treated as raw regular expression. Since the above
+example has (((\d+))), the actual regular expression contains <tt>(\d+)</tt>,
+so any number can be used. For example, "given a setting @a equal to 2".
+
+    @a.assert == 2
+
+Typically you will want to put triggers is helper files, rather then
+place them directly in the demonstration document.
 
 This concludes the basic overview of QED's specification system, which
 is itself a QED document. Yes, we eat our own dog food.
 
-Q.E.D.
-
 ---
-require 'qed_helper'
+require 'helper'