dev-utils 1.0

data/etc/doc/UnitTestOrganisation.textile

@@ -0,0 +1,253 @@
+
+!header dev-utils/test main
+
+h1.    Unit Test Organisation
+
+!toc
+
+<div class="planned">
+
+(Everything in this section is _planned_ functionality.)
+
+h2.        Introduction
+
+Unit testing can be a pain to organise.
+* You have to tell your test code where to find the library code that it's
+  testing.
+* You need a mechanism for running all your tests at once, but would also like
+  to be able to run just one, or a few.
+* If the tests need data, you need to organise that as well.  Sometimes you
+  need to work on a copy of the data so you don't muck it up for the next
+  test run.
+
+All of these organisational hassles are dealt with by the @dev-utils/test@
+package.  It provides a method for running your test suite (specifying which
+tests if you like), which manages the load path.  It also provides a method
+for accessing test data in a flexible way.  These only work if you follow some
+conventions (detailed below).  So the final benefit provided by
+@dev-utils/test@ is a documented approach to managing the unit testing
+part of any project.
+
+The whole point of @dev-utils/test@ is to collect a certain unit testing
+organisation methodology in one place, and make that reusable across projects.
+This is better than having to roll your own on each new project, usually
+without a clear strategy.
+
+This document contains:
+* the rules for using @dev-utils/test@ with your project;
+* the @dev-utils/test@ approach in detail;
+* the ground rules to follow so @dev-utils/test@ can work with your project;
+* configuration options in case you want to vary some things;
+* information about the complete sample project included in the distribution.
+
+p(comment). I'll probably forget about a "complete sample project".  It should
+be easy enough to use without that.  Perhaps refer to a live project that uses
+it.
+
+
+h2.        A @dev-utils/test@ Project: Summary
+
+Relative to your project's root directory:
+
+* Library code goes under @lib/@.  So when a unit test does @require
+  'projX/init'@, it will be @lib/projX/init.rb@ that is loaded.
+
+* Unit test files are named, for example, @tc_projX.rb@, and go in @test/@ or
+  a subdirectory.
+
+* You have a master test file, @test/TEST.rb@, which loads and runs some or
+  all of your unit tests.  Writing this file is extremely easy, as
+  @dev-utils/test@ does all the hard work.
+
+** Running @ruby test/TEST.rb@ is the *only* way to run your unit tests.
+
+** This program gives you options over which tests are run and how much output
+   is given.
+
+* Test data (files containing data that are used for unit tests) is located in
+  @test/DATA@ or a subdirectory.  Unit tests use a method called @load_data@
+  to access this test data.
+
+h3.            Using Rake to Run Tests
+
+Pursuant to the running of unit tests via @test/TEST.rb@, here is a Rake task
+you can set up to run your tests for you.
+
+<pre>
+  desc "Run unit tests"
+  task :test do
+     exec "ruby test/TEST.rb #{ARGV.join(' ')}"
+  end
+</pre>
+
+If that is in your Rakefile, and the Rakefile is in the project's root
+directory, then you can run @rake test@ from any directory in the project, and
+your unit tests will run.  There are various command-line options you can give
+to @test/TEST.rb@, as the next section will detail.
+
+
+h2.        A @dev-utils/test@ Project: Detail
+
+To make use of @dev-utils/test@, this is how you operate.  All your
+unit tests are coded in files like @tc_<i>foo</i>.rb@ in the @test@
+directory, or subdirectories.  There is one master test file
+@test/TEST.rb@, which will load and run all of the unit test files.
+Thanks to this package, however, writing that file is easy.
+
+This is what happens when you run @ruby test/TEST.rb --help@:
+
+<pre style="font-size:10pt"> Welcome to the dev-utils/test automatic unit test runner.  Here are the
+  options:
+  
+     -q              quiet mode
+     -Q              very quiet mode
+     -v              verbose mode (default)
+     -s              run unit tests in separate test suites
+     -h              show help
+     str1 str2 ...   run only those tests whose filenames contain str1 or
+                     str2 or ...
+
+  For example, to run only those tests whose filenames include "remote" or
+  "db", and to run a separate suite for each test file, and to run in quiet
+  mode:
+
+    ruby test/TEST.rb -q remote db -s
+</pre>
+
+As the developer, you don't need to do any programming to make this happen;
+you just need to create @test/TEST.rb@, in which you call one method.
+This is what that file looks like:
+
+<pre>
+    require 'rubygems'
+    require 'dev-utils/test'
+
+    DevUtils::Test.load_tests(__FILE__, *ARGV)
+</pre>
+
+As a sneak peek behind the scenes, @load_tests@ uses <code>__FILE__</code> to
+orient itself, using default values to locate the @lib@ directory (so it can
+manipulate the Ruby load path), and the @DATA@ directory (so calls to
+@load_data@ will work).
+
+So far, we have covered two of the three organisational hassles listed in the
+introduction.  The remaining one is managing test data.  This is handled by
+the @load_data@ method.
+
+All your test data is contained in files underneath the @test/DATA@
+directory.  You use the path to those files (relative to @test/DATA@)
+to identify the data file you want to load.  Simple enough.  So a unit test
+for an email reader might look like this:
+
+<pre>
+  def test_sender_extraction
+    input  = Test.load_data('bulk/emails.txt')
+    output = EmailParser.parse(input)
+    assert_equal(...)
+  end
+</pre>
+
+In that case, the data in the @test/DATA/bulk/emails.txt@ file was served up
+as a String.  But @load_data@ is more flexible than that.  It defaults to
+returning a String, but can return a File (opened for reading) or a Pathname
+instead.  Also, it can make a copy of the file (to a temporary place) and
+point you to that.
+
+So a unit test that is modifying an SQLite database might look like this:
+
+<pre>
+  def test_database_modification
+    dbfile = Test.load_data('customers3.db', :pathname, :copy)
+    init_system(dbfile)
+    ...
+  end
+</pre>
+
+The above code uses <i>@Test@</i> instead of <i>@DevUtils::Test@</i>
+because it is assumed that an @include DevUtils@ was performed in the
+test class.
+
+
+h3.            Consequences
+
+The consequence of writing unit tests using @dev-utils/test@ is that they
+cannot be run directly.  Unit tests are written _assuming_ that they can find
+the right library file in the load path.  Without being run through
+@test/TEST.rb@, this assumption does not (necessarily) hold.
+
+And if a unit test calls @load_data@ without the initialization step that
+@load_tests@ provides (or without explicit initialization - see below), then
+that data will not be found.
+
+
+h2.        Ground Rules
+
+<b><i>The information here has been effectively stated in the Summary section
+above.  Get rid of this.</i></b>
+
+In order to benefit from these unit testing features, you must follow some
+conventions in the way you organise your project and write your code.  If your
+project is called @projectX@, then this is how it should be organised:
+
+* The unit tests themselves are named @tc_<i>foo</i>.rb@, and are
+  located under the @projectX/test@ directory.  The name of that
+  directory doesn't matter, but we're assuming that for the following points.
+
+* The master test runner is @projectX/test/TEST.rb@.  Unit tests are
+  *always* run through this program.  It contains the code shown in the
+  previous section.
+
+* The library code goes in @projectX/lib/...@.  Observing this
+  convention means that @load_tests@ knows where to find the library code that
+  is being tested.
+
+* If the tests make use of data files, those files are located in the
+  @projectX/test/DATA@ directory.  This way, the default will work and
+  the @load_tests@ method above will set the data directory correctly.
+
+* ...
+
+
+h2.        Configurations
+
+If you want the test data directory to be something other than
+@test/DATA@, or you want the lib directory to be something other than
+@lib@ (both relative to the root directory of the project), then the
+following methods are available to you:
+* @DevUtils::Test.project_dir = ...@
+* @DevUtils::Test.set_project_dir_from(path, project_name)@
+* @DevUtils::Test.lib_dir  = ...@
+* @DevUtils::Test.test_dir = ...@
+* @DevUtils::Test.data_dir = ...@
+
+If you want to specify any of them, then you *must* specify the project
+directory first, as all the others are interpreted relative to that.  Also,
+these directories must be specified _before_ you call @load_tests@.  Really,
+the only appropriate place for any of this is @test/TEST.rb@.
+
+p. @set_project_dir_from@ is the easier way to set the project directly.  If you
+use @project_dir=@ instead, _make sure_ you specify an absolute path (_I think
+that requirement still stands..._).
+
+Here is an example of a @unit-tests/run_tests.rb@ file with full
+customisation.  The name of the project is @projectX@.
+
+<pre>
+  require 'rubygems'
+  require 'dev-utils/test'
+  include DevUtils
+
+  Test.set_project_dir_from(__FILE__, "projectX")
+  Test.lib_dir = "."
+  Test.test_dir = "unit-tests"
+  Test.data_dir = "etc/test-data"
+
+  Test.load_tests(__FILE__, *ARGV)
+</pre>
+
+
+h2.        A Complete Sample Project
+
+p(comment). Not bloody likely.
+
+</div>

data/etc/doc/generate.rb

@@ -0,0 +1,187 @@
+#
+# = generate.rb, for the ruby-journal project.
+#
+# Documents are written in Textile and converted to HTML with RedCloth.
+#
+# However, RedCloth only generates HTML _fragments_.  We need to generate HTML _documents_,
+# with <tt><head></tt> information (especially CSS), etc.
+#
+# The simple function +generate_document+ does this.
+#
+
+require 'rubygems'
+require 'redcloth'
+require 'extensions/io'
+require 'celsoft.com/template'
+
+  #
+  # Takes the Textile file from +path+ (relative to ~/Projects/dev-utils) and generates an HTML
+  # file in the appropriate place, which is the <tt>build/www</tt> directory, and with an +html+
+  # instead of +textile+ extension.
+  #
+  # The HTML document will contain an inline stylesheet.
+  #
+  # The first "h1." tag in the document is used as the title of the HTML page. 
+  #
+  # Special lines !header and !toc are expanded.
+  #
+def generate_document(input_path, output_dir)
+  output_path = File.join(output_dir, "#{File.basename(input_path)}".sub(/\.textile/, ".html"))
+  raw_text = File.read(input_path)
+  #trace {'input_path'}
+  #trace { 'raw_text.length' }
+  input_text = process_text(raw_text)
+  red_cloth_text = RedCloth.new(input_text)
+  red_cloth_text.fold_lines = true
+  html_fragment = red_cloth_text.to_html
+  html = html_wrap(html_fragment)
+  File.write(output_path, html)
+  #File.write(output_path + '.tmp', input_text)
+end
+
+  #
+  # Expand any meta-markers like !header and !toc.
+  #
+def process_text(text)
+  require 'shellwords'
+  text.gsub(/^!(.*)\s*$/) {
+    command, *args = Shellwords.shellwords($1.strip)
+    case command
+    when 'header' then header(*args)
+    when 'toc'
+      _toc = toc(text)
+      _toc
+    else
+      raise "Unknown command embedded in textile input: #{command}"
+    end
+  }
+end
+
+CSS_FILE = 'etc/doc/textile.css'
+
+  #
+  # Wraps the given HTML fragment in head, body, etc., to produce a proper document.
+  #
+  # It points to a hardcoded stylesheet. 
+  #
+def html_wrap(fragment)
+  require 'extensions/string'
+  title = fragment.scan(%r{<h1>(.*?)</h1>}).first || []
+  title = title.first || "(no title)"
+  return %{
+    <html>
+    <head>
+      <title>#{title}</title>
+      <style type="text/css">
+        #{File.read(CSS_FILE).tabto(6)}
+      </style>
+    </head>
+    <body>
+    #{fragment}
+    </body>
+    </html>
+  }.tabto(0)
+end
+
+def header(*args)
+  require_arg = args.shift or raise ArgumentError
+  require_text = "%(small-title)<code>require '#{require_arg}'</code>%"
+  if args.shift == 'main'
+    main_page_link = '%(mylink)"main page":index.html%'
+  else
+    main_page_link = ''
+  end
+  %!table{width:100%}.\n| #{require_text} |>. #{main_page_link} |\n\n!
+end
+
+TOC_TEMPLATE = Template::Document.new
+TOC_TEMPLATE.load %!
+  <table class="toc_table">
+    <tr>
+      <td>
+        <span class="header">Links</span><br/>
+        <ul id="links">
+        ${each links}
+          <li><a href="${var href}">${var name}</a></li>
+        ${end}
+        </ul>
+      </td>
+      <td>
+        <span class="header">Contents</span><br/>
+        <ul id="contents">
+        ${each contents}
+          <li><a href="#\${var anchor}">${var heading}</a>
+            ${if subheadings}
+            <ul>
+              ${each subheadings}
+                <li><a href="#\${var anchor}">${var heading}</a></li>
+              ${end}
+            </ul>
+          </li>
+          ${end}
+        ${end}
+        </ul>
+      </td>
+    </tr>
+  </table>
+!
+
+Heading = Struct.new(:level, :heading, :anchor)
+
+  # Returns the HTML for a table containing links (from links.dat) and the contents
+  # of this page, derived from the given text.  h2 and h3 markup elements are taken
+  # to be first- and second-level headings in the text.  The text itself is modified
+  # so that those headings have anchors on them.
+def toc(text)
+    # Form links: [ { 'name' => 'Synopsis', 'href' => 'Synopsis.html' }, ... ]
+  links = links().map { |name, href|
+    Hash[ 'name', name, 'href', href ]
+  }
+
+    # Form contents: [
+    #   { 'heading' => 'Introduction', 'anchor' => 'Introduction', 'subheadings' => [ { ... } ] },
+    #   ...
+    # ]
+  regex = /^h([234])\.\s+(.*?)$/
+  headings = text.grep(regex).map { |line|
+    line =~ regex
+    level, heading = $1.to_i - 1, $2.strip
+    anchor = heading.gsub(/[^\s\w]/, '')
+    #Hash[ 'level', level, 'heading', heading, 'anchor', anchor ]
+    Heading.new(level, heading, anchor)
+  }
+  contents = []
+  headings.each do |h|
+    case h.level
+    when 1
+      contents << Hash['heading', h.heading, 'anchor', h.anchor]
+    when 2
+      (contents.last['subheadings'] ||= []) << Hash['heading', h.heading, 'anchor', h.anchor]
+    end
+  end
+
+    # Place anchors into document.  This changes the input text.
+  text.gsub!(regex) {
+    match = Regexp.last_match
+    heading = $2.strip
+    anchor = heading.gsub(/[^\s\w]/, '')
+    match[0].chomp + %{ <a name="#{anchor}"/>\n}
+  }
+
+    # Run it through the template.
+  TOC_TEMPLATE.data = { 'links' => links, 'contents' => contents }
+  TOC_TEMPLATE.output
+end
+
+  # Return [ [name, href], [name, href], ... ].
+def links
+  @links ||=
+    begin
+      links_file = Pathname.new(__FILE__).dirname + 'links.dat'
+      File.readlines(links_file).grep(/^\w/).map { |line|
+        line =~ %r{^(.*?)/(.*)$} or raise "Bad data in links.dat."
+        [$1.strip, $2.strip]
+      }
+    end
+end
+

data/etc/doc/index.textile

@@ -0,0 +1,110 @@
+!header dev-utils nomain
+
+h1.    The Ruby dev-utils Project
+
+!toc
+
+h2.        About dev-utils
+
+p. @dev-utils@ provides utilites to assist the process of developing Ruby
+programs.  At the moment, the target areas are debugging and unit testing
+(planned).
+
+Version 1.0 was released on 2004-10-08 as a RubyGem.  RPA and tarball
+installation will be provided shortly in 1.0.1.  Throughout this
+documentation, there are references to planned features.  These will be
+released in 2.0, for which there is no estimated completion date.
+
+h3.            Debugging
+
+With @dev-utils/debug@ you can:
+
+* Escape to an IRB session from a running program.
+
+<pre style="margin-left:5em">
+  breakpoint
+  breakpoint 'Person#name'           # Identify it when it happens.
+  breakpoint { @name }               # Default return value.
+</pre>
+
+* Access a no-config logfile for debugging.
+
+<pre style="margin-left:5em">
+  debug 'Database connection established'   # Look in ./debug.log
+</pre>
+
+* Trace expressions in that logfile.
+
+<pre style="margin-left:5em">
+  trace 'x + y'
+  trace 'Process.pid'
+  trace 'names', :pp                 # Pretty-print.
+  trace 'page_structure', :yaml      # YAML representation.
+</pre>
+
+* %(planned)Find the difference between complex objects (planned).%
+
+For more information, see "Debugging Aids":DebuggingAids.html.
+
+<div class="planned">
+
+h3.            Unit Testing (Planned)
+
+With @dev-utils/test@ you can:
+* Run some or all of your unit tests, automatically finding the library code.
+* Load test data from a separate data directory.
+
+For more information, see "Unit Test Organisation":UnitTestOrganisation.html.
+
+</div>
+
+
+h2.        Internet Links
+
+|{width:25ex}. Home page: | "http://dev-utils.rubyforge.org":home             |
+| Project page:           | "http://rubyforge.org/projects/dev-utils":project |
+| Download:               | "http://rubyforge.org/frs/?group_id=270":download |
+| API Documentation:      | "http://dev-utils.rubyforge.org/api":api          |
+
+[home]http://dev-utils.rubyforge.org
+[project]http://rubyforge.org/projects/dev-utils
+[download]http://rubyforge.org/frs/?group_id=270
+[api]http://dev-utils.rubyforge.org/api
+
+
+h2.        Administrivia
+
+h3.          Credits
+
+The breakpoint-related code was contributed unwittingly by Joel VanderWerf and
+Florian Gross.  The rest of the code is by Gavin Sinclair.
+
+h3.          Notes
+
+p. @dev-utils@ depends on "@extensions@":http://extensions.rubyforge.org, version
+0.5 or greater.
+
+Runnable examples are located in the @examples@ directory of the distribution.
+
+h3.          License
+
+Copyright (c) 2004, Gavin Sinclair.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions: 
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software. 
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE. 
+