qed 2.3.0 → 2.4.0

data/History.rdoc

@@ -1,5 +1,20 @@
 = RELEASE HISTORY
 
+== 2.4.0 / 2010-09-02
+
+All engines go! QED has not been tested against 1.8.6, 1.8.7 and 1.9.2.
+Underthehood steps are not organized in doubely-linked lists, which makes
+them much more robust and flexible. This release also improves scoping,
+test counts, and inline documentation parsing.
+
+Changes:
+
+* Use new doubly-linked list step design.
+* Fix -r option on command line.
+* Provide #instance_exec core extension for Ruby 1.8.6.
+* Scope is extended by and includes applique.
+
+
 == 2.3.0 / 2010-07-14
 
 Bug to the scurry! QED has broken through the code/document ceiling and

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/eg/view_error.rdoc

@@ -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/eg/website.rdoc

@@ -0,0 +1,12 @@
+= Addition
+
+  require 'calculator'
+  calculator = Caclulater.new
+
+A Calculator can add two numbers. 
+
+  calculator.push 2
+  calculator.push 2
+  calculator.add
+  calculator.output.assert == 4
+

data/lib/qed/advice.rb

@@ -1,3 +1,5 @@
+require 'qed/core_ext/instance_exec'
+
 module QED
 
   # = Advice
@@ -12,8 +14,7 @@ module QED
   #
   # == Pattern Matchers (When)
   #
-  # Matchers are evaluated when they match a blocks
-  # commentary.
+  # Matchers are evaluated when they match a description.
   #
   # == Event Signals (Before, After)
   #
@@ -67,7 +68,7 @@ module QED
 
     #
     def call_matchers(scope, section)
-      match = section.commentary
+      match = section.text
       args  = section.arguments
       matchers.each do |(patterns, proc)|
         compare = match

data/lib/qed/command.rb

@@ -134,7 +134,7 @@ module QED
           @options[:loadpath] ||= []
           @options[:loadpath].concat(arg.split(/[:;]/).map{ |dir| File.expand_path(dir) })
         end
-        opt.on('--require', "-r", "require library") do |arg|
+        opt.on('--require', "-r LIB", "require library") do |arg|
           @options[:requires] ||= []
           @options[:requires].concat(arg.split(/[:;]/)) #.map{ |dir| File.expand_path(dir) })
         end
@@ -207,7 +207,7 @@ module QED
         end
       end
       files = files.flatten.uniq
-      files.map{|f| File.expand_path(f) }.sort
+      files.map{|f| File.expand_path(f) }.uniq.sort
     end
 
     # Parse command-line options along with profile options.
@@ -349,4 +349,3 @@ module QED
   end
 
 end
-

data/lib/qed/core_ext/instance_exec.rb

@@ -0,0 +1,36 @@
+class Object
+
+  unless method_defined?(:instance_exec) # 1.9
+    require 'thread'
+
+    module InstanceExecMethods #:nodoc:
+    end
+
+    include InstanceExecMethods
+
+    # Evaluate the block with the given arguments within the context of
+    # this object, so self is set to the method receiver.
+    #
+    # From Mauricio's http://eigenclass.org/hiki/bounded+space+instance_exec
+    #
+    # This version has been borrowed from Rails for compatibility sake.
+    def instance_exec(*args, &block)
+      begin
+        old_critical, Thread.critical = Thread.critical, true
+        n = 0
+        n += 1 while respond_to?(method_name = "__instance_exec#{n}")
+        InstanceExecMethods.module_eval { define_method(method_name, &block) }
+      ensure
+        Thread.critical = old_critical
+      end
+
+      begin
+        send(method_name, *args)
+      ensure
+        InstanceExecMethods.module_eval { remove_method(method_name) } rescue nil
+      end
+    end
+
+  end
+
+end

data/lib/qed/demo.rb

@@ -93,4 +93,3 @@ module QED
   end
 
 end
-

data/lib/qed/evaluator.rb

@@ -8,7 +8,7 @@ module QED
     #
     def initialize(script, *observers)
       @script  = script
-      @ast     = script.parse
+      @steps   = script.parse
 
       #@file    = script.file
       #@scope   = script.scope
@@ -21,46 +21,85 @@ module QED
     #
     def run
       advise!(:before_demo, @script)
-      process
+      advise!(:demo, @script)
+      run_steps
       advise!(:after_demo, @script)
     end
 
     #
-    def process
-      @ast.each do |section|
-        evaluate(section)
+    def run_steps #process
+      @steps.each do |step|
+        evaluate(step)
       end
     end
 
-    # Evaluate a demo section.
-    def evaluate(section)
-      advise!(:text, section) # TODO: rename to :step?
-      evaluate_links(section)
-      advise!(:before_step, section, @script.file)
+    #
+    def evaluate(step)
+      type = step.type
+      advise!(:before_step, step) #, @script.file)
+      advise!("before_#{type}".to_sym, step) #, @script.file)
+      case type
+      when :head
+        evaluate_head(step)
+      when :desc
+        evaluate_desc(step)
+      when :data
+        evaluate_data(step)
+      when :code
+        evaluate_code(step)
+      else
+        raise "fatal: unknown #{type}"
+      end
+      advise!("after_#{type}".to_sym, step) #, @script.file)
+      advise!(:after_step, step) #, @script.file)
+    end
+
+    #
+    def evaluate_head(step)
+      advise!(:head, step)
+    end
+
+    #
+    def evaluate_desc(step)
+      evaluate_links(step)
       begin
-        advise!(:when, section)
-        # TODO: how to handle catching asserts in advice?
+        advise!(:desc, step)
+        advise!(:when, step) # triggers matchers
+      rescue SystemExit
+        pass!(step)
+      rescue Assertion => exception
+        fail!(step, exception)
+      rescue Exception => exception
+        error!(step, exception)
+      else
+        pass!(step)
       end
-      if section.code?
-        begin
-          advise!(:code, section)
-          @script.evaluate(section.eval_code, section.lineno)
-        rescue SystemExit
-          pass!(section)
-        rescue Assertion => exception
-          fail!(section, exception)
-        rescue Exception => exception
-          error!(section, exception)
-        else
-          pass!(section)
-        end
+    end
+
+    #
+    def evaluate_data(step)
+      advise!(:data, step)
+    end
+
+    # Evaluate a demo step.
+    def evaluate_code(step)
+      begin
+        advise!(:code, step)
+        @script.evaluate(step.code, step.lineno)
+      rescue SystemExit
+        pass!(step)
+      rescue Assertion => exception
+        fail!(step, exception)
+      rescue Exception => exception
+        error!(step, exception)
+      else
+        pass!(step)
       end
-      advise!(:after_step, section, @script.file)
     end
 
-    # TODO: Not sure how to handle loading links in comment mode.
-    def evaluate_links(section)
-      section.commentary.scan(/\[qed:\/\/(.*?)\]/) do |match|
+    # TODO: Not sure how to handle loading links in --comment runner mode.
+    def evaluate_links(step)
+      step.text.scan(/\[qed:\/\/(.*?)\]/) do |match|
         file = $1
         # relative to demo script
         if File.exist?(File.join(@script.directory,file))
@@ -77,25 +116,25 @@ module QED
     end
 
     #
-    def pass!(section)
-      advise!(:pass, section)
+    def pass!(step)
+      advise!(:pass, step)
     end
 
     #
-    def fail!(section, exception)
-      advise!(:fail, section, exception)
+    def fail!(step, exception)
+      advise!(:fail, step, exception)
       #raise exception
     end
 
     #
-    def error!(section, exception)
-      advise!(:error, section, exception)
+    def error!(step, exception)
+      advise!(:error, step, exception)
       #raise exception
     end
 
     #
     def import!(file)
-      advise!(:unload)
+      advise!(:unload) # should this also occur just befor after_demo ?
       eval(File.read(file), @script.binding, file)
       advise!(:load, file)
     end

data/lib/qed/extensions/filefixtures.rb

@@ -0,0 +1,27 @@
+# This extension provides a simple means for 
+# create file-system fixtures.
+
+require 'erb'
+
+# Set global temporary directory.
+$tmpdir = 'tmp'
+
+#
+def copy_fixture(name, tmpdir=$tmpdir)
+  FileUtils.mkdir(tmpdir)
+  srcdir = File.join(demo_directory, 'fixtures', name)
+  paths  = Dir.glob(File.join(srcdir, '**', '*'), File::FNM_DOTMATCH)
+  paths.each do |path|
+    basename = File.basename(path)
+    next if basename == '.'
+    next if basename == '..'
+    dest = File.join(tmpdir, path.sub(srcdir+'/', ''))
+    if File.directory?(path)
+      FileUtils.mkdir(dest)
+    else
+      text = ERB.new(File.read(path)).result
+      File.open(dest, 'w'){ |f| f << text }
+    end
+  end
+end
+

data/lib/qed/extensions/shell_session.rb

@@ -0,0 +1,2 @@
+# This extension provides a basic means for testing
+# shell commands.

data/lib/qed/meta/data.rb

@@ -0,0 +1,29 @@
+Object.__send__(:remove_const, :VERSION) if Object.const_defined?(:VERSION)      # becuase Ruby 1.8~ gets in the way
+
+module QED
+
+  def self.__DIR__
+    File.dirname(__FILE__)
+  end
+
+  def self.gemfile
+    @gemfile ||= (
+      require 'yaml'
+      YAML.load(File.new(__DIR__ + '/gemfile'))
+    )
+  end
+
+  def self.profile
+    @profile ||= (
+      require 'yaml'
+      YAML.load(File.new(__DIR__ + '/profile'))
+    )
+  end
+
+  def self.const_missing(name)
+    key = name.to_s.downcase
+    gemfile[key] || profile[key] || super(name)
+  end
+
+end
+

data/lib/qed/meta/gemfile

@@ -0,0 +1,10 @@
+name: qed
+version: 2.4.0
+date: 2010-09-02
+
+requires:
+- ansi
+- facets
+- ae (test)
+- syckle (build)
+

data/lib/qed/parser.rb

@@ -36,7 +36,7 @@ module QED
       when :comment
         parse_comment_lines
       else
-        index = -1
+        index = 0  #-1
         File.readlines(file).to_a.map do |line|
           [index += 1, line]
         end
@@ -46,25 +46,32 @@ module QED
     # TODO: It would be nice if we could get ther require statement for the 
     # comment mode to be relative to an actual loadpath.
     def parse_comment_lines
-      omit = false
+      ruby_omit = false
+      rdoc_omit = false
       lines = [
         [0, "Load #{File.basename(file)} script.\n"],
         [0, "\n"],
         [0, "  require '#{file}'\n"]
       ]
-      index = 0
+      index = 1
       File.readlines(file).each do |l|
         case l
+        when /^=begin(?!\s+qed)/
+          ruby_omit = true
+        when /^=end/
+          ruby_omit = false
         when /^\s*\#\-\-\s*$/
-          omit = true
+          rdoc_omit = true
         when /^\s*\#\+\+\s*$/
-          omit = false
-        when /^\s*\#\ \-\-/  # ?
-          # -- skip internal comments
-        when /^\s*\#/    
-          lines << [index, l.lstrip.sub(/^\#\ ?/, '')] unless omit
+          rdoc_omit = false
+        ##when /^\s*\#\ \-\-/  # not needed just double comment
+        ##  # -- skip internal comments
+        when /^\s*##/
+          ## skip internal comments
+        when /^\s*\#/
+          lines << [index, l.lstrip.sub(/^\#\ ?/, '')] unless (ruby_omit or rdoc_omit)
         else
-          lines << [index, "\n"] unless lines.last[1] == "\n"
+          lines << [index, "\n"] unless lines.last[1] == "\n" unless (ruby_omit or rdoc_omit)
         end
         index += 1
       end
@@ -135,33 +142,37 @@ module QED
 
     def parse
       tree  = []
-      mode  = :rem
+      flush = true
       pend  = false
-      block = Block.new
+      block = Block.new(file)
       lines.each do |lineno, line|
         case line
         when /^\s*$/
-          case mode
-          when :rem
-            pend = true unless line == 0
-            block.rem << [lineno, line]
-          when :raw
+          if flush
+            pend = true unless lineno == 0
+            block.raw << [lineno, line]
+          else
             block.raw << [lineno, line]
           end
         when /\A\s+/
-          mode = :raw
+          if flush
+            tree << block.ready!(flush, tree.last)
+            block = Block.new(file)         
+          end
+          pend  = false
+          flush = false
           block.raw << [lineno, line]
         else
-          if pend || mode == :raw
-            pend = false
-            mode = :rem
-            tree << block.ready!
-            block = Block.new
+          if pend || !flush
+            tree << block.ready!(flush, tree.last)
+            pend  = false
+            flush = true
+            block = Block.new(file)
           end
-          block.rem << [lineno, line]
+          block.raw << [lineno, line]
         end
       end
-      tree << block.ready!
+      tree << block.ready!(flush, tree.last)
       @ast = tree
     end
 
@@ -176,97 +187,160 @@ module QED
 
     # Section Block
     class Block
-      # Block commentary.
-      attr :rem
-
       # Block raw code/text.
       attr :raw
 
+      # previous block
+      attr :back_step
+
+      # next block
+      attr :next_step
+
       #
-      def initialize
-        @rem = []
-        @raw = []
-        @has_code = true
+      def initialize(file)
+        @file = file
+        @raw  = []
+        @type = :description
+        @back_step = nil
+        @next_step = nil
       end
 
       #
-      def ready!
-        @commentary = rem.map{ |lineno, line| line }.join
-        @example    = raw.map{ |lineno, line| line }.join
-        @has_code   = false if @raw.empty?
-        @has_code   = false if continuation?
+      def ready!(flush, back_step)
+        @flush     = flush
+        @back_step = back_step
+
+        @text  = raw.map{ |lineno, line| line }.join
+        @type  = parse_type
+
+        @back_step.next_step = self if @back_step
+
         self
       end
 
       #
-      def commentary
-        @commentary
+      def to_s
+        case type
+        when :description
+          text
+        else
+          text
+        end
+      end
+
+      #
+      def text
+        @text
       end
 
       #
-      def example
-        @example
+      def flush?
+        @flush
       end
 
       # Returns an Array of prepared example text
       # for use in advice.
       def arguments
-        continuation? ? [example_argument] : []
+        if next_step && next_step.data?
+          [next_step.sample_text]
+        else
+          []
+        end
       end
 
-      #
-      def code?
-        @has_code
+      # What type of block is this?
+      def type
+        @type
       end
 
-      # First line of example text.
-      def lineno
-        @line ||= @raw.first.first
-      end
+      #
+      def head? ; @type == :head ; end
 
       #
-      def code
-        @example
-      end
+      def desc? ; @type == :desc ; end
 
       #
-      def eval_code
-        @eval_code ||= tweak_code
+      def code? ; @type == :code ; end
+
+      # Any commentary ending in `...` or `:` will mark the following
+      # block as a plain text *sample* and not example code to be evaluated.
+      def data? ; @type == :data ; end
+
+      #
+      alias_method :header?, :head?
+
+      #
+      alias_method :description?, :desc?
+
+
+      # First line of example text.
+      def lineno
+        @line ||= @raw.first.first
       end
 
       #
-      def tweak_code
-        code = example.dup
-        code.gsub!(/\n\s*\#\ ?\=\>/, '.assert == ')
-        code.gsub!(/\s*\#\ ?\=\>/, '.assert == ')
-        code
+      def code
+        @code ||= tweak_code
       end
 
       # Clean up the example text, removing unccesseary white lines
       # and triple quote brackets, but keep indention intact.
-      def clean_example
-        text = example.chomp.sub(/\A\n/,'')
-        if md = /\A["]{3,}(.*?)["]{3,}\Z/.match(text)
-          text = md[1]
+      def clean_text
+        str = text.chomp.sub(/\A\n/,'')
+        if md = /\A["]{3,}(.*?)["]{3,}\Z/.match(str)
+          str = md[1]
         end
-        text.rstrip
+        str.rstrip
       end
 
-      # When the example is raw text and passed to an adivce block, this
+      # When the text is sample text and passed to an adivce block, this
       # provides the prepared form of the example text, removing white lines,
       # triple quote brackets and indention.
-      def example_argument
-        text = example.tabto(0).chomp.sub(/\A\n/,'')
-        if md = /\A["]{3,}(.*?)["]{3,}\Z/.match(text)
-          text = md[1]
+      def sample_text
+        str = text.tabto(0).chomp.sub(/\A\n/,'')
+        if md = /\A["]{3,}(.*?)["]{3,}\Z/.match(str)
+          str = md[1]
+        end
+        str.rstrip
+      end
+
+      # TODO: object_hexid
+      def inspect
+        %[#<Block:#{object_id} "#{text[0..25]} ...">]
+      end
+
+    protected
+
+      #
+      def next_step=(n)
+        @next_step = n
+      end
+
+    private
+
+      #
+      def parse_type
+        if flush?
+          if /\A[=#]/ =~ text
+            :head
+          else
+            :desc
+          end
+        else
+          if back_step && /(\.\.\.|\:)\s*\Z/m =~ back_step.text.strip
+            :data
+          else
+            :code
+          end
         end
-        text.rstrip
       end
 
-      # And commentary ending in `...` or `:` will mark the following
-      # example as plain text and not code to be evaluated.
-      def continuation?
-        /(\.\.\.|\:)\s*\Z/m =~ commentary
+      #
+      def tweak_code
+        code = text.dup
+        code.gsub!(/\n\s*\#\ ?\=\>/, '.assert = ')
+        code.gsub!(/\s*\#\ ?\=\>/, '.assert = ')
+        code
       end
 
     end