dev-utils 1.0

data/HISTORY.txt

@@ -0,0 +1,36 @@
+(All changes by Gavin Sinclair <gsinclair@soyabean.com.au> unless otherwise
+noted or input credited.)
+
+=== 2004-10-08
+
+Version 1.0 released.
+
+=== 2004-10-06-8
+
+Internal version 0.0.2, with the following changes:
+
+* Commented out the code in <tt>test.rb</tt> and <tt>debug/diff.rb</tt>.
+  These files are not ready for release, but I don't want to delay the release
+  of the basic functionality (breakpoints, logging, and tracing).
+
+* <tt>dev-utils/debug-inline.rb</tt> and <tt>dev-utils/test-inline.rb</tt>
+  removed; no longer needed.  When you require 'dev-utils/debug', the
+  DevUtils::Debug module is included in the toplevel for convenience.  I doubt
+  this will cause problematic clashes, but at least the option is there to
+  later allow a non-intrusive library, like <tt>dev-utils/debug/module</tt>.
+
+* Removed Synopsis.textile and put simple code snippets into the main page.
+
+* Added MIT license.
+
+* Textile documentation polished up.  Examples added, planned stuff so marked,
+  comments removed.  RDoc documentation completed.
+
+=== 2004-09-24
+
+* Cementing version 0.0.1, as I'm going to introduce Florian Gross's
+  breakpoint.rb and Binding.of_caller (which will help trace() as well).  Also
+  removing some documentation to clear the decks for a 0.0.2 actual release.
+
+
+vim: ft=txt ai comments=fb\:* tw=80 fo=tcq

data/MIT-LICENSE.txt

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

data/README.txt

@@ -0,0 +1,21 @@
+= The Ruby dev-utils Project
+
+<tt>dev-utils</tt> is a collection of methods to aid Ruby development.  It is
+well described at its homepage: http://dev-utils.rubyforge.org.
+
+Version 1.0 was released on Friday Oct 08, 2004.  The only class of interest,
+API-wise, is DevUtils::Debug.
+
+== Installation
+
+At the 1.0 release, only installation by RubyGems is supported.  This will be
+revisited shortly for 1.0.1, with RPA and tarball installation being offered.
+
+== Documentation and Examples
+
+The API is documented via RDoc.  Users should visit the homepage for general
+documentation.  Examples are located in the +examples+ directory of the
+distribution.
+
+A local copy of the documentation can be created with the command <tt>rake
+www</tt>.  You need Rake, Extensions, and RedCloth.

data/Rakefile

@@ -0,0 +1,135 @@
+require 'rake'
+require 'rake/rdoctask'
+require 'rake/gempackagetask'
+require 'rubygems'
+Gem.manage_gems
+
+#
+# ===========================  U N I T   T E S T S  ===========================
+#
+
+desc 'Run unit tests'
+task :test do
+  # Might wait until I've got some...
+end
+
+#
+# ===========================  P A C K A G I N G  =============================
+#
+
+PKG_VERSION = File.read('VERSION').strip
+
+spec = Gem::Specification.new do |s|
+  s.name = 'dev-utils'
+  s.version = PKG_VERSION
+  s.summary = 'Debugging utilities: breakpoints, debugging, and tracing.'
+  s.description = s.summary
+  s.add_dependency('extensions', '>= 0.5')
+  s.required_ruby_version = '>= 1.8.1'
+  s.files = FileList['[A-Z]*', '{etc,examples,lib,test}/**/*'].to_a
+  s.require_path = 'lib'
+  s.autorequire = nil
+  s.has_rdoc = true
+  s.extra_rdoc_files = FileList['*.txt'].to_a
+  s.rdoc_options << '--main' << 'README.txt' << '--title' << 'dev-utils API Documentation'
+  s.test_files = []
+  s.author = 'Gavin Sinclair'
+  s.email = 'gsinclair@soyabean.com.au'
+  s.homepage = 'http://dev-utils.rubyforge.org'
+  s.rubyforge_project = 'dev-utils'
+end
+
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.package_dir = 'build/pkg'
+  pkg.need_zip = false
+  pkg.need_tar = false
+end
+
+desc "Install the gem"
+task :install => :repackage do
+  sh "gem install --local --no-rdoc build/pkg/dev-utils-#{PKG_VERSION}"
+end
+
+#
+# ==============================  W E B S I T E ===============================
+#
+
+directory 'build/www'
+directory 'build/www/api'
+
+desc "Build the RDoc documentation"
+Rake::RDocTask.new(:rdoc) do |rt|
+  rt.rdoc_dir = 'build/www/api'
+  rt.rdoc_files.include('*.txt', 'lib/**/*.rb')
+  rt.main = 'README.txt'
+  rt.title = 'dev-utils API Documentation'
+  rt.options << '--inline-source'
+end
+
+#
+# Building the web pages (source: etc/doc/*.textile; target: build/www/*.html)
+# 
+# I should be able to name the targets, generated from the sources, and have a rule that
+# generates HTML from Textile.  This rule should take account of timestamps, and keep in mind
+# that a change in the CSS or generate.rb or links.dat requires regeneration throughout.
+#
+
+desc "Build the Textile documentation"
+task :textile => ['build/www']
+
+dependencies = FileList['etc/doc/{*.css,*.rb,*.dat}'].to_a
+Dir['etc/doc/*.textile'].each do |source|
+  target = source.sub('etc/doc', 'build/www').sub('.textile', '.html')
+    # Set the file task, so Rake knows about it.
+  file target => [source, *dependencies] do
+    require 'etc/doc/generate'
+    generate_document source, 'build/www'
+  end
+    # Collect the targets, so the 'textile' task can aggregate them all.
+  task :textile => target
+end
+
+desc "Build the web page"
+task :www => [:rerdoc, :textile] do
+end
+
+desc 'Build a text version of the home page'
+task :textpage => :textile do
+  text = `lynx -dump build/www/index.html`
+    # There is some filtering we need to do.
+    #   ***** This is very delicate and needs to be kept up to date! *****
+  if true
+      # Remove top of page until the text "About dev-utils"
+    text.sub!(/\A.*?^\s*About dev-utils/m, "\nAbout dev-utils")
+      # Remove unwanted references.
+    unwanted_refs = '5678'
+    text.gsub!(/\[[#{unwanted_refs}]\]/, '')
+    unwanted_refs.split(//).each do |label|
+      text.sub!(/^\s*#{label}\. \S+\s*$/, '')
+    end
+      # Turn file:// URLs into http:// URLs.
+    text.gsub!(%r{file://\S+/www/}, 'http://dev-utils.rubyforge.org/')
+  end
+  puts text
+end
+
+#
+# ===========================  P U B L I S H I N G  ===========================
+#
+
+desc 'Publish the web stuff to RubyForge'
+task 'publish-textile' => :textile do
+  Dir.chdir 'build/www' do
+    system "scp #{Dir['*.html'].join(' ')} gsinclair@rubyforge.org:/var/www/gforge-projects/dev-utils"
+  end
+end
+
+desc 'Publish the API documentation to RubyForge'
+task 'publish-api' => :rerdoc do
+  Dir.chdir 'build/www' do
+    system "scp -r api gsinclair@rubyforge.org:/var/www/gforge-projects/dev-utils"
+  end
+end
+
+# vim: ft=ruby
+

data/VERSION

@@ -0,0 +1 @@
+1.0

data/etc/doc/DebuggingAids.textile

@@ -0,0 +1,450 @@
+
+!header dev-utils/debug main
+
+h1.    Debugging Aids
+
+!toc
+
+
+h2.        Introduction
+
+Ruby offers several aids to debugging.  @dev-utils/debug@ offers more.
+
+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).%
+
+These are discussed in detail below.
+
+
+h2.        Escape to an IRB Session
+
+Ruby's debugger allows you to step through code and find the value of
+local variables, but setting breakpoints can be difficult, code
+stepping can be flaky, and running a complex program through the
+debugger is slow.
+
+A partial solution to these problems is to escape from a running program to an
+open IRB session containing the current environment.  This simulates the
+setting of breakpoints, even allowing for conditions.  Those "breakpoints"
+remain in place between program runs as well, until you remove the relevant
+line of code.  The program runs normally, not through the debugger, so there
+are no speed issues.
+
+During the IRB session, you can interact with the program: get and set
+local (or other) variables, call methods, and so on.  When you finish
+with IRB, end the session with @CTRL-D@ and the program will continue
+running.
+
+p. @dev-utils/debug@ defines two convenient *aliases* for you: *iv*
+for @instance_variables@ and *lv* for @local_variables@.  Note that IRB will
+load your @$HOME/.irbrc@ file, even though it's being run from within your
+program.  This means you can define other aliases and helpful methods there.
+
+h3.          Breakpoint Example
+
+The following code comes from @examples/breakpoint-example.rb@ in the distribution:
+
+<pre>
+  require 'dev-utils/debug'
+  
+  class Person
+    def initialize(name, age)
+      @name, @age = name, age
+      breakpoint 'Person#initialize'
+    end
+  
+    attr_reader :age
+    def name
+      breakpoint('Person#name') { @name }
+    end
+  end
+  
+  person = Person.new('John Smith', 23)
+  puts "Name: #{person.name}"
+</pre>
+
+In English: we have a @Person@ class containing a name and age.  When a Person
+object is initialized, we have a breakpoint.  When a Person's name is queried
+(via @Person#name@) we have another breakpoint.  This one uses the default
+return value feature, which means we can force a different return value when
+that method is called.  After the class is defined, a Person object is
+created, and its name is printed, meaning both breakpoints will be triggered.
+
+To demonstrate the behaviour of this short program, we will run it three times
+and muck about with IRB.  In the console output below, @^D@ represents the
+keystroke _CTRL-D_, which terminates the breakpoint session.  Be careful not
+to type @exit@, as that will terminate the whole program.
+
+In the first run, we will simply exit IRB each time, allowing the program to
+proceed as intended.
+
+<pre>
+  Executing breakpoint "Person#initialize" at breakpoint-example.rb:19 in 'initialize'
+  >> ^D
+  Executing breakpoint "Person#name" at breakpoint-example.rb:24 in 'name'
+  >> ^D
+  Name: John Smith
+</pre>
+
+In the second run, we inspect the @age@ local variable while the object is
+being initialized, and set the @@name@ instance variable to something
+different.  We skip the next breakpoint.  When the name is printed out, we can
+see that changing the instance variable has been effective.  (By the way, we
+don't demonstrate it here, but changing _local_ variables is effective as
+well.)
+
+<pre>
+  Executing breakpoint "Person#initialize" at breakpoint-example.rb:19 in 'initialize'
+  >> lv
+  => ["name", "age", "_"]
+  >> age
+  => 23
+  >> name
+  => "John Smith"
+  >> @name = "Mary Jones"
+  => "Mary Jones"
+  >> ^D
+  Executing breakpoint "Person#name" at breakpoint-example.rb:24 in 'name'
+  >> ^D
+  Name: Mary Jones
+</pre>
+
+In the thirs and final run, we skip the first breakpoint.  When the second one
+is triggered, during @Person#name@, we call the @age@ method, inspect the
+@@name@ instance variable, and then force the method to return a different
+value.  Again, we see the effectiveness of this when the name is printed after
+we exit the breakpoint.
+
+<pre>
+  Executing breakpoint "Person#initialize" at breakpoint-example.rb:19 in 'initialize'
+  >> ^D
+  Executing breakpoint "Person#name" at breakpoint-example.rb:24 in 'name'
+  >> age                  # This is calling a method...
+  => 23
+  >> self.age()           # ...this method, in fact.
+  => 23
+  >> @name
+  => "John Smith"
+  >> throw :debug_return, 'Maybellene Maconachie'
+  Name: Maybellene Maconachie
+</pre>
+
+Note that we haven't changed the value of @@name@ in the above example, only
+forced a bogus return value from @Person#name@.  If the program were to print
+the person's name again, it would print "John Smith".
+
+h3.          Breakpoint Caveats
+
+There are two things to note with this breakpoint functionality:
+* It sets the interrupt handler so that IRB can deal with it.  If there's
+some way to reset this to whatever was in place beforehand, I'd like to know.
+In practice, this shouldn't be a problem, because you only use breakpoints
+while debugging, and you're not likely to care about interrupts at that time.
+* The IRB prompt is set to @--simple-prompt@, no matter what's in your config
+file.  This is a matter of convenience, as you don't really need a fancy
+prompt in this situation.  However, I might try to make this more flexible in
+a future version.
+
+
+h2.        Zero-conf Logfile for Debugging and Tracing
+
+Logging is a very useful general tool, and there are two excellent
+logging packages for Ruby: @logger@ (in the standard library) and the
+more powerful @log4r@.  But if all you want to do is record a few
+pieces of debugging information, then configuring a logger can seem
+like too much hassle.  Throwing output to @STDERR@ is often a
+reasonable solution, but that can interfere with the output of your
+program.  It also interferes with a unit test display, if that's
+running in the console.
+
+So @dev-utils/debug@ offers a no-frills log file for capturing any
+debugging information you want to generate.  You use it like this:
+
+<pre>
+  debug 'Database connection established'
+</pre>
+
+The log file will be @debug.log@ in the current directory when you run the
+program.
+
+You can see an example of logging and tracing below.
+
+
+h3.          Tracing Expressions
+
+This is an extra convenience to go with the zero-conf debug logger
+described above.  "Tracing" means recording the value of an exression,
+typically a single variable.  But that usually means a statement like
+this: @puts "x = #{x}"@.  The simple alternative offered here is this:
+
+<pre>
+  trace 'x'
+</pre>
+
+Of course, the @'x'@ can be any exression, like
+
+<pre>
+  trace 'x + y - avg(a,b,c)'
+  trace 'Process.pid'
+</pre>
+
+If these two trace statements are executed, then something like the
+following lines will appear in your debugging log file:
+
+<pre>
+  D, [#244] DEBUG : x = 5
+  D, [#244] DEBUG : x + y - avg(a,b,c) = 42
+</pre>
+
+You can see an example of logging and tracing below.
+
+h3.            Tailoring the Output Format
+
+By default, the values emitted by @trace@ are formatted with @inspect@.  This
+works well for numbers, strings, and short arrays.  However, for hashes, long
+arrays, arrays of hashes, custom objects with many attributes, etc., other
+formats are likely to be more suitable.  The following examples show how you
+can select a different format conveniently, using @ENV@, which will typically
+contain a large number of elements.  See the "API
+Documentation":api/classes/DevUtils/Debug.html#M000005 for more detail.
+
+<pre>
+  trace ENV, :p               # inspect (default)
+  trace ENV, :s               # to_s
+  trace ENV, :pp              # pretty print
+  trace ENV, :yaml            # YAML
+</pre>
+
+h3.            Using Rake to View the Log
+
+If you use "Rake":http://rake.rubyforge.org to run your program or unit tests,
+then the working directory when the program starts will be the directory
+containing the @Rakefile@.  That means that the log file will be @debug.log@
+in that directory.
+
+The great thing about Rake is that you can run it from anywhere; well,
+any _subdirectory_ in your project.  Rake will keep looking in parent
+directories until it finds a Rakefile.  It will then @chdir@
+accordingly.  So it doesn't matter from where you _run_ Rake; the log
+file will live in a predictable location.
+
+This means you can easily create a Rake task to view the log file:
+
+<pre>
+  task :log do
+    puts File.read('debug.log')
+  end
+</pre>
+
+If you have a @test@ task to run your unit tests, and they write to
+the debug logfile, you can now do this:
+
+<pre>
+  $ rake test
+  ...
+  $ rake log
+  ...
+</pre>
+
+Or:
+
+<pre>
+  $ rake test && rake log
+</pre>
+ 
+<div class="planned">
+
+h3.            Planned Features
+
+Configure the logfile with a statement like one of the following:
+
+<pre>
+  Debug.logger = nil
+  Debug.logger = STDERR
+  Debug.logger = Logger.new(...)
+  Debug.logfile = '/var/log/projX/debug.log'
+</pre>
+
+The logger used is always a @Logger@ object (see @logger@ in the
+standard library).  So you can control it to the extent that it
+allows.  The default logger used has a bare minimum of extraneous
+output, and if you use @Debug.logfile=@, then that maxim is
+maintained.
+
+There are also some improvements that can be made to the output:
+* Show milliseconds instead of process ID at the start of each line.
+* Less crap at the start of each line.
+* Nice formatting of long lines.
+
+Finally, making available an advanced @.irbrc@ file with @ri@ integration and
+more would be a good addition to the project.
+
+</div>
+
+h3.            Different Kinds of "Debugging" Information
+
+Just a note of clarification.  In many systems, especially long-running ones,
+it is a good practice to keep logfiles, so that you can see what's going on,
+monitor activity, measure performance, and so on.  If you include some
+debugging information, you can get some information on the internal state of
+the system just before a crash.  This kind of "debugging" information is part
+of an overall logging strategy.
+
+The "debugging" information that @dev-utils/debug@ is concerned with,
+however, is _not_ part of any strategy.  It is simply for when you
+have a bug you need to track down, and want some temporary output
+(especially tracing; see next section) to aid that cause.  That is why
+there's a simple default filename that keeps getting overwritten; we
+simply don't need numbered backups or daily rolling logfiles for this
+throwaway information.
+
+h3.          Logging and Tracing Example
+
+The following code comes from @examples/log-trace-example.rb@ in the distribution:
+
+<pre>
+  require 'dev-utils/debug'
+  require 'extensions/enumerable'  # dev-utils depends on extensions anyway.
+  
+  debug "Running sanity check of dev-utils/debug logging and tracing."
+  
+  x, y = 5, 10
+  trace 'x + y'
+  trace 'Process.pid'
+  
+  debug "Now we test the various output formatters."
+  
+  words = %w(wren fibonnaci smelt bovine smeglicious craptacular
+             inoccidental myrmidon boondoggle)
+  word_lengths = words.build_hash { |word| [word, word.length] }
+  
+  [:p, :s, :pp, :y].each_with_index do |symbol, idx|
+    debug ''
+    debug "#{idx+1}. #{symbol.inspect} format"
+    trace 'words', symbol
+    debug ''
+    trace 'word_lengths', symbol
+  end
+</pre>
+
+When run, it produces the following output (snipped):
+
+<pre>
+  D, [#2168] DEBUG : Running sanity check of dev-utils/debug logging and tracing.
+  D, [#2168] DEBUG : x + y = 15
+  D, [#2168] DEBUG : Process.pid = 2168
+  D, [#2168] DEBUG : Now we test the various output formatters.
+  D, [#2168] DEBUG :
+  D, [#2168] DEBUG : 1. :p format
+  D, [#2168] DEBUG : words = ["wren", "fibonnaci", "smelt", "bovine", "smeglicious
+  ", "craptacular", "inoccidental", "myrmidon", "boondoggle"]
+  D, [#2168] DEBUG :
+  D, [#2168] DEBUG : word_lengths = {"craptacular"=>11, "smelt"=>5, "boondoggle"=>
+  10, "myrmidon"=>8, "bovine"=>6, "fibonnaci"=>9, "smeglicious"=>11, "wren"=>4, "i
+  noccidental"=>12}
+  ...
+  ...
+  D, [#2168] DEBUG : 4. :y format
+  D, [#2168] DEBUG : words = ---
+  D, [#2168] DEBUG :    - wren
+  D, [#2168] DEBUG :    - fibonnaci
+  D, [#2168] DEBUG :    - smelt
+  D, [#2168] DEBUG :    - bovine
+  D, [#2168] DEBUG :    - smeglicious
+  D, [#2168] DEBUG :    - craptacular
+  D, [#2168] DEBUG :    - inoccidental
+  D, [#2168] DEBUG :    - myrmidon
+  D, [#2168] DEBUG :    - boondoggle
+  D, [#2168] DEBUG :
+  D, [#2168] DEBUG : word_lengths = ---
+  D, [#2168] DEBUG :    craptacular: 11
+  D, [#2168] DEBUG :    smelt: 5
+  D, [#2168] DEBUG :    boondoggle: 10
+  D, [#2168] DEBUG :    myrmidon: 8
+  D, [#2168] DEBUG :    bovine: 6
+  D, [#2168] DEBUG :    fibonnaci: 9
+  D, [#2168] DEBUG :    smeglicious: 11
+  D, [#2168] DEBUG :    wren: 4
+  D, [#2168] DEBUG :    inoccidental: 12
+</pre>
+
+h3.          Vim Mappings
+
+The following Vim shortcuts are useful for creating debug and trace lines.
+Put them, or a preferred variant, in your
+@$HOME/.vim/ftplugin/ruby_yourname.vim@ file (change @.vim@ to @vimfiles@ on
+Windows).
+
+p. @,D@ and @,T@ in _insert_ mode add a debug or trace statement after the cursor.
+You'll want to use them on a blank line, usually after hitting ENTER, or 'o'
+or 'O' in normal mode.  In _normal_ mode, those key sequences create a line
+_above_ the current one, and put their statement there.  In all cases, the
+cursor is left between the quotes.
+
+<pre>
+  imap ,D debug ""<Esc>i
+  nmap ,D O,D
+  imap ,T trace ''<Esc>i
+  nmap ,T O,T
+</pre>
+
+If you translate these into your editor of choice, let me know and I'll
+include them here.
+
+
+<div class="planned">
+
+
+
+h2.        Finding Differences Between Complex Objects (Planned)
+
+It is common when unit testing to compare objects, especially with a
+method call like @assert_equal(expected, actual)@.  But if you are
+comparing two _complex_ objects (i.e. with many and possibly nested
+composed objects), and find that they are _not_ equal, but when you
+pretty-print them you find that they _look_ equal, then finding the
+difference can be a pain.
+
+Enter @Debug.diff@.  You give it two objects, and it recurses their
+composed objects, evaluating them until it finds a difference, and it
+returns it.  @diff@ is really intended for use in IRB.  You can ask
+for the <i>n</i>th difference, all the differences, or the number of
+differences.  For example:
+
+<pre>
+  ... irb session ...
+</pre>
+
+</div>
+
+
+
+h2. Conclusion
+
+p. @dev-utils/debug@ offers several very useful debugging aids that
+are designed to work well with unit testing and with Rake.  There are
+plans for more, and suggestions are most welcome.