From: ara.t.howard@...
Date: 2006-01-14T00:48:37+09:00
Subject: Re: Design contracts and refactoring (was Re: mathn: ugly warnings)

On Fri, 13 Jan 2006, Mathieu Bouchard wrote:

> Is there a way for code to get automatically included by rdoc and counted as
> doc without having it in two places in the source code? I mean code that
> would get run when loading a library. That way, doing "ri MyStuff" could
> display the contract for MyStuff, supposing that it's in the same file as
> the implementation.
>
> However I suppose that doing it for unit-tests (that are presumably in a
> separate file) isn't supported... yet.

oh yeah - i forgot to mention that the README is auto generated using the
samples too.  so, if one has

   ~ > cat sample/a.rb
     require "yaml"
     y 42


   ~ > ruby sample/a.rb
   ---
   42

then the above text, exactly, is used both to auto-generate the readme AND as
a unit test (getting expected from sample/expected/a.rb).


here's how the tests (samples) are run:


     #
     # find sample and expected dirs
     #
       sampledir = File::expand_path(File::join(dirname, File::join("..", "sample")))
       expecteddir = File::join sampledir, "expected"
     #
     # this tests everything in samples/* and compares against samples/expected/*
     #
       Class::new(Test::Unit::TestCase) do
         def setup; end
         samples = Dir[File::join(sampledir, "*")].select{|entry| test ?f, entry}
         test_nn = "test_sample_00"

         sample_output_expected  = lambda do |sample, expected|
           lambda do
             actual = IO::popen("ruby -I#{ libdir } #{ sample } 2>&1"){|pipe| pipe.read}
             expected = IO::read expected
             begin
               actual_doc = ::YAML::load actual
               expected_doc = ::YAML::load expected
             rescue Exception
               nil # load failure
             ensure
               assert_equal actual, expected
             end
           end
         end

         samples.each do |sample|
           dirname, basename = File::split sample
           expected = File::join expecteddir, basename
           next unless test ?e, sample and test ?e, expected
           define_method(test_nn, sample_output_expected[sample, expected])
           test_nn.succ!
         end
       end


the README file is a template which is expanded to include a

   ~> cat a.rb
     the code

   ~> ruby a.rb
     the output

section for each sample.


primative i know... but works really well for my simple libs.  it might be
worth abstractin to use a few output formats (besides yaml) and to use jamis
buck's syntax module to actually markup the code in the readme.


regards.

-a
-- 
strong and healthy, who thinks of sickness until it strikes like lightning?
preoccupied with the world, who thinks of death, until it arrives like
thunder?  -- milarepa