qed 2.1.1 → 2.2.0

data/DIARY.rdoc

@@ -0,0 +1,117 @@
+= Diary
+
+== 2010-06-06 / HTML Won't Do
+
+There have proven to be significant issues associated with translating markup to HTML and having QED evalute the HTML, rather than plain text. To begin with different markup engines translate special characeters in differnt ways. RDoc for instance will translate astrisks around a word into 'b' tags, whereas Textile translates them to 'em' tags. Still other characters are translated into HTML escape codes, eg. <code>\&amp;#8216;</code>. There are a variety of these and each markup language will translate them according to it's own rules (or not at all). This means pattern matches in advice have to take these translations into account. Instead of matching on an asterisk we might need to match on +<b>+. A minor naggle perhaps, but it means being exceptionally aware of all translaterions that occur, and moreover, that applique may not be portable across markup languages.
+
+There are other discrepencies as well such as the translation of code blocks to \<pre> vs. \<pre>\<code> tags, but all this aside, while perhaps annoying, it can be managed. A normalization procedure can help mitage the issues. However, the ultimate problem is your classic YAGNI, the fact that little, if anything, is gained by using HTML as the defacto document format. And this is simply because everyone will write there documents in a text-based markup, none of which fully support the HTML that QED could utilize. For instance RDoc and Markdown do not have a notation for tables (although extended Markdown might). Textile does not have a clean notation for \<pre> blocks --you have to use \<pre>! And ASCIIDoc, while a very capable documentation system has a verbose syntax that is not particullary suited to reading in plain text. Perhaps if all the available markdown languages were equally as capable, it would be worth the additional effort. But lacking this I beleive more advantage can ultimately be gained by allowing QED to have it's own markup syntax one suited best to it's purpose.
+
+
+== 2010-02-03 / Some Determinations
+
+In the end I have decided on loading helpers on the fly via
+special AHREF links. We still need a plan for loading global
+helpers though.
+
+Also, per last entry, Before and After stays b/c When doesn't
+quite cover the usecase. However, I definately encourge the use
+of helper methods in place of Before and After clauses.
+
+
+== 2010-01-28 / Before and After
+
+Wouldn't it better to allow helpers to define methods, which
+can be called in the steps for setting things up, rather than
+using "magic" Before and After clauses which give no indication
+that something has happened?
+
+  = Examples
+
+  == Example #1
+
+  For example #1 we will use example1[helper/example1] support file.
+  First we need to prepare the example. It is a complex process, so we
+  have made a special method for it. See the helper[helper/example1]
+  file for details.
+
+    ex = prepare_example1
+
+  Now we can show that the example is hip.
+
+    ex.assert.hip == true
+
+So we could get rid of Before(:step) and After(:step) definitions this
+way, and it's not such a big loss, b/c we still have #When, and 
+After(:Step) is of very rare utility which can be worked around.
+
+
+== 2010-01-30 / The Best Way to Handle Helpers
+
+1) Should helpers be stored in a special location relative
+to the demo file, from which all helpers in that location
+are loaded automatically. This simplifies loading, but it
+makes support for per-demo helpers more awkward.
+This option also means taking special consideration for
+helpers when documenting --any reference to them will have
+to be tacked-on rather then be an integral part of the document
+itself.
+
+We might do something like this:
+
+  demos/
+    demo1.rdoc
+    demo1/
+      helper.rb
+    demo2.rdoc
+    demo2/
+      helper.rb
+    share/
+      helper.rb
+
+Such that demo1/helper.rb only applies to demo1.rdoc, and 
+likewise for demo2, but both use share/helper.rb.
+
+2) Or, should the demo be able to specify which helpers to
+load via href links. This allows full flexability it selecting
+behavior for the demo. It also means the documentation will
+have references to helpers built-in (although they will have
+to be augmented when documenting to ensure the hrefs link
+correctly). But session-oriented advice doesn't make much
+sense in a per-demo context. We could ignore that, or place
+session advice in a separate location. While this option
+is more flexible, it also means demos may be more difficult
+to follow, because one must scan the links in the document
+to determine which helpers are being used.
+
+An example demo might look like:
+
+  == Examples
+
+  == Example 1
+
+  For example #1 we will use example1[helper/example1] support file.
+
+  ... and so on ...
+
+  == Example 2
+  
+  For example #2 we will use example2[helper/example2] support file.
+  
+  ... and so on ...
+
+In which case it seems prudent to load these helpers as they are 
+evaluated, rather than all at once at the start. However this insinuates
+that there is only one before and after advice at a time, and when
+would before advice for the entire demo run, upon loading the helper?
+
+I think it would be better to use When clauses. Then the helpers could
+be loaded all at once at the start and it would not matter. And instead of
+<code>Before do</code> use <code>When /*/ do</code> for general before
+clauses.
+
+However, if referenced helpers are to be loaded all at once at the start,
+it seems almost silly to even allow helpers to be referenced in the
+document. With the exception of using them as footnotes, it conveys too
+much positional indication. So either load them when they are encountered,
+or use option #1.
+

data/HISTORY

@@ -1,5 +1,41 @@
 = RELEASE HISTORY
 
+== 2.2.0 / 2010-06-20
+
+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

data/PROFILE

@@ -0,0 +1,16 @@
+--- 
+title: QED
+suite: proutils
+summary: Quod Erat Demonstrandum
+authors: Thomas Sawyer <transfire@gmail.com>
+created: 2006-12-16
+
+description:
+  QED (Quality Ensured Demonstrations) is a TDD/BDD framework
+  utilizing Literate Programming techniques.
+
+resources:
+  home: http://proutils.github.com/qed
+  work: http://github.com/protuils/qed
+  repo: git://github.com/proutils/qed.git
+

data/README.rdoc

@@ -1,8 +1,8 @@
 = Ruby Q.E.D.
 
       homepage: http://proutils.rubyforge.org/qed
-  mailing list: http://groups.google.com/group/tigerops-community
-   development: http://github.com/proutils/qed/tree/master
+  mailing list: http://groups.google.com/group/proutils
+   development: http://github.com/proutils/qed
 
 
 == Introduction
@@ -10,23 +10,22 @@
 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.
+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". 
 
-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.
+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.
 
 
 == Features
 
-* Demos can be RDoc, Markdown or any other conforming text format. 
-* Uses the excellent Assertive Expressive library for assertion system.
-* Helpers are easily loaded relative to running document.
+* 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.
 * Documentation tool provides nice output with jQuery-based TOC.
 
@@ -35,21 +34,22 @@ designing reusable libraries.
 
 === Assertion Syntax
 
-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:
+QED uses the AE (Assertive Expressive) library to provide an elegant means to
+make assertions. To give a quick overview, assertion can be written as:
 
     4.assert == 5
 
 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 block containing these assertions.
+code blocks containing these assertions.
 
 You can learn more about AE at http://proutils.github.com/ae.
 
 === Document Structure
 
-QED documents are simply text files --thus a practice of literate programming.
-For example:
+QED documents are simply text files called *demonstrandum*. Because they 
+largely consist of free-form descriptive text, they are a practice pure 
+Literate Programming. For example:
 
     = Example
 
@@ -61,13 +61,14 @@ For example:
 
         5.assert == 5
 
-As you can see, we used RDoc for this document. 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. However QED recognizes
+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
-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.
+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.
 
 Give this design some thought. It should become clear that this approach is
 especially fruitful in that it allows *documentation* and *specification*
@@ -83,25 +84,57 @@ To run a document through QED, simply use the +qed+ command.
 
   $ qed -v demo/01_example.rdoc
 
-The <tt>-v</tt> option specifies verbatim mode, which outputs the entire
+The <code>-v</code> option specifies verbatim mode, which outputs the entire
 document.
 
-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).
+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).
+
+=== Utilizeing Applique
+
+QED demonstrandum descriptive text is not stricty passive explination. 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 
+applique will apply, create an <code>applique/</code> directory. In this
+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
+either *event advice*, which is simply triggered by some fixed cycle
+of running, such as <code>Before :document</code> or <code>After :all</code>,
+and *pattern advice* which are used to match against descriptive
+phrases in the QED demos. An example would be:
+
+  When "a new round is started" do
+    @round = []
+  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.
+
+It is rather amazing what can be accomplished with such a system,
+be sure to look at QED's own demonstandum to get a better notion of
+how you can put the the system to use.
+
+=== Generating Documentation
 
 To generate documentation from QED documents, use the +qedoc+ command.
 
   $ 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>.
+When documenting, QED recognizes the format by the file extension and 
+treats it accordingly. An extension of <code>.qed</code> is treated the same
+as <code>.rdoc</code>.
+
+Use the <code>--help</code> options on each command to get more information
+on the use of these commands.
+
 
-Use the <tt>--help</tt> options on each command to get more information on
-the use of these commands.
 
 
 == Requirements

data/REQUIRE

@@ -0,0 +1,9 @@
+runtime:
+  - ae
+  - ansi
+  - facets
+  - tilt
+  - nokogiri
+
+development:
+  - syckle

data/ROADMAP

@@ -0,0 +1,12 @@
+= ROADMAP
+
+== 2.2.0
+
+* Simplify code. I do not think we need both an Evaluator and Scope classes.
+
+== 2.3.0
+
+* Add a distributed evaluator, probably using Drb. This will allow the code
+portion of documents to run in an isolated process. It will also make it possible
+(in the long run) to run tests in parallel acrosss a cluster.
+

data/VERSION

@@ -0,0 +1,5 @@
+name : qed
+major: 2
+minor: 2
+patch: 0
+date : 2010-06-20

data/demo/01_demos.rdoc

@@ -0,0 +1,56 @@
+= Demonstrations
+
+== Standard Sections
+
+QED demos are light-weight specification documents, highly suitable
+to interface-driven design. The documents are divided up into
+clauses separated by blank lines. Clauses that are flush to the 
+left margin are always explanation or comment clauses. Indented
+clauses are always executable code.
+
+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 "pass".
+
+For example, the following passes:
+
+    (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
+
+And this would have raised a NameError:
+
+    expect NameError do
+      nobody_knows_method
+    end
+
+== Neutral Code Blocks
+
+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
+
+Now lets try out our new macro definition.
+
+    assert_integer(4)
+
+Let's prove that it can also fail:
+
+    expect Assertion do
+      assert_integer("IV")
+    end
+

data/demo/02_advice.rdoc

@@ -0,0 +1,158 @@
+= Advice
+
+Advice are event-based procedures 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.
+
+Typically you will want to put advice definitions is applique
+files, rather then place them directly in the demonstration
+document, but you can do so, as you will see in this document.
+
+== Before and After
+
+QED supports *before* and *after* clauses in a specification
+through the use of Before and After code blocks. These blocks
+are executed at the beginning and at the end of each indicated
+step.
+
+We use a *before* clause if we want to setup some code at the
+start of each code step.
+
+    a, z = nil, nil
+
+    Before do
+      a = "BEFORE"
+    end
+
+And an *after* clause to teardown objects after a code step.
+
+    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 that the *before*
+and *after* clauses work.
+
+    a.assert == "BEFORE"
+
+    a = "A"
+    z = "Z"
+
+And now.
+
+    z.assert == "AFTER"
+
+There can be more than one before and after clause at a time. If we
+define a new *before* or *after* clause later in the document,
+it will be appended to the current list of clauses in use.
+
+As a demonstration of this:
+
+    b = nil
+
+    Before do
+      b = "BEFORE AGAIN"
+    end
+
+We will see it is the case.
+
+    b.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.
+
+== Caveats of Before and After
+
+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.
+
+  def prepare_example
+    "Hello, World!"
+  end
+
+Then we can reuse it in later code blocks.
+
+  example = prepare_example
+  example.assert == "Hello, World!"
+
+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.
+
+== Event Targets
+
+There is a small set of advice targets that do not come before
+or after an event, rather they occur *upon* a particular event.
+These include +:load+ and +:unload+ for when a new helper is loaded;
++:pass+, +:fail+ and +:error+ for when a code block passes, fails or
+raises an error; and +:text+ and +:code+ which target the immediate
+processing of a text block and code excecution.
+
+These event targets can be advised by calling the +When+ method
+with the target type as an argument along with the code block
+to be run when the event is triggered.
+
+  x = []
+
+  When(:text) do |section|
+    section.text.scan(/^\*(.*?)$/) do |m|
+      x << $1.strip
+    end
+  end
+
+Not let see if it worked:
+
+* SampleA
+* SampleB
+* SampleC
+
+So +x+ should now contain these three list samples.
+
+  x.assert == [ 'SampleA', 'SampleB', 'SampleC' ]
+
+
+== Pattern Matchers
+
+QED also supports comment match triggers. With the +When+ method one can
+define procedures to run when a given pattern matches 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
+
+When clauses can also use consecutive pattern matching. For instance
+we could write:
+
+  When 'first match #(((\d+)))', 'then match #(((\d+)))' do |i1, i2|
+    @a = [i1.to_i, i2.to_i]
+  end
+
+So that 'first match #1' will be looked for first, and only after
+that if 'then match #2' is found, will it be condiered a complete match.
+All regular expression slots are collected from all matches and passed to
+the block. We can see that the rule matched this very paragraph:
+
+  @a.assert == [1,2]
+
+This concludes the basic overview of QED's specification system, which
+is itself a QED document. Yes, we eat our own dog food.
+