README.xmpfilter

xmpfilter  http://eigenclass.org/hiki.rb?xmpfilter
Copyright (c) 2005-2008 Mauricio Fernandez <mfp@acm.org> http://eigenclass.org
                        rubikitch <rubikitch@ruby-lang.org>
Use and distribution subject to the terms of the Ruby license.

Overview
========
xmpfilter is a small tool that can be used to
* generate Test::Unit assertions, RSpec expectations and
  expectations blocks semi-automatically
* annotate source code with intermediate results (a bit like irb
  --simple-prompt but only for the lines explicitly marked with # =>)
  Very useful for example code (such as postings to ruby-talk).

Usage
=====
xmpfilter takes its input from stdin and writes to stdout. It can run in
several modes (annotation, Test::Unit assertion expansion, RSpec expectation
generation, expectations expectations generation, marker insertion); see 
 xmpfilter -h 
README.emacs and README.vim describe how to use xmpfilter from your editor.

Example: code annotation
========================
Just add "# =>" markers to the lines whose values you want to be shown:

 a, b = "foo", "baz"
 a + b                                             # =>
 a.size                                            # =>

will be expanded to (in one keypress in a decent editor, see README.emacs and
README.vim)

 a, b = "foo", "baz"
 a + b                                             # => "foobaz"
 a.size                                            # => 3

This saves much cut&pasting when you're posting to ruby-list/ruby-talk/ruby-core
(We use it all the time).


Example: multi-line code annotation
===================================
Just add "# =>" markers to the next lines whose values you want to be shown with pp:

a = ["1111111111111111111111111111111111111111111111111111", 123334324234242342,
  1332333333,6,8 ]
1                               # => 
a
# => 

will be expanded to (in one keypress in a decent editor, see README.emacs and
README.vim)

a = ["1111111111111111111111111111111111111111111111111111", 123334324234242342,
  1332333333,6,8 ]
1                               # => 1
a
# => ["1111111111111111111111111111111111111111111111111111",
#     123334324234242342,
#     1332333333,
#     6,
#     8]


Example: assertion generation
=============================

xmpfilter can generate assertions based on the current behavior of the code
to be tested (iow. the current behavior is assumed to be correct and is used
to generate assertions which won't be modified by further runs of
xmpfilter), making it quite useful for regression testing.

Imagine you have a ComplexClass you want to test. You might start with

    class TestComplexClass < Test::Unit::TestCase
      def setup; @o = ComplexClass.new("foo", false) end
    end

and then want to add some tests:

  def test_insertion
    @o.insert "bar"
    @o.insert "baz"
    # ... assertions here
  end

At this point, you want to add several assertions to verify that the values
returned by @o.size, @o.last, @o.first, @o.complex_computation and @o.last(2)
are correct. You can just write the following and feed the file to
xmpfilter in -u mode (the # => markers can also be inserted by
xmpfilter, see README.vim for more information:

  def test_insertion
    @o.insert "bar"
    @o.insert "baz"
    @o.size                                        # =>
    @o.last                                        # =>
    @o.first                                       # =>
    @o.complex_computation                         # =>
    @o.last(2)                                     # =>
  end

xmpfilter will run the test and remember what happened in each marked line,
and then rewrite the code so that it looks for instance like

  def test_insertion
    @o.insert "bar"
    @o.insert "baz"
    assert_equal(2, @o.size)
    assert_equal("baz", @o.last)
    assert_equal("bar", @o.first)
    assert_in_delta(3.14159265358979, @o.complex_computation, 0.0001)
    assert_equal(["baz", "bar"], @o.last(2))
  end

As you can see, it can save some typing.

You can edit the generated assertions as you want: xmpfilter will not
modify lines without the "# =>" marker. xmpfilter can be used repeatedly as
you add more assertions. Imagine you want to verify that @o.last(3) raises an
ArgumentError. You can simply add one line marked with # => :
  
  ...
    assert_in_delta(3.14159265358979, @o.complex_computation, 0.0001)
    assert_equal(["baz", "bar"], @o.last(2))
    @o.last(3)                                     # =>
  end

and have it expanded by xmpfilter:

  ...
    assert_in_delta(3.14159265358979, @o.complex_computation, 0.0001)
    assert_equal(["baz", "bar"], @o.last(2))
    assert_raise(ArgumentError){ @o.last(3) } 
  end


Example: RSpec expectations
===========================
Here's some code before and after filtering it with xmpfilter:

  class X
    Y = Struct.new(:a)
    def foo(b); b ? Y.new(2) : 2 end
    def bar; raise "No good" end
    def baz; nil end
    def fubar(x); x ** 2.0 + 1 end
    def babar; [1,2] end
    A = 1
    A = 1
  end

  context "Testing xmpfilter's expectation expansion" do
    setup do
      @o = X.new
    end

    specify "Should expand should_equal expectations" do
      @o.foo(true)   # =>
      @o.foo(true).a # =>
      @o.foo(false)  # =>
    end

    specify "Should expand should_raise expectations" do
      @o.bar         # =>
    end

    specify "Should expand should_be_nil expectations" do
      @o.baz         # =>
    end

    specify "Should expand correct expectations for complex values" do
      @o.babar       # =>
    end

    specify "Should expand should_be_close expectations" do
      @o.fubar(10)   # =>
    end
  end


after piping it to xmpfilter -s:

  class X
    Y = Struct.new(:a)
    def foo(b); b ? Y.new(2) : 2 end
    def bar; raise "No good" end
    def baz; nil end
    def fubar(x); x ** 2.0 + 1 end
    def babar; [1,2] end
    A = 1
    A = 1 # !> already initialized constant A
  end

  context "Testing xmpfilter's expectation expansion" do
    setup do
      @o = X.new
    end

    specify "Should expand should_equal expectations" do
      (@o.foo(true)).should_be_a_kind_of X::Y
      (@o.foo(true).inspect).should_equal "#<struct X::Y a=2>"
      (@o.foo(true).a).should_equal 2
      (@o.foo(false)).should_equal 2
    end

    specify "Should expand should_raise expectations" do
      lambda{(@o.bar)}.should_raise RuntimeError
    end

    specify "Should expand should_be_nil expectations" do
      (@o.baz).should_be_nil
    end

    specify "Should expand correct expectations for complex values" do
      (@o.babar).should_equal [1, 2]
    end

    specify "Should expand should_be_close expectations" do
      (@o.fubar(10)).should_be_close(101.0, 0.0001)
    end
  end


Example: expectations expectations
==================================
Expectations is a light-weight unit testing framework by Jay Fields.
(http://expectations.rubyforge.org)

Here's some code before and after filtering it with xmpfilter:

  require 'rubygems'
  require 'expectations'

  S = Struct.new :a
  Expectations do
    1 + 1  # =>
    "a".length # =>
    [][1] # =>
    1.hoge # =>
    1.1 + 1.0 # =>
    S.new(1) # =>
  end

after piping it to xmpfilter --expectations:

  require 'rubygems'
  require 'expectations'

  S = Struct.new :a
  Expectations do
    expect 2 do
      1 + 1
    end

    expect 1 do
      "a".length
    end

    expect nil do
      [][1]
    end

    expect NoMethodError do
      1.hoge
    end

    expect 2.0999..2.1001 do
      1.1 + 1.0
    end

    expect S do
      S.new(1)
    end

    expect "#<struct S a=1>" do
      S.new(1).inspect
    end

  end


License
=======
xmpfilter is licensed under the same terms as Ruby.