rdoctest 0.0.1

data/README.rdoc

@@ -0,0 +1,155 @@
+= Rdoctest
+
+http://github.com/stephencelis/rdoctest
+
+A {doctest}[http://docs.python.org/py3k/library/doctest.html] for Ruby.
+
+
+== Why?
+
+You'll improve your test coverage and documentation in one fell swoop.
+
+
+== How?
+
+Install the gem:
+
+  % [sudo] gem install rdoctest
+
+
+Use the CLI:
+
+  % rdoctest lib/**/*.rb
+  Loaded suite /.../bin/rdoctest
+  Started
+  .
+  Finished in ... seconds.
+
+  1 tests, 7 assertions, 0 failures, 0 errors, 0 skips
+
+
+== Examples
+
+=== Formatting
+
+Rdoctest expects well-formatted RDoc. This means:
+
+* Indent examples by 2 spaces.
+
+    # For example:
+    #
+    #   1 + 1 # This code is indented by 2 spaces.
+
+
+* If your example is a block of code, use <tt># =></tt> to designate the
+  expected result.
+
+    # Short blocks can have the result on the same line:
+    #
+    #   1 + 1 # => 2
+    #
+    # Longer blocks can have the result on the line following:
+    #
+    #   def hello_world
+    #     puts "Hello, world!"
+    #   end
+    #   # => nil
+
+
+* If your example is an IRB session, use <tt>>></tt> and <tt>=></tt>
+  accordingly.
+
+    # Simple:
+    #
+    #   >> 1 + 1
+    #   => 2
+    #
+    # More complex:
+    #
+    #   >> def hello_world
+    #   >>   puts "Hello, world!"
+    #   >> end
+    #   => nil
+    #   >> hello_world
+    #   Hello, world!
+    #   => nil
+    #
+    # Use ellipses for partial matches:
+    #
+    #   >> goodbye_world
+    #   NameError: undefined local variable or method `goodbye_world'...
+
+
+=== CLI
+
+Rdoctest's CLI works a lot like Ruby's.
+
+  % rdoctest -h
+  Usage: rdoctest [options] [file ...]
+      -Idirectory
+      -rlibrary
+      ...
+
+If you're testing a complex project, make sure you prepare necessary libraries
+and load paths:
+
+  % rdoctest -Ilib -rmylibrary lib/**/*.rb
+
+
+=== Rake
+
+Rdoctest comes with a Rake task that you can load in your Rakefile.
+
+  require 'rdoctest/task'
+  Rdoctest::Task.new
+
+
+And run in your project:
+
+  % rake doctest
+
+
+It comes with a similar configuration to Rake's TestTask.
+
+  Rdoctest::Task.new :test do |t|
+    t.libs      << 'lib'          # The 'lib' directory is loaded by default,
+    t.ruby_opts << '-rrdoctest'   # but require needed files with +ruby_opts+.
+  end
+
+
+== Roadmap
+
+* Better detection of code blocks (the 3-space indent is too restrictive).
+* Test plain text files (READMEs, for example).
+* Autotest integration?
+* Test shell snippets (beginning with <tt>$</tt> and <tt>%</tt>)?
+
+
+== Prior Art
+
+{rubydoctest}[http://github.com/tablatom/rubydoctest].
+
+
+== License
+
+(The MIT License)
+
+(c) 2010 Stephen Celis <stephen@stephencelis.com>
+
+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/Rakefile

@@ -0,0 +1,5 @@
+$LOAD_PATH.unshift File.expand_path(File.join(File.dirname(__FILE__), 'lib'))
+$LOAD_PATH.unshift File.expand_path(File.join(File.dirname(__FILE__), 'bin'))
+require 'rdoctest/task'
+Rdoctest::Task.new
+task :default => :doctest

data/bin/rdoctest

@@ -0,0 +1,31 @@
+#!/usr/bin/env ruby
+require 'optparse'
+lib = File.expand_path(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift lib
+
+options = OptionParser.new do |option|
+  option.banner = "Usage: #{basename = File.basename $0} [options] [file ...]"
+  option.on('-Idirectory') { |v|
+    $LOAD_PATH.concat v.split File::PATH_SEPARATOR
+  }
+  option.on('-rlibrary') { |v|
+    require v
+  }
+  option.on('--version') {
+    require 'rdoctest/version'
+    puts "#{basename} #{Rdoctest::Version::VERSION}"
+    exit
+  }
+  option.on('-h', '--help') {
+    puts option
+    exit
+  }
+end
+options.parse!
+
+if ARGF.argv.empty?
+  puts options
+  exit
+end
+
+load 'rdoctest/runner.rb'

data/lib/rdoctest/runner.rb

@@ -0,0 +1,152 @@
+require 'stringio'
+require 'strscan'
+require 'test/unit'
+
+module Rdoctest
+  # The Runner takes RDoc example text and creates tests for them.
+  #
+  # ==== Example
+  #
+  # Writing inline code that ends with <tt># =></tt> and the result will create
+  # an assertion that the code evaluation is equal to that result.
+  #
+  #   1 + 1
+  #   # => 2
+  #
+  # You can also write an assertion on a single line.
+  #
+  #   2 + 2 # => 4
+  #
+  # If you want to assert errors or output, mimic an IRB session.
+  #
+  #   >> puts 'hello world'
+  #   hello world
+  #   => nil
+  #   >> def ok
+  #   >>   a
+  #   >> end
+  #   => nil
+  #
+  # Use ellipses for partial matches.
+  #
+  #   >> a
+  #   NameError: undefined local variable or method `a'...
+  class Runner
+    @@ruby = /(.+?)# =>([^\n]+\n)/m
+    @@irb  = /((?:^>> [^\n]+\n)+)((?:(?!^(?:>>|=>))[^\n]+\n)*)(^=> [^\n]+)?/m
+
+    attr_reader :files
+
+    def initialize
+      @files = {}
+    end
+
+    def run
+      parse
+      execute
+    end
+
+    private
+
+    def parse
+      filename = lineno = in_comment = in_test = nil
+
+      ARGF.each do |line|
+        lineno, filename = 0, ARGF.filename if filename != ARGF.filename
+        lineno += 1
+
+        next in_comment = nil unless line.sub! /^ *# ?/, ''
+        in_comment   = lineno if line =~ /^={1,6} \S/
+        in_comment ||= lineno
+
+        if in_test
+          in_test = false if line !~ /^(?: {2,}|$)/
+        else
+          in_test = true  if line =~ /^ {2}\S/
+        end
+
+        line = "\n" unless in_test
+        ((files[filename] ||= {})[in_comment] ||= '') << line if in_comment
+      end
+    end
+
+    def execute
+      files.each_pair do |filename, lineno_and_lines|
+        class_name = File.basename(filename, '.rb')
+        class_name.gsub!(/(?:^|_)(\w+:{,2})/) { |r| r.capitalize }
+        class_name.gsub! /\W+/, ''
+        class_name = 'Rdoctest' if class_name.empty?
+        require_filename filename
+
+        test_class = Class.new Test::Unit::TestCase do
+          lineno_and_lines.each_pair do |lineno, lines|
+            next unless lines =~ /\S/ # /(?:^|# )=>/
+            lines.gsub! /^  /, ''
+
+            define_method "assert_eval" do |expected, result, filename, lineno|
+              if expected.gsub!(/\.{3,}/, '.*')
+                assertion, expected = 'match', /#{expected}/
+              else
+                assertion = 'equal'
+              end
+
+              instance_eval <<ASSERTION, filename, lineno
+assert_#{assertion} #{expected.inspect}, #{result.inspect}
+ASSERTION
+            end
+
+            define_method "test_line_#{lineno}" do
+              assertions = []
+              scanner = StringScanner.new lines
+
+              binding = send :binding
+              while scanner.skip_until(@@ruby)
+                code_lineno = lineno + scanner.pre_match.count("\n")
+                expected_lineno = code_lineno + scanner[1].count("\n")
+
+                result = eval scanner[1], binding #, filename, code_lineno
+                assert_eval scanner[2].strip, result.inspect, filename,
+                  expected_lineno
+              end
+
+              scanner.pos = 0
+              binding = send :binding
+              while scanner.skip_until(@@irb)
+                code_lineno = lineno + scanner.pre_match.count("\n")
+                output_lineno = code_lineno + scanner[2].to_s.count("\n")
+                expected_lineno = output_lineno + scanner[3].to_s.count("\n")
+
+                begin
+                  stdout, $stdout = $stdout, StringIO.new
+                  result = eval scanner[1].gsub(/^>> /, ''), binding
+                rescue => e
+                  puts "#{e.class}: #{e}"
+                ensure
+                  $stdout, stdout = stdout, $stdout
+                end
+
+                stdout.rewind
+                output = stdout.read
+                assert_eval scanner[2], output, filename, output_lineno
+
+                if scanner[3]
+                  expected = scanner[3].sub(/^=> /, '').strip
+                  assert_eval expected, result.inspect, filename,
+                    expected_lineno
+                end
+              end
+            end
+          end
+        end
+
+        Object.const_set "#{class_name}Test", test_class
+      end
+    end
+
+    def require_filename filename
+      require filename.gsub(%r{^(?:lib)/|.rb$}, '') unless filename == '-'
+    end
+  end
+end
+
+Rdoctest::Runner.new.run

data/lib/rdoctest/task.rb

@@ -0,0 +1,79 @@
+require 'rake'
+require 'rake/tasklib'
+
+module Rdoctest
+  # See the README for more information.
+  class Task < Rake::TaskLib
+    # :enddoc:
+    attr_accessor :libs
+    attr_accessor :name
+    attr_accessor :options
+    attr_accessor :pattern
+    attr_accessor :ruby_opts
+    attr_accessor :test_files
+    attr_accessor :verbose
+    attr_accessor :warning
+
+    def initialize name = :doctest
+      @libs       = %w(lib)
+      @name       = name
+      @options    = nil
+      @pattern    = nil
+      @ruby_opts  = []
+      @test_files = nil
+      @verbose    = false
+      @warning    = false
+      yield self if block_given?
+      @pattern    = 'lib/**/*.rb' if @pattern.nil? && @test_files.nil?
+      define
+    end
+
+    def define
+      desc name ? "Run doctests for #{name}" : 'Run doctests'
+      task name do
+        ruby "#{run_code} #{ruby_opts_string} #{file_list_string}"
+      end
+    end
+
+    private
+
+    def ruby_opts_string
+      opts = []
+      opts << %(-I"#{lib_path}") unless libs.empty?
+      opts << %(-w) if warning
+      opts.concat ruby_opts
+      opts.join ' '
+    end
+
+    def lib_path
+      libs.join File::PATH_SEPARATOR
+    end
+
+    def run_code
+      $LOAD_PATH.each do |path|
+        file = File.join path, 'rdoctest'
+        return file if File.executable?(file)
+      end
+    end
+
+    def file_list_string
+      file_list.join ' '
+      # Dir[*file_list].join ' '
+    end
+
+    def file_list
+      if ENV['TEST']
+        Dir[ENV['TEST']]
+      else
+        result = []
+        result += test_files.to_a if test_files
+        result << pattern if pattern
+        result
+      end
+    end
+
+    def options_list
+      ENV['TESTOPTS'] || @options
+    end
+  end
+end

data/lib/rdoctest/version.rb

@@ -0,0 +1,9 @@
+module Rdoctest
+  module Version
+    MAJOR = 0
+    MINOR = 0
+    PATCH = 1
+
+    VERSION = [MAJOR, MINOR, PATCH].compact.join('.').freeze
+  end
+end

data/lib/rdoctest.rb

@@ -0,0 +1,2 @@
+module Rdoctest # :nodoc:
+end

metadata

@@ -0,0 +1,71 @@
+--- !ruby/object:Gem::Specification 
+name: rdoctest
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 0
+  - 1
+  version: 0.0.1
+platform: ruby
+authors: 
+- Stephen Celis
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-12-05 00:00:00 -06:00
+default_executable: rdoctest
+dependencies: []
+
+description: Scans RDoc text for examples and tests them.
+email: stephen@stephencelis.com
+executables: 
+- rdoctest
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- README.rdoc
+- Rakefile
+- lib/rdoctest/runner.rb
+- lib/rdoctest/task.rb
+- lib/rdoctest/version.rb
+- lib/rdoctest.rb
+- bin/rdoctest
+has_rdoc: true
+homepage: http://github.com/stephencelis/rdoctest
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --main
+- README.rdoc
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: A doctest for Ruby.
+test_files: []
+