[BioRuby] BioRuby Documentation effort

[Ara.T.Howard]

On Fri, 16 Sep 2005, Pjotr Prins wrote:

> I edited the tutorial - and it is in CVS. I think it is a good start, but
> what we also need is more on how a biologist should approach Ruby and
> BioRuby. I.e. most of the examples are centered around access and some minor
> sequence alteration. What other good examples can we think of that puts a
> distance between BioConductor and/or BioPerl, for example?
>
> Secondly I would like to use some system where examples double as unit tests
> - like BioConductor and Python have. That should make certain examples are
> always correct. Any ideas on this?

i've done this the following way before:

using as an example:

   harp:~ > cat a.rb
   require 'yaml'
   #
   # an example class
   #
     class C
       def initialize hash
         @h = hash
       end
       def method
         @h['answer'] == 42
       end
     end
   #
   # read input from stdin if there is any, else use a default
   #
     stdin = ! STDIN.tty?

     default_input = <<-yaml
       key    : value
       foo    : bar
       answer : 42
     yaml

     input = YAML::load(stdin ? STDIN.read : default_input)
   #
   # create an object and get the output of a method
   #
     c = C::new input
     output = c.method
   #
   # dump output on stdout in yaml format
   #
     y output


   harp:~ > ruby a.rb
   --- true


using the sample program as a unit test:

   harp:~ > cat b.rb
   require 'yaml'
   require 'test/unit'

   class ATest < Test::Unit::TestCase
     def run_a_rb input
       pipe = IO::popen 'ruby a.rb', 'r+'
       pipe.write input.to_yaml
       pipe.close_write
       output = YAML::load pipe.read
       pipe.close_read
       output
     end
     def test_0
       assert_equal true, run_a_rb('answer' => 42)
     end
     def test_1
       assert_equal true, run_a_rb('answer' => 41)
     end
   end



   harp:~ > ruby b.rb
   Loaded suite b
   Started
   .F
   Finished in 0.08528 seconds.

     1) Failure:
   test_1(ATest) [b.rb:17]:
   <true> expected but was
   <false>.

   2 tests, 2 assertions, 1 failures, 0 errors


obviously it needs to be a bit more robust - but you get the idea eh: each
sample progam takes one input and produces on ouput.  the input and output
should, ideally be conbinations of strings, hashes, arrays, fixnums, and
floats because these objects are very easy to read in yaml.  the test cases
simple construct objects and run the program with them.  because the output of
the program is also in yaml quite complex outputs can be verified and, if you
stick to hashes/arrays/strings/floats/fixnums, also read quite easily.

cheers.

-a
-- 
===============================================================================
| email :: ara [dot] t [dot] howard [at] noaa [dot] gov
| phone :: 303.497.6469
| Your life dwells amoung the causes of death
| Like a lamp standing in a strong breeze.  --Nagarjuna
===============================================================================