tablatom-rubydoctest 0.2.1 → 1.0.0

data/lib/result.rb

@@ -0,0 +1,63 @@
+$:.unshift(File.dirname(__FILE__)) unless
+  $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+
+require 'lines'
+
+module RubyDocTest
+  class Result < Lines
+    
+    def normalize_result(s)
+      s.gsub(/:0x[a-f0-9]{8}>/, ':0xXXXXXXXX>').strip
+    end
+    
+    def expected_result
+      @expected_result ||=
+        begin
+          lines.first =~ /^#{Regexp.escape(indentation)}=>\s(.*)$/
+          ([$1] + (lines[1..-1] || [])).join("\n")
+        end
+    end
+    
+    # === Tests
+    # doctest: Strings should match
+    # >> r = RubyDocTest::Result.new(["=> 'hi'"])
+    # >> r.matches? 'hi'
+    # => true
+    #
+    # >> r = RubyDocTest::Result.new(["=> \"hi\""])
+    # >> r.matches? "hi"
+    # => true
+    #
+    # doctest: Regexps should match
+    # >> r = RubyDocTest::Result.new(["=> /^reg.../"])
+    # >> r.matches? /^reg.../
+    # => true
+    #
+    # >> r = RubyDocTest::Result.new(["=> /^reg.../"])
+    # >> r.matches? /^regexp/
+    # => false
+    #
+    # doctest: Arrays should match
+    # >> r = RubyDocTest::Result.new(["=> [1, 2, 3]"])
+    # >> r.matches? [1, 2, 3]
+    # => true
+    #
+    # doctest: Arrays of arrays should match
+    # >> r = RubyDocTest::Result.new(["=> [[1, 2], [3, 4]]"])
+    # >> r.matches? [[1, 2], [3, 4]]
+    # => true
+    #
+    # doctest: Hashes should match
+    # >> r = RubyDocTest::Result.new(["=> {:one => 1, :two => 2}"])
+    # >> r.matches?({:two => 2, :one => 1})
+    # => true
+    def matches?(actual_result)
+      normalize_result(actual_result.inspect) ==
+      normalize_result(expected_result) \
+        or
+      actual_result == eval(expected_result, TOPLEVEL_BINDING)
+    rescue Exception
+      false
+    end
+  end
+end

data/lib/rubydoctest.rb

@@ -2,270 +2,28 @@ $:.unshift(File.dirname(__FILE__)) unless
   $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
 
 require 'irb'
+require "runner"
 
-class RubyDocTest
+module RubyDocTest
   
   class << self
-    attr_accessor :trace
-  end
-
-  PROMPT_RX = /^[>?]>( |\s*$)/
-  
-  RESULT_RX = /^=> /
-  
-  CODE_LINE_RX = /^(    |\t)/
-  
-  def initialize(src, file_name)
-    @passed = 0
-    @block_count = 0
-    @failures = []
-    @src_lines = src.split("\n")
-    @line_num = 0
-    @file_name = file_name
+    attr_accessor :trace, :ignore_interactive
+    attr_writer :output_format
     
-    # next_line # get first line
-  end
-  
-  def run
-    run_file
-    print_report
-  end
-  
-  attr_accessor :passed, :failures, :current_line, :src_lines, :line_num, :block_count
-  
-  def environment
-    TOPLEVEL_BINDING
-  end
-  
-  def next_line
-    @line_num += 1
-    @current_line = src_lines.shift
-  end
-  
-  def next_line?
-    src_lines.any?
-  end
-  
-  def strip_prompt(s)
-    s.sub(PROMPT_RX, "")
-  end
-
-  def result_start?(s=current_line)
-    s =~ RESULT_RX
-  end
-  
-  def string_result_start?(s=current_line)
-    s =~ /^=>""/
-  end
-  
-  def statement_start?(s=current_line)
-    s =~ PROMPT_RX
-  end
-  
-  def strip_result_marker(s=current_line)
-    s.sub(RESULT_RX, "")
-  end
-  
-  def normalize_result(s)
-    s.gsub(/:0x[a-f0-9]{8}>/, ':0xXXXXXXXX>').strip
-  end
-  
-  def code_line?(s=current_line)
-    s =~ CODE_LINE_RX
-  end
-  
-  def code_block_start?(s=current_line)
-    l = unindent_code_line
-    code_line? && (statement_start?(l) || irb_interrupt?(l))
-  end
-  
-  def blank_line?(s=current_line)
-    s =~ /^\s*$/
-  end
-  
-  def irb_interrupt?(line)
-    line =~ /!!!/
-  end
-  
-  def run_file
-    # run_code_block if code_block_start?
-    while next_line
-      run_code_block if code_block_start?
-    end
-    failures.length == 0
-  end
-  
-  def unindent_code_line(s=current_line)
-    s.sub(CODE_LINE_RX, "")
-  end
-  
-  
-  def get_code_lines
-    lines = []
-    while blank_line? || code_line?
-      lines << [unindent_code_line, line_num]
-      next_line
-    end
-    lines.pop while blank_line?(lines.last)
-    lines
-  end
-  
-  
-  def run_code_block
-    self.block_count += 1
-    
-    lines = get_code_lines
-    
-    reading = :statement
-
-    result = nil
-    statement = ""
-    statement_line = lines.first.last
-    lines.each do |line, line_num|
-      
-      if irb_interrupt?(line)
-        evaluate(statement, statement_line) unless statement == ""
-        
-        puts statement unless statement.blank?
-        puts "=> #{result}" unless result.blank?
-        puts
-        
-        start_irb
-        line = nil
-        
-      elsif string_result_start?(line)
-        reading = :string_result
-        line = nil
-        result = ""
-        
-      elsif result_start?(line)
-        reading = :ruby_result
-        line = strip_result_marker(line)
-        result = ""
-
-      elsif statement_start?(line)
-        if result
-          # start of a new statement
-          if reading == :string_result
-            # end of a string result statement
-            result.chomp!
-            run_statement(statement, result, statement_line, true)
-          else
-            run_statement(statement, result, statement_line)
-          end
-          statement_line = line_num
-          statement = ""
-          result = nil
-        end
-        reading = :statement
-      end
-      
-      if reading == :statement
-        # The statement has a prompt on every line
-        if line
-          line = strip_prompt(line)
-          statement << line + "\n" 
-        end
+    def output_format
+      if @output_format == :ansi or (@output_format.nil? and STDOUT.tty?)
+        :ansi
+      elsif @output_format == :html
+        :html
       else
-        # There's only one result marker - stripped above
-        result << line + "\n" if line
+        :plain
       end
-      
-    end
-    
-    if result.nil?
-      # The block ends with a statement - just evaluate it
-      evaluate(statement, statement_line)
-    else
-      run_statement(statement, result, statement_line)
-    end
-  end
-  
-  
-  def start_irb
-    IRB.init_config(nil)
-    IRB.conf[:PROMPT_MODE] = :SIMPLE
-    irb = IRB::Irb.new(IRB::WorkSpace.new(environment))
-    IRB.conf[:MAIN_CONTEXT] = irb.context
-    irb.eval_input
-  end
-  
-  
-  def run_statement(statement, expected_result, statement_line, string_comparison=false)
-    actual_result = evaluate(statement, statement_line)
-    
-    if result_matches?(expected_result, actual_result, string_comparison)
-      self.passed += 1
-    else
-      actual_result = actual_result.inspect unless string_comparison
-      failures << [statement, actual_result, expected_result, statement_line]
-    end
-  end
-  
-  
-  def result_matches?(expected_result, actual_result, string_comparison)
-    if string_comparison
-      actual_result == expected_result
-    else
-      actual_result = actual_result.inspect
-      normalize_result(expected_result) == normalize_result(actual_result) or
-          # If the expected result looks like a literal, see if they eval to equal objects - this will often fail
-          if expected_result =~ /^[:\[{A-Z'"%\/]/
-            begin
-              eval(expected_result) == eval(actual_result)
-            rescue Exception
-              false
-            end
-          end
     end
-  end
-  
-  
-  def evaluate(statement, line_num)
-    statement.gsub!("__FILE__", @file_name.inspect)
-    eval(statement, environment, __FILE__, __LINE__)
-  rescue SyntaxError => e
-    puts "Syntax error in statement on line #{line_num}:"
-    puts indent(statement)
-    puts e.to_s
-    puts
-    exit 1
-  rescue Exception => e
-    puts "Exception in statement on line #{line_num}:"
-    puts indent(statement)
-    puts e.backtrace
     
-    if RubyDocTest.trace
-      raise
-    else
-      puts e.to_s
-      puts
-      exit 1      
+    def indent(s, level=4)
+      spaces = " " * level
+      spaces + s.split("\n").join("\n#{spaces}")
     end
   end
   
-  
-  def number_run
-    passed + failures.length
-  end
-  
-  def indent(s, level=4)
-    spaces = " " * level
-    spaces + s.split("\n").join("\n#{spaces}")
-  end
-  
-  def print_report
-    statements_per_block = number_run.to_f / block_count
-    puts("%d blocks, %d tests (avg. %.1f/block), %d failures\n\n" %
-         [block_count, number_run, statements_per_block, failures.length])
-    
-    failures.each do |statement, actual, expected, lnum|
-      puts "Failure line #{lnum}"
-      puts "  Statement:", indent(statement)
-      puts "  Expected:",  indent(expected)
-      puts "  Got:\n",     indent(actual)
-      puts
-    end
-  end
-
 end

data/lib/rubydoctest/version.rb

@@ -1,8 +1,8 @@
 module Rubydoctest #:nodoc:
   module VERSION #:nodoc:
-    MAJOR = 0
-    MINOR = 2
-    TINY  = 1
+    MAJOR = 1
+    MINOR = 0
+    TINY  = 0
 
     STRING = [MAJOR, MINOR, TINY].join('.')
   end

data/lib/runner.rb

@@ -0,0 +1,370 @@
+$:.unshift(File.dirname(__FILE__)) unless
+  $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+
+require 'rubydoctest'
+require 'statement'
+require 'result'
+require 'special_directive'
+require 'code_block'
+require 'test'
+
+module RubyDocTest
+  class Runner
+    attr_reader :groups, :blocks, :tests
+    
+    @@color = {
+      :html => {
+        :red    => %{<font color="red">%s</font>},
+        :yellow => %{<font color="#C0C000">%s</font>},
+        :green  => %{<font color="green">%s</font>}
+      },
+      :ansi => {
+        :red    => %{\e[31m%s\e[0m},
+        :yellow => %{\e[33m%s\e[0m},
+        :green  => %{\e[32m%s\e[0m}
+      },
+      :plain => {
+        :red    => "%s",
+        :yellow => "%s",
+        :green  => "%s"
+      }
+    }
+    
+    # The evaluation mode, either :doctest or :ruby.
+    #
+    # Modes:
+    #   :doctest
+    #     - The the Runner expects the file to contain text (e.g. a markdown file).
+    #       In addition, it assumes that the text will occasionally be interspersed
+    #       with irb lines which it should eval, e.g. '>>' and '=>'.
+    #
+    #   :ruby
+    #     - The Runner expects the file to be a Ruby source file.  The source may contain
+    #       comments that are interspersed with irb lines to eval, e.g. '>>' and '=>'.
+    attr_accessor :mode
+    
+    # === Tests
+    # 
+    # doctest: Runner mode should default to :doctest and :ruby from the filename
+    # >> r = RubyDocTest::Runner.new("", "test.doctest")
+    # >> r.mode
+    # => :doctest
+    #
+    # >> r = RubyDocTest::Runner.new("", "test.rb")
+    # >> r.mode
+    # => :ruby
+    #
+    # doctest: The src_lines should be separated into an array
+    # >> r = RubyDocTest::Runner.new("a\nb\n", "test.doctest")
+    # >> r.instance_variable_get("@src_lines")
+    # => ["a", "b"]
+    def initialize(src, file_name = "test.doctest", initial_mode = nil)
+      @src, @file_name = src, file_name
+      @mode = initial_mode || (File.extname(file_name) == ".rb" ? :ruby : :doctest)
+      
+      @src_lines = src.split("\n")
+      @groups, @blocks = [], []
+      $rubydoctest = self
+    end
+    
+    # doctest: Using the doctest_require: SpecialDirective should require a file relative to the current one.
+    # >> r = RubyDocTest::Runner.new("# doctest_require: 'doctest_require.rb'", __FILE__)
+    # >> r.prepare_tests
+    # >> is_doctest_require_successful?
+    # => true
+    def prepare_tests
+      @groups = read_groups
+      @blocks = organize_blocks
+      @tests = organize_tests
+      eval(@src, TOPLEVEL_BINDING, @file_name) if @mode == :ruby
+    end
+    
+    # === Tests
+    # doctest: Run through a simple inline doctest (rb) file and see if it passes
+    # >> file = File.join(File.dirname(__FILE__), "..", "test", "inline.rb")
+    # >> r = RubyDocTest::Runner.new(IO.read(file), "inline.rb")
+    # >> r.pass?
+    # => true
+    def pass?
+      prepare_tests
+      @tests.all?{ |t| t.pass? }
+    end
+    
+    # === Description
+    # Starts an IRB prompt when the "!!!" SpecialDirective is given.
+    def start_irb
+      IRB.init_config(nil)
+      IRB.conf[:PROMPT_MODE] = :SIMPLE
+      irb = IRB::Irb.new(IRB::WorkSpace.new(TOPLEVEL_BINDING))
+      IRB.conf[:MAIN_CONTEXT] = irb.context
+      catch(:IRB_EXIT) do
+        irb.eval_input
+      end
+    end
+    
+    def format_color(text, color)
+      @@color[RubyDocTest.output_format][color] % text.to_s
+    end
+    
+    def run
+      prepare_tests
+      newline = "\n       "
+      everything_passed = true
+      puts "=== Testing '#{@file_name}'..."
+      ok, fail, err = 0, 0, 0
+      @tests.each do |t|
+        if SpecialDirective === t and t.name == "!!!"
+          start_irb unless RubyDocTest.ignore_interactive
+        else
+          begin
+            if t.pass?
+              ok += 1
+              status = ["OK".center(4), :green]
+              detail = nil
+            else
+              fail += 1
+              everything_passed = false
+              status = ["FAIL".center(4), :red]
+              detail = format_color(
+                "Got: #{t.actual_result}#{newline}Expected: #{t.expected_result}" + newline +
+                  "  from #{@file_name}:#{t.first_failed.result.line_number}",
+                :red)
+              
+            end
+          rescue EvaluationError => e
+            err += 1
+            status = ["ERR".center(4), :yellow]
+            exception_text = e.original_exception.to_s.split("\n").join(newline)
+            if RubyDocTest.output_format == :html
+              exception_text = exception_text.gsub("<", "&lt;").gsub(">", "&gt;")
+            end
+            detail = format_color(
+              "#{e.original_exception.class.to_s}: #{exception_text}" + newline +
+                "  from #{@file_name}:#{e.statement.line_number}" + newline +
+                e.statement.source_code,
+              :yellow)
+          end
+          puts \
+            "#{format_color(*status)} | " +
+            "#{t.description.split("\n").join(newline)}" +
+            (detail ? newline + detail : "")
+        end
+      end
+      puts \
+        "#{@blocks.select{ |b| b.is_a? CodeBlock }.size} comparisons, " +
+        "#{@tests.size} doctests, " +
+        "#{fail} failures, " +
+        "#{err} errors"
+      everything_passed
+    end
+    
+    # === Tests
+    # 
+    # doctest: Non-statement lines get ignored while statement / result lines are included
+    #          Default mode is :doctest, so non-irb prompts should be ignored.
+    # >> r = RubyDocTest::Runner.new("a\nb\n >> c = 1\n => 1")
+    # >> groups = r.read_groups
+    # >> groups.size
+    # => 2
+    #
+    # doctest: Group types are correctly created
+    # >> groups.map{ |g| g.class }
+    # => [RubyDocTest::Statement, RubyDocTest::Result]
+    #
+    # doctest: A ruby document can have =begin and =end blocks in it
+    # >> r = RubyDocTest::Runner.new(<<-RUBY, "test.rb")
+    #    some_ruby_code = 1
+    #    =begin
+    #     this is a normal ruby comment
+    #     >> z = 10
+    #     => 10
+    #    =end
+    #    more_ruby_code = 2
+    #    RUBY
+    # >> groups = r.read_groups
+    # >> groups.size
+    # => 2
+    # >> groups.map{ |g| g.lines.first }
+    # => [" >> z = 10", " => 10"]
+    def read_groups(src_lines = @src_lines, mode = @mode, start_index = 0)
+      groups = []
+      (start_index).upto(src_lines.size) do |index|
+        line = src_lines[index]
+        case mode
+        when :ruby
+          case line
+          
+          # Beginning of a multi-line comment section
+          when /^=begin/
+            groups +=
+              # Get statements, results, and directives as if inside a doctest
+              read_groups(src_lines, :doctest_with_end, index)
+          
+          else
+            if g = match_group("\\s*#\\s*", src_lines, index)
+              groups << g
+            end
+          
+          end
+        when :doctest
+          if g = match_group("\\s*", src_lines, index)
+            groups << g
+          end
+          
+        when :doctest_with_end
+          break if line =~ /^=end/
+          if g = match_group("\\s*", src_lines, index)
+            groups << g
+          end
+          
+        end
+      end
+      groups
+    end
+    
+    def match_group(prefix, src_lines, index)
+      case src_lines[index]
+      
+      # An irb '>>' marker after a '#' indicates an embedded doctest
+      when /^(#{prefix})>>(\s|\s*$)/
+        Statement.new(src_lines, index, @file_name)
+      
+      # An irb '=>' marker after a '#' indicates an embedded result
+      when /^(#{prefix})=>\s/
+        Result.new(src_lines, index)
+      
+      # Whenever we match a directive (e.g. 'doctest'), add that in as well
+      when /^(#{prefix})(#{SpecialDirective::NAMES_FOR_RX})(.*)$/
+        SpecialDirective.new(src_lines, index)
+      
+      else
+        nil
+      end
+    end
+    
+    # === Tests
+    # 
+    # doctest: The organize_blocks method should separate Statement, Result and SpecialDirective
+    #          objects into CodeBlocks.
+    # >> r = RubyDocTest::Runner.new(">> t = 1\n>> t + 2\n=> 3\n>> u = 1", "test.doctest")
+    # >> r.prepare_tests
+    # 
+    # >> r.blocks.first.statements.map{|s| s.lines}
+    # => [[">> t = 1"], [">> t + 2"]]
+    # 
+    # >> r.blocks.first.result.lines
+    # => ["=> 3"]
+    # 
+    # >> r.blocks.last.statements.map{|s| s.lines}
+    # => [[">> u = 1"]]
+    # 
+    # >> r.blocks.last.result
+    # => nil
+    #
+    # doctest: Two doctest directives--each having its own statement--should be separated properly
+    #          by organize_blocks.
+    # >> r = RubyDocTest::Runner.new("doctest: one\n>> t = 1\ndoctest: two\n>> t + 2", "test.doctest")
+    # >> r.prepare_tests
+    # >> r.blocks.map{|b| b.class}
+    # => [RubyDocTest::SpecialDirective, RubyDocTest::CodeBlock,
+    #     RubyDocTest::SpecialDirective, RubyDocTest::CodeBlock]
+    #
+    # >> r.blocks[0].value
+    # => "one"
+    #
+    # >> r.blocks[1].statements.map{|s| s.lines}
+    # => [[">> t = 1"]]
+    #
+    # >> r.blocks[2].value
+    # => "two"
+    #
+    # >> r.blocks[3].statements.map{|s| s.lines}
+    # => [[">> t + 2"]]
+    def organize_blocks(groups = @groups)
+      blocks = []
+      current_statements = []
+      groups.each do |g|
+        case g
+        when Statement
+          current_statements << g
+        when Result
+          blocks << CodeBlock.new(current_statements, g)
+          current_statements = []
+        when SpecialDirective
+          case g.name
+          when "doctest:"
+            blocks << CodeBlock.new(current_statements) unless current_statements.empty?
+            current_statements = []
+          when "doctest_require:"
+            doctest_require = eval(g.value, TOPLEVEL_BINDING, @file_name, g.line_number)
+            if doctest_require.is_a? String
+              require_relative_to_file_name(doctest_require, @file_name)
+            end
+          when "!!!"
+            # ignore
+          end
+          blocks << g
+        end
+      end
+      blocks << CodeBlock.new(current_statements) unless current_statements.empty?
+      blocks
+    end
+    
+    def require_relative_to_file_name(file_name, relative_to)
+      load_path = $:.dup
+      $:.unshift File.expand_path(File.join(File.dirname(relative_to), File.dirname(file_name)))
+      require File.basename(file_name)
+    ensure
+      $:.shift
+    end
+    
+    # === Tests
+    # 
+    # doctest: Tests should be organized into groups based on the 'doctest' SpecialDirective
+    # >> r = RubyDocTest::Runner.new("doctest: one\n>> t = 1\ndoctest: two\n>> t + 2", "test.doctest")
+    # >> r.prepare_tests
+    # >> r.tests.size
+    # => 2
+    # >> r.tests[0].code_blocks.map{|c| c.statements}.flatten.map{|s| s.lines}
+    # => [[">> t = 1"]]
+    # >> r.tests[1].code_blocks.map{|c| c.statements}.flatten.map{|s| s.lines}
+    # => [[">> t + 2"]]
+    # >> r.tests[0].description
+    # => "one"
+    # >> r.tests[1].description
+    # => "two"
+    #
+    # doctest: Without a 'doctest' SpecialDirective, there is one Test called "Default Test".
+    # >> r = RubyDocTest::Runner.new(">> t = 1\n>> t + 2\n=> 3\n>> u = 1", "test.doctest")
+    # >> r.prepare_tests
+    # >> r.tests.size
+    # => 1
+    # 
+    # >> r.tests.first.description
+    # => "Default Test"
+    # 
+    # >> r.tests.first.code_blocks.size
+    # => 2
+    def organize_tests(blocks = @blocks)
+      tests = []
+      assigned_blocks = nil
+      unassigned_blocks = []
+      blocks.each do |g|
+        case g
+        when CodeBlock
+          (assigned_blocks || unassigned_blocks) << g
+        when SpecialDirective
+          case g.name
+          when "doctest:"
+            assigned_blocks = []
+            tests << Test.new(g.value, assigned_blocks)
+          when "!!!"
+            tests << g
+          end
+        end
+      end
+      tests << Test.new("Default Test", unassigned_blocks) unless unassigned_blocks.empty?
+      tests
+    end
+  end
+end