qed 2.9.0 → 2.9.1

data/{qed/01_demos.rdoc → demo/01_demos.md}

@@ -1,6 +1,6 @@
-= QED Demonstrandum
+# QED Demonstrandum
 
-== Steps
+## Steps
 
 QED demos are light-weight specification documents, highly suitable
 to interface-driven design. The documents are divided up into
@@ -29,7 +29,7 @@ And this would have raised a NameError.
       nobody_knows_method
     end
 
-== Defining Custom Assertions
+## 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.

data/{qed/02_advice.rdoc → demo/02_advice.md}

@@ -1,4 +1,4 @@
-= Advice
+# Advice
 
 Advice are event-based procedures that augment demonstrations.
 They are used to keep demonstrations clean of extraneous,
@@ -9,7 +9,7 @@ Typically you will want to put advice definitions in 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
+## Before and After
 
 QED supports *before* and *after* clauses in a specification
 through the use of Before and After code blocks. These blocks
@@ -64,26 +64,26 @@ 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
+## 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
+    def prepare_example
+      "Hello, World!"
+    end
 
 Then we can reuse it in later code blocks.
 
-  example = prepare_example
-  example.assert == "Hello, World!"
+    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
+## Event Targets
 
 There is a small set of advice targets that do not come before or after,
 rather they occur *upon* a particular event. These include +:pass+, +:fail+
@@ -95,13 +95,13 @@ 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 = []
+    x = []
 
-  When(:step) do |section|
-    section.text.scan(/^\*(.*?)$/) do |m|
-      x << $1.strip
+    When(:step) do |section|
+      section.text.scan(/^\*(.*?)$/) do |m|
+        x << $1.strip
+      end
     end
-  end
 
 Now let's see if it worked.
 
@@ -111,9 +111,9 @@ Now let's see if it worked.
 
 So +x+ should now contain these three list samples.
 
-  x.assert == [ 'SampleA', 'SampleB', 'SampleC' ]
+    x.assert == [ 'SampleA', 'SampleB', 'SampleC' ]
 
-== Pattern Matchers
+## 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.
@@ -159,7 +159,7 @@ that if 'then match #2' is found, will it be considered 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]
+    @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.

data/{qed/03_helpers.rdoc → demo/03_helpers.md}

@@ -1,31 +1,31 @@
-= Helpers
+# Helpers
 
 There are two ways to load advice scripts. Manually loaded
-helpers act per demonstrandum and apply only to the currently
+helpers act pe-demonstrandum and so apply only to the currently
 executing demo. Automaticly loaded helpers apply to all 
 demonstrandum within their preview.
 
 Helper scripts can be written just like demonstration scripts,
 or they can be defined as pure Ruby scripts.
 
-== Automatic Helpers
+## Automatic Helpers
 
 Automatic helpers, known as the "applique" are loaded at the
 start of a session and apply equally to all demonstrandum within
-the same or lower directory as teh demo. These helpers are placed
+the same or lower directory as the demo. These helpers are placed
 in an +applique+ subdirectory. For instance this document uses,
-{applique/env.rb}[applique/env.rb].
+[applique/env.rb](applique/env.rb).
 
-== Manual Helpers
+## Manual Helpers
 
 Manual helpers are loaded per-demonstration by using specially
 marked links.
 
-For example, because this link, Advice[qed://helpers/advice.rb],
-begins with +qed:+, it will be used to load a helper. We can 
+For example, because this link, [Advice](qed://helpers/advice.rb),
+begins with `qed:`, it will be used to load a helper. We can 
 see this with the following assertion.
 
-  pudding.assert.include?('loaded advice.rb')
+    pudding.assert.include?('loaded advice.rb')
 
 No where in the demonstration have we defined +pudding+, but
 it has been defined for us in the advice.rb helper script.
@@ -35,7 +35,7 @@ helper is keeping count of decriptive paragraphs. Since the
 helper script was loaded two paragraphs back, the next count
 will be 3.
 
-  count.assert == 3
+    count.assert == 3
 
 Helpers are vital to building test-demonstration suites for
 applications. But here again, only use them as necessary.

data/{qed/04_samples.rdoc → demo/04_samples.md}

@@ -1,6 +1,6 @@
-= Test Samples
+# Test Samples
 
-== Flat-file Data
+## Flat-file Data
 
 When creating testable demonstrations, there are times when sizable
 chunks of data are needed. It is convenient to store such data in
@@ -19,7 +19,7 @@ Files are looked-up relative to the location of the current document.
 If not found then they will be looked-up relative to the current
 working directory.
 
-== Tabular Data
+## Tabular Data
 
 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.
@@ -29,7 +29,7 @@ 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.
 
-Every row in the {table.yml table}[table.yml] will be assigned to
+Every row in the [table.yml table](table.yml) will be assigned to
 the block parameters and run through the subsequent assertion.
 
     Table File.dirname(__FILE__) + '/samples/table.yml' do |x, y|
@@ -38,7 +38,7 @@ the block parameters and run through the subsequent assertion.
 
 Without the block, the +Table+ methods simply returns the sample data.
 
-== Considerations
+## Considerations
 
 Both Data and Table are some what "old fashion" approches to sample
 data. New techinques using plain text blocks are more convenient

data/{qed/05_quote.rdoc → demo/05_quote.md}

@@ -1,4 +1,4 @@
-= Quotes
+# Quotes
 
 We do not always want verbatim clauses to be interpreted as code.
 Sometimes it would more useful to treat them a plain text to 
@@ -7,9 +7,9 @@ which the preceeding paragraph can make use in a processing rule.
 For example let say we want to make an example out of the following
 text:
 
-  The file will contain
+    The file will contain
 
-  this text
+    this text
 
 The use of the colon (`:`) tells the processor that the next
 segment is a plain text continuation of the current segment, rather
@@ -19,7 +19,7 @@ the end of the arguments list of any applicable processing rule.
 Behind the scenes we created a rule to set the text to an instance
 variable called @quote_text, and we can verify it is so.
 
-  @quote_text.assert == "The file will contain\n\nthis text"
+    @quote_text.assert == "The file will contain\n\nthis text"
 
 Alternately we can use a colon (':') instead of ellipsis. We can repeat
 the same statment as above.
@@ -27,11 +27,11 @@ the same statment as above.
 For example let say we want to make an example out of the following
 text:
 
-  The file will contain
+    The file will contain
 
-  different text
+    different text
 
 And again we can verify that it did in fact set the @quote_text variable.
 
-  @quote_text.assert == "The file will contain\n\ndifferent text"
+    @quote_text.assert == "The file will contain\n\ndifferent text"
 

data/{qed/07_toplevel.rdoc → demo/07_toplevel.md}

@@ -1,4 +1,4 @@
-= Toplevel Simulation
+# Toplevel Simulation
 
 QED simulates Ruby's TOPLEVEL environment in both the Demonstrandum
 and the Applique contexts. This serves two important purposes.
@@ -10,31 +10,31 @@ the code it is intended to test.
 Let's look at some examples. For starters, we have access to a class
 defined at the "toplevel" in the applique.
 
-  ToplevelClass
+    ToplevelClass
 
 We can also call a method defined in the toplevel.
 
-  toplevel_method.assert == true
+    toplevel_method.assert == true
 
 At the demonstrandum level we can define reusable methods.
 
-  def demo_method
-    true
-  end
+    def demo_method
+      true
+    end
 
-  demo_method.assert == true
+    demo_method.assert == true
 
 And at the demonstrandum level even singleton methods are accessible.
 
-  def self.singleton_method; true; end
+    def self.singleton_method; true; end
 
-  singleton_method.assert == true
+    singleton_method.assert == true
 
 QED uses a self-extend modules to achieve this simulation, so the
 contexts are in fact a bit more capable then even Ruby's TOPLEVEL.
 For instance, #define_method can be used.
 
-  define_method(:named_method){ true }
+    define_method(:named_method){ true }
 
-  named_method.assert == true
+    named_method.assert == true
 

data/{qed/08_cross_script.rdoc → demo/08_cross_script.md}

@@ -1,25 +1,25 @@
-= Cross-Scripting Setup
+# Cross-Scripting Setup
 
 We define some variables here to make sure it is
 not visible in the next script.
 
 Let's set two local variables.
 
-  a = 100
-  b = 200
+    a = 100
+    b = 200
 
 And two instance varaibles.
 
-  @a = 1000
-  @b = 2000
+    @a = 1000
+    @b = 2000
 
 Also let check how it effect constants.
 
-  CROSS_SCRIPT_CONSTANT = "cross?"
+    CROSS_SCRIPT_CONSTANT = "cross?"
 
 And a method.
 
-  def cross_script_method
-    "common"
-  end
+    def cross_script_method
+      "common"
+    end
 

data/{qed/09_cross_script.rdoc → demo/09_cross_script.md}

@@ -1,29 +1,28 @@
-= Cross-Scripting Check
+# Cross-Scripting Check
 
 Make sure local and instance variables from previous
 QED scripts are not visible in this document.
 
-  expect NameError do
-    a.assert = 100
-    b.assert = 200
-  end
+    expect NameError do
+      a.assert = 100
+      b.assert = 200
+    end
 
 And two instance_varaibles
 
-  @a.assert! == 1000
-  @b.assert! == 2000
-
+    @a.assert! == 1000
+    @b.assert! == 2000
 
 Method definitions also do not cross QED scripts.
 
-  expect NameError do
-    cross_script_method
-  end
+    expect NameError do
+      cross_script_method
+    end
 
 Since each demo is encapsulated in a separated class scope, constants also
 do not make their way across.
 
-  expect NameError do
-    CROSS_SCRIPT_CONSTANT
-  end
+    expect NameError do
+      CROSS_SCRIPT_CONSTANT
+    end
 

data/demo/10_constant_lookup.md

@@ -0,0 +1,16 @@
+# Missing Constant
+
+If a constant is missing it is because it was not found
+in either the demos scope, the applique or at the toplevel.
+
+    begin
+      UnknownConstant
+    rescue => err
+      # no colon means toplevel
+      err.name.to_s.refute.include?('::')
+    end
+
+A constant defined in the applique is visible.
+
+    APPLIQUE_CONSTANT.assert = true
+

data/{qed/11_embedded_rules.rdoc → demo/11_embedded_rules.md}

@@ -1,4 +1,4 @@
-= Meta Code
+# Meta Code
 
 All code steps are evaluated in a rescue clause. If an error occurs, it
 is captured and reported through the test report, and execution continues.
@@ -6,20 +6,20 @@ However, sometimes this is not desired. To evaluate a step without the
 rescue clause, and effective *fail fast*, append `^` mark to the end of
 the desription text, like so. ^
 
-  When 'this is cool' do |text|
-    @text = text
-  end
+    When 'this is cool' do |text|
+      @text = text
+    end
 
 Now, let's try it by saying, "this is cool":
 
-  And this is the text.
+    And this is the text.
 
 Did it work?
 
-  @text.assert == "And this is the text."
+    @text.assert == "And this is the text."
 
 
-== Match Separator
+## Match Separator
 
 The `When` method can take a list of String or Regexp as arguments.
 If any of the strings contain `...`, the string will be split into
@@ -27,20 +27,20 @@ two at this point, which effective means that any text can occur
 within this space. It behaves much like adding `((*.?))`, but parses
 more quickly by dividing the string into multiple matches.
 
-  When 'Let /(\w+)/ be ... scared of /(\w+)/' do |name, monster|
-    @name    = name
-    @monster = monster
-  end
+    When 'Let /(\w+)/ be ... scared of /(\w+)/' do |name, monster|
+      @name    = name
+      @monster = monster
+    end
 
 Okay let's try it: Let John be very scared of Zombies.
 
 So now what is the name?
 
-  @name.assert == "John"
+    @name.assert == "John"
 
 What is the monster?
 
-  @monster.assert == "Zombies"
+    @monster.assert == "Zombies"
 
 Did it work?