debuglog 1.0.0

data/README

@@ -0,0 +1,38 @@
+debuglog: zero-conf debug.log file for simple and hassle-free debugging
+
+Synopsis
+
+    Debuglog gives you debug, trace and time  methods that write their output to
+    the file ./debug.log.
+
+        require 'debuglog'     # or require 'debuglog/auto'
+
+        debug "Message..."
+        trace :x, binding
+        time('Task') { action }
+
+    You can change the names of the methods and the filename.
+
+        require 'debuglog/manual'
+
+        DebugLog.configure(
+          :debug => :my_debug,
+          :trace => :my_trace,
+          :time  => :my_time,
+          :filename => 'log/xyz.log'
+        )
+
+        my_debug "Message..."
+        my_trace :x, binding
+        my_time('Task') { action }
+
+    In either case, the log file will look something like this:
+
+    DebugLog -- 2010-07-25 18:58:22 +1000
+    -------------------------------------
+    [00.3] Message...
+    [00.5] x == 5
+    [00.6] Task: 1.0831 sec
+
+
+See http://gsinclair.github.com/debuglog.html for full details.

data/doc/debuglog.markdown

@@ -0,0 +1,262 @@
+---
+layout: default
+title: Debuglog
+---
+
+# Debuglog -- a zero-conf debug.log file
+
+**Status: awaiting release (July 2010)**
+
+* This will be replaced by a table of contents
+{:toc}
+
+
+## Synopsis
+
+Debuglog gives you `debug`, `trace` and `time` methods that write their output
+to the file `./debug.log`.
+
+{% highlight ruby %}
+
+    require 'debuglog'     # or require 'debuglog/auto'
+
+    debug "Message..."
+    trace :x, binding
+    time('Task') { action }
+
+{% endhighlight %}
+
+You can change the names of the methods and the filename.
+
+{% highlight ruby %}
+
+    require 'debuglog/manual'
+
+    DebugLog.configure(
+      :debug => :my_debug,
+      :trace => :my_trace,
+      :time  => :my_time,
+      :filename => 'log/xyz.log'
+    )
+
+    my_debug "Message..."
+    my_trace :x, binding
+    my_time('Task') { action }
+
+{% endhighlight %}
+
+In either case, the log file will look something like this:
+
+    DebugLog -- 2010-07-25 18:58:22 +1000
+    -------------------------------------
+    [00.3] Message...
+    [00.5] x == 5
+    [00.6] Task: 1.0831 sec
+
+The `[00.3]` etc. is the number of seconds (rounded) since the program started
+(well, since `require 'debuglog'`, anyway).
+
+More nuanced configuration is possible; see [Configuration](#Configuration).
+
+### Installation
+
+    $ [sudo] gem install debuglog
+
+Source code is hosted on Github.  See [Project details](#project_details).
+
+
+## Description
+
+Debuglog allows you easy access to a log file named `debug.log` in the current
+directory.  In that file, you can record:
+* arbitrary messages with `debug`
+* the value of variables with `trace`
+* the time taken to execute some code with `time`
+
+Of course, any or all of those methods names might be used by another library or
+by your own code. You can choose different method names and a different
+filename; see [Configuration](#Configuration).  Debuglog will raise an
+exception (`DebugLog::Error`) if it detects a method clash.
+
+### `debug`
+
+The `debug` method is straightforward.  It calls `to_s` on its argument(s) and
+writes them to the log file.
+
+[col]: http://gsinclair.github.com/col.html
+
+### `trace`
+
+`trace` requires you to pass the binding with the `binding` method.  The two
+following lines are equivalent:
+
+{% highlight ruby %}
+
+    trace :radius, binding
+    debug "radius == #{radius.pretty_inspect}"
+
+{% endhighlight %}
+
+> Tip: You may choose to `alias _b binding` for convenience; DebugLog doesn't do that
+> for you.
+
+If you want the output truncated, pass an integer argument:
+
+{% highlight ruby %}
+
+    trace :text, binding, 30
+
+{% endhighlight %}
+
+### `time`
+
+`time` calculates the amount of time taken to execute the code in the block
+given and records it in the log file.
+
+{% highlight ruby %}
+
+    time("Process configuration file") { @options = parse_config }
+
+{% endhighlight %}
+
+It requires a single string (`#to_s`) argument and a block.
+
+### Notes
+
+`Debuglog` is a synonym for `DebugLog`, so you don't have to trouble yourself to
+remember the capitalisation.
+
+The text written to the log file has some nice touches:
+* Multi-line output is indented correctly.
+* `-------` is inserted each time an extra second of running time has elapsed.
+  This gives you a quick visual indication of how much logfile activity is
+  taking place.  If more than one second has elapsed since the last log item,
+  something like `------- (3 sec)` is emitted.
+
+
+## Configuration
+
+The [Synopsis](#synopsis) gave a good example of configuration:
+
+{% highlight ruby %}
+
+    require 'debuglog/manual'
+
+    DebugLog.configure(
+      :debug => :my_debug,
+      :trace => :my_trace,
+      :time  => :my_time,
+      :filename => 'log/xyz.log'
+    )
+
+{% endhighlight %}
+
+This changes the names of the methods that Debuglog defines.  The motivation for
+that, of course, is another library or your own code defining methods of those
+names.  Debuglog will raise an exception (`DebugLog::Error`) if it detects a
+method name clash.  (Of course, you might load the other library _after_
+Debuglog, in which case it won't detect the clash.)  This precaution is taken
+because they are common method names at the top-level, and it's just not right
+for a debugging library to _cause_ bugs.
+
+If you omit a method name from the configuration, that method will not be
+defined.  The following code defines the method `d` instead of `debug`, but does
+_not_ define `trace` or `time`.  The standard filename `debug.log` is used.
+
+{% highlight ruby %}
+
+    DebugLog.configure(
+      :debug => :d,
+    )
+
+{% endhighlight %}
+
+If you want to change one or two methods but leave the rest as standard, simply
+do:
+
+{% highlight ruby %}
+
+    DebugLog.configure(
+      :debug => :d,
+      :trace => :trace,
+      :time  => :time
+    )
+
+{% endhighlight %}
+
+Once you have called `DebugLog.configure`, any further calls to it will be
+ignored with a message on STDERR.  That includes this case:
+
+{% highlight ruby %}
+
+    require 'debuglog'           # should be 'debuglog/manual'
+
+    DebugLog.configure(...)
+
+{% endhighlight %}
+
+The code `require 'debuglog` is equivalent to the following code, meaning
+your one shot at calling `configure` has been taken.
+
+{% highlight ruby %}
+
+    require 'debuglog/manual'
+
+    DebugLog.configure(
+      :debug => :debug,
+      :trace => :trace,
+      :time  => :time,
+      :file  => 'debug.log'
+    )
+
+{% endhighlight %}
+
+Final note: if you specify a file that is not writable, an error
+(`DebugLog::Error`) will be raised.
+
+
+## Endnotes
+
+### Motivation
+
+Debugging to a log file is very useful, even if your program doesn't do
+"logging" as such.  Ages ago I released `dev-utils/debug` which did this and
+intended to do more.  That's outdated now, only working on 1.8, so a revisit was
+worthwhile with a better name.  (If anyone wants the old name for something
+else, they're welcome to it.)
+
+### Dependencies and requirements
+
+Debuglog does not depend on any other libraries and works in Ruby 1.8 and Ruby
+1.9.
+
+Unit tests are implemented in [Attest](http://gsinclair.github.com/attest.html).
+
+### Project details
+
+* Author: Gavin Sinclair (user name: `gsinclair`; mail server: `gmail.com`)
+* Date: July 2010
+* Licence: MIT licence
+* Project homepage: [http://gsinclair.github.com/debuglog.html][home]
+* Source code: [http://github.com/gsinclair/debuglog][code]
+* Documentation: (project homepage)
+
+[home]: http://gsinclair.github.com/debuglog.html
+[code]: http://github.com/gsinclair/debuglog
+
+### Possible future enhancements
+
+Color.  For instance, `debug "!! Object pool overloaded"` could print the
+message (minus the exclamation marks) in red.  Traces could be in yellow.  Times
+could be in dark cyan, etc.
+
+Further to the above: symbol arguments to `debug` could provide some color
+using the `Col` library.  E.g. `debug "blah...", :yb` for yellow bold.
+
+Method to turn it off and on: `DebugLog.off` and `DebugLog.on` or something.
+
+Indenting via `DebugLog.indent` and `DebugLog.outdent`.
+
+Options for `trace` output: `p` for `:inspect`; `y` for `:to_yaml` etc.  I
+don't see why the current `:pretty_inspect` would ever be insufficient, but of
+course there may be cases.

data/lib/debuglog.rb

@@ -0,0 +1,17 @@
+#
+# Usage:
+#
+#   require 'debuglog'
+#   debug "..."        # -> writes "..." to 'debug.log'
+#
+# Note: +debug+ is the _default_ method name.  You can set a different one like
+# this:
+#
+#   require 'debuglog/manual'
+#   DebugLog.configure(...)  # todo: complete
+#   dbg "..."          # -> writes "..." to 'debug.log'
+#
+# If +debug+ (or the name you choose manually) is the name of an existing
+# method, it will _not_ be overwritten.
+
+require 'debuglog/auto'

data/lib/debuglog/auto.rb

@@ -0,0 +1,2 @@
+require 'debuglog/manual'
+DebugLog.autoconfigure

data/lib/debuglog/manual.rb

@@ -0,0 +1,177 @@
+#
+# require 'debuglog/manual'
+#
+# DebugLog.configure(:debug => :dbg)
+# dbg "..."         # -> writes "..." to file 'debug.log'
+#
+
+class DebugLog
+
+  @@instance = nil
+
+  DEFAULT_CONFIGURATION = {
+    :debug => :debug,
+    :trace => :trace,
+    :time  => :time,
+    :file  => 'debug.log'
+  }
+
+  class Error < StandardError; end
+
+  def DebugLog.err(string)
+    raise ::DebugLog::Error, "DebugLog error -- #{string}"
+  end
+
+  def DebugLog.configure(hash)
+    if @@instance.nil?
+      @@instance = DebugLog.new(hash)
+    else
+      err("DebugLog already configured")  # todo: replace
+    end
+  end
+
+  def DebugLog.autoconfigure
+    configure(DEFAULT_CONFIGURATION)
+  end
+
+  def initialize(config)
+    @kernel_methods_defined = []
+    _create_kernel_method(config[:debug], :debug)
+    _create_kernel_method(config[:trace], :trace)
+    _create_kernel_method(config[:time],  :time)
+    @filename = config[:filename] || 'debug.log'
+    begin
+      @fh = File.open(@filename, 'w')
+    rescue => e
+      raise DebugLog::Error, "#{e.class} (#{e.message})"
+    end
+    @fh.sync = true
+    @start_time = Time.now
+    header = "DebugLog -- #{@start_time}"
+    @fh.puts header
+    @fh.puts('-' * header.length)
+  end
+
+  def debug(*args)
+    string = args.map { |x| x.to_s }.join
+    _write(string)
+  end
+
+  def trace(expr, _binding, *options)
+    value = eval expr, _binding
+    require 'pp'
+    formatter = :pretty_inspect
+    ##  if (m = options.find { |o| o.is_a? Symbol })
+    ##    case m
+    ##    when :p        then :inspect
+    ##    when :s, :to_s then :to_s
+    ##    when :pp       then (require 'pp'; :pretty_inspect)
+    ##    when :yaml     then (require 'yaml'; :to_yaml)
+    ##    when :ap       then (require 'ap'; :ap)
+    ##    else           then :inspect
+    ##    end
+    ##  else
+    ##    :inspect
+    ##  end
+    value = value.send(formatter)
+    if (n = options.find { |o| o.is_a? Integer })
+      value = value[0...n] + "..."
+    end
+    message =
+      if value.index("\n")
+        value = value.gsub(/^/, '  ')
+        "#{expr} ==\n#{value}"
+      else
+        "#{expr} == #{value}"
+      end
+    _write(message)
+  end
+
+  def time(task, &block)
+    result = nil
+    message =
+      if block.nil?
+        "*** Debuglog.task: block required (#{caller[0]}) ***"
+      else
+        t = Time.now
+        result = block.call
+        t = sprintf "%.3f", (Time.now - t)
+        "#{task}: #{t} sec"
+      end
+    _write(message)
+    result
+  end
+
+  def _write(message)
+    time = (Time.now - @start_time)
+    if time.to_i != @time.to_i
+      elapsed = time.to_i - @time.to_i
+      if elapsed > 1
+        @fh.puts "------- (#{elapsed} sec)"
+      else
+        @fh.puts "-------"
+      end
+    end
+    @time = time
+    time = sprintf "%04.1f", time.to_f
+    if message.index("\n")
+      lines = message.split("\n")
+      @fh.puts "[#{time}] #{lines.shift}"
+      indent = " " * (time.size+3)
+      lines.each do |line| @fh.puts "#{indent}#{line}" end
+    else
+      text = "[#{time}] #{message}"
+      @fh.puts(text)
+    end
+  end
+
+  def _create_kernel_method(name, target)
+    if name.nil?
+      return 
+    elsif Kernel.respond_to? name
+      DebugLog.err "DebugLog: Method clash in Kernel: #{name.inspect}"
+    else
+      Kernel.module_eval %{
+        def #{name}(*args, &block)
+          DebugLog.call_method(:#{target}, *args, &block)
+        end
+      }, __FILE__, __LINE__ - 4
+      @kernel_methods_defined << name
+    end
+  end
+
+  DEBUG_METHODS = [:debug, :trace, :time]
+  def DebugLog.call_method(name, *args, &block)
+    if DEBUG_METHODS.include? name
+      if @@instance
+        @@instance.send(name, *args, &block)
+      else
+        err %{
+          ~ DebugLog is not configured.  You can:
+          ~   * require 'debuglog/auto' or call DebugLog.autoconfigure; or
+          ~   * call DebugLog.configure(...) to configure it manually
+        }.strip.gsub(/^\s+~ /, '')
+      end
+    else
+      err "illegitimate method called: #{name}"
+    end
+  end
+
+  def terminate   # For testing
+    @fh.close unless @fh.closed?
+    @kernel_methods_defined.each do |m|
+      Kernel.send(:remove_method, m)
+    end
+  end
+  private :terminate
+
+  def DebugLog.wipe_slate_clean_for_testing
+    if @@instance
+      @@instance.send(:terminate)
+      @@instance = nil
+    end
+  end
+
+end  # class DebugLog
+
+Debuglog = DebugLog

data/test/_setup.rb

@@ -0,0 +1,14 @@
+require 'debuglog'
+require 'ruby-debug'
+
+Attest.custom :debuglog, {
+  :description => "Last line of log file",
+  :parameters  => [ [:regex, Regexp], [:filename, String] ],
+  :run => proc {
+    file_data = File.read(filename)
+    test('file exists') { N! file_data }
+    test('file has data in it') { file_data.size > 0 }
+    last_line = file_data.split("\n").last
+    test('match') { Mt last_line, regex }
+  }
+}

data/test/debuglog-auto.rb

@@ -0,0 +1,66 @@
+D "Debuglog auto configuration" do
+  D.<< {
+    DebugLog.send :wipe_slate_clean_for_testing
+    DebugLog.autoconfigure
+  }
+
+  D "Debuglog and DebugLog are the same thing" do
+    Id Debuglog, DebugLog
+  end
+  D "Methods are defined in Kernel" do
+    kernel_methods = Kernel.instance_methods
+    T { kernel_methods.include? :debug }
+    T { kernel_methods.include? :trace }
+    T { kernel_methods.include? :time }
+  end
+  D "debug" do
+    debug "abc123"
+    T :debuglog, /abc123/, "debug.log"
+    debug -189
+    T :debuglog, /-189/, "debug.log"
+    D "multiple arguments" do
+      x = 5
+      debug "The value of x is ", x, "!"
+      T :debuglog, /The value of x is 5!/, "debug.log"
+    end
+    D "multi-line text" do
+      text = "I must go down to the seas again\nTo the lonely sea and the sky\nAnd all I want is a tall ship\nAnd a star to steer her by\n     -- John Masefield"
+      debug text
+      log_text_lines = File.read("debug.log").split("\n").last(5)
+      # The text in the log file should be indented to look good.
+      Mt log_text_lines.shift, /\[\d\d\.\d\] I must go down to the seas again$/
+      Eq log_text_lines.shift, "       To the lonely sea and the sky"
+      Eq log_text_lines.shift, "       And all I want is a tall ship"
+      Eq log_text_lines.shift, "       And a star to steer her by"
+      Eq log_text_lines.shift, "            -- John Masefield"
+    end
+  end
+  D "trace" do
+    D "array" do
+      foo = [1,2,3]
+      trace :foo, binding
+      T :debuglog, /foo == \[1, 2, 3\]/, "debug.log"
+    end
+    D "string" do
+      str = "blah"
+      trace :str, binding
+      T :debuglog, /str == "blah"/, "debug.log"
+    end
+    D "truncate output" do
+      str = "x" * 100
+      trace :str, binding, 30
+      T :debuglog, /str == "xxxxxxxxxxxxxxxxxxxxxxxxxxxxx\.\.\./, "debug.log"
+    end
+    D "different formats" do
+      # not really interested in this feature at the moment
+    end
+  end
+  D "time" do
+    time('sum to 10') { 1+2+3+4+5+6+7+8+9+10 }
+    T :debuglog, /sum to 10: .* sec/, "debug.log"
+    D "return value of block is accessible" do
+      sum = time('sum') { 1 + 1 }
+      Eq sum, 2
+    end
+  end
+end

data/test/debuglog-manual-1.rb

@@ -0,0 +1,39 @@
+D "DebugLog manual configuration (successful)" do
+  D.< { DebugLog.send :wipe_slate_clean_for_testing }
+
+  D ":debug => :my_debug, :filename => 'xyz.txt'" do
+    Debuglog.configure(:debug => :my_debug, :filename => 'xyz.txt')
+    D "my_debug method works" do
+      my_debug "abc123"
+      T :debuglog, /abc123/, "xyz.txt"
+    end
+    D "debug, trace and time methods are not defined" do
+      E(NoMethodError) { debug "abc123" }
+      E(NoMethodError) { trace :x, binding }
+      E(NoMethodError) { time('task') { :foo } }
+    end
+  end
+
+  D ":trace => :my_trace, :time => :my_time" do
+    Debuglog.configure(:trace => :my_trace, :time => :my_time)
+    D "my_trace and my_time methods work" do
+      foo = :chorus
+      my_trace "foo", binding
+      xT :debuglog, /foo == :chorus/, "debug.log"
+      my_time('blah') { :dotdotdot }
+      T :debuglog, /blah: .* sec/, "debug.log"
+    end
+    D "debug method not defined" do
+      E(NoMethodError) { debug "..." }
+    end
+  end
+
+  D "empty configuration" do
+    Debuglog.configure({})
+    D "debug, trace and time methods don't work" do
+      E(NoMethodError) { debug "abc123" }
+      E(NoMethodError) { trace :x, binding }
+      E(NoMethodError) { time('task') { :foo } }
+    end
+  end
+end

data/test/debuglog-manual-2.rb

@@ -0,0 +1,27 @@
+D "DebugLog manual configuration (unsuccessful)" do
+  D.< { DebugLog.send :wipe_slate_clean_for_testing }
+
+  D "clash with existing :debug method" do
+    def Kernel.debug() :foo end
+    E(DebugLog::Error) { DebugLog.autoconfigure }
+  end
+
+  D "clash with custom methods" do
+    def Kernel.my_debug() :foo end
+    def Kernel.my_trace() :foo end
+    def Kernel.my_time()  :foo end
+    E(DebugLog::Error) { DebugLog.configure(:debug => :my_debug) }
+    E(DebugLog::Error) { DebugLog.configure(:trace => :my_trace) }
+    E(DebugLog::Error) { DebugLog.configure(:time  => :my_time)  }
+  end
+
+  D "calling methods without having configured -> error" do
+    # At this point DebugLog is not configured.
+    E(NameError) { debug }
+    E(DebugLog::Error) { DebugLog.call_method(:debug, "...") }
+  end
+
+  D "specifying unwritable log file -> error" do
+    E(DebugLog::Error) { DebugLog.configure(:filename => '/fodsfw/fgsg/e/debug.log') }
+  end
+end

metadata

@@ -0,0 +1,75 @@
+--- !ruby/object:Gem::Specification 
+name: debuglog
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 1
+  - 0
+  - 0
+  version: 1.0.0
+platform: ruby
+authors: 
+- Gavin Sinclair
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-12-12 00:00:00 +11:00
+default_executable: 
+dependencies: []
+
+description: "    require 'debuglog' and record debugging information (including variable traces\n    and timing information) to the file debug.log -- cheap and easy.\n"
+email: gsinclair@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/debuglog/auto.rb
+- lib/debuglog/manual.rb
+- lib/debuglog.rb
+- README
+- test/_setup.rb
+- test/debuglog-auto.rb
+- test/debuglog-manual-1.rb
+- test/debuglog-manual-2.rb
+- doc/debuglog.markdown
+has_rdoc: true
+homepage: http://gsinclair.github.com/debuglog.html
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Zero-conf debug.log file with 'debug', 'trace' and 'time' methods
+test_files: 
+- test/_setup.rb
+- test/debuglog-auto.rb
+- test/debuglog-manual-1.rb
+- test/debuglog-manual-2.rb