dev-utils 1.0

data/lib/dev-utils/debug/irb.rb

@@ -0,0 +1,176 @@
+# = dev-utils/debug/irb.rb
+#
+# DevUtils::Debug.breakpoint and some aliases are implemented here.  Do not load this file
+# directly.
+#
+
+require 'irb'
+require 'extensions/binding'
+
+module DevUtils::Debug
+
+    #
+    # Method:: *breakpoint*
+    # Aliases:: *break_point*, *goirb*
+    #
+    # === Description
+    # 
+    # This will pop up an interactive ruby session from whereever it is called in a Ruby
+    # application. In IRB you can examine the environment of the break point, peeking
+    # and poking local variables, calling methods, viewing the stack (with +caller+), etc.
+    #
+    # This is like setting breakpoints in a debugger, except that you are running the program
+    # normally (debuggers tend to run programs more slowly).  Debuggers are generally more
+    # flexible, but this is a good lightweight solution for many cases.  You <em>can not</em>
+    # step through the code with this technique.  But you can, of course, set multiple
+    # breakpoints.  And you can make breakpoints conditional.
+    #
+    # You can force a breakpoint to return a certain value.  This is typically only useful if
+    # the breakpoint is the last value in a method, as this will cause the method to return a
+    # different value than normal.  This is demonstrated in the example below.
+    #
+    # You can also give names to break points which will be used in the message that is
+    # displayed upon execution of them.  This helps to differentiate them at runtime if you
+    # have set several breakpoints in the code.
+    #
+    # === Parameters
+    #
+    # _name_:: A String to identify the breakpoint, giving a more informative message.
+    # _context_:: Any object; IRB will use this as its context.  The default is the current
+    #             scope's binding, which is nearly always what you will want.
+    # _block_:: Will be executed when the breakpoint returns normally.  Bypassed if you
+    #           <tt>throw :debug_return, </tt><em>value</em> from IRB.  Unless you are
+    #           _planning_ to use the <tt>debug_return</tt> feature for a given breakpoint,
+    #           you don't need to worry about the block.
+    #
+    # === Typical Invocation
+    #
+    #   breakpoint                          # Plain message.
+    #   breakpoint "Person#name"            # More informative message.
+    #   breakpoint { normal_return_value }
+    #
+    # === Example
+    #
+    # Here's a sample of how breakpoints should be placed:
+    #
+    #   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("Random Person", 23)
+    #   puts "Name: #{person.name}"
+    #
+    # And here is a sample debug session:
+    #
+    #   Executing break point "Person#initialize" at file.rb:4 in `initialize'
+    #   irb(#<Person:0x292fbe8>):001:0> <b>local_variables</b>
+    #   => ["name", "age", "_", "__"]
+    #   irb(#<Person:0x292fbe8>):002:0> [name, age]
+    #   => ["Random Person", 23]
+    #   irb(#<Person:0x292fbe8>):003:0> [@name, @age]
+    #   => ["Random Person", 23]
+    #   irb(#<Person:0x292fbe8>):004:0> self
+    #   => #<Person:0x292fbe8 @age=23, @name="Random Person">
+    #   irb(#<Person:0x292fbe8>):005:0> @age += 1; self
+    #   => #<Person:0x292fbe8 @age=24, @name="Random Person">
+    #   irb(#<Person:0x292fbe8>):006:0> exit
+    #   Executing break point "Person#name" at file.rb:9 in `name'
+    #   irb(#<Person:0x292fbe8>):001:0> throw(:debug_return, "Overriden name")
+    #   Name: Overriden name
+    #
+    # This example is explored more thoroughly at
+    # http://dev-utils.rubyforge.org/DebuggingAids.html.
+    #
+    # === Credits
+    #
+    # Joel VanderWerf and Florian Gross have contributed the code and documentation for this
+    # method.
+    #
+  def breakpoint(name = nil, context = nil, &block)
+    file, line, method = *caller.first.match(/^(.+?):(\d+)(?::in `(.*?)')?/).captures
+    message = "Executing breakpoint #{name.inspect if name} at #{file}:#{line}"
+    message << " in '#{method}'" if method
+
+    body = lambda do |_context|
+      puts message
+      catch(:debug_return) do |value|
+        IRB.start_session(IRB::WorkSpace.new(_context))
+        block.call if block        
+      end
+    end
+
+      # Run IRB with the given context, if it _is_ given.
+    return body.call(context) if context
+      # Otherwise, run IRB with the parent scope's binding, giving access to
+      # the local variables of the method that called method.
+    Binding.of_caller do |binding_context|
+      body.call(binding_context)
+    end
+  end
+
+  alias :break_point :breakpoint
+  alias :goirb       :breakpoint
+  
+  alias lv local_variables
+  alias iv instance_variables
+end
+
+# :stopdoc:
+
+module ::IRB
+   
+   class << self; remove_method :parse_opts; end
+   def IRB.parse_opts
+     # Don't touch ARGV, which belongs to the app which called this module.
+   end
+
+   def IRB.start_session(object)
+     unless $irb
+       IRB.setup nil
+       ## maybe set some opts here, as in parse_opts in irb/init.rb?
+     end
+
+     @CONF[:PROMPT_MODE] = :SIMPLE
+
+     workspace = WorkSpace.new(object)
+
+     if @CONF[:SCRIPT] ## normally, set by parse_opts
+       $irb = Irb.new(workspace, @CONF[:SCRIPT])
+     else
+       $irb = Irb.new(workspace)
+     end
+
+     @CONF[:IRB_RC].call($irb.context) if @CONF[:IRB_RC]
+     @CONF[:MAIN_CONTEXT] = $irb.context
+
+     trap 'INT' do
+       $irb.signal_handle
+     end
+
+     custom_configuration if defined?(IRB.custom_configuration)
+
+     catch :IRB_EXIT do
+       $irb.eval_input
+     end
+
+     puts
+
+     ## might want to reset your app's interrupt handler here
+   end
+end
+
+class Object
+   include IRB::ExtendCommandBundle # so that Marshal.dump works
+end
+
+# :startdoc:

data/lib/dev-utils/debug/log.rb

@@ -0,0 +1,107 @@
+# = dev-utils/debug/log.rb
+#
+# DevUtils::Debug.{debug,trace,logger=,logfile=} are implemented here.  Do not load this file
+# directly.
+#
+
+require 'logger'
+require 'extensions/binding'
+require 'extensions/object'
+
+module DevUtils::Debug
+
+    # The target of logging messages from _debug_ and _trace_.
+  DEBUGLOG = Logger.new(File.new('debug.log', 'w'))
+  DEBUGLOG.datetime_format = " \010"
+  DEBUGLOG.progname = "\010\010\010"
+
+    #
+    # Write _message_ to the debugging log.
+    #
+    # The <em>debugging log</em> is a zero-conf logfile.  Here is an example usage:
+    #
+    #   $ cat example.rb
+    #
+    #   require 'dev-utils/debug'
+    #
+    #   debug "Setting variables x and y"
+    #   x = 5; y = 17
+    #   trace 'x + y'
+    #   puts "Finished"
+    #
+    #   $ ruby example.rb
+    #   Finished
+    #
+    #   $ cat debug.log
+    #   D, [#244] DEBUG : Setting variables x and y
+    #   D, [#244] DEBUG : x + y = 22
+    #   
+    # Simply with <tt>require 'dev-utils/debug'</tt>, you have availed yourself of a handy
+    # debugging log file which you don't have to create.
+    #
+    # See also the _trace_ method.
+    #
+  def debug(message)
+    DEBUGLOG.debug message
+  end
+
+    #
+    # Prints a trace message to DEBUGLOG (at debug level).  Useful for emitting
+    # the value of variables, etc.  Use like this:
+    #
+    #   x = y = 5
+    #   trace 'x'        # -> 'x = 5'
+    #   trace 'x ** y'   # -> 'x ** y = 3125'
+    #
+    # If you have a more complicated value, like an array of hashes, then you'll probably want
+    # to use an alternative output format.  For instance:
+    #
+    #   trace 'value', :yaml
+    #
+    # Valid output format values (the _style_ parameter) are:
+    #
+    #   :p :inspect
+    #   :pp                     (pretty-print, using 'pp' library)
+    #   :s :to_s
+    #   :y :yaml :to_yaml       (using the 'yaml' library')
+    #
+    # The default is <tt>:p</tt>.
+    #
+  def trace(expr, style=:p)
+    unless expr.respond_to? :to_str
+      message = "trace: Can't evaluate the given value: #{caller.first}"
+      DEBUGLOG.warn message
+    else
+      Binding.of_caller do |b|
+        value = b.eval(expr.to_str)
+        formatter = TRACE_STYLES[style] || :inspect
+        case formatter
+        when :pp then require 'pp'
+        when :y, :yaml, :to_yaml then require 'yaml'
+        end
+        value_s = value.send(formatter)
+        message = "#{expr} = #{value_s}"
+        lines = message.split(/\n/)
+        indent = "   "
+        DEBUGLOG.debug lines.shift            # First line unindented.
+        lines.each do |line|
+          DEBUGLOG.debug(indent + line)       # Other lines indented.
+        end
+      end
+    end
+  end
+  TRACE_STYLES = {}  # :nodoc:
+  TRACE_STYLES.update( :pp => :pp_s, :s => :to_s, :p => :inspect, :y => :to_yaml,
+                       :yaml => :to_yaml, :inspect => :inspect, :to_yaml => :to_yaml )
+
+    # Planned feature; not yet implemented.
+  def logger=(x)
+    warn 'logger= is not implemented; ignoring'
+  end
+
+    # Planned feature; not yet implemented.
+  def logfile=(x)
+    warn 'logfile= is not implemented; ignoring'
+  end
+
+end  # module DevUtils::Debug

data/lib/dev-utils/test.rb

@@ -0,0 +1,267 @@
+#
+# = dev-utils/test.rb
+#
+# _Planned_ functionality to support <b>unit testing</b>.  Nothing here at the moment.
+#
+
+=begin
+
+#
+# = dev-utils/test.rb
+#
+# Testing utilities DevUtils::Test.{load_tests,load_data} and various project directory access
+# methods are implemented here.  See DevUtils::Test for documentation.
+#
+
+require 'test/unit'
+require 'test/unit/ui/console/testrunner'
+require 'optparse'
+require 'ostruct'
+
+module DevUtils
+    #
+    # ...
+    #
+  class Test
+
+      #
+      # Loads all unit test files matching the arguments given in the sense described below.
+      # A typical use for this is:
+      #
+      #   DevUtils::Test.load_tests(__FILE__, *ARGV)
+      #
+      # That will load all 'tc_*.rb' files in or below the directory in which the calling
+      # program is located.  If any arguments are provides, they are substrings used to
+      # restrict the tests that are run, giving the user an easy way to select a unit test.
+      #
+      # For example, if the arguments "str" and "num" are given, then for any test file to be
+      # loaded, its filename must contain either or both of those substrings.  It's a hassle
+      # for the user to type the whole filename, so this makes test selection more practical.
+      #
+      # I'll experiment with accepting other arguments like "-q" and "-v" to mean "quiet" and
+      # "verbose" respectively.  Verbose is default, meaning each test filename is relayed to
+      # STDERR to inform the user what's going on.  Other arguments: "-h" for help (to explain
+      # this whole thing), and "-s" for separate running of each test, instead of running all
+      # tests in one big suite.
+      #
+      # The <b>ultimate purpose</b> of this is to implement a unit test suite runner in a
+      # reusable fashion, rather than coding one up for each project.  Therefore, the file
+      # <tt>test/TEST.rb</tt>, for instance, would consist of:
+      #
+      #   require 'rubygems'
+      #   require 'dev-utils/test'
+      #
+      #   DevUtils::Test.load_tests(__FILE__, ARGV)
+      #
+      # The user can then simply run:
+      # 
+      #   ruby test/TEST.rb -h           # get help on options
+      #   ruby test/TEST.rb -q           # quiet operation
+      #   ruby test/TEST.rb -s           # separate suite per test file
+      #   ruby test/TEST.rb str io       # only tests that have "str" or "io" in the filename
+      #
+      # The convention of naming test files "tc_XYZ.rb" must be followed for this to work.
+      #
+    def self.load_tests(path, args)
+      if self.project_dir.nil?
+          # This is the usual case.  We derive the project directory from the path.  The fact
+          # that @project_dir is nil means that all defaults have been accepted.  Therefore we
+          # must be in the +test+ directory.
+        path = File.expand_path(path)
+        unless FileTest.exist?(path)
+          raise RuntimeError, "Internal state problem: path '#{path}' doesn't exist"
+        end
+        test_dir = File.dirname(path)
+        project_dir = File.dirname(test_dir)
+        self.project_dir = project_dir
+        _assert_path self.lib_dir
+        _assert_path self.test_dir
+          # We don't assert the existence of the test data directory because it's not
+          # mandatory.
+      else
+          # In this case, the project directory has been specified prior to calling this
+          # method.  We will simply use the values provided or derived.
+      end 
+
+        # The main things to do in this method: modify the load path; parse the arguments
+        # given, decide which test files to load, and load them.
+        
+        # 1. Handle the load path.
+      $:.unshift self.lib_dir 
+
+        # 2. Parse the arguments given to this method.
+      opts = _parse_options(args)
+
+      Dir.chdir(self.test_dir) do
+          # 3. Decide which test files to load.
+        test_files = Dir['**/tc_*.rb']
+        unless opts.patterns.empty?
+          test_files = test_files.select { |fn| opts.patterns.any? { |str| fn.index(str) } }
+        end
+
+          # 4. Load them, using separate test suites if requested.
+        test_files.each do |test_file|
+          STDERR.puts "Loading test file: #{test_file}" if opts.mode == :verbose
+          require test_file
+            # TODO: take care of separate test suites, and respect --very-quiet.
+        end 
+        if opts.separate
+          test_cases = []
+          ObjectSpace.each_object(Class) do |klass|
+            test_cases << klass if klass < ::Test::Unit::TestCase
+          end
+          test_cases.sort_by { |c| c.name }.each do |klass|
+            STDERR.puts "Running test class #{klass}" if opts.mode == :verbose
+            output_level =
+              case opts.mode
+              when :veryquiet then ::Test::Unit::UI::SILENT
+              when :quiet then ::Test::Unit::UI::PROGRESS_ONLY
+              when :verbose then ::Test::Unit::UI::NORMAL
+              end
+            runner = ::Test::Unit::UI::Console::TestRunner.new(klass.suite, output_level)
+            runner.start
+          end
+        else
+          # We let all test cases run in a single suite on exit.
+        end
+      end
+    end  # def load_tests
+
+      #
+      # This method is aimed at allowing unit tests to access data resources easily.  Those
+      # resources are files buried in a <i>test data</i> directory, so they do not clutter the
+      # unit tests themselves.
+      #
+      # You access a test data resource by its path relative to the test data directory.  The
+      # unit test runs blissfully unaware of where that directory is.  See ... for a
+      # demonstration.  (TODO: write a high-level document that ties this all together.)
+      #
+      # Once the test data resource is located, the default is to load the file and return its
+      # contents as a string.  You can get different behaviour by specifying the XXX
+      #
+      # The default is to return a String.  The +flags+ provided affect this:
+      # * <tt>:string</tt> means return a String
+      # * <tt>:file</tt> means return a File
+      # * <tt>:pathname</tt> means return a Pathname
+      # * <tt>:copy</tt> means return a _copy_ of the file (<tt>:file</tt> and
+      #   <tt>:pathname</tt> only)
+      # * <tt>:write</tt> means resource is intended to be _written_, therefore don't complain
+      #   if it doesn't exist (<tt>:file</tt> and <tt>:pathname</tt> only)
+      #
+      # An error of some sort is raised if the file doesn't exist, unless <tt>:write</tt> is
+      # specified.
+      #
+    def self.load_data(resource_path, *flags)
+      if self.data_directory.nil?
+        raise RuntimeError,
+          "Test data directory hasn't been defined.  Use #{self}.data_directory="
+      end
+    end
+
+    def self.set_project_dir_from(path, project_name)
+      path = File.expand_path(path)
+      _assert_path path
+      # The project dir is everything in the path up to and including the first instance of the
+      # project name.
+      if path =~ /\A(.*?#{project_name}).*\Z/
+        self.project_dir = $1
+      else
+        raise RuntimeError, "Project name '#{project_name}' not found in path '#{path}'"
+      end
+    end
+
+    def self.project_dir=(path)
+      path = File.expand_path(path)
+      _assert_path path
+      @project_dir = path
+    end
+
+    def self.project_dir
+      @project_dir
+    end
+    
+    def self.lib_dir=(path)
+      raise RuntimeError, "Project directory not set" unless project_dir
+      _assert_path path
+      @lib_dir = File.join(project_dir, path)
+    end
+
+    def self.lib_dir
+      return @lib_dir if @lib_dir
+      File.join(project_dir, 'lib')
+    end
+
+    def self.test_dir=(path)
+      raise RuntimeError, "Project directory not set" unless project_dir
+      _assert_path path
+      @test_dir = File.join(project_dir, path)
+    end
+
+    def self.test_dir
+      return @test_dir if @test_dir
+      File.join(project_dir, 'test')
+    end
+
+    def self.data_dir=(path)
+      raise RuntimeError, "Project directory not set" unless project_dir
+      _assert_path path
+      @data_dir = File.join(project_dir, path)
+    end
+
+    def self.data_dir
+      return @data_dir if @data_dir
+      File.join(project_dir, 'data')
+    end
+
+  private
+
+    def self._assert_path(path)
+      unless FileTest.exist?(path)
+        raise RuntimeError, "Path doesn't exist: #{path}"
+      end
+    end
+ 
+      #
+      # Parse the given arguments for the test loader.  Return an OpenStruct with 'mode',
+      # 'separate', and 'patterns' attributes.
+      #
+    def self._parse_options(args)
+      opts = OpenStruct.new
+      opts.mode = :verbose
+      opts.separate = false
+      opts.patterns = []
+      parser = OptionParser.new do |op|
+        op.banner =<<EOF 
+
+ Welcome to the dev-utils/test automatic unit test runner.
+ Here are the options:
+
+EOF
+        op.on('-q', '--quiet', "Quiet mode")               { opts.mode = :quiet }
+        op.on('-Q', '--very-quiet', "Very quiet mode")     { opts.mode = :veryquiet }
+        op.on('-v', '--verbose', "Verbose mode (default)") { opts.mode = :verbose }
+        op.on('-s', '--separate', "Separate test suite for each test file") { opts.separate = true }
+        op.on('-h', '--help', "Show this message") { _show_help(op) }
+        op.separator ""
+        op.separator " For example, to run only those tests whose filenames include 'remote' or"
+        op.separator " 'db', and to run a separate suite for each test file, and to run in quite"
+        op.separator " mode:"
+        op.separator ""
+        op.separator "   ruby test/TEST.rb -q remote db -s"
+      end
+      parser.parse!(args)
+      opts.patterns = args.dup
+      args.clear
+      opts
+    end
+
+    def self._show_help(parser)
+      STDERR.puts parser
+      exit
+    end
+
+  end  # class Test
+
+end  # module DevUtils
+
+=end