tablatom-rubydoctest 0.2.1 → 1.0.0

data/History.txt

@@ -1,3 +1,7 @@
+== 0.3.0 2008-06-17
+
+* Added ability to put doctest code within .rb file comments
+
 == 0.2.1 2008-05-26
 
 * Adding self-doctesting doctests

data/License.txt

@@ -1,20 +1,19 @@
-Copyright (c) 2008 FIXME full name
+Copyright (c) 2008 Tom Locke, Nic Williams, Duane Johnson
 
-Permission is hereby granted, free of charge, to any person obtaining
-a copy of this software and associated documentation files (the
-"Software"), to deal in the Software without restriction, including
-without limitation the rights to use, copy, modify, merge, publish,
-distribute, sublicense, and/or sell copies of the Software, and to
-permit persons to whom the Software is furnished to do so, subject to
-the following conditions:
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
 
-The above copyright notice and this permission notice shall be
-included in all copies or substantial portions of the Software.
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
-NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
-LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
-OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
-WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/Manifest.txt

@@ -4,26 +4,34 @@ Manifest.txt
 PostInstall.txt
 README.txt
 Rakefile
+Ruby DocTest.tmproj
 bin/rubydoctest
 config/hoe.rb
 config/requirements.rb
+lib/code_block.rb
+lib/doctest_require.rb
+lib/lines.rb
+lib/result.rb
 lib/rubydoctest.rb
 lib/rubydoctest/version.rb
+lib/runner.rb
+lib/special_directive.rb
+lib/statement.rb
+lib/test.rb
 rubydoctest.gemspec
 script/console
 script/destroy
 script/generate
+script/rstakeout
 script/txt2html
 setup.rb
 tasks/deployment.rake
 tasks/doctests.rake
 tasks/environment.rake
 tasks/website.rake
-test/doctest/file_relative.doctest
-test/doctest/runner.doctest
-test/doctest/simple.doctest
-test/test_helper.rb
-test/test_rubydoctest.rb
+textmate/DocTest (Markdown).textmate
+textmate/DocTest (Ruby).textmate
+textmate/DocTest (Text).textmate
 website/index.html
 website/index.txt
 website/javascripts/rounded_corners_lite.inc.js

data/PostInstall.txt

@@ -1,8 +1,7 @@
 
-rubydoctest comes as an executable that takes a file or directory:
+rubydoctest comes as an executable that takes a list of files:
 	
-	rubydoctest .
-	rubydoctest some/path/to/tests
+	rubydoctest lib/*.rb
 	rubydoctest simple.doctest
 
 

data/README.txt

@@ -1,24 +1,37 @@
-= rubydoctest
+= Ruby DocTest
 
-* http://github.com/tablatom/rubydoctest
+Official repository:
+	* http://github.com/tablatom/rubydoctest
 
-== DESCRIPTION:
+Wiki documentation:
+	* http://github.com/tablatom/rubydoctest/wikis
 
-Ruby version of Python's doctest tool, but a bit different.
+== Description:
 
-== FEATURES/PROBLEMS:
+Ruby version of Python's doctest tool, but a bit different. Ruby DocTest
+allows you to:
 
-* FIX (list of features or problems)
+	1. Write tests in irb format and keep them as comments next to your Ruby code.
+	2. Write markdown documents with irb format tests embedded in them.
 
-== SYNOPSIS:
+== Synopsis:
 
-rubydoctest comes as an executable that takes a file or directory:
+rubydoctest comes as an executable that takes a list of files:
 	
-  rubydoctest .
+  rubydoctest lib/*.rb
 	rubydoctest simple.doctest
 
-== EXAMPLE:
+== Examples:
 	
+Here is how you might use RubyDocTest within a ruby source file (say called five.rb):
+
+	# doctest: Add 5 and 5 to get 10
+	# >> five_and_five
+	# => 10
+	def five_and_five
+	  5 + 5
+	end
+
 Here is an example doctest file (say called simple.doctest):
 	
 	# Simple test of RubyDocTest
@@ -33,30 +46,9 @@ Here is an example doctest file (say called simple.doctest):
 		>> 1 + 2
 		=> 4
 
-	Test a some multiline statements
-
-		>> 
-			class Person
-				attr_accessor :name
-			end
-
-		>> Person
-		=> Person
-		>> p = Person.new
-		>> p.name = "Tom"
-		>> p.name
-		=> "Tom"
-
-
-		>> "a
-		b"
-		=> "a\nb"
-
-		>> 1 +
-		?> 2
-		=> 3
+See the doc directory of this project for more .doctest examples and documentation.
 
-== INSTALL:
+== Installation:
 
 Major releases:
 
@@ -66,9 +58,9 @@ Build from source:
 
 	git clone git://github.com/tablatom/rubydoctest.git
 	cd rubydoctest
-	rake manifest && rake install
+	rake manifest:refresh && rake install
 
-== SELF-DOCTESTING:
+== Testing DocTest:
 	
 Ruby DocTest uses itself to test and document itself.
 
@@ -79,31 +71,30 @@ using script/rstakeout
 
 	rake test:doctest:auto
 
-== TEXTMATE BUNDLE:
+== TextMate Bundle:
 	
 See http://github.com/drnic/ruby-doctest-tmbundle
 
-== LICENSE:
+== License:
 
 (The MIT License)
 
-Copyright (c) 2008 FIX
-
-Permission is hereby granted, free of charge, to any person obtaining
-a copy of this software and associated documentation files (the
-'Software'), to deal in the Software without restriction, including
-without limitation the rights to use, copy, modify, merge, publish,
-distribute, sublicense, and/or sell copies of the Software, and to
-permit persons to whom the Software is furnished to do so, subject to
-the following conditions:
-
-The above copyright notice and this permission notice shall be
-included in all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
-CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
-TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
-SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+Copyright (c) 2008 Tom Locke, Nic Williams, Duane Johnson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the 'Software'), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/bin/rubydoctest

@@ -1,35 +1,51 @@
 #!/usr/bin/env ruby
 
-USAGE = "USAGE: rdoctest [ --html ] [ --trace ] [ --debugger ] <path>"
-
-SUFFIX = "{r,}doctest"
+if ARGV.empty?
+  puts <<-DIRECTIONS
+  USAGE: rubydoctest [options] <files>
+  
+  rubydoctest parses Ruby files (.rb) or DocTest files (.doctest) for irb-style
+  sessions in comments, and runs the commented sessions as tests.
+  
+  Options:
+    Output Format:
+      --html  - output in HTML format
+      --plain - force output in plain text (no Ansi colors)
+    
+    Debug:
+      --ignore-interactive - do not heed !!! special directives
+      --trace     - turn backtrace on to debug Ruby DocTest
+      --debugger  - include ruby-debug library / gem
+  
+  See http://github.com/tablatom/rubydoctest/wikis for more information.
+  DIRECTIONS
+  exit 0
+end
 
-file = ARGV.pop or (puts USAGE; exit 1)
+options, files = ARGV.partition{ |a| a =~ /^--/ }
 
 requires = ['rubygems', File.dirname(__FILE__) + "/../lib/rubydoctest"]
-requires << 'ruby-debug' if ARGV.include?("--debugger")
-
-command = if ARGV.include?("--rcov")
-            args = (ARGV - ["--rcov"]).map { |a| %("#{a}") }.join(' ')
-            "rcov -x /gems/,rdoctest"
-          else
-            "ruby"
-          end
-trace = "RubyDocTest.trace = true;" if ARGV.include?("--trace")
+requires << 'ruby-debug' if options.include?("--debugger")
+ruby_lines = []
+ruby_lines << "RubyDocTest.trace = true;" if options.include?("--trace")
+ruby_lines << "RubyDocTest.ignore_interactive = true;" if options.include?("--ignore-interactive")
 
 requires = requires.map {|lib| "require '#{lib}'; "}.join
 
-puts "<html><body><pre>" if ARGV.include?("--html")
-
-files = if File.directory?(file)
-          Dir["#{file}/**/*.#{SUFFIX}"]
-        else
-          [file]
-        end
-
-files.reverse_each do |f|
-  puts  "*** " + f.sub("#{file}/", "").sub(".#{SUFFIX}", ""), "" if files.length > 1
-  system %(#{command} -e "#{requires} #{trace} RubyDocTest.new(File.read('#{f}'), '#{f}').run")
+def files_runner(command, files, requires, lines)
+  files.reverse_each do |f|
+    system %(#{command} -e "#{requires} #{lines.join(" ")} RubyDocTest::Runner.new(File.read('#{f}'), '#{f}').run")
+  end
 end
 
-puts "</pre></body></html>" if ARGV.include?("--html")
+if options.include?("--plain")
+  ruby_lines << "RubyDocTest.output_format = :plain;" 
+  files_runner("ruby", files, requires, ruby_lines)
+elsif options.include?("--html")
+  ruby_lines << "RubyDocTest.output_format = :html;" 
+  puts "<html><body><pre>"
+  files_runner("ruby", files, requires, ruby_lines)
+  puts "</pre></body></html>"
+else
+  files_runner("ruby", files, requires, ruby_lines)
+end

data/config/hoe.rb

@@ -1,15 +1,13 @@
 require 'rubydoctest/version'
 
-AUTHOR = ['Tom Locke', 'Dr Nic Williams']  # can also be an array of Authors
-EMAIL = "drnicwilliams@gmail.com"
+AUTHOR = ['Duane Johnson', 'Tom Locke', 'Dr Nic Williams']  # can also be an array of Authors
+EMAIL = "duane.johnson@gmail.com"
 DESCRIPTION = "Ruby version of Python's doctest tool, but a bit different."
 GEM_NAME = 'rubydoctest' # what ppl will type to install your gem
 RUBYFORGE_PROJECT = 'rubydoctest' # The unix name for your project
 HOMEPATH = "http://#{RUBYFORGE_PROJECT}.rubyforge.org"
 DOWNLOAD_PATH = "http://rubyforge.org/projects/#{RUBYFORGE_PROJECT}"
-EXTRA_DEPENDENCIES = [
-#  ['activesupport', '>= 1.3.1']
-]    # An array of rubygem dependencies [name, version]
+EXTRA_DEPENDENCIES = []
 
 @config_file = "~/.rubyforge/user-config.yml"
 @config = nil

data/lib/code_block.rb

@@ -0,0 +1,68 @@
+$:.unshift(File.dirname(__FILE__)) unless
+  $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+
+require 'statement'
+require 'result'
+
+module RubyDocTest
+  # A +CodeBlock+ is a group of one or more ruby statements, followed by an optional result.
+  # For example:
+  #  >> a = 1 + 1
+  #  >> a - 3
+  #  => -1
+  class CodeBlock
+    attr_reader :statements, :result, :passed
+    
+    def initialize(statements = [], result = nil)
+      @statements = statements
+      @result = result
+    end
+    
+    # === Tests
+    # doctest: Single statement with result should pass
+    # >> ss = [RubyDocTest::Statement.new([">> a = 1"])]
+    # >> r = RubyDocTest::Result.new(["=> 1"])
+    # >> cb = RubyDocTest::CodeBlock.new(ss, r)
+    # >> cb.pass?
+    # => true
+    #
+    # doctest: Single statement without result should pass by default
+    # >> ss = [RubyDocTest::Statement.new([">> a = 1"])]
+    # >> cb = RubyDocTest::CodeBlock.new(ss)
+    # >> cb.pass?
+    # => true
+    #
+    # doctest: Multi-line statement with result should pass
+    # >> ss = [RubyDocTest::Statement.new([">> a = 1"]),
+    #          RubyDocTest::Statement.new([">> 'a' + a.to_s"])]
+    # >> r = RubyDocTest::Result.new(["=> 'a1'"])
+    # >> cb = RubyDocTest::CodeBlock.new(ss, r)
+    # >> cb.pass?
+    # => true
+    def pass?
+      if @computed
+        @passed
+      else
+        @computed = true
+        @passed =
+          begin
+            actual_results = @statements.map{ |s| s.evaluate }
+            @result ? @result.matches?(actual_results.last) : true
+          end
+      end
+    end
+    
+    def actual_result
+      @statements.last.actual_result
+    end
+    
+    def expected_result
+      @result.expected_result
+    end
+    
+    def lines
+      @statements.map{ |s| s.lines }.flatten +
+      @result.lines
+    end
+  end
+end

data/lib/doctest_require.rb

@@ -0,0 +1,3 @@
+def is_doctest_require_successful?
+  true
+end

data/lib/lines.rb

@@ -0,0 +1,143 @@
+module RubyDocTest
+  # === Description
+  # Keeps track of which lines within a document belong to a group.  Line groups are
+  # determined by their indentation level, as in the Python programming language.
+  #
+  # === Example
+  #  This line and the next one
+  #    are part of the same group
+  #
+  #  But this line is separate from
+  #  this line.
+  #
+  # === Note
+  # This class also considers one '#' character (comment) as an indentation character,
+  # i.e. similar to how whitespace is treated.
+  class Lines
+    def initialize(doc_lines, line_index = 0)
+      @doc_lines, @line_index = doc_lines, line_index
+    end
+    
+    
+    def line_number
+      @line_index + 1
+    end
+    
+    # === Tests
+    # doctest: Return an array of 1 line if there is only one line
+    # >> l = RubyDocTest::Lines.new(["line 1"])
+    # >> l.lines
+    # => ["line 1"]
+    #
+    # doctest: Remove indentation from lines 2 to the end of this Lines group.
+    # >> l = RubyDocTest::Lines.new(["line 1", "  line 2", "  line 3", "    line 4"])
+    # >> l.lines
+    # => ["line 1", "line 2", "line 3", "  line 4"]
+    def lines
+      r = range
+      size = r.last - r.first + 1
+      if size > 1
+        # Remove indentation from all lines after the first,
+        # as measured from the 2nd line's indentation level
+        idt2 = indentation(@doc_lines, @line_index + 1)
+        [@doc_lines[range.first]] +
+        @doc_lines[(range.first + 1)..(range.last)].
+          map{ |l| $1 if l =~ /^#{Regexp.escape(idt2)}(.*)/ }
+      else
+        @doc_lines[range]
+      end
+    end
+    
+    
+    # === Description
+    # Calculate the range of python-like indentation within this Lines group
+    #
+    # === Tests
+    # >> l = RubyDocTest::Lines.new([])
+    #
+    # doctest: Return a range of one line when there is only one line to begin with
+    # >> l.range %w(a), 0
+    # => 0..0
+    #
+    # doctest: Return a range of one line when there are two lines, side by side
+    # >> l.range %w(a b), 0
+    # => 0..0
+    # >> l.range %w(a b), 1
+    # => 1..1
+    #
+    # doctest: Return a range of two lines when there are two lines, the second blank
+    # >> l.range ["a", ""], 0
+    # => 0..1
+    #
+    # doctest: Return a range of two lines when the second is indented
+    # >> l.range ["a", " b"], 0
+    # => 0..1
+    #
+    # doctest: Indentation can also include the ?> marker
+    # >> l.range [">> 1 +", "?> 2"], 0
+    # => 0..1
+    def range(doc_lines = @doc_lines, start_index = @line_index)
+      end_index = start_index
+      idt = indentation(doc_lines, start_index)
+      # Find next lines that are blank, or have indentation more than the first line
+      remaining_lines(doc_lines, start_index + 1).each do |current_line|
+        if current_line =~ /^(#{Regexp.escape(idt)}(\s+|\?>\s)|\s*$)/
+          end_index += 1
+        else
+          break
+        end
+      end
+      # Compute the range from what we found
+      start_index..end_index
+    end
+    
+    def inspect
+      "#<#{self.class} lines=#{lines.inspect}>"
+    end
+    
+    protected
+    
+    # === Tests
+    # >> l = RubyDocTest::Lines.new([])
+    #
+    # doctest: Get a whitespace indent from a line with whitespace
+    # >> l.send :indentation, [" a"], 0
+    # => " "
+    #
+    # doctest: Get a whitespace and '#' indent from a comment line
+    # >> l.send :indentation, [" # a"], 0
+    # => " # "
+    def indentation(doc_lines = @doc_lines, line_index = @line_index)
+      if doc_lines[line_index]
+        doc_lines[line_index][/^(\s*#\s*|\s*)(\?>\s)?/]
+      else
+        ""
+      end
+    end
+    
+    
+    # === Description
+    # Get lines from +start_index+ up to the end of the document.
+    #
+    # === Tests
+    # >> l = RubyDocTest::Lines.new([])
+    # 
+    # doctest: Return an empty array if start_index is out of bounds
+    # >> l.send :remaining_lines, [], 1
+    # => []
+    # >> l.send :remaining_lines, [], -1
+    # => []
+    #
+    # doctest: Return the specified line at start_index, up to and including the
+    #          last line of +doc_lines+.
+    # >> l.send :remaining_lines, %w(a b c), 1
+    # => %w(b c)
+    # >> l.send :remaining_lines, %w(a b c), 2
+    # => %w(c)
+    #
+    def remaining_lines(doc_lines = @doc_lines, start_index = @line_index)
+      return [] if start_index < 0 or start_index >= doc_lines.size
+      doc_lines[start_index..-1]
+    end
+  end
+end