qed 2.1.1 → 2.2.0

data/demo/03_helpers.rdoc

@@ -0,0 +1,42 @@
+= Helpers
+
+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.
+
+== Global Helpers
+
+Global helpers are loaded at the start of a session and
+apply equally to all demonstrations in a suite. Global
+helpers are simply Ruby scripts and are placed in an
++environment+ subdirectory. For instance this document
+is used <a href="environment/env.rb">environment/env.rb</a>.
+
+== Local Helpers
+
+Helper scripts can be written just like demonstration scripts,
+or they can be defined as pure Ruby scripts. Either way
+they 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 global
+helper. We can see this with the following:
+
+  pudding.assert.include?('load advice.rb')
+
+No where in the demonstration have we  defined +pudding+, but
+it has been defined for us in the advice.rb helper script.
+
+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.
+
+  count.assert == 3
+
+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.
+

data/demo/04_fixtures.rdoc

@@ -0,0 +1,29 @@
+= Fixtures
+
+== 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
+separate files. The +Data+ method makes is easy to load such files.
+
+    Data('demo/fixtures/data.txt').assert =~ /dolor/
+
+All files are found relative to the location of current document.
+
+== 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.
+This makes it easy to test tables of examples.
+
+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
+the block parameters and run through the subsequent assertion.
+
+    Table 'demo/fixtures/table.yml' do |x, y|
+      x.upcase.assert == y
+    end
+

data/demo/05_quote.rdoc

@@ -0,0 +1,24 @@
+= Quotes
+
+We do not always want verbatum clauses to be interpreted as code.
+Sometimes it would more useful to trest them a plan text to 
+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
+
+  this text
+
+The use of the ellipsis ('...') tells the processor that the next
+segment is a continuation of the current segment. If the next segment
+is varbatum it will be added to 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, as we can now verify:
+
+  @quote_text.assert == "The file will contain\n\nthis text"
+
+

data/demo/07_toplevel.rdoc

@@ -0,0 +1,42 @@
+= Toplevel Simulation
+
+QED simulates Ruby's TOPLEVEL environment in both the Demonstrandum
+and the Applique contexts. This serves two important purposes.
+First, it provides the tester the environment that is most intutive.
+And second, and more importantly, it stays out of the actual
+TOPLEVEL space to prevent any potential interferece with any of 
+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
+
+We can also call a method defined in the toplevel.
+
+  toplevel_method.assert == true
+
+At the demonstrandum level we can define reusable methods.
+
+  def demo_method
+    true
+  end
+
+  demo_method.assert == true
+
+And at the demonstrandum level even singleton methods are accessible.
+
+  def self.singleton_method; true; end
+
+  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 }
+
+  named_method.assert == true
+
+
+

data/demo/08_cross_script.rdoc

@@ -0,0 +1,27 @@
+= 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
+
+And two instance varaibles.
+
+  @a = 1000
+  @b = 2000
+
+Also let check how it effect constants.
+
+  CROSS_SCRIPT_CONSTANT = "cross?"
+
+And a method.
+
+  def cross_script_method
+    "common"
+  end
+
+
+

data/demo/09_cross_script.rdoc

@@ -0,0 +1,27 @@
+= 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
+
+And two instance_varaibles
+
+  @a.assert! == 1000
+  @b.assert! == 2000
+
+
+Method definitions also do not cross QED scripts.
+
+  expect NameError do
+    cross_script_method
+  end
+
+Constants, on the other hand, like global variables do make
+their way across.
+
+  CROSS_SCRIPT_CONSTANT.assert == "cross?"
+

data/demo/10_constant_lookup.rdoc

@@ -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 the toplevel.
+
+  begin
+    UnknownConstant
+  rescue => err
+    # no colon means toplevel
+    /[^:]UnknownConstant/ =~ err.message
+  end
+
+A constant defined in the applique is visible.
+
+  APPLIQUE_CONSTANT.assert = true
+

data/demo/applique/constant.rb

@@ -0,0 +1,2 @@
+APPLIQUE_CONSTANT = true
+

data/demo/applique/env.rb

@@ -0,0 +1,5 @@
+Before do
+  @steps ||= 0
+  @steps += 1
+end
+

data/demo/applique/fileutils.rb

@@ -0,0 +1 @@
+require 'tmpdir'

data/demo/applique/markup.rb

@@ -0,0 +1,10 @@
+When "lets say we have", "document called (((.*?))) with the following contents" do |file, text|
+  file = Dir.tmpdir + '/sow/examples/' + file
+  FileUtils.mkdir_p(File.dirname(file))
+  File.open(file, 'w'){ |f| f << text }
+end
+
+When 'when we run these examples' do
+  Dir.chdir(Dir.tmpdir + '/sow/examples/')
+end
+

data/demo/applique/quote.rb

@@ -0,0 +1,4 @@
+When "we want to make an example out of the following text" do |text|
+  @quote_text = text
+end
+

data/demo/applique/toplevel.rb

@@ -0,0 +1,15 @@
+
+# Define a toplevel class to ensure it is accessible.
+class ToplevelClass
+end
+
+# Define a toplevel method to ensure it is also accessible.
+def toplevel_method
+  true
+end
+
+# Define a toplevel method to ensure it is also accessible.
+def self.toplevel_singleton_method
+  true
+end
+

data/demo/fixtures/data.txt

@@ -0,0 +1 @@
+Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

data/demo/fixtures/table.yml

@@ -0,0 +1,5 @@
+---
+- [ try  , TRY ]
+- [ me   , ME  ]
+- [ mc   , MC  ]
+

data/demo/helpers/advice.rb

@@ -0,0 +1,40 @@
+# This helper is used to demonstrate
+# the use of advice --before, after
+# and when clauses.
+
+count   = 0
+pudding = []
+
+When(:load) do
+  pudding << "load #{File.basename(__FILE__)}"
+end
+
+When(:unload) do
+  pudding << "unload #{File.basename(__FILE__)}"
+end
+
+#Before do
+#  pudding << :before_step
+#end
+
+#After do
+#  pudding << :after_step
+#end
+
+When /.*?/ do
+  count += 1
+end
+
+When /proof is in the pudding/ do
+  pudding << 'proof'
+end
+
+#When /proof is in the pussing/ do
+#  pudding << :proof
+#end
+
+#
+def prepare_example
+  "Hello, World!"
+end
+

data/demo/helpers/sample.rb

@@ -0,0 +1,4 @@
+#require 'ae/should'
+puts "This is just here to demonstrate that helpers are loaded."
+puts
+

data/demo/helpers/toplevel.rb

@@ -0,0 +1,6 @@
+class ToplevelExample
+  def foo
+    "foo"
+  end
+end
+

data/eg/hello_world.rdoc

@@ -0,0 +1,15 @@
+= Hello World
+
+Did you know that famous `Hello World` moniker is
+eleven characters long?
+
+    "Hello World".size.assert == 11
+
+To pass a piece of literal text on with a description
+we simply need to end it with a ...
+
+    Now this text will appear verbatim.
+    In the applique arguments.
+
+That's all.
+

data/lib/qed.rb

@@ -1,5 +1,24 @@
+require 'yaml'
+
 module QED
-  VERSION="2.1.1"  #:till: VERSION="<%= version %>"
+  DIRECTORY = File.dirname(__FILE__) + '/qed'
+
+  PROFILE = YAML.load(File.new(DIRECTORY + '/profile.yml')) rescue {}
+  PACKAGE = YAML.load(File.new(DIRECTORY + '/package.yml')) rescue {}
+
+  VERSION = PACKAGE.values_at('major','minor','patch','build').compact.join('.')
+
+  #
+  def self.const_missing(name)
+    key = name.to_s.downcase
+    if PACKAGE.key?(key)
+      PACKAGE[key]
+    elsif PROFILE.key?(key)
+      PROFILE[key]
+    else
+      super(name)
+    end
+  end
 end
 
 require 'qed/session'

data/lib/qed/advice.rb

@@ -8,7 +8,7 @@ module QED
   # This class tracks advice defined by demo scripts
   # and helpers. It is instantiated in Scope, so that
   # the advice methods will have access to the same
-  # local binding and the demo scripts themselves.
+  # local binding and the scripts themselves.
   #
   class Advice
 
@@ -21,41 +21,15 @@ module QED
       @events   = Events.new
     end
 
-    def call(type, *args)
+    def call(scope, type, *args)
       case type
       when :when
-        @patterns.call(*args)
+        @patterns.call(scope, *args)
       else
-        @events.call(type, *args)
+        @events.call(scope, type, *args)
       end
     end
   end
 
-  #
-  module Advisable
-
-    def __advice__
-      @__advice__ ||= Advice.new
-    end
-
-    def When(pattern, &procedure)
-      case pattern
-      when Symbol
-        __advice__.events.add(:"#{pattern}", &procedure)
-      else
-        __advice__.patterns.add(pattern, &procedure)
-      end
-    end
-
-    def Before(type=:code, &procedure)
-      __advice__.events.add(:"before_#{type}", &procedure)
-    end
-
-    def After(type=:code, &procedure)
-      __advice__.events.add(:"after_#{type}", &procedure)
-    end
-
-  end
-
 end
 

data/lib/qed/advice/events.rb

@@ -2,7 +2,8 @@ module QED
 
   class Advice
 
-    # Event advice: Before, After and Upon.
+    # This class encapsulates advice on symbolic targets,
+    # such as Before, After and Upon.
     #
     class Events
 
@@ -20,10 +21,12 @@ module QED
       end
 
       #
-      def call(type, *args)
+      def call(scope, type, *args)
+        
         @signals.each do |set|
           proc = set[type.to_sym]
-          proc.call(*args) if proc
+          #proc.call(*args) if proc
+          scope.instance_exec(*args, &proc) if proc
         end
       end