RubyGems - qed - Versions diffs - 1.3 → 2.0.0 - Mend

qed 1.3 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (40) hide show

data/CHANGELOG.txt +647 -0
data/HISTORY +16 -0
data/bin/qedoc +2 -51
data/demo/error.rdoc +21 -0
data/demo/{03_site.qed → website.rdoc} +0 -0
data/doc/qedoc/index.html +160 -69
data/lib/qed.rb +2 -2
data/lib/qed/advice.rb +61 -0
data/lib/qed/advice/events.rb +54 -0
data/lib/qed/advice/patterns.rb +64 -0
data/lib/qed/command.rb +76 -65
data/lib/qed/config.rb +48 -13
data/lib/qed/evaluator.rb +124 -0
data/lib/qed/reporter/base.rb +93 -39
data/lib/qed/reporter/bullet.rb +79 -0
data/lib/qed/reporter/dotprogress.rb +9 -29
data/lib/qed/reporter/html.rb +61 -0
data/lib/qed/reporter/verbatim.rb +41 -47
data/lib/qed/scope.rb +77 -0
data/lib/qed/script.rb +66 -399
data/lib/qed/session.rb +95 -0
data/lib/qedoc/command.rb +76 -0
data/lib/{qed → qedoc}/document.rb +31 -22
data/lib/{qed → qedoc}/document/jquery.js +0 -0
data/lib/{qed → qedoc}/document/markup.rb +0 -0
data/lib/{qed → qedoc}/document/template.rhtml +0 -0
data/meta/requires +2 -0
data/meta/version +1 -1
metadata +71 -34
data/Syckfile +0 -70
data/demo/01_spec.qed +0 -175
data/demo/02_err.qed +0 -18
data/demo/data.txt +0 -1
data/demo/helpers/sample.rb +0 -4
data/demo/table.yml +0 -5
data/lib/qed/extract.rb +0 -137
data/lib/qed/reporter/ditto.rb +0 -72
data/lib/qed/reporter/summary.rb +0 -68
data/lib/qed/runner.rb +0 -198
data/lib/qed/script1.rb +0 -495

data/HISTORY CHANGED Viewed

@@ -1,5 +1,21 @@
 = RELEASE HISTORY
+== 10.03.04 / 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 / 2009-12-07
 This release adds a significant new feature, Comment Matchers.

data/bin/qedoc CHANGED Viewed

@@ -1,52 +1,3 @@
 #!/usr/bin/env ruby
-require 'optparse'
-require 'qed/document'
-options = {}
-usage = OptionParser.new do |usage|
-  usage.banner = "Usage: qedoc [OPTIONS] <QEDFile1> [ <QEDFile2> ... ]"
-  usage.on("-o", "--output [DIR]", "Output directory") do |dir|
-    options[:output]= dir
-  end
-  usage.on("-t", "--title [TITLE]", "Title of Document") do |title|
-    options[:title]= title
-  end
-  usage.on("--css [URI]", "Specify a URI for a CSS file add to HTML header.") do |uri|
-    options[:css] = uri
-  end
-  usage.on("--dryrun", "") do
-    options[:dryrun] = true
-  end
-  usage.on("-q", "--quiet", "") do
-    options[:quiet] = true
-  end
-  usage.on_tail("-h", "--help", "display this help message") do
-    puts usage
-    exit
-  end
-end
-usage.parse!
-options[:paths] = ARGV.dup
-#opts[:output] = cli.options[:file]
-#opts[:dryrun] = cli.options[:dryrun]
-#opts[:quiet]  = cli.options[:quiet]
-#opts[:css]    = cli.options[:css]
-#opts[:title]  = cli.options[:title]
-doc = QED::Document.new(options)
-doc.generate
+require 'qedoc/command'
+QEDoc::Command.run

data/demo/error.rdoc ADDED Viewed

@@ -0,0 +1,21 @@
+= Examples of Failure
+This document is here simply to demonstrate what
+a failed and error raising code steps looks like.
+When run with the -v (verbatim) option, for instance, +qed+
+will highlight the following sections in red and give a brief
+error message.
+== Failure
+This step demonstrates a failed assertion.
+  1.assert == 2
+== Error
+This step demonstrates a raised error.
+  raise "Just because"

data/demo/{03_site.qed → website.rdoc} RENAMED Viewed

File without changes

data/doc/qedoc/index.html CHANGED Viewed

@@ -98,7 +98,9 @@
     </div>
     <div id="content">
-      <h1>Standard Sections</h1>
+      <body>
+<h1>Demonstrations</h1>
+<h2>Standard Sections</h2>
 <p>
 QED demos are light-weight specification documents, highly suitable to
 interface-driven design. The documents are divided up into clauses
@@ -109,7 +111,7 @@ executable code.
 <p>
 Each code section is executed in order of appearance, within a rescue
 wrapper that captures any failures or errors. If neither a failure or error
-occur then the code gets a &#8220;pass&#8221;.
+occur then the code gets a “pass”.
 </p>
 <p>
 For example, the following passes:
@@ -118,7 +120,7 @@ For example, the following passes:
     (2 + 2).assert == 4
 </pre>
 <p>
-While the following would &#8220;fail&#8221;, as indicated by the raising
+While the following would “fail”, as indicated by the raising
 of an Assertion error:
 </p>
 <pre>
@@ -134,13 +136,13 @@ And this would have raised a NameError:
       nobody_knows_method
     end
 </pre>
-<h1>Neutral Code</h1>
+<h2>Neutral Code Blocks</h2>
 <p>
 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.
 </p>
-<h1>Defining Custom Assertions</h1>
+<h2>Defining Custom Assertions</h2>
 <p>
 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.
@@ -157,45 +159,44 @@ Now lets try out our new macro definition.
     assert_integer(4)
 </pre>
 <p>
-Let&#8217;s prove that it can also fail:
+Let’s prove that it can also fail:
 </p>
 <pre>
     expect Assertion do
-      assert_integer(&quot;IV&quot;)
+      assert_integer("IV")
     end
 </pre>
-<h1>Helper File</h1>
+</body>
+<body>
+<h1>Advice</h1>
 <p>
-Helpers can be defined at the bottom of any QED document by placing the
-code after a triple-dash divider (ie. &#8220;&#8212;&#8221;). 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 <tt>require</tt>
-or <tt>load</tt> in the bottom section to import them. The bottom section
-is run first, before any the steps.
+Advice are wrapper methods that augment demonstrations. They are used to
+keep demonstrations clean of extraneous, repetitive and merely
+adminstrative code that the reader does not need to see over and over.
 </p>
-<h1>Before and After Clauses</h1>
+<h2>Before and After</h2>
 <p>
 QED supports <b>before</b> and <b>after</b> clauses in a specification
-through the use of before and after code blocks. Before and after clauses
-are executed at the beginning and at the end of each subsequent step.
+through the use of Before and After code blocks. These blocks are executed
+at the beginning and at the end of each indicated step.
 </p>
 <p>
 We use a <b>before</b> clause if we want to setup some code at the start of
-each step.
+each code step.
 </p>
 <pre>
     a, z = nil, nil
     Before do
-      a = &quot;BEFORE&quot;
+      a = "BEFORE"
     end
 </pre>
 <p>
-And an <b>after</b> clause to teardown objects after a step.
+And an <b>after</b> clause to teardown objects after a code step.
 </p>
 <pre>
     After do
-      z = &quot;AFTER&quot;
+      z = "AFTER"
     end
 </pre>
 <p>
@@ -204,78 +205,113 @@ ensure their visibility in the scope later. Now, lets verify that the
 <b>before</b> and <b>after</b> clauses work.
 </p>
 <pre>
-    a.assert == &quot;BEFORE&quot;
+    a.assert == "BEFORE"
-    a = &quot;A&quot;
-    z = &quot;Z&quot;
+    a = "A"
+    z = "Z"
 </pre>
 <p>
 And now.
 </p>
 <pre>
-    z.assert == &quot;AFTER&quot;
+    z.assert == "AFTER"
 </pre>
 <p>
-There can only be one before or after clause at a time. So if we define a
-new <b>before</b> or <b>after</b> clause later in the document, it will
-replace the current clause(s) in use.
+There can be more than one before and after clause at a time. If we define
+a new <b>before</b> or <b>after</b> clause later in the document, it will
+be appended to the current list of clauses in use.
 </p>
 <p>
 As a demonstration of this:
 </p>
 <pre>
+    b = nil
     Before do
-      a = &quot;BEFORE AGAIN&quot;
+      b = "BEFORE AGAIN"
     end
 </pre>
 <p>
 We will see it is the case.
 </p>
 <pre>
-    a.assert == &quot;BEFORE AGAIN&quot;
+    b.assert == "BEFORE AGAIN"
 </pre>
 <p>
 Only use <b>before</b> and <b>after</b> clauses when necessary
-&#8212;specifications are generally more readable without them. Indeed,
+—specifications are generally more readable without them. Indeed,
 some developers make a policy of avoiding them altogether. YMMV.
 </p>
-<h1>External Data</h1>
+<h2>Caveats of Before and After</h2>
 <p>
-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 <tt>Data</tt> method makes is easy to load such files.
+Instead of using Before and After clauses, it is wiser to define a reusable
+setup method. For example, in the helper if we define a method such as
+#prepare_example.
 </p>
 <pre>
-    Data('data.txt').assert =~ /dolor/
+  def prepare_example
+    "Hello, World!"
+  end
 </pre>
 <p>
-All files are found relative to the location of current document.
+Then we can reuse it in later code blocks.
 </p>
-<h1>Tabular Steps</h1>
+<pre>
+  example = prepare_example
+  example.assert == "Hello, World!"
+</pre>
 <p>
-The <tt>Table</tt> method is similar to the <tt>Data</tt> 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 advantage to this is that it gives the reader an indication of what is
+going on behind the scenes, rather the having an object just magically
+appear.
 </p>
+<h2>Event Targets</h2>
 <p>
-The arity of the table block corresponds to the number of columns in each
-row of the table. Each row is assigned in turn and run through the coded
-step. Consider the following example:
+There is a small set of advice targets that do not come before or after an
+event, rather they occur <b>upon</b> a particular event. These include
+<tt>:load</tt> and <tt>:unload</tt>, for when a new helper is loaded;
+<tt>:pass</tt>, <tt>:fail</tt> and <tt>:error</tt> for when a code block
+passes, fails or raises an error; and <tt>:tag</tt> which is a low-level
+target triggered upon parsing each element in the HTML conversion of the
+demonstration.
 </p>
 <p>
-Every row in the <a href="http://table.yml">table.yml table</a> will be
-assigned to the block parameters and run through the subsequent assertion.
+These event targets can be advised by calling the <tt>When</tt> method with
+the target type as an argument along with the code block to be run when the
+event is triggered.
 </p>
 <pre>
-    Table 'table.yml' do |x, y|
-      x.upcase.assert == y
-    end
+  x = []
+  When(:tag) do |element|
+    x &lt;&lt; element.text.strip if element.name == 'li'
+  end
 </pre>
-<h1>Comment Triggers</h1>
+<p>
+Not let see it is worked:
+</p>
+<ul>
+<li>SampleA
+</li>
+<li>SampleB
+</li>
+<li>SampleC
+</li>
+</ul>
+<p>
+So <tt>x</tt> should now contain these three list samples.
+</p>
+<pre>
+  x.assert == [ 'SampleA', 'SampleB', 'SampleC' ]
+</pre>
+<h2>Pattern Matchers</h2>
 <p>
 QED also supports comment match triggers. With the <tt>When</tt> method one
-can define setup and teardown procedures by matching against comment text.
-For example:
+can define procedures to run when a given pattern matches comment text. For
+example:
 </p>
 <pre>
     When 'given a setting @a equal to (((\d+)))' do |n|
@@ -284,7 +320,7 @@ For example:
 </pre>
 <p>
 Now, @a will be set to 1 whenever a comment like this one contains,
-&#8220;given a setting @a equal to 1&#8221;.
+“given a setting @a equal to 1”.
 </p>
 <pre>
     @a.assert == 1
@@ -295,8 +331,8 @@ 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, &#8220;given a
-setting @a equal to 2&#8221;.
+<tt>(\d+)</tt>, so any number can be used. For example, “given a
+setting @a equal to 2”.
 </p>
 <pre>
     @a.assert == 2
@@ -306,34 +342,89 @@ Typically you will want to put triggers is helper files, rather then place
 them directly in the demonstration document.
 </p>
 <p>
-This concludes the basic overview of QED&#8217;s specification system,
+This concludes the basic overview of QED’s specification system,
 which is itself a QED document. Yes, we eat our own dog food.
 </p>
-<hr size="1"></hr><p>
-<a href="http://helper.rb">1</a> Helper
+</body>
+<body>
+<h1>Helpers</h1>
+<p>
+There are two ways to load advice scripts. Either per demonstration or
+globally. Per demonstration helpers apply only to the current
+demonstration. Global helpers apply to all demonstrations.
+</p>
+<h2>Global Helpers</h2>
+<p>
+Global helpers are loaded at the start of a session and apply equally to
+all demonstrations in a suite.
 </p>
-<h1>Examples of Failure</h1>
+<h2>Local Helpers</h2>
 <p>
-This document is here simply to demonstrate what a failed step looks like.
+Helper scripts can be written just a demonstration scripts, or they can be
+defined as pure Ruby scripts. Either way they are loaded per-demonstration
+by using specially marked links.
+</p>
+<p>
+For example, because this link, <a href="qed://helpers/advice.rb">Advice</a>, begins with <tt>require:</tt>,
+it will be used to load a global helper. We can see this with the
+following:
 </p>
 <pre>
-  1.assert == 2
+  pudding.assert.include?('load advice.rb')
 </pre>
 <p>
-And this step demonstrates an error.
+No where in the demonstration have we defined <tt>pudding</tt>, but it has
+been defined for us in the advice.rb helper script.
+</p>
+<p>
+We can also see that the generic When clause in our advice helper is
+keeping count of descriptions. Since the helper script was loaded three
+paragraphs back, the count will be 3.
 </p>
 <pre>
-  raise &quot;just because&quot;
+  count.assert == 3
 </pre>
 <p>
-When run with the -v (verbatim) option, <tt>qed</tt> will highlight these
-in red and give a brief error message.
+Helpers are vital to building test-demonstration suites for applications.
+But here again, only use them as necessary. The more helpers you use the
+more difficult your demos will be to follow.
 </p>
-<hr size="1"></hr><p>
-<a href="http://helper.rb">1</a> Helper
+</body>
+<body>
+<h1>Fixtures</h1>
+<h2>Flat-file Data</h2>
+<p>
+When creating testable demonstrations, there are times when sizable chunks
+of data are needed. It is convenient to store such data in separate files.
+The <tt>Data</tt> method makes is easy to load such files.
 </p>
+<pre>
+    Data('fixtures/data.txt').assert =~ /dolor/
+</pre>
+<p>
+All files are found relative to the location of current document.
+</p>
+<h2>Tabular Data</h2>
+<p>
+The <tt>Table</tt> method is similar to the <tt>Data</tt> 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.
+</p>
+<p>
+The arity of the table block corresponds to the number of columns in each
+row of the table. Each row is assigned in turn and run through the coded
+step. Consider the following example:
+</p>
+<p>
+Every row in the <a href="http://table.yml">table.yml table</a> will be
+assigned to the block parameters and run through the subsequent assertion.
+</p>
+<pre>
+    Table 'fixtures/table.yml' do |x, y|
+      x.upcase.assert == y
+    end
+</pre>
+</body>
     </div>
   </div>