exemplor 2000.2.0 → 2010.0.0

data/.gitignore

@@ -1 +1,2 @@
+exemplor.gemspec
 pkg

data/TODO

@@ -1,9 +1,7 @@
+* add symbol to_proc and tap
 * exemplor executable that can run multiple example files
-* #teardown
-* Use fancy unicode characters for tests status:
 * TextMate bundle that does nice cmd+r output
-# (i) = ∙
-# (I) = •
-# (s) = ✓
-# (f) = ✗
-# (e) = ☠
+* smarter macros for examples.rb - this could be clearer
+* discuss example grouping in doc (philosophy)
+
+* test requiring exemplor does *not* trigger at exit

data/VERSION

@@ -1 +1 @@
-2000.2.0
+2010.0.0

data/examples.rb

@@ -30,11 +30,11 @@ eg "version matches file" do
 end
 
 eg "errors are caught and nicely displayed" do
-  actual_yaml = YAML.load run_example(:an_error)
-  error_hash = actual_yaml[actual_yaml.keys.first]
-   # the rest of the bactrace is platform & exemplor version specific
-  error_hash['backtrace'] = error_hash['backtrace'][0...1]
-  Check(actual_yaml).is(YAML.load(extract_expected(:an_error)))
+  result = YAML.load(run_example(:an_error))[0]
+  Check(result['status']).is('error')
+  Check(result['result']['class']).is('RuntimeError')
+  Check(result['result']['message']).is('boom!')
+  Check(result['result']['backtrace'][0]).is('examples/an_error.rb:4')
 end
 
 eg { check_output_matches_expected_for :no_checks }

data/examples/an_error.rb

@@ -2,13 +2,4 @@ require 'exemplor'
 
 eg 'Raising an error' do
   raise "boom!"    
-end
-
-__END__
-
-(e) Raising an error: 
-  class: RuntimeError
-  message: boom!
-  backtrace: 
-  - examples/an_error.rb:4
-  # ... more backtrace lines
+end

data/examples/assertion_failure.rb

@@ -7,7 +7,10 @@ end
 
 __END__
 
-(f) Assertion failure: 
-  (f) list.first: 
+- name: Assertion failure
+  status: failure
+  result: 
+  - name: list.first
+    status: failure
     expected: 2
     actual: 1

data/examples/assertion_success.rb

@@ -7,5 +7,9 @@ end
 
 __END__
 
-(s) Asserting first is first: 
-  (s) list.first: 1
+- name: Asserting first is first
+  status: success
+  result: 
+  - name: list.first
+    status: success
+    result: 1

data/examples/assertion_success_and_failure.rb

@@ -10,9 +10,16 @@ end
 
 __END__
 
-(f) Some successes, then a fail: 
-  (s) list.first: 1
-  (s) list[1]: 2
-  (f) list.last: 
+- name: Some successes, then a fail
+  status: failure
+  result: 
+  - name: list.first
+    status: success
+    result: 1
+  - name: list[1]
+    status: success
+    result: 2
+  - name: list.last
+    status: failure
     expected: 1
     actual: 3

data/examples/check_parsing.rb

@@ -30,15 +30,39 @@ end
 
 __END__
 
-(I) plain call: 
-  (i) foo: bar
-(I) whitespace after the call (seriously): 
-  (i) foo: bar
-(I) comment after the call: 
-  (i) foo: bar
-(I) with brackets: 
-  (i) String.new('test'): test
-(s) with brackets and is: 
-  (s) String.new('test'): test
-(s) with disambiguation: 
-  (s) foo bar: bar
+- name: plain call
+  status: info (with checks)
+  result: 
+  - name: foo
+    status: info
+    result: bar
+- name: whitespace after the call (seriously)
+  status: info (with checks)
+  result: 
+  - name: foo
+    status: info
+    result: bar
+- name: comment after the call
+  status: info (with checks)
+  result: 
+  - name: foo
+    status: info
+    result: bar
+- name: with brackets
+  status: info (with checks)
+  result: 
+  - name: String.new('test')
+    status: info
+    result: test
+- name: with brackets and is
+  status: success
+  result: 
+  - name: String.new('test')
+    status: success
+    result: test
+- name: with disambiguation
+  status: success
+  result: 
+  - name: foo bar
+    status: success
+    result: bar

data/examples/check_with_disambiguation.rb

@@ -9,6 +9,12 @@ end
 
 __END__
 
-(I) Array appending: 
-  (i) list.last before append: 42
-  (i) list.last after append: 2
+- name: Array appending
+  status: info (with checks)
+  result: 
+  - name: list.last before append
+    status: info
+    result: 42
+  - name: list.last after append
+    status: info
+    result: 2

data/examples/checking_nil.rb

@@ -10,7 +10,15 @@ end
 
 __END__
 
-(I) checking nil works correctly: 
-  (i) nil: 
-(s) asserting for nil works correctly: 
-  (s) nil: 
+- name: checking nil works correctly
+  status: info (with checks)
+  result: 
+  - name: nil
+    status: info
+    result: 
+- name: asserting for nil works correctly
+  status: success
+  result: 
+  - name: nil
+    status: success
+    result:

data/examples/dumping_classes.rb

@@ -10,6 +10,12 @@ end
 
 __END__
 
-(i) class name is printed when example returns a class: Object
-(I) class name is printed when check is given a class: 
-  (i) Object: Object
+- name: class name is printed when example returns a class
+  status: info (no checks)
+  result: Object
+- name: class name is printed when check is given a class
+  status: info (with checks)
+  result: 
+  - name: Object
+    status: info
+    result: Object

data/examples/helpers.rb

@@ -14,4 +14,6 @@ end
 
 __END__
 
-(i) Example calling helper: foo
+- name: Example calling helper
+  status: info (no checks)
+  result: foo

data/examples/no_checks.rb

@@ -6,4 +6,6 @@ end
 
 __END__
 
-(i) An example block without any checks prints the value of the block: foo
+- name: An example block without any checks prints the value of the block
+  status: info (no checks)
+  result: foo

data/examples/no_checks_non_string.rb

@@ -12,5 +12,7 @@ end
 
 __END__
 
-(i) Non-string return values get converted to yaml: !ruby/object:MyClass 
-  foo: bar
+- name: Non-string return values get converted to yaml
+  status: info (no checks)
+  result: !ruby/object:MyClass 
+    foo: bar

data/examples/oneliner.rb

@@ -4,4 +4,6 @@ eg { 1+2 }
 
 __END__
 
-(i) 1+2: 3
+- name: 1+2
+  status: info (no checks)
+  result: 3

data/examples/with_checks.rb

@@ -9,7 +9,15 @@ end
 
 __END__
 
-(I) Accessing different parts of an array: 
-  (i) list.first: 1
-  (i) list[1]: 2
-  (i) list.last: 3
+- name: Accessing different parts of an array
+  status: info (with checks)
+  result: 
+  - name: list.first
+    status: info
+    result: 1
+  - name: list[1]
+    status: info
+    result: 2
+  - name: list.last
+    status: info
+    result: 3

data/examples/with_setup.rb

@@ -13,7 +13,15 @@ end
 
 __END__
 
-(s) Modified env: 
-  (s) @str: foo bar
-(s) Unmodified env: 
-  (s) @str: foo
+- name: Modified env
+  status: success
+  result: 
+  - name: "@str"
+    status: success
+    result: foo bar
+- name: Unmodified env
+  status: success
+  result: 
+  - name: "@str"
+    status: success
+    result: foo

data/lib/exemplor.rb

@@ -1,12 +1,28 @@
 require 'orderedhash'
 require 'yaml'
 
+def OrderedHash(&blk)
+  ohsh = OrderedHash.new
+  blk.call(ohsh)
+  ohsh
+end
+
+def YAML.without_header(obj)
+  obj.to_yaml.match(/^--- \n?/).post_match
+end
+
+class String
+  def indent
+    self.split("\n").map { |line| '  ' + line }.join("\n")
+  end
+end
+
 module Exemplor
   
   def self.version() File.read(__FILE__.sub('lib/exemplor.rb','VERSION')) end
   
   class ExampleDefinitionError < StandardError ; end
-    
+  
   class Check
     
     attr_reader :expectation, :value
@@ -48,7 +64,72 @@ module Exemplor
     
   end
   
-  class Example
+  class ResultPrinter
+    
+    attr_reader :name,:status,:result,:stderr
+    
+    def initialize(name,status,result,stderr)
+      @name,@status,@result,@stderr = name,status,result,stderr
+    end
+    
+    def failure?
+      [:error,:failure].include?(self.status)
+    end
+    
+    def yaml
+      hsh = OrderedHash do |o|
+        o['name'] = self.name
+        o['status'] = case status = self.status
+          when :info  : 'info (no checks)'
+          when :infos : 'info (with checks)'
+          else ; status.to_s
+        end
+        o['result'] = self.result
+      end
+      YAML.without_header([hsh])# prints an array
+    end
+    
+    def fancy
+      # •∙ are inverted in my terminal font (Incosolata) so I'm swapping them
+      require 'term/ansicolor'
+      case status
+      when :info : blue format_info("• #{name}", result)
+      when :infos
+        formatted_result = result.map do |r|
+          format_info("• #{r['name']}", r['result']).rstrip
+        end.join("\n")
+        blue("∙ #{name}\n#{formatted_result.indent}")
+      when :success
+        green("✓ #{name}")
+      when :failure
+        # sooo hacky
+        failure = result.find { |r| r['status'] == 'failure' }
+        out = failure.dup
+        out.delete('status')
+        out.delete('name')
+        color(:red,  "✗ #{name} - #{failure['name']}\n#{YAML.without_header(out).indent}")
+      when :error
+        class_and_message = "#{result['class']} - #{result['message']}"
+        backtrace = result['backtrace'].join("\n")
+        color(:red, "☠ #{name}\n#{class_and_message.indent}\n#{backtrace.indent}")
+      end
+    end
+    
+    def blue(str) color(:blue,str) end
+    def green(str) color(:green,str) end
+    
+    def color(color, str)
+      [Term::ANSIColor.send(color), str, Term::ANSIColor.reset].join
+    end
+    
+    # whatahack
+    def format_info(str, result)
+      YAML.without_header({'FANCY' => result}).sub('FANCY', str)
+    end
+    
+  end
+  
+  class ExampleEnv
     
     class << self
       
@@ -57,6 +138,66 @@ module Exemplor
       
       def setup(&blk) self.setup_block = blk end
       
+      # runs the block in the example environment, returns triple:
+      # [status, result, stderr]
+      def run(&code)
+        env = self.new
+        stderr = StringIO.new
+        status, result = begin
+          real_stderr = $stderr ; $stderr = stderr # swap stderr
+          
+          env.instance_eval(&self.setup_block) if self.setup_block
+          value = env.instance_eval(&code)
+          result = env._status == :info ? 
+            render_value(value) : render_checks(env._checks)
+          [env._status, result]
+          
+        rescue Object => error
+          [:error, render_error(error)]
+        ensure
+          $stderr = real_stderr # swap stderr back
+        end
+        [status, result, stderr.rewind && stderr.read]
+      end
+      
+      # -- these "render" methods could probably be factored away
+      
+      # yaml doesn't want to print a class
+      def render_value(value)
+        value.kind_of?(Class) ? value.inspect : value
+      end
+      
+      def render_checks(checks)
+        failure = nil
+        out = []
+        checks.each do |check|
+          failure = check if check.failure?
+          break if failure
+          out << OrderedHash do |o|
+            o['name'] = check.name
+            o['status'] = check.status.to_s
+            o['result'] = render_value check.value
+          end
+        end
+        if failure
+          out << OrderedHash do |o|
+            o['name'] = failure.name
+            o['status'] = failure.status.to_s
+            o['expected'] = failure.expectation
+            o['actual'] = render_value failure.value
+          end
+        end
+        out
+      end
+
+      def render_error(error)
+        OrderedHash do |o|
+          o['class'] = error.class.name
+          o['message'] = error.message
+          o['backtrace'] = error.backtrace
+        end
+      end
+      
     end
     
     attr_accessor :_checks
@@ -74,12 +215,17 @@ module Exemplor
       check
     end
     
+    def _status
+      (:info    if _checks.empty?) ||
+      (:infos   if _checks.all? { |c| c.info? }) ||
+      (:success if _checks.all? { |c| c.success? }) ||
+      (:failure if _checks.any? { |c| c.failure? })
+    end
+    
   end
   
   class Examples
     
-    attr_writer :setup_block
-    
     def initialize
       @examples = OrderedHash.new
     end
@@ -94,11 +240,10 @@ module Exemplor
       patterns = Regexp.new(patterns.join('|'))
       examples_to_run = @examples.select { |name,_| name =~ patterns }
       return 0 if examples_to_run.empty?
-      examples_to_run.each do |name, body|
-        status, out, stderr = run_example(body)
-        print_yaml("#{status_icon(status)} #{name}" => out)
-        print_stderr stderr
-        fails +=1 if [:error,:failure].include?(status)
+      examples_to_run.each do |name, code|
+        result = ResultPrinter.new(name, *ExampleEnv.run(&code))
+        fails +=1 if result.failure?
+        puts($stdout.tty? ? result.fancy : result.yaml)
       end
       (fails.to_f/examples_to_run.size)*100
     end
@@ -106,103 +251,7 @@ module Exemplor
     def list(patterns)
       patterns = Regexp.new(patterns.join('|'))
       list = @examples.keys.select { |name| name =~ patterns }
-      print_yaml list
-    end
-    
-    def print_yaml(obj)
-      out = obj.to_yaml.match(/^--- \n/).post_match
-      out = colorize out if $stdout.tty?
-      print(out)
-    end
-    
-    def print_stderr(stderr)
-      unless stderr.empty?
-        $stdout.tty? ? $stdout.puts("#{Term::ANSIColor.reset}(STDERR):\n#{stderr}") : $stderr.puts(stderr)
-      end
-    end
-    
-    # hacky
-    def colorize(out)
-      require 'term/ansicolor'
-      out.split("\n").map do |line|
-        case line
-        when /^(?:\s{2})?(\(s\))/ 
-          start_color(line, :green)
-        when /^(?:\s{2})?(\(f\))/ 
-          start_color(line, :red)
-        when /^(?:\s{2})?(\(e\))/ 
-          start_color(line, :red)
-        when /^(?:\s{2})?(\(i\))/i
-          start_color(line, :blue)
-        else
-          line
-        end
-      end.join("\n") + "\n#{Term::ANSIColor.reset}"
-    end
-    
-    def start_color(line, color)
-      "#{Term::ANSIColor.reset}#{Term::ANSIColor.send(color)}#{line}"
-    end
-    
-    def run_example(code)
-      status = :info
-      env = Example.new
-      stderr = StringIO.new
-      out = begin
-        real_stderr = $stderr
-        $stderr = stderr
-        
-        env.instance_eval(&Example.setup_block) if Example.setup_block
-        value = env.instance_eval(&code)
-        if env._checks.empty?
-          render_value value
-        else
-          status = :infos if env._checks.all? { |check| check.info? }
-          status = :success if env._checks.all? { |check| check.success? }
-          status = :failure if env._checks.any? { |check| check.failure? } 
-          render_checks(env._checks)
-        end
-      rescue Object => error
-        status = :error
-        render_error(error)
-      ensure
-        $stderr = real_stderr
-      end
-      [status, out, stderr.rewind && stderr.read]
-    end
-    
-    def render_checks(checks)
-      failure = nil
-      out = OrderedHash.new
-      checks.each do |check|
-        failure = check if check.failure?
-        break if failure
-       
-        out["#{status_icon(check.status)} #{check.name}"] = render_value check.value
-      end
-      if failure
-        fail_out = out["#{status_icon(failure.status)} #{failure.name}"] = OrderedHash.new
-        fail_out['expected'] = failure.expectation
-        fail_out['actual'] = render_value failure.value
-      end
-      out
-    end
-    
-    def render_error(error)
-      out = OrderedHash.new
-      out['class'] = error.class.name
-      out['message'] = error.message
-      out['backtrace'] = error.backtrace
-      out
-    end
-    
-    def status_icon(status)      
-      icon = status == :infos ? '(I)' : "(#{status.to_s.slice(0,1)})"
-    end
-    
-    # yaml doesn't want to print a class
-    def render_value(value)
-      value.kind_of?(Class) ? value.inspect : value
+      print YAML.without_header(list)
     end
     
   end
@@ -213,12 +262,26 @@ module Exemplor
       @examples ||= Examples.new
     end
     
+    def extract_example_file(caller_trace)
+      @example_file ||= caller_trace.first.split(":").first
+    end
+    
+    # attr_reader :example_file
+    
+    def run_directly?
+      @example_file == $0
+    end
+    
   end
   
 end
 
+# Defines an example. After definition, an example is an entry in the
+# Examples.examples ordered hash, the key is the name, the body is the example
+# code
 def eg(name = nil, &example)
-  return Exemplor::Example if name.nil? && example.nil?
+  Exemplor.extract_example_file caller # only runs once
+  return Exemplor::ExampleEnv if name.nil? && example.nil?
   if name.nil?
      file, line_number = caller.first.match(/^(.+):(\d+)/).captures
      line = File.readlines(file)[line_number.to_i - 1].strip
@@ -228,11 +291,14 @@ def eg(name = nil, &example)
   Exemplor.examples.add(name, &example)
 end
 
+# Parses the command line args and either runs or lists the examples.
 at_exit do
-  args = ARGV.dup
-  if args.delete('--list') || args.delete('-l')
-    Exemplor.examples.list(args)
-  else
-    exit Exemplor.examples.run(args)
+  if Exemplor.run_directly?
+    args = ARGV.dup
+    if args.delete('--list') || args.delete('-l')
+      Exemplor.examples.list(args)
+    else
+      exit Exemplor.examples.run(args)
+    end
   end
-end
+end 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: exemplor
 version: !ruby/object:Gem::Version 
-  version: 2000.2.0
+  version: 2010.0.0
 platform: ruby
 authors: 
 - Myles Byrne
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-11-03 00:00:00 +11:00
+date: 2009-11-25 00:00:00 +11:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -62,7 +62,6 @@ files:
 - examples/ten_percent_failures.rb
 - examples/with_checks.rb
 - examples/with_setup.rb
-- exemplor.gemspec
 - lib/exemplor.rb
 has_rdoc: true
 homepage: http://github.com/quackingduck/exemplor

data/exemplor.gemspec

@@ -1,80 +0,0 @@
-# Generated by jeweler
-# DO NOT EDIT THIS FILE
-# Instead, edit Jeweler::Tasks in Rakefile, and run `rake gemspec`
-# -*- encoding: utf-8 -*-
-
-Gem::Specification.new do |s|
-  s.name = %q{exemplor}
-  s.version = "2000.2.0"
-
-  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
-  s.authors = ["Myles Byrne"]
-  s.date = %q{2009-11-03}
-  s.email = %q{myles@myles.id.au}
-  s.extra_rdoc_files = [
-    "README"
-  ]
-  s.files = [
-    ".gitignore",
-     "README",
-     "Rakefile",
-     "TODO",
-     "VERSION",
-     "examples.rb",
-     "examples/an_error.rb",
-     "examples/assertion_failure.rb",
-     "examples/assertion_success.rb",
-     "examples/assertion_success_and_failure.rb",
-     "examples/check_parsing.rb",
-     "examples/check_with_disambiguation.rb",
-     "examples/checking_nil.rb",
-     "examples/dumping_classes.rb",
-     "examples/helpers.rb",
-     "examples/no_checks.rb",
-     "examples/no_checks_non_string.rb",
-     "examples/oneliner.rb",
-     "examples/ten_percent_failures.rb",
-     "examples/with_checks.rb",
-     "examples/with_setup.rb",
-     "exemplor.gemspec",
-     "lib/exemplor.rb"
-  ]
-  s.homepage = %q{http://github.com/quackingduck/exemplor}
-  s.rdoc_options = ["--charset=UTF-8"]
-  s.require_paths = ["lib"]
-  s.rubygems_version = %q{1.3.5}
-  s.summary = %q{A light-weight, low-fi way to provide executable usage examples of your code.}
-  s.test_files = [
-    "examples/an_error.rb",
-     "examples/assertion_failure.rb",
-     "examples/assertion_success.rb",
-     "examples/assertion_success_and_failure.rb",
-     "examples/check_parsing.rb",
-     "examples/check_with_disambiguation.rb",
-     "examples/checking_nil.rb",
-     "examples/dumping_classes.rb",
-     "examples/helpers.rb",
-     "examples/no_checks.rb",
-     "examples/no_checks_non_string.rb",
-     "examples/oneliner.rb",
-     "examples/ten_percent_failures.rb",
-     "examples/with_checks.rb",
-     "examples/with_setup.rb"
-  ]
-
-  if s.respond_to? :specification_version then
-    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
-    s.specification_version = 3
-
-    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
-      s.add_runtime_dependency(%q<orderedhash>, [">= 0.0.6"])
-      s.add_runtime_dependency(%q<term-ansicolor>, [">= 1.0.3"])
-    else
-      s.add_dependency(%q<orderedhash>, [">= 0.0.6"])
-      s.add_dependency(%q<term-ansicolor>, [">= 1.0.3"])
-    end
-  else
-    s.add_dependency(%q<orderedhash>, [">= 0.0.6"])
-    s.add_dependency(%q<term-ansicolor>, [">= 1.0.3"])
-  end
-end