watcher 1.1.0 → 1.2.0

data/lib/watcher/version.rb

@@ -1,7 +1,7 @@
 module Watcher
   module VERSION #:nodoc:
     MAJOR = 1
-    MINOR = 1
+    MINOR = 2
     TINY  = 0
 
     STRING = [MAJOR, MINOR, TINY].join('.')

data/script/txt2html

@@ -1,4 +1,4 @@
-#!/usr/bin/ruby
+#!/usr/bin/env ruby
 
 GEM_NAME = 'watcher' # what ppl will type to install your gem
 RUBYFORGE_PROJECT = 'watcher'

data/test/tc_event.rb

@@ -0,0 +1,73 @@
+#!/usr/bin/ruby -w
+# -*- Ruby -*-
+# Watcher Tests
+#
+# Summary::   Watcher provides advanced integrated exception handling and
+#             logging functionality to your Ruby programs.
+# Author::    Karrick McDermott (karrick@karrick.org)
+# Date::      2008-07-04
+# Copyright:: Copyright (c) 2008 by Karrick McDermott.  All rights reserved.
+# License::   Simplified BSD License.
+
+######################################################################
+
+require "test/unit"
+require "event"
+
+class TestEvent < Test::Unit::TestCase
+  def setup
+    @title = 'TITLE'
+    @time = Time.now.utc
+    @fail_actions = {:failure => :error}
+    @relationship = :child
+    @base = nil
+
+    # Create a root event node
+    #   (time, hier, title, fail_actions, relationship)
+    @root = Event.new(@time, nil, @title, @fail_actions, :child)
+  end
+
+  def test_child_of_child
+    first_child = @root.child
+    assert_kind_of(Event, first_child)
+    assert_equal('0.a', first_child.hier)
+    
+    second_child = first_child.child
+    assert_equal('0.a.0', second_child.hier)
+  end
+
+  def test_sibling_of_sibling
+    first_sibling = @root.sibling
+    assert_kind_of(Event, first_sibling)
+    assert_equal('1', first_sibling.hier)
+    
+    second_sibling = first_sibling.sibling
+    assert_kind_of(Event, second_sibling)
+    assert_equal('2', second_sibling.hier)
+  end
+
+  def test_child_of_sibling
+    sibling = @root.sibling
+    assert_kind_of(Event, sibling)
+    assert_equal('1', sibling.hier)
+    
+    child = sibling.child
+    assert_kind_of(Event, child)
+    assert_equal('1.a', child.hier)
+  end
+
+  def test_sibling_of_child
+    child = @root.child
+    assert_kind_of(Event, child)
+    assert_equal('0.a', child.hier)
+    
+    sibling = child.sibling
+    assert_kind_of(Event, sibling)
+    assert_equal('0.b', sibling.hier)
+  end
+
+# def test_initialize_fail_actions
+#   assert_raise(:ArgumentError) { Event.new(@time, nil, @title, {}, :child)
+#   
+# end
+end

data/test/test_watcher.rb

@@ -1,11 +1,98 @@
-require File.dirname(__FILE__) + '/test_helper.rb'
-
-class TestWatcher < Test::Unit::TestCase
-
-  def setup
-  end
-  
-  def test_truth
-    assert true
-  end
-end
+require File.dirname(__FILE__) + '/test_helper.rb'
+require File.dirname(__FILE__) + '/tc_event.rb'
+
+class TestWatcher < Test::Unit::TestCase
+  MAX_ATTEMPTS = 3
+  
+  def setup
+    params = {:warn_symbol=>'WARNING', :error_symbol => 'ERROR'}
+    params = params.merge(:verbosity => :verbose)
+    params = params.merge(:default_fail => {:failure => :error})
+    @w = Watcher.create(params)
+  end
+  
+  def test_exception_causes_warning
+    @w.verbose("Test -- exception causes warning") do
+      # Ensure that when pass :warn, Watcher will not re-raise exception,
+      # provided the :proc doesn't throw an exception as well
+      assert_nothing_thrown do
+        @w.debug("causing an exception, but catch with :warn", :failure => :warn) do
+          raise RuntimeError.new("exception")
+        end
+      end
+    end
+  end
+  
+  def test_exception_reraised
+    @w.verbose("Test -- exception re-raised") do
+      # Ensure that when no :failure passed, Watcher will re-raise exception
+      assert_raise(RuntimeError) do
+        @w.debug("causing an exception, no catch") do
+          raise RuntimeError.new("exception")
+        end
+      end
+
+      # Ensure that when pass :error, Watcher will re-raise exception,
+      assert_raise(RuntimeError) do
+        @w.debug("causing an exception, no catch", :failure => :error) do
+          raise RuntimeError.new("exception")
+        end
+      end
+    end
+  end
+  
+  def test_retries_then_reraise
+    @w.verbose("Test -- retries resulting in re-raising exception") do
+      # Watcher will execute specified number of tries, then re-raise.
+      # The Proc simply closes over out retry_count variable, incrementing it.
+      attempt_count = 0   # Count how many tries actually occured
+      assert_raise(RuntimeError) do
+        @w.debug("causing exception with #{MAX_ATTEMPTS} tries then error", {:tries => MAX_ATTEMPTS, :proc => lambda { |e| attempt_count += 1 }, :failure => :error}) do
+            raise RuntimeError.new("exception")
+        end
+      end
+      # NOTE: off-by-one because we run Proc in-between attempts
+      assert_equal(MAX_ATTEMPTS-1, attempt_count)
+    end
+  end
+
+  def test_retries_then_warn
+    @w.verbose("Test -- retries resulting in log warning") do
+      # Watcher will execute specified number of tries, then warn.
+      # The Proc simply closes over out retry_count variable, incrementing it.
+      attempt_count = 0   # Count how many tries actually occured
+      assert_nothing_thrown do
+        @w.debug("causing exception with #{MAX_ATTEMPTS} tries then warning", {:tries => MAX_ATTEMPTS, :proc => lambda { |e| attempt_count += 1 }, :failure => :warn}) do
+            raise RuntimeError.new("exception")
+        end
+      end
+      # NOTE: off-by-one because we run Proc in-between attempts
+      assert_equal(MAX_ATTEMPTS-1, attempt_count)
+    end
+  end
+  
+  def test_embedded_levels
+    @w.verbose("Test -- embedded levels") do
+      assert_nothing_thrown do
+        @w.debug("outside level, re-raise if error", :failure => :error) do
+          @w.debug("inside level, warn if error", :failure => :warn) do
+            raise RuntimeError.new("exception")
+          end
+        end
+      end
+    end
+  end
+
+  def test_send_email_without_output_file
+    # Watcher with output sent to STDOUT, and give
+    # signal to send email.
+    # Result should append a note to the log.
+    # (It should probably throw an exception, because invocation is wrong.)
+    
+    # Let's get an entry on the log, but don't wrap around a block
+    @w.always("about to test sending email without output file")
+    assert_raise(ArgumentError) do
+      @w.send_email("root@localhost", "FAIL: Watcher should not have sent this")
+    end
+  end
+end

data/test/ts_package.rb

@@ -0,0 +1,11 @@
+#!/usr/bin/ruby -w
+# -*- Ruby -*-
+#
+# TO EXECUTE:
+# $ cd ~/dev/watcher
+# $ ruby -I lib:test test/ts_package.rb
+
+require "test/unit"
+
+require "tc_event"
+require "test_watcher"

data/website/index.html

@@ -33,104 +33,105 @@
     <h1>watcher</h1>
     <div id="version" class="clickable" onclick='document.location = "http://rubyforge.org/projects/watcher"; return false'>
       <p>Get Version</p>
-      <a href="http://rubyforge.org/projects/watcher" class="numbers">1.1.0</a>
+      <a href="http://rubyforge.org/projects/watcher" class="numbers">1.2.0</a>
     </div>
-    <h1>&#x2192; &#8216;watcher&#8217;</h1>
-
-
-	<h2>What</h2>
-
-
-	<h2>Installing</h2>
-
-
-	<p><pre class='syntax'><span class="ident">sudo</span> <span class="ident">gem</span> <span class="ident">install</span> <span class="ident">watcher</span></pre></p>
-
-
-	<h2>The basics</h2>
-
-
-	<h2>Demonstration of usage</h2>
-
-
-	<h2>Forum</h2>
-
-
-	<p><a href="http://groups.google.com/group/watcher">http://groups.google.com/group/watcher</a></p>
-
-
-	<p><span class="caps">TODO</span> &#8211; create Google Group &#8211; watcher</p>
-
-
-	<h2>How to submit patches</h2>
-
-
-	<p>Read the <a href="http://drnicwilliams.com/2007/06/01/8-steps-for-fixing-other-peoples-code/">8 steps for fixing other people&#8217;s code</a> and for section <a href="http://drnicwilliams.com/2007/06/01/8-steps-for-fixing-other-peoples-code/#8b-google-groups">8b: Submit patch to Google Groups</a>, use the Google Group above.</p>
-
-
-	<p><span class="caps">TODO</span> &#8211; pick <span class="caps">SVN</span> or Git instructions</p>
-
-
-	<p>The trunk repository is <code>svn://rubyforge.org/var/svn/watcher/trunk</code> for anonymous access.</p>
-
-
-	<p><span class="caps">OOOORRRR</span></p>
-
-
-	<p>You can fetch the source from either:</p>
-
-
-	<ul>
-	<li>rubyforge: <span class="caps">MISSING IN ACTION</span></li>
-	</ul>
-
-
-	<p><span class="caps">TODO</span> &#8211; You can not created a RubyForge project, OR have not run <code>rubyforge config</code>
+    <h1>&amp;#x2192; &#8216;watcher&#8217;</h1>
+<h2>What</h2>
+<ul>
+	<li>Exception handling without the boiler-plate code.</li>
+	<li>Multiple tiers of verbosity.</li>
+	<li>Flexible logging capabilities, including to files, <span class="caps">STDERR</span>, email.</li>
+	<li>Nested, and hierarchical log output for descriptive stack-frame level<br />
+  understanding where an exception was thrown.</li>
+	<li>Ability to change the time format of your logs by supplying an arbitrary<br />
+  Proc to return the time in the format of your choice.</li>
+	<li>Ability to customize the layout of the logs, by turning off hierarchical<br />
+  view, or changing Strings used to indicate events.</li>
+	<li>Email log files automatically, based on number of errors or warnings.</li>
+	<li>Ability to invoke arbitrary sequence of events if exception is thrown,<br />
+  including invocation of Proc objects.</li>
+</ul>
+<h2>Installing</h2>
+<p><pre class='syntax'><span class="ident">sudo</span> <span class="ident">gem</span> <span class="ident">install</span> <span class="ident">watcher</span></pre></p>
+<h2>The basics</h2>
+<p>A simple example demonstrating multiple embedded levels, and how the<br />
+inside block simply logs the error so that the second puts statement still executes.<br />
+<br />
+<pre class='syntax'>
+<span class="comment"># create Watcher instance with defaults</span>
+<span class="global">$watcher</span> <span class="punct">=</span> <span class="constant">Watcher</span><span class="punct">.</span><span class="ident">create</span>
+
+<span class="global">$watcher</span><span class="punct">.</span><span class="ident">verbose</span><span class="punct">(&quot;</span><span class="string">doing something dangerous</span><span class="punct">&quot;)</span> <span class="keyword">do</span>
+  <span class="ident">puts</span> <span class="punct">&quot;</span><span class="string">be careful...</span><span class="punct">&quot;</span>
+  <span class="global">$watcher</span><span class="punct">.</span><span class="ident">debug</span><span class="punct">(&quot;</span><span class="string">going to do something very dangerous</span><span class="punct">&quot;,</span> <span class="symbol">:failure</span> <span class="punct">=&gt;</span> <span class="symbol">:warn</span><span class="punct">)</span> <span class="keyword">do</span>
+    <span class="keyword">raise</span> <span class="punct">&quot;</span><span class="string">ouch!</span><span class="punct">&quot;</span>
+  <span class="keyword">end</span>
+  <span class="ident">puts</span> <span class="punct">&quot;</span><span class="string">that wasn't so bad... just a log entry!</span><span class="punct">&quot;</span>
+<span class="keyword">end</span>
+</pre><br />
+<br />
+h2. Demonstration of usage<br />
+<br />
+<p>A more complicated example of sending a reference to a Proc to attempt<br />
+to recover from an condition.</p>
+<p><pre class='syntax'>
+<span class="comment"># create Watcher instance with slightly modified defaults</span>
+<span class="global">$watcher</span> <span class="punct">=</span> <span class="constant">Watcher</span><span class="punct">.</span><span class="ident">create</span><span class="punct">(</span><span class="symbol">:output</span> <span class="punct">=&gt;</span> <span class="ident">log_file</span><span class="punct">)</span>
+
+<span class="global">$watcher</span><span class="punct">.</span><span class="ident">debug</span><span class="punct">(&quot;</span><span class="string">starting <span class="expr">#{File.basename($0)}</span></span><span class="punct">&quot;)</span> <span class="keyword">do</span>
+  <span class="comment"># Look for CONFIG_PATH.  If not found, log warning then re-write it</span>
+  <span class="ident">params</span> <span class="punct">=</span> <span class="punct">{</span><span class="symbol">:tries</span> <span class="punct">=&gt;</span> <span class="number">2</span><span class="punct">,</span> <span class="symbol">:failure</span> <span class="punct">=&gt;</span> <span class="symbol">:error</span><span class="punct">,</span>
+            <span class="symbol">:proc</span> <span class="punct">=&gt;</span> <span class="ident">lambda</span> <span class="punct">{</span> <span class="punct">|</span><span class="ident">e</span><span class="punct">|</span> <span class="ident">write_config</span><span class="punct">(</span><span class="ident">config_path</span><span class="punct">)</span> <span class="punct">}}</span>
+  <span class="ident">msg</span> <span class="punct">=</span> <span class="punct">&quot;</span><span class="string">ensuring existance of config file [<span class="expr">#{config_path}</span>]</span><span class="punct">&quot;</span>
+  <span class="global">$watcher</span><span class="punct">.</span><span class="ident">verbose</span><span class="punct">(</span><span class="ident">msg</span><span class="punct">,</span> <span class="ident">params</span><span class="punct">)</span> <span class="keyword">do</span>
+    <span class="keyword">raise</span> <span class="punct">&quot;</span><span class="string">file not found</span><span class="punct">&quot;</span> <span class="keyword">unless</span> <span class="constant">File</span><span class="punct">.</span><span class="ident">file?</span><span class="punct">(</span><span class="constant">File</span><span class="punct">.</span><span class="ident">expand_path</span><span class="punct">(</span><span class="ident">config_path</span><span class="punct">))</span>
+  <span class="keyword">end</span>
+
+  <span class="comment"># invoke utility, which uses $watcher as well</span>
+  <span class="ident">fsc</span> <span class="punct">=</span> <span class="constant">FileSystemChecker</span><span class="punct">.</span><span class="ident">new</span><span class="punct">(</span><span class="symbol">:config_path</span> <span class="punct">=&gt;</span> <span class="ident">config_path</span><span class="punct">)</span>
+  <span class="ident">fsc</span><span class="punct">.</span><span class="ident">check_file_systems</span><span class="punct">(</span><span class="symbol">:all</span> <span class="punct">=&gt;</span> <span class="ident">all_flag</span><span class="punct">,</span> <span class="symbol">:remount</span> <span class="punct">=&gt;</span> <span class="ident">remount_flag</span><span class="punct">)</span>
+<span class="keyword">end</span>
+
+<span class="keyword">if</span> <span class="ident">email_flag</span> <span class="keyword">and</span> <span class="punct">(</span><span class="global">$watcher</span><span class="punct">.</span><span class="ident">errors</span> <span class="punct">&gt;</span> <span class="number">0</span> <span class="keyword">or</span> <span class="global">$watcher</span><span class="punct">.</span><span class="ident">warnings</span> <span class="punct">&gt;</span> <span class="number">0</span><span class="punct">)</span>
+  <span class="global">$watcher</span><span class="punct">.</span><span class="ident">send_email</span><span class="punct">(</span><span class="ident">email</span><span class="punct">,</span> <span class="punct">'</span><span class="string">FAIL: Required filesystems are not mounted</span><span class="punct">')</span>
+<span class="keyword">end</span>
+</pre></p>
+<h2>Forum</h2>
+<p><a href="http://groups.google.com/group/watcher">http://groups.google.com/group/watcher</a></p>
+<p><span class="caps">TODO</span> &#8211; create Google Group &#8211; watcher</p>
+<h2>How to submit patches</h2>
+<p>Read the <a href="http://drnicwilliams.com/2007/06/01/8-steps-for-fixing-other-peoples-code/">8 steps for fixing other people&#8217;s code</a> and for section <a href="http://drnicwilliams.com/2007/06/01/8-steps-for-fixing-other-peoples-code/#8b-google-groups">8b: Submit patch to Google Groups</a>, use the Google Group above.</p>
+<p><span class="caps">TODO</span> &#8211; pick <span class="caps">SVN</span> or Git instructions</p>
+<p>The trunk repository is <code>svn://rubyforge.org/var/svn/watcher/trunk</code> for anonymous access.</p>
+<p><span class="caps">OOOORRRR</span></p>
+<p>You can fetch the source from either:</p>
+<ul>
+	<li>rubyforge: <span class="caps">MISSING</span> IN <span class="caps">ACTION</span></li>
+</ul>
+<p><span class="caps">TODO</span> &#8211; You can not created a RubyForge project, OR have not run <code>rubyforge config</code><br />
 yet to refresh your local rubyforge data with this projects&#8217; id information.</p>
-
-
-	<p>When you do this, this message will magically disappear!</p>
-
-
-	<p>Or you can hack website/index.txt and make it all go away!!</p>
-
-
-	<ul>
+<p>When you do this, this message will magically disappear!</p>
+<p>Or you can hack website/index.txt and make it all go away!!</p>
+<ul>
 	<li>github: <a href="http://github.com/GITHUB_USERNAME/watcher/tree/master">http://github.com/GITHUB_USERNAME/watcher/tree/master</a></li>
-	</ul>
-
-
+</ul>
 <pre>git clone git://github.com/GITHUB_USERNAME/watcher.git</pre>
-
-	<p><span class="caps">TODO</span> &#8211; add &#8220;github_username: username&#8221; to ~/.rubyforge/user-config.yml and newgem will reuse it for future projects.</p>
-
-
-	<ul>
+<p><span class="caps">TODO</span> &#8211; add &#8220;github_username: username&#8221; to ~/.rubyforge/user-config.yml and newgem will reuse it for future projects.</p>
+<ul>
 	<li>gitorious: <a href="git://gitorious.org/watcher/mainline.git">git://gitorious.org/watcher/mainline.git</a></li>
-	</ul>
-
-
+</ul>
 <pre>git clone git://gitorious.org/watcher/mainline.git</pre>
-
-	<h3>Build and test instructions</h3>
-
+<h3>Build and test instructions</h3>
+<p><i>Sorry, no unit tests yet&#8230;</i></p>
 
 <pre>cd watcher
-rake test
 rake install_gem</pre>
-
-	<h2>License</h2>
-
-
-	<p>This code is free to use under the terms of the <span class="caps">MIT</span> license.</p>
-
-
-	<h2>Contact</h2>
-
-
-	<p>Comments are welcome. Send an email to <a href="mailto:karrick@karrick.net"><span class="caps">FIXME</span> full name</a> via the <a href="http://groups.google.com/group/watcher">forum</a></p>
+<h2>License</h2>
+<p>This code is free to use under the terms of the Simplified <span class="caps">BSD</span> license.</p>
+<h2>Contact</h2>
+<p>Comments are welcome. Send an email to <a href="mailto:karrick@karrick.org">Karrick McDermott</a> via the <a href="http://groups.google.com/group/watcher">forum</a></p>
     <p class="coda">
-      <a href="karrick@karrick.net">FIXME full name</a>, 20th July 2008<br>
+      <a href="karrick@karrick.org">Karrick McDermott</a>, 30th July 2008<br>
       Theme extended from <a href="http://rb2js.rubyforge.org/">Paul Battley</a>
     </p>
 </div>

data/website/index.txt

@@ -5,6 +5,18 @@ h1. → 'watcher'
 
 h2. What
 
+* Exception handling without the boiler-plate code.
+* Multiple tiers of verbosity.
+* Flexible logging capabilities, including to files, STDERR, email.
+* Nested, and hierarchical log output for descriptive stack-frame level
+  understanding where an exception was thrown.
+* Ability to change the time format of your logs by supplying an arbitrary
+  Proc to return the time in the format of your choice.
+* Ability to customize the layout of the logs, by turning off hierarchical
+  view, or changing Strings used to indicate events.
+* Email log files automatically, based on number of errors or warnings.
+* Ability to invoke arbitrary sequence of events if exception is thrown,
+  including invocation of Proc objects.
 
 h2. Installing
 
@@ -12,10 +24,49 @@ h2. Installing
 
 h2. The basics
 
+<p>A simple example demonstrating multiple embedded levels, and how the
+inside block simply logs the error so that the second puts statement still executes.
+
+<pre syntax="ruby">
+# create Watcher instance with defaults
+$watcher = Watcher.create
+
+$watcher.verbose("doing something dangerous") do
+  puts "be careful..."
+  $watcher.debug("going to do something very dangerous", :failure => :warn) do
+    raise "ouch!"
+  end
+  puts "that wasn't so bad... just a log entry!"
+end
+</pre>
 
 h2. Demonstration of usage
 
+<p>A more complicated example of sending a reference to a Proc to attempt
+to recover from an condition.</p>
+
+<pre syntax="ruby">
+# create Watcher instance with slightly modified defaults
+$watcher = Watcher.create(:output => log_file)
 
+$watcher.debug("starting #{File.basename($0)}") do
+  # Look for CONFIG_PATH.  If not found, log warning then re-write it
+  params = {:tries => 2, :failure => :error,
+            :proc => lambda { |e| write_config(config_path) }}
+  msg = "ensuring existance of config file [#{config_path}]"
+  $watcher.verbose(msg, params) do
+    raise "file not found" unless File.file?(File.expand_path(config_path))
+  end
+
+  # invoke utility, which uses $watcher as well
+  fsc = FileSystemChecker.new(:config_path => config_path)
+  fsc.check_file_systems(:all => all_flag, :remount => remount_flag)
+end
+
+if email_flag and ($watcher.errors > 0 or $watcher.warnings > 0)
+  $watcher.send_email(email, 'FAIL: Required filesystems are not mounted')
+end
+</pre>
 
 h2. Forum
 
@@ -68,16 +119,17 @@ TODO - add "github_username: username" to ~/.rubyforge/user-config.yml and newge
 
 h3. Build and test instructions
 
+<p><i>Sorry, no unit tests yet...</i></p>
+
 <pre>cd watcher
-rake test
 rake install_gem</pre>
 
 
 h2. License
 
-This code is free to use under the terms of the MIT license. 
+This code is free to use under the terms of the Simplified BSD license. 
 
 h2. Contact
 
-Comments are welcome. Send an email to "FIXME full name":mailto:karrick@karrick.net via the "forum":http://groups.google.com/group/watcher
+Comments are welcome. Send an email to "Karrick McDermott":mailto:karrick@karrick.org via the "forum":http://groups.google.com/group/watcher