watcher 1.1.0

data/History.txt

@@ -0,0 +1,21 @@
+== 1.1.0 2008-07-22
+
+* 1 major enhancement:
+  * Initial public release (via RubyForge)
+
+* 4 minor enhancements:
+  * Consolidated the verification stage and the action perform stage to a
+    single pair of methods, as opposed to two methods to verify, and two
+    similar methods to perform.  This was to prevent changes from one section
+    from causing an hard-to-find bug in the other section.
+  * Added ability to track number of warnings and errors.  Warnings are
+    Exceptions that are not re-raised.  Errors are Exceptions that are
+    re-raised.
+  * Added ability to send log output to a specified email address.
+  * Cleaned up RDoc formatting, and improved readability.
+
+== 1.0.0 2008-07-09
+
+* 1 major enhancement:
+  * Initial private release
+  * Major functionality features working.  No critical bugs, just TODO items.

data/License.txt

@@ -0,0 +1,27 @@
+(Simplified BSD License)
+
+Copyright (c) 2008 Karrick McDermott
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+
+1. Redistributions of source code must retain the above copyright
+   notice, this list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright
+   notice, this list of conditions and the following disclaimer in the
+   documentation and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
+FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
+COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
+INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
+ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.

data/Manifest.txt

@@ -0,0 +1,25 @@
+History.txt
+License.txt
+Manifest.txt
+PostInstall.txt
+README.txt
+Rakefile
+TODO
+config/hoe.rb
+config/requirements.rb
+lib/watcher.rb
+lib/watcher/version.rb
+script/console
+script/destroy
+script/generate
+script/txt2html
+setup.rb
+tasks/deployment.rake
+tasks/environment.rake
+tasks/website.rake
+test/watcher-example.rb
+website/index.html
+website/index.txt
+website/javascripts/rounded_corners_lite.inc.js
+website/stylesheets/screen.css
+website/template.html.erb

data/PostInstall.txt

@@ -0,0 +1,7 @@
+
+For more information on watcher, see http://watcher.rubyforge.org
+
+NOTE: Change this information in PostInstall.txt 
+You can also delete it if you don't want it.
+
+

data/README.txt

@@ -0,0 +1,105 @@
+= watcher
+
+* http://watcher.rubyforge.org
+
+== DESCRIPTION:
+
+Watcher provides advanced integrated exception handling and logging
+functionality to your Ruby programs.
+
+This is useful both in the development stage of a program, and while
+in production use, for instance on a server, as Watcher can be
+directed to email generated log files to a specified user in the event
+of errors or warnings.
+
+By combining exception handling and detailed logging facilities,
+Watcher greatly reduces code-bloat and potential program flow logic
+flaws, as Watcher eliminates the necessity to write a tremendous
+amount of boiler-plate code in the form of "begin, rescue, ensure,
+end" blocks.
+
+Watcher also provides a very flexible exception handling capability,
+allowing a programmer to easily direct Watcher what actions to take in
+the event of an exception.  These failure actions may include any
+combination of logging the failure, invoking a Proc object, retrying
+the code, and allowing the exception to propagate up the call-stack by
+re-raising the exception.  Exceptions that are re-raised in a child
+call-stack are caught by the parent call-stack, and are then dealt
+with by the programmer determined rules of the parent call-stack.  All
+this happens while Watcher ensures the logs are properly maintained
+for the various actions taken.
+
+== FEATURES/PROBLEMS:
+
+* 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.
+
+== SYNOPSIS:
+
+# create Watcher instance with slightly modified defaults
+$watcher=Watcher.create(:output=>log_file, :verbosity=>:warn)
+
+$watcher.info("starting #{File.basename($0)}") do
+  # Look for CONFIG_PATH.  If not found, log warning then re-write it
+  fail_actions=[:log, lambda {write_config(config_path)}]
+  $watcher.info("searching for [#{config_path}].", fail_actions) do
+    if not File.exists?(config_path)
+      raise RuntimeError.new("WARNING: Missing [#{config_path}].  Creating a default config file.  (You should probably verify it...)")
+    end
+  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)
+  if email_flag and $watcher.errors > 0
+    $watcher.send_email(email,'FAIL: Required filesystems are not mounted')
+  end
+end
+
+== REQUIREMENTS:
+
+* Passion for coding.
+
+== INSTALL:
+
+$ sudo gem install
+
+== LICENSE:
+
+(The Simplified BSD License)
+
+Copyright (c) 2008 Karrick McDermott
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+
+1. Redistributions of source code must retain the above copyright
+   notice, this list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright
+   notice, this list of conditions and the following disclaimer in the
+   documentation and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
+FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
+COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
+INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
+ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.

data/Rakefile

@@ -0,0 +1,4 @@
+require 'config/requirements'
+require 'config/hoe' # setup Hoe + all gem configuration
+
+Dir['tasks/**/*.rake'].each { |rake| load rake }

data/TODO

@@ -0,0 +1,23 @@
+CRITICAL
+
+* none
+
+MINOR
+
+* Write unit tests.  This goes without saying.
+
+* Write some non-trivial example code.  I have developed and ported several non-trivial utilities from Logger to Watcher, and am extremely happy with the results.  Now let me get something ready to package with this gem.
+
+* Consolidation/refactoring of warnings and errors. (Principle of least surprise should be applied.)  The :log fail action would now imply a warning, while a :raise implies an error. (This is not immediately intuitive.)
+
+* Trap signals to clean up properly.
+
+* Log rotation.
+
+LOW
+
+* Figure out how to get ri documentation working.
+
+* Provide a Watcher.destroy method which closes the Watcher instance and changes the @@watcher class attribute back to nil.
+
+* Validate data when attributes accessors invoked, for instance @current_indent.

data/config/hoe.rb

@@ -0,0 +1,75 @@
+require 'watcher/version'
+
+AUTHOR = 'Karrick McDermott'  # can also be an array of Authors
+EMAIL = "karrick@karrick.net"
+DESCRIPTION = "Watcher provides advanced integrated exception handling and logging functionality to your Ruby programs."
+GEM_NAME = 'watcher' # what ppl will type to install your gem
+RUBYFORGE_PROJECT = 'watcher' # The unix name for your project
+HOMEPATH = "http://#{RUBYFORGE_PROJECT}.rubyforge.org"
+DOWNLOAD_PATH = "http://rubyforge.org/projects/#{RUBYFORGE_PROJECT}"
+EXTRA_DEPENDENCIES = [
+#  ['activesupport', '>= 1.3.1']
+]    # An array of rubygem dependencies [name, version]
+
+@config_file = "~/.rubyforge/user-config.yml"
+@config = nil
+RUBYFORGE_USERNAME = "unknown" # Don't change this.  Modify your "~/.rubyforge/user-config.yml" file.
+def rubyforge_username
+  unless @config
+    begin
+      @config = YAML.load(File.read(File.expand_path(@config_file)))
+    rescue
+      puts <<-EOS
+ERROR: No rubyforge config file found: #{@config_file}
+Run 'rubyforge setup' to prepare your env for access to Rubyforge
+ - See http://newgem.rubyforge.org/rubyforge.html for more details
+      EOS
+      exit
+    end
+  end
+  RUBYFORGE_USERNAME.replace @config["username"]
+end
+
+
+REV = nil
+# UNCOMMENT IF REQUIRED:
+# REV = YAML.load(`svn info`)['Revision']
+VERS = Watcher::VERSION::STRING + (REV ? ".#{REV}" : "")
+RDOC_OPTS = ['--quiet', '--title', 'watcher documentation',
+    "--opname", "index.html",
+    "--line-numbers",
+    "--main", "README",
+    "--inline-source"]
+
+class Hoe
+  def extra_deps
+    @extra_deps.reject! { |x| Array(x).first == 'hoe' }
+    @extra_deps
+  end
+end
+
+# Generate all the Rake tasks
+# Run 'rake -T' to see list of generated tasks (from gem root directory)
+$hoe = Hoe.new(GEM_NAME, VERS) do |p|
+  p.developer(AUTHOR, EMAIL)
+  p.description = DESCRIPTION
+  p.summary = DESCRIPTION
+  p.url = HOMEPATH
+  p.remote_rdoc_dir = '' # Release to root (Watcher is my only project)
+  p.rsync_args << ' --exclude=statsvn/'
+  p.rubyforge_name = RUBYFORGE_PROJECT if RUBYFORGE_PROJECT
+  p.test_globs = ["test/**/test_*.rb"]
+  p.clean_globs |= ['**/.*.sw?', '*.gem', '.config', '**/.DS_Store']  #An array of file patterns to delete on clean.
+
+  # == Optional
+  p.changes = p.paragraphs_of("History.txt", 0..1).join("\n\n")
+  #p.extra_deps = EXTRA_DEPENDENCIES
+
+  #p.spec_extras = {}    # A hash of extra values to set in the gemspec.
+end
+
+CHANGES = $hoe.paragraphs_of('History.txt', 0..1).join("\\n\\n")
+PATH    = (RUBYFORGE_PROJECT == GEM_NAME) ? RUBYFORGE_PROJECT : "#{RUBYFORGE_PROJECT}/#{GEM_NAME}"
+$hoe.remote_rdoc_dir = File.join(PATH.gsub(/^#{RUBYFORGE_PROJECT}\/?/,''), 'rdoc')
+$hoe.rsync_args = '-av --delete --ignore-errors'
+$hoe.spec.post_install_message = File.open(File.dirname(__FILE__) + "/../PostInstall.txt").read rescue ""

data/config/requirements.rb

@@ -0,0 +1,15 @@
+require 'fileutils'
+include FileUtils
+
+require 'rubygems'
+%w[rake hoe newgem rubigen].each do |req_gem|
+  begin
+    require req_gem
+  rescue LoadError
+    puts "This Rakefile requires the '#{req_gem}' RubyGem."
+    puts "Installation: gem install #{req_gem} -y"
+    exit
+  end
+end
+
+$:.unshift(File.join(File.dirname(__FILE__), %w[.. lib]))

data/lib/watcher/version.rb

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