debuglog 1.0.0 → 1.0.1

data/.gitignore

@@ -0,0 +1,4 @@
+debug.log
+xyz.txt
+tags
+*.gem

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in col.gemspec
+gemspec

data/History.txt

@@ -0,0 +1,8 @@
+=== 1.0.1 / 2023-01-06
+
+* Fixed bugs in `trace`
+* Improved documentation and project management (Bundler)
+
+=== 1.0.0 / 2012-01-03
+
+* First release (not yet announced)

data/LICENCE

@@ -0,0 +1,19 @@
+Copyright (c) 2005 Gavin Sinclair (gsinclair@gmail.com)
+
+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,47 @@
+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 "Creating #{n} connections"
+    trace "names.first", binding
+    time('Process config file') { Subsystem.configure(ARGV.shift) }
+
+The log file (default ./debug.log) will look something like this:
+
+    DebugLog -- 2011-12-28 18:58:22 +1000
+    -------------------------------------
+    [00.3] Creating 14 connections
+    [00.8] names.first == "Sandy White"
+    [01.9] Process config file: 1.0831 sec
+
+The [00.3] etc. is the number of seconds (rounded) since the program started
+(well, since require 'debuglog', anyway).
+
+You can use different method names (to avoid a clash) and a different filename
+with some initial configuration.
+
+    require 'debuglog/manual'
+
+    DebugLog.configure(
+      :debug => :my_debug,
+      :trace => :my_trace,
+      :time  => :my_time,
+      :filename => 'log/xyz.log'
+    )
+
+    my_debug "Creating #{n} connections"
+    my_trace "names.first", binding
+    my_time('Process config file') { Subsystem.configure(ARGV.shift) }
+
+
+= HOMEPAGE
+
+See http://gsinclair.github.com/debuglog.html for full details.
+
+MIT Licence

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/TODO.txt

@@ -0,0 +1,11 @@
+* Get it working in 1.8.7
+   - one failing test at the moment
+* See if it works in 1.8.6
+   - Whitestone doesn't work in 1.8.6 (and never will) so I can only test
+     it by tring it
+
+
+Future features
+
+* Colour, whether directly (:red, etc.) or indirectly (traces are yellow,
+  timings are cyan, strings with !! are red, ...)

data/debuglog.gemspec

@@ -0,0 +1,29 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "debuglog/version"
+
+Gem::Specification.new do |s|
+  s.name        = "debuglog"
+  s.version     = DebugLog::VERSION
+  s.authors     = ["Gavin Sinclair"]
+  s.email       = ["gsinclair@gmail.com"]
+  s.homepage    = "http://gsinclair.github.com/debuglog.html"
+  s.summary     = "Zero-conf debug.log file with 'debug', 'trace' and 'time' methods"
+  s.description = <<-EOF
+    require 'debuglog' and record debugging information (including variable traces
+    and timing information) to the file debug.log -- cheap and easy.
+  EOF
+
+  s.rubyforge_project = ""
+  s.has_rdoc = false
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.add_development_dependency "bundler"
+  s.add_development_dependency "whitestone"
+
+  s.required_ruby_version = '>= 1.8.6'    # Tested.
+end

data/doc/debuglog.markdown

@@ -1,262 +1,278 @@
----
-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.
+---
+layout: default
+title: Debuglog
+---
+
+# Debuglog -- a zero-conf debug.log file
+
+* 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 "Creating #{n} connections"
+    trace "names.first", binding
+    time('Process config file') { Subsystem.configure(ARGV.shift) }
+
+{% endhighlight %}
+
+The log file (default `./debug.log`) will look something like this:
+
+    DebugLog -- 2011-12-28 18:58:22 +1000
+    -------------------------------------
+    [00.3] Creating 14 connections
+    [00.8] names.first == "Sandy White"
+    [01.9] Process config file: 1.0831 sec
+
+The `[00.3]` etc. is the number of seconds (rounded) since the program started
+(well, since `require 'debuglog'`, anyway).
+
+You can use different method names (to avoid a clash) and a different filename
+with some initial configuration.
+
+{% highlight ruby %}
+
+    require 'debuglog/manual'
+
+    DebugLog.configure(
+      :debug => :my_debug,
+      :trace => :my_trace,
+      :time  => :my_time,
+      :filename => 'log/xyz.log'
+    )
+
+    my_debug "Creating #{n} connections"
+    my_trace "names.first", binding
+    my_time('Process config file') { Subsystem.configure(ARGV.shift) }
+
+{% endhighlight %}
+
+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` emits the value of an expression. You are required 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 %}
+
+The above examples use a symbol to trace a variable.  You can, however, pass in
+any expression:
+
+{% highlight ruby %}
+
+    trace "names.find { |n| n.length > 7 }", binding
+
+{% 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 to avoid a name clash with another library or your own code.
+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.  Years 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 name `dev-utils` for
+something else, they're welcome to it.)
+
+### Dependencies and requirements
+
+Debuglog does not depend on any other libraries. It is tested on Ruby versions
+1.8.\[67] and 1.9.\[123]. It should continue to work on future 1.9 releases.
+
+Unit tests are implemented in [Whitestone](http://gsinclair.github.com/whitestone.html).
+
+### Project details
+
+* Author: Gavin Sinclair (user name: `gsinclair`; mail server: `gmail.com`)
+* 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
+
+### History
+
+* 6 JAN 2012: Version 1.0.1 released (improved documentation)
+* 3 JAN 2012: Version 1.0.0 released but not announced
+* JULY 2010: Implemented but not released
+
+See History.txt for more details.
+
+### 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.