dev-utils 1.0

data/etc/doc/links.dat

@@ -0,0 +1,9 @@
+#
+# The links that should appear on each page, in order.  Used by generate.rb.
+#
+
+Main                   /index.html
+Debugging Aids         /DebuggingAids.html
+Unit Test Organisation /UnitTestOrganisation.html
+API Documentation      /api/index.html
+

data/etc/doc/textile.css

@@ -0,0 +1,150 @@
+
+body {
+  font-family: georgia, verdana, serif;
+  margin: 20px 50px;
+  width: 45em;
+}
+
+.small-title {
+  font-family: courier new;
+  font-size: 10pt;
+  margin: 0px;
+  color: green;
+}
+
+.mylink {
+  font-family: georgia, verdana, serif;
+  font-size: 10pt;
+}
+
+h1 {
+  border-bottom: 1px solid;
+  padding-bottom: 3px;
+  margin-top: 2px;
+  color: green;
+  font-size: 30pt;
+}
+
+h2 {
+  font-size: 20pt;
+  color: darkblue;
+}
+
+h3 {
+  font-size: 16pt;
+  color: darkblue;
+}
+
+p,li {
+  margin: 10px 15px 5px 15px;
+  font-size: 12pt;
+  line-height: 1.5em;
+  text-align: justify;
+}
+
+p {
+  margin-top: 18px;
+}
+
+code {
+  padding-left: 0.15em;
+  padding-right: 0.1em;
+  background-color: #f9f9f9;
+}
+
+pre {
+  margin-left: 3em;
+  background-color: #f6f6f6;
+  padding-top: 1ex;
+  padding-bottom: 1ex;
+}
+
+.comment {
+  margin-left: 4em;
+  margin-right: 2em;
+  font-size: 11pt;
+  font-style: italic;
+  color: darkgreen;
+}
+
+/* Planned functionality. */
+
+.planned {
+  border: 1px dotted lightgray;
+  background-color: rgb(224,255,221);
+  padding: 5px;
+}
+
+div.planned {
+  margin-top: 20pt;
+}
+      
+.planned code, .planned pre {
+  background-color: rgb(219,255,215);
+}
+
+/* Table of contents and links. */
+
+.toc_table {
+  font: 10pt, verdana,sans-serif;
+}
+
+.toc_table .header {
+  font-weight: bold;
+  color: #666;
+}
+
+.toc_table a {
+  text-decoration: none;
+}
+
+.toc_table td {
+  vertical-align: top;
+  padding-left: 1em;
+  padding-right: 1em;
+}
+
+.toc_table ul {
+  margin-left: 1em;
+  padding-left: 1em;
+}
+
+.toc_table ul li ul {
+  margin-left: 1ex;
+  padding-left: 1ex;
+}
+
+.toc_table ul li {
+  padding-left: 0;
+  margin-left: 0;
+  font-family: Arial, sans-serif;
+  font-size: 10pt;
+  text-align: left;
+  line-height: 9pt;
+  list-style-type: square;
+  color: #CCC;
+}
+
+.toc_table ul li ul li {
+  list-style-type: none;
+  font-style: italic;
+}
+
+#contents li a {
+  color: #55A;
+}
+
+#contents li a:hover {
+  color: #66F;
+}
+
+#links li a {
+  color: #5A5;
+}
+
+#links li a:hover {
+  color: #6D6;
+}
+
+/* vim: sw=2 ts=2 et sts=2
+*/

data/examples/breakpoint-example.rb

@@ -0,0 +1,30 @@
+#
+# To run this example, simply do
+#
+#   ruby breakpoint-exqample.rb
+#
+# It will escape to IRB at various points.  You can query the local variables, etc., and even
+# try a "throw :debug_return, 5" to force a return from the method.
+#
+
+begin
+  require 'rubygems'
+rescue LoadError
+end
+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}"
+

data/examples/log-trace-example.rb

@@ -0,0 +1,35 @@
+#
+# To run this example, just do
+#
+#   ruby log-trace-example.rb
+#
+# You should see a file "debug.log" in your current directory.
+#
+
+begin
+  require 'rubygems'
+rescue LoadError
+end
+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
+

data/lib/dev-utils/debug.rb

@@ -0,0 +1,32 @@
+#
+# = dev-utils/debug.rb
+#
+# See DevUtils::Debug for documentation.
+#
+
+  #
+  # Base module for <tt>dev-utils</tt>.
+  #
+module DevUtils
+    #
+    # <tt>DevUtils::Debug</tt> contains methods to aid debugging Ruby programs, although when
+    # using these methods, you don't care about the module; it is included into the top-level
+    # when you <code>require 'dev-utils/debug'</code>.
+    #
+    # The methods are:
+    # * #breakpoint, for escaping to IRB from a running program, with local environment intact;
+    # * #debug, for logging debugging messages to a zero-conf logfile; and
+    # * #trace, for tracing expressions to that same file.
+    #
+    # Planned features include a method for determining the difference between two complex
+    # objects.
+    #
+  module Debug
+  end
+end
+
+require 'dev-utils/debug/irb'
+require 'dev-utils/debug/log'
+#require 'dev-utils/debug/diff'
+
+include DevUtils::Debug

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

@@ -0,0 +1,187 @@
+# = dev-utils/debug/diff.rb
+#
+# _Planned_ functionality to support <b>comparing complex objects</b> and <b>discovering object
+# topologies</b>.  Nothing here for now.
+#
+
+=begin
+
+# Implement Debug.diff here.  Do not load this file directly.
+
+module DevUtils::Debug
+    #
+    # Helps identify the difference between two objects when it's not immediately obvious to
+    # the eye.
+    # 
+    # +o1+ and +o2+ are simply objects to be compared.  If one or the other is a built-in type,
+    # like String, then it's a simple yes/no answer and this method doesn't buy you much.  If
+    # they are both complex objects (aggregating other data, like a Struct or data object),
+    # then the comparison takes place with each of their composed objects, recursively.
+    #
+    # The typical usage: <tt>diff(x, y)</tt> returns an array representing the first difference
+    # found, like <tt>['age: 31', 'age: 84']</tt>.  This is designed to be output with +puts+
+    # in +irb+, so they appear one string per line.
+    #
+    # The +flags+ modify the result.  Only one flag is currently observed.  If it's a number,
+    # say 3, then the third difference, in alphabetical order, is returned.  If it's
+    # <tt>:all</tt>, then all differences are returned in an array of arrays.  If it's
+    # <tt>:n</tt>, then the number of differences is returned.
+    #
+    # == Examples
+    #
+    # ...
+    #
+  def diff(o1, o2, *flags)
+    case (flag = flags.first || 1)
+    when :n
+      op = :count
+      n = -1
+    when :all
+      op = :find_all
+      n = -1
+    when Numeric
+      op = :find_one
+      n = flag.to_i
+      n = 1 if n < 1
+    else
+      raise ArgumentError, flag.inspect
+    end
+    diff = catch(:found) do
+      diffs = _diff(o1, o2, '', n)
+      case op
+      when :find_one
+        return nil      # If we get this far, no difference was found.
+      when :find_all
+        return diffs
+      when :count
+        return diffs.size
+      end
+    end
+    return diff         # This was thrown from _diff; it's a single result.
+  end
+
+  private
+
+    #
+    # +o1+ and +o2+ are the objects being compared.  +base+ is the base name for the fields so
+    # far (so we can report the full path of the field name, like 'person.name.first').  +n+ is
+    # the number of differences we should skip before immediately returning the one we're
+    # after.
+    #
+    # Each time we find a difference, we add it to +diffs+ and decrement n.  If n is zero, we
+    # have found the difference we were looking for so we throw :found and the difference (a
+    # 2-tuple).
+    #
+    # We return an array of all the differences we have found.
+    #
+  def _diff(o1, o2, base, n)
+    if _immediate?(o1) or _immediate?(o2)
+      return "Immediate value(s)"
+      #return [o1,o2].map { |o| "#{field_path}: #{o.inspect}" }
+    else
+        # Both objects are complex, and we're happy.
+      h1 = _hash_representation(o1)
+      h2 = _hash_representation(o2)
+      fields = (h1.keys + h2.keys).uniq.sort
+      diffs = []
+      fields.each do |f|
+        v1 = h1[f]
+        v2 = h2[f]
+        goirb binding if $X
+        if v1 == v2
+          next
+        else
+            # We've found two unequal values. If they're immediate values,
+            # we count it as a difference.  If they're complex, then we
+            # recurse into them.
+          field_path = [base, f].reject { |s| s.empty? }.join('.')
+          if _immediate?(v1) or _immediate?(v2)
+            diff = [v1,v2].map { |v| "#{field_path}: #{v.inspect}" }
+            throw :found, diff if (n -= 1).zero?
+            diffs << diff
+          else
+            diffs.concat _diff(v1, v2, field_path, n)
+          end
+        end
+      end
+      return diffs
+    end
+  end
+
+    #
+    # Returns true iff the given object is an "immediate value".  That means a fundamenal Ruby
+    # data type.  It's an arbitrary definition, and the choices are hardcoded.  Hopefully I can
+    # think of a better heuristic.
+    #
+  def _immediate?(object)
+    [Numeric, String, Range, Array, Hash, NilClass, TrueClass,
+      FalseClass].any? { |klass| klass === object }
+  end
+
+    #
+    # Returns a hash representation of an object, mapping field names to values.
+    #
+  def _hash_representation(object)
+    _methods = object.public_methods(false)
+    if Struct === object
+        # In a Struct, if X is an attribute, then there are methods X and X=.
+      fields = _methods.grep(/=/).map { |meth| meth.to_s.tr('=', '') }
+      fields = fields.select { |meth| _methods.include? meth }
+    else
+        # In a general complex oject, if X in an attribute, then there is a method X and an
+        # instance variable @X.
+      _variables = object.instance_variables.map { |v| v.tr('@', '') }
+      fields = _variables.select { |v| _methods.include? v }
+    end
+      # Now we've got the fields, which in all cases are public methods.  So we call them to
+      # get the values and construct our hash.
+    result = {}
+    fields.each do |field|
+      result[field] = object.send(field)
+    end
+    result
+  end
+
+  #
+  # Implementation notes for diff.
+  #
+  # Approach:
+  #   * we don't dig into arrays or hashes, etc.; those are "immediate" values along
+  #     with Numeric, String, Range, etc.
+  #   * if object under inspection is immediate, we compare with 'equal?' and that's it
+  #   * OK, so we've got two complex objects
+  #     * get hash representations, one level deep: field => value
+  #       * there is special logic for Structs
+  #     * if field sets are different, do we care?
+  #       * we can just report that field F is X in o1 but is nil in o2
+  #     * examine fields in alphabetical order
+  #       * compare values (with #equal?)
+  #         * if equal, go to next field
+  #         * if not equal
+  #           * if value(s) are immediate, compare and report (or skip, or count,
+  #             according to flags)
+  #           * otherwise, dig into those values (recurse)
+  #
+
+  # Alternative notes for diff.
+  #
+  # Approach:
+  #   * have a separate method 'structure(obj)', which returns the structure of the
+  #     given object; e.g. structure(person) -> ['name', 'age', 'address.number',
+  #     'address.road', 'address.city']
+  #     * that 'structure' method would be useful for some other things
+  #     * you can yield each bit as it's done
+  #   * use 'structure' and 'eval' to get the value of things
+  #     * be smart about nil values; e.g. person.address could be nil, which
+  #       would represent a different, but compatible, structure
+  #
+  # This seems simpler than mixing it all up as in the implementation above.
+
+end  # module Kernel
+
+class Object
+  def topology
+  end
+end
+
+=end