qed 2.2.2 → 2.3.0

data/demo/07_toplevel.rdoc

@@ -38,5 +38,3 @@ For instance, #define_method can be used.
 
   named_method.assert == true
 
-
-

data/lib/qed/advice.rb

@@ -12,15 +12,14 @@ module QED
   #
   # == Pattern Matchers (When)
   #
-  # Matchers are evaluated in Scope context, via #instance_exec,
-  # so that the advice methods will have access to the same
-  # scope as the demonstrandum themselves.
+  # Matchers are evaluated when they match a blocks
+  # commentary.
   #
   # == Event Signals (Before, After)
   #
   # Event advice are triggered on symbolic targets which 
   # represent an event in the evaluation process, such as
-  # before any demo is run, or after all demo finish running.
+  # before an example is run, or after a demo finishes.
   #
   class Advice
 
@@ -68,10 +67,9 @@ module QED
 
     #
     def call_matchers(scope, section)
-      match = section.text
-      args  = section.args
-
-      @matchers.each do |(patterns, proc)|
+      match = section.commentary
+      args  = section.arguments
+      matchers.each do |(patterns, proc)|
         compare = match
         matched = true
         params  = []

data/lib/qed/command.rb

@@ -73,6 +73,9 @@ module QED
     # Move to root directory?
     attr_accessor :root
 
+    # Parse mode.
+    attr_accessor :mode
+
     #
     # TODO: Should extension and profile have a common reference?
     def initialize
@@ -121,6 +124,9 @@ module QED
         opt.on('--root', '-R', "run command from project's root directory") do
           @options[:root] = true
         end
+        opt.on('--comment', '-c', "Run comment code.") do
+          @options[:mode] = :comment
+        end
         opt.on('--ext', '-e NAME', "runtime extension [default]") do |name|
           @options[:extension] = name
         end
@@ -157,30 +163,51 @@ module QED
 
     # Default recognized demos file types.
     DEMO_TYPES = %w{qed rdoc md markdown}
+    CODE_TYPES = %w{rb}
 
-    # Returns a list of demo files.
+    # Returns a list of demo files. The files returned depends on the
+    # +files+ attribute and if none given, then the current run mode.
     def demos
       @demos ||= (
-        files = self.files
-        if files.empty?
-          files << DEMO_LOCATION
+        if mode == :comment
+          demos_in_comment_mode
+        else
+          demos_in_normal_mode
         end
-        files = files.map{|pattern| Dir[pattern]}.flatten.uniq
-        files = files.map do |file|
-          if File.directory?(file)
-            Dir[File.join(file,'**','*.{' + DEMO_TYPES.join(',') + '}')]
-          else
-            file
-          end
-        end
-        files = files.flatten.uniq
-        files.map{|f| File.expand_path(f) }.sort
       )
     end
 
-    # Session instance.
-    def session
-      @session ||= Session.new(demos, :format=>format, :trace=>trace)
+    # Collect default files to process in normal demo mode.
+    def demos_in_normal_mode
+      demos_gather(DEMO_LOCATION, DEMO_TYPES)
+    end
+
+    # Collect default files to process in code comment mode.
+    #
+    # TODO: Sure removing applique files is the best approach?
+    #
+    # TODO: Either add environment alond with applique or deprecate environment
+    # as an alternate name.
+    def demos_in_comment_mode
+      files = demos_gather('lib', CODE_TYPES)
+      files = files.reject{ |f| f.index('applique/') }  # don't include applique files ???
+      files
+    end
+
+    #
+    def demos_gather(default_location, extensions=DEMO_TYPES)
+      files = self.files
+      files << default_location if files.empty?
+      files = files.map{|pattern| Dir[pattern]}.flatten.uniq
+      files = files.map do |file|
+        if File.directory?(file)
+          Dir[File.join(file,'**','*.{' + extensions.join(',') + '}')]
+        else
+          file
+        end
+      end
+      files = files.flatten.uniq
+      files.map{|f| File.expand_path(f) }.sort
     end
 
     # Parse command-line options along with profile options.
@@ -221,6 +248,11 @@ module QED
       end
     end
 
+    # Session instance.
+    def session
+      @session ||= Session.new(demos, :format=>format, :trace=>trace, :mode=>mode)
+    end
+
     # Project's root directory.
     def root_directory
       @root_directory ||= find_root

data/lib/qed/{script.rb → demo.rb}

@@ -6,9 +6,9 @@ module QED
   require 'qed/parser'
   require 'qed/evaluator'
 
-  # = Script
+  # = Demo
   #
-  class Script
+  class Demo
 
     #
     attr :applique
@@ -16,14 +16,18 @@ module QED
     # Demonstrandum file.
     attr :file
 
+    #
+    attr :mode
+
     #
     attr :scope
 
     # New Script
-    def initialize(applique, file, scope=nil)
-      @applique = applique.dup # localize copy of applique
+    def initialize(file, applique, options={})
       @file     = file
-      @scope    = scope || Scope.new(applique, file)
+      @applique = applique.dup # localize copy of applique
+      @scope    = options[:scope] || Scope.new(applique, file)
+      @mode     = options[:mode]
       @binding  = @scope.__binding__
       #@loadlist = []
       #apply_environment
@@ -77,7 +81,7 @@ module QED
     # Parse script.
     # Retruns an abstract syntax tree.
     def parse
-      Parser.new(file).parse
+      Parser.new(file, :mode=>mode).parse
     end
 
     #

data/lib/qed/evaluator.rb

@@ -20,48 +20,47 @@ module QED
 
     #
     def run
-      advise!(:before_document, @script)
+      advise!(:before_demo, @script)
       process
-      advise!(:after_document, @script)
+      advise!(:after_demo, @script)
     end
 
     #
     def process
       @ast.each do |section|
-        case section.type
-        when :code
-          evaluate_code(section)
-        when :text
-          evaluate_text(section)
-        end
+        evaluate(section)
       end
     end
 
-    #
-    def evaluate_code(section)
-      advise!(:before_code, section, @script.file)
+    # Evaluate a demo section.
+    def evaluate(section)
+      advise!(:text, section) # TODO: rename to :step?
+      evaluate_links(section)
+      advise!(:before_step, section, @script.file)
       begin
-        advise!(:code, section)
-        @script.evaluate(section.text, section.line)
-        pass!(section)
-      rescue Assertion => exception
-        fail!(section, exception)
-      rescue Exception => exception
-        error!(section, exception)
+        advise!(:when, section)
+        # TODO: how to handle catching asserts in advice?
       end
-      advise!(:after_code, section, @script.file)
-    end
-
-    #
-    def evaluate_text(section)
-      advise!(:text, section)
-      evaluate_links(section)
-      advise!(:when, section)
+      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
+      advise!(:after_step, section, @script.file)
     end
 
-    #
+    # TODO: Not sure how to handle loading links in comment mode.
     def evaluate_links(section)
-      section.text.scan(/\[qed:\/\/(.*?)\]/) do |match|
+      section.commentary.scan(/\[qed:\/\/(.*?)\]/) do |match|
         file = $1
         # relative to demo script
         if File.exist?(File.join(@script.directory,file))
@@ -72,7 +71,7 @@ module QED
         when '.rb'
           import!(file)
         else
-          Script.new(@script.applique, file, @script.scope).run
+          Demo.new(file, @script.applique, :scope=>@script.scope).run
         end
       end
     end

data/lib/qed/package.yml

@@ -1,5 +1,5 @@
 name : qed
 major: 2
-minor: 2
-patch: 2
-date : 2010-06-21
+minor: 3
+patch: 0
+date : 2010-07-14

data/lib/qed/parser.rb

@@ -5,25 +5,80 @@ module QED
   # evaluator.
   # 
   # Technically is defines it's own markup language
-  # but for interoperability sake it ...
+  # but for interoperability sake it is RDoc and a bit of
+  # support for Markdown.
   class Parser
 
     #
-    def initialize(file)
-      @lines = File.readlines(file).to_a
-      @ast = []
+    def initialize(file, options={})
+      @file    = file
+      @options = options
+      @ast     = []
     end
 
     # Abstract Syntax Tree
     attr :ast
 
+    # File to parse.
+    attr :file
+
+    # Parser options.
+    attr :options
+
+    #
+    def lines
+      @lines ||= parse_lines
+    end
+
+    #
+    def parse_lines
+      case options[:mode]
+      when :comment
+        parse_comment_lines
+      else
+        index = -1
+        File.readlines(file).to_a.map do |line|
+          [index += 1, line]
+        end
+      end
+    end
+
+    # 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
+      lines = [
+        [0, "Load #{File.basename(file)} script.\n"],
+        [0, "\n"],
+        [0, "  require '#{file}'\n"]
+      ]
+      index = 0
+      File.readlines(file).each do |l|
+        case l
+        when /^\s*\#\-\-\s*$/
+          omit = true
+        when /^\s*\#\+\+\s*$/
+          omit = false
+        when /^\s*\#\ \-\-/  # ?
+          # -- skip internal comments
+        when /^\s*\#/    
+          lines << [index, l.lstrip.sub(/^\#\ ?/, '')] unless omit
+        else
+          lines << [index, "\n"] unless lines.last[1] == "\n"
+        end
+        index += 1
+      end
+      lines
+    end
+
+=begin
     # Parse the demo into an abstract syntax tree.
     #
     # TODO: I know there has to be a faster way to do this.
     def parse
       blocks = [[]]
       state  = :none
-      @lines.each_with_index do |line, lineno|
+      lines.each do |lineno, line|
         case line
         when /^$/
           case state 
@@ -76,6 +131,39 @@ module QED
         #cont = (/\.\.\.\s*^/ =~ text ? true : false)
       end
     end
+=end
+
+    def parse
+      tree  = []
+      mode  = :rem
+      pend  = false
+      block = Block.new
+      lines.each do |lineno, line|
+        case line
+        when /^\s*$/
+          case mode
+          when :rem
+            pend = true unless line == 0
+            block.rem << [lineno, line]
+          when :raw
+            block.raw << [lineno, line]
+          end
+        when /\A\s+/
+          mode = :raw
+          block.raw << [lineno, line]
+        else
+          if pend || mode == :raw
+            pend = false
+            mode = :rem
+            tree << block.ready!
+            block = Block.new
+          end
+          block.rem << [lineno, line]
+        end
+      end
+      tree << block.ready!
+      @ast = tree
+    end
 
     # TODO: We need to preserve the indentation for the verbatim reporter.
     #def clean_quote(text)
@@ -86,82 +174,101 @@ module QED
     #  text.rstrip
     #end
 
-    #
-    class Section
-      attr :text
-      attr :line
-      def initialize(text, line)
-        @text = text
-        @line = line
+    # Section Block
+    class Block
+      # Block commentary.
+      attr :rem
+
+      # Block raw code/text.
+      attr :raw
+
+      #
+      def initialize
+        @rem = []
+        @raw = []
+        @has_code = true
       end
-    end
 
-    #
-    class TextSection < Section
+      #
+      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?
+        self
+      end
 
-      attr :args
+      #
+      def commentary
+        @commentary
+      end
 
-      attr :cont
+      #
+      def example
+        @example
+      end
 
-      def initialize(text, line, *args)
-        @text = text
-        @line = line
-        @args = args
-        @cont = []
+      # Returns an Array of prepared example text
+      # for use in advice.
+      def arguments
+        continuation? ? [example_argument] : []
       end
 
       #
-      def <<(text)
-        @cont << clean_continuation(text)
-        @args << block_continuation(text)
+      def code?
+        @has_code
+      end
+
+      # First line of example text.
+      def lineno
+        @line ||= @raw.first.first
       end
 
       #
-      def type
-        :text
+      def code
+        @example
       end
 
-      # TODO: Use ':' or '...' ?
-      def cont?
-        #/\:\s*\Z/m =~ text
-        /\.\.\.\s*\Z/m =~ text
+      #
+      def eval_code
+        @eval_code ||= tweak_code
       end
 
-      # Clean up the text, removing unccesseary white lines and triple
-      # quote brackets, but keep indention intact.
-      def clean_continuation(text)
-        text = text.chomp.sub(/\A\n/,'')
+      #
+      def tweak_code
+        code = example.dup
+        code.gsub!(/\n\s*\#\ ?\=\>/, '.assert == ')
+        code.gsub!(/\s*\#\ ?\=\>/, '.assert == ')
+        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]
         end
         text.rstrip
       end
 
-      # Block the text, removing white lines, triple quote brackets
-      # and indention.
-      def block_continuation(text)
-        text = text.tabto(0).chomp.sub(/\A\n/,'')
+      # When the example is raw 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]
         end
         text.rstrip
       end
-    end
 
-    #
-    class CodeSection < Section
-      #attr :args
-      def intialize(text, line) #, *args)
-        @text = text
-        @line = line
-        #@args = args
-      end
-      #def <<(arg)
-      #  @args << arg
-      #end
-      def type
-        :code
+      # 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
       end
+
     end
 
   end