exemplor 2.2.0

data/.gitignore

@@ -0,0 +1 @@
+pkg

data/README

@@ -0,0 +1,152 @@
+Examplor (the exemplar)
+=======================
+
+An example-based test framework inspired by [testy](http://github.com/ahoward/testy).
+
+Simpler that BDD/TDD, fancier than a file with a bunch of print statements.
+
+Very tiny api. Here it is
+    
+    eg.helpers do
+      ... your helpers ...
+    end
+    
+    eg.setup { ... setup codez ... }
+      
+    eg "an example" do
+      ... example code ...
+    end
+    
+    eg "another example" do
+      ... etc ...
+    end                                      
+
+The output is both human readable and machine parsable, which means you can test your tests.
+
+Writing Examples
+----------------
+
+See `examples.rb` and `/examples` for more examples.
+
+The simplest possible example:
+                                
+    eg 'An example block without any checks prints the value of the block' do
+      "foo"
+    end
+    
+    #=>
+    
+    (i) An example block without any checks prints the value of the block: foo
+
+The 'i' stands for 'info' which means the example ran without error.
+
+Inspecting a few values, by default `Check` prints it's argument and the value of the argument:
+                                
+    eg 'Accessing different parts of an array' do
+      list = [1, 2, 3]
+      Check(list.first)
+      Check(list[1])
+      Check(list.last)
+    end
+    
+    #=>
+    
+    (I) Accessing different parts of an array: 
+      (i) list.first: 1
+      (i) list[1]: 2
+      (i) list.last: 3
+
+The capital 'I' means all checks were 'info' checks.
+
+Call's to `Check` with the same argument can be disambiguated with `[]`:
+
+    eg 'Array appending' do
+      list = [1, 42]
+      Check(list.last)["before append"]
+      list << 2
+      Check(list.last)["after append"]
+    end
+    
+    #=>
+    
+    (I) Array appending: 
+      (i) list.last before append: 42
+      (i) list.last after append: 2
+
+Errors are caught and reported nicely:
+    
+    eg 'Raising an error' do
+      raise "boom!"    
+    end
+
+    #=>
+
+    (e) Raising an error: 
+      class: RuntimeError
+      message: boom!
+      backtrace: 
+      - examples/an_error.rb:4
+      # ... more backtrace lines
+
+Once you're happy with how your code is running you can make some assertions about its behaviour by adding `is()` calls after your `Check()` statements:
+    
+    
+    eg 'Asserting first is first' do
+      list = [1, 2, 3]
+      Check(list.first).is(1)
+    end
+
+    #=>
+
+    (s) Asserting first is first: 
+      (s) list.first: 1
+
+'s' stands for 'success' and 'f' for failure:
+
+    eg 'Assertion failure' do
+      list = [1, 2, 3]
+      Check(list.first).is(2)
+    end
+
+    #=>
+
+    (f) Assertion failure: 
+      (f) list.first: 
+        expected: 2
+        actual: 1
+
+
+Running Examples
+----------------
+
+Running with `--list` or `-l` lists all examples:
+
+    $> ruby examples.rb -l
+    - errors are caught and nicely displayed
+    - check_output_matches_expected_for :no_checks
+    - check_output_matches_expected_for :oneliner
+    - check_output_matches_expected_for :no_checks_non_string
+    - check_output_matches_expected_for :with_checks
+    - check_output_matches_expected_for :check_with_disambiguation
+    - check_output_matches_expected_for :assertion_success
+    - check_output_matches_expected_for :assertion_failure
+    - check_output_matches_expected_for :assertion_success_and_failure
+    - check_output_matches_expected_for :helpers
+    - check_output_matches_expected_for :with_setup
+    - called with --list arg
+    - called with --l arg
+    - called with some other arg (always interpreted as a regex)
+
+Otherwise the first argument is taken as a regex and only examples who's titles match are run:
+    
+    $> ruby examples.rb called
+    (s) called with --list arg: 
+      (s) list: 
+      - Modified env
+      - Unmodified env
+    (s) called with --l arg: 
+      (s) list: 
+      - Modified env
+      - Unmodified env
+    (s) called with some other arg (always interpreted as a regex): 
+      (s) tests_run: 1

data/Rakefile

@@ -0,0 +1,16 @@
+# require "mg"
+# MG.new("exemplor.gemspec")
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gs|
+    gs.name     = "exemplor"
+    gs.homepage = "http://github.com/quackingduck/exemplor"
+    gs.summary  = "A light-weight, low-fi way to provide executable usage examples or your code."
+    gs.email    = "myles@myles.id.au"
+    gs.authors  = ["Myles Byrne"]
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Install jeweler to build gem"
+end

data/TODO

@@ -0,0 +1,6 @@
+* support multiple groups
+* #teardown
+* Use fancy unicode characters for tests status:
+# ‣
+# ✓
+# ✗

data/VERSION

@@ -0,0 +1 @@
+2.2.0

data/examples.rb

@@ -0,0 +1,59 @@
+# TODO: switch to gem version
+require 'lib/exemplor'
+
+# slow because each test runs in a subshell
+
+eg.helpers do
+
+  def run_example(name, args = nil)
+    `ruby -Ilib examples/#{name}.rb#{' ' + args if args}`
+  end
+
+  def extract_expected(name)
+    File.read("examples/#{name}.rb").split('__END__').last
+  end
+  
+  def expected_and_actual(example_name)
+    [extract_expected(example_name).strip, run_example(example_name).strip]
+  end
+  
+  def check_output_matches_expected_for(example_name)
+    expected_output, output = expected_and_actual(example_name)
+    Check(output).is(expected_output)
+  end
+
+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)))
+end
+
+eg { check_output_matches_expected_for :no_checks }
+eg { check_output_matches_expected_for :oneliner }
+eg { check_output_matches_expected_for :no_checks_non_string }
+eg { check_output_matches_expected_for :with_checks }
+eg { check_output_matches_expected_for :check_with_disambiguation }
+eg { check_output_matches_expected_for :assertion_success }
+eg { check_output_matches_expected_for :assertion_failure }
+eg { check_output_matches_expected_for :assertion_success_and_failure }
+eg { check_output_matches_expected_for :helpers }
+eg { check_output_matches_expected_for :with_setup }
+
+eg "called with --list arg" do
+  list = YAML.load(run_example(:with_setup, '--list'))
+  Check(list).is(["Modified env", "Unmodified env"])
+end
+
+eg "called with --l arg" do
+  list = YAML.load(run_example(:with_setup, '--list'))
+  Check(list).is(["Modified env", "Unmodified env"])
+end
+
+eg "called with some other arg (always interpreted as a regex)" do
+  tests_run = YAML.load(run_example(:with_setup, 'Unmodified')).size
+  Check(tests_run).is(1)
+end

data/examples/an_error.rb

@@ -0,0 +1,14 @@
+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

data/examples/assertion_failure.rb

@@ -0,0 +1,13 @@
+require 'exemplor'
+
+eg 'Assertion failure' do
+  list = [1, 2, 3]
+  Check(list.first).is(2)
+end
+
+__END__
+
+(f) Assertion failure: 
+  (f) list.first: 
+    expected: 2
+    actual: 1

data/examples/assertion_success.rb

@@ -0,0 +1,11 @@
+require 'exemplor'
+
+eg 'Asserting first is first' do
+  list = [1, 2, 3]
+  Check(list.first).is(1)
+end
+
+__END__
+
+(s) Asserting first is first: 
+  (s) list.first: 1

data/examples/assertion_success_and_failure.rb

@@ -0,0 +1,18 @@
+require 'exemplor'
+
+eg 'Some successes, then a fail' do
+  list = [1, 2, 3]
+  Check(list.first).is(1)
+  Check(list[1]).is(2)
+  Check(list.last).is(1)
+  Check(list[2]).is(3) # would be successful but we never get here
+end
+
+__END__
+
+(f) Some successes, then a fail: 
+  (s) list.first: 1
+  (s) list[1]: 2
+  (f) list.last: 
+    expected: 1
+    actual: 3

data/examples/check_with_disambiguation.rb

@@ -0,0 +1,14 @@
+require 'exemplor'
+
+eg 'Array appending' do
+  list = [1, 42]
+  Check(list.last)["before append"]
+  list << 2
+  Check(list.last)["after append"]
+end
+
+__END__
+
+(I) Array appending: 
+  (i) list.last before append: 42
+  (i) list.last after append: 2

data/examples/helpers.rb

@@ -0,0 +1,17 @@
+require 'exemplor'
+
+eg.helpers do
+  
+  def foo
+    "foo"
+  end
+  
+end
+
+eg 'Example calling helper' do
+  foo
+end
+
+__END__
+
+(i) Example calling helper: foo

data/examples/no_checks.rb

@@ -0,0 +1,9 @@
+require 'exemplor'
+
+eg 'An example block without any checks prints the value of the block' do
+  "foo"
+end
+
+__END__
+
+(i) An example block without any checks prints the value of the block: foo

data/examples/no_checks_non_string.rb

@@ -0,0 +1,15 @@
+require 'exemplor'
+
+class MyClass
+  def inspect
+    "<MyClass instance>"
+  end
+end
+
+eg 'Non-string return values get inspected' do
+  MyClass.new
+end
+
+__END__
+
+(i) Non-string return values get inspected: <MyClass instance>

data/examples/oneliner.rb

@@ -0,0 +1,7 @@
+require 'exemplor'
+
+eg { 1+2 }
+
+__END__
+
+(i) 1+2: 3

data/examples/with_checks.rb

@@ -0,0 +1,15 @@
+require 'exemplor'
+
+eg 'Accessing different parts of an array' do
+  list = [1, 2, 3]
+  Check(list.first)
+  Check(list[1])
+  Check(list.last)
+end
+
+__END__
+
+(I) Accessing different parts of an array: 
+  (i) list.first: 1
+  (i) list[1]: 2
+  (i) list.last: 3

data/examples/with_setup.rb

@@ -0,0 +1,20 @@
+require 'exemplor'
+
+  
+eg.setup { @str = "foo" }
+
+eg 'Modified env' do
+  @str << " bar"
+  Check(@str).is("foo bar")
+end
+
+eg 'Unmodified env' do
+  Check(@str).is("foo")
+end
+
+__END__
+
+(s) Modified env: 
+  (s) @str: foo bar
+(s) Unmodified env: 
+  (s) @str: foo

data/exemplor.gemspec

@@ -0,0 +1,66 @@
+# 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 = "2.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-10-12}
+  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_with_disambiguation.rb",
+     "examples/helpers.rb",
+     "examples/no_checks.rb",
+     "examples/no_checks_non_string.rb",
+     "examples/oneliner.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 or 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_with_disambiguation.rb",
+     "examples/helpers.rb",
+     "examples/no_checks.rb",
+     "examples/no_checks_non_string.rb",
+     "examples/oneliner.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
+    else
+    end
+  else
+  end
+end

data/lib/exemplor.rb

@@ -0,0 +1,224 @@
+require 'rubygems' # TODO: remove
+require 'orderedhash'
+require 'yaml'
+
+module Exemplor
+  
+  class ExampleDefinitionError < StandardError ; end
+    
+  class Check
+    
+    attr_reader :expectation, :value
+    
+    def initialize(name, value)
+      @name  = name
+      @value = value
+    end
+    
+    def [](disambiguate)
+      @disambiguate = disambiguate
+    end
+    
+    def name
+      @name + (@disambiguate ? " #{@disambiguate}" : '')
+    end
+    
+    def is(expectation)
+      @expectation = expectation
+    end
+    
+    def status
+      return :info if !@expectation
+      @value == @expectation ? :success : :failure
+    end
+    
+    def success?
+      status == :success
+    end
+    
+    def failure?
+      status == :failure
+    end
+    
+    def info?
+      status == :info
+    end
+    
+  end
+  
+  class Example
+    
+    class << self
+      
+      alias_method :helpers, :class_eval
+      attr_accessor :setup_block
+      
+      def setup(&blk) self.setup_block = blk end
+      
+    end
+    
+    attr_accessor :_checks
+    
+    def initialize
+      @_checks = []
+    end
+    
+    # fragile. doesnt work with calls like
+    # Check(get('/'))
+    # Check foo
+    def Check(value)
+      file, line_number = caller.first.match(/^(.+):(\d+)/).captures
+      line = File.read(file).map[line_number.to_i - 1]
+      name = line[/Check\((.+?)\)/,1]
+      check = Check.new(name, value)
+      _checks << check
+      check
+    end
+    
+  end
+  
+  class Examples
+    
+    attr_writer :setup_block
+    
+    def initialize
+      @examples = OrderedHash.new
+    end
+    
+    def add(name, &body)
+      @examples[name] = body
+    end
+    
+    def run(patterns)
+      # unoffically supports multiple patterns
+      patterns = Regexp.new(patterns.join('|'))
+      @examples.each do |name, body|
+        if name =~ patterns
+          status, out = run_example(body)
+          print_yaml("#{status_icon(status)} #{name}" => out)
+        end
+      end
+    end
+    
+    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
+    
+    # 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
+      out = begin
+        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 = :fail if env._checks.any? { |check| check.failure? }          
+          render_checks(env._checks)
+        end
+      rescue Object => error
+        status = :error
+        render_error(error)
+      end
+      [status, out]
+    end
+    
+    def render_value(value)
+      out = case value
+        when String, Numeric : value
+        else ; value.inspect ; end
+    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}"] = check.value
+      end
+      if failure
+        fail_out = out["#{status_icon(failure.status)} #{failure.name}"] = OrderedHash.new
+        fail_out['expected'] = failure.expectation
+        fail_out['actual'] = 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
+    
+  end
+  
+  class << self
+    
+    def examples
+      @examples ||= Examples.new
+    end
+    
+  end
+  
+end
+
+def eg(name = nil, &example)
+  return Exemplor::Example if name.nil? && example.nil?
+  if name.nil?
+     file, line_number = caller.first.match(/^(.+):(\d+)/).captures
+     line = File.read(file).map[line_number.to_i - 1]
+     name = line[/^\s*eg\s*\{\s*(.+?)\s*\}\s*$/,1] if name.nil?
+     raise Exemplor::ExampleDefinitionError, "example at #{caller.first} has no name so must be on one line" if name.nil?
+  end
+  Exemplor.examples.add(name, &example)
+end
+
+at_exit do
+  args = ARGV.dup
+  if args.delete('--list') || args.delete('-l')
+    Exemplor.examples.list(args)
+  else
+    Exemplor.examples.run(args)
+  end
+end

metadata

@@ -0,0 +1,83 @@
+--- !ruby/object:Gem::Specification 
+name: exemplor
+version: !ruby/object:Gem::Version 
+  version: 2.2.0
+platform: ruby
+authors: 
+- Myles Byrne
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-10-12 00:00:00 +11:00
+default_executable: 
+dependencies: []
+
+description: 
+email: myles@myles.id.au
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README
+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_with_disambiguation.rb
+- examples/helpers.rb
+- examples/no_checks.rb
+- examples/no_checks_non_string.rb
+- examples/oneliner.rb
+- examples/with_checks.rb
+- examples/with_setup.rb
+- exemplor.gemspec
+- lib/exemplor.rb
+has_rdoc: true
+homepage: http://github.com/quackingduck/exemplor
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: A light-weight, low-fi way to provide executable usage examples or your code.
+test_files: 
+- examples/an_error.rb
+- examples/assertion_failure.rb
+- examples/assertion_success.rb
+- examples/assertion_success_and_failure.rb
+- examples/check_with_disambiguation.rb
+- examples/helpers.rb
+- examples/no_checks.rb
+- examples/no_checks_non_string.rb
+- examples/oneliner.rb
+- examples/with_checks.rb
+- examples/with_setup.rb