loggability 0.0.1

data/History.rdoc

@@ -0,0 +1,4 @@
+== v0.0.1 [2012-04-06] Michael Granger <ged@FaerieMUD.org>
+
+First release.
+

data/Manifest.txt

@@ -0,0 +1,19 @@
+ChangeLog
+History.rdoc
+Manifest.txt
+README.rdoc
+Rakefile
+bin/loggability
+lib/loggability.rb
+lib/loggability/constants.rb
+lib/loggability/formatter.rb
+lib/loggability/formatter/color.rb
+lib/loggability/formatter/default.rb
+lib/loggability/formatter/html.rb
+lib/loggability/logger.rb
+spec/lib/helpers.rb
+spec/loggability/formatter/color_spec.rb
+spec/loggability/formatter/html_spec.rb
+spec/loggability/formatter_spec.rb
+spec/loggability/logger_spec.rb
+spec/loggability_spec.rb

data/README.rdoc

@@ -0,0 +1,200 @@
+= loggability
+
+home   :: http://deveiate.org/projects/loggability
+code   :: http://bitbucket.org/ged/loggability
+docs   :: http://deveiate.org/code/loggability
+github :: http://github.com/ged/loggability
+
+
+== Description
+
+A composable logging system built on the standard Logger library.
+
+You can add Loggability to large libraries and systems, then hook everything
+up later when you know where you want logs to be written, at what level of
+severity, and in which format.
+
+An example:
+
+    # Load a bunch of libraries
+	require 'strelka'
+	require 'inversion'
+	require 'treequel'
+	require 'loggability'
+
+    # Now tell everything that's using Loggability to log to an HTML
+	# log file at INFO level
+	Loggability.write_to( '/usr/local/www/htdocs/log.html' )
+	Loggability.format_as( :html )
+	Loggability.level = :info
+
+
+== Prerequisites
+
+* Ruby 1.9.3 or better, Rubinius 2.0 or better
+
+It will probably work under any other interpreter in which Logger works, but
+it's only tested in the above.
+
+
+== Installation
+
+    $ gem install loggability
+
+
+== Usage
+
+Loggability is split up into two parts: {log hosts}[rdoc-ref:Loggability::LogHost]
+and {log clients}[rdoc-ref:Loggability::LogClient]. A <b>log
+host</b> is an object that contains a Logger instance that will be used to
+log stuff. A <b>log client</b> is an object that will write logging messages to a
+particular <b>log host</b>'s Logger.
+
+Both parts require that you extend the object with Loggability.
+
+=== Setting Up A 'Log Host'
+
+To install a Logger into an object, you use the +log_as+ declaration with a
+Symbol that will be used as the key for the object's Logger:
+
+    module MyProject
+        extend Loggability
+        log_as :my_project
+    end
+
+After declaring itself as a log host, it will have an associated Loggability::Logger
+object that's a wrapper around a Logger instance:
+
+    MyProject.logger
+    # => #<Loggability::Logger:0x4e0c :my_project ...>
+
+Since it's still a Logger object, you can call all the regular Logger methods:
+
+    MyProject.logger.level = Logger::WARN
+
+    MyProject.logger.debug("Created logger")
+    MyProject.logger.info("Program started")
+    MyProject.logger.warn("Nothing to do!")
+
+    begin
+        File.each_line(path) do |line|
+            unless line =~ /^(\w+) = (.*)$/
+                MyProject.logger.error("Line in wrong format: #{line}")
+            end
+        end
+    rescue => err
+        MyProject.logger.fatal("Caught exception; exiting")
+        MyProject.logger.fatal(err)
+    end
+
+or use a few new convenience methods for changing the logging level:
+
+    MyProject.logger.level = :debug
+
+...installing a different formatter:
+
+    MyProject.logger.format_as( :html )
+
+...changing the output destination:
+
+    log_messages = []
+    MyProject.logger.output_to( log_messages )
+
+...{and more}[rdoc-ref:Loggability::Logger].
+
+
+=== Setting Up A 'Log Client'
+
+To add an object that will log to your log host, after you <tt>extend Loggability</tt>,
+use the +log_to+ declaration to hook up the object (and instances of the object if
+you use +log_to+ in a Class) to the log host you specify:
+
+    class MyProject::Server
+        extend Loggability
+        log_to :my_project
+
+        def initialize( config={} )
+            self.log.debug "Creating a server with config: %p" % [ config ]
+            #...
+        end
+    end
+
+You can fetch any object's Logger through the Loggability object:
+
+    Loggability[ MyProject ]
+    # => #<Loggability::Logger:0x007f88ca3bf510 ...>
+
+    Loggability[ MyProject::Server ]
+    # => #<Loggability::Logger:0x007f88ca3bf510 ...>
+
+Calling the object's <tt>#log</tt> method will return a Proxy for its host's Logger object that will include the object's name in the log messages 'progname'.
+
+You can also use the <b>log host</b> itself as the argument to +log_to+:
+
+    class MyProject::Client
+        extend Loggability
+        log_to MyProject
+    end
+
+
+=== Aggregate Logging
+
+If you have several <b>log hosts</b>, and you want to affect them all simultaneously,
+you can do that using the aggregate functions of Loggability. They're the same as the
+methods on Loggability::Logger:
+
+    # Set all logs to log at INFO level
+    Loggability.level = :info
+    
+    # Write HTML logs
+    Loggability.format_with( :html )
+    
+    # Log everything to the same logfile
+    Loggability.output_to( "/tmp/my_project_log.html" )
+
+
+== Contributing
+
+You can check out the current development source with
+Mercurial[http://bitbucket.org/ged/loggability], or if you prefer Git, via
+{its Github mirror}[https://github.com/ged/loggability].
+
+After checking out the source, run:
+
+    $ rake newb
+
+This task will install any missing dependencies, run the tests/specs,
+and generate the API documentation.
+
+
+== License
+
+Copyright (c) 2012, Michael Granger
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice,
+  this list of conditions and the following disclaimer.
+
+* 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.
+
+* Neither the name of the author/s, nor the names of the project's
+  contributors may be used to endorse or promote products derived from this
+  software without specific prior written permission.
+
+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 OWNER 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,49 @@
+#!/usr/bin/env rake
+
+require 'rake/clean'
+
+begin
+	require 'hoe'
+rescue LoadError
+	abort "This Rakefile requires 'hoe' (gem install hoe)"
+end
+
+Hoe.plugin :mercurial
+Hoe.plugin :signing
+Hoe.plugin :deveiate
+
+Hoe.plugins.delete :rubyforge
+
+hoespec = Hoe.spec 'loggability' do
+	self.readme_file = 'README.rdoc'
+	self.history_file = 'History.rdoc'
+	self.extra_rdoc_files = FileList[ '*.rdoc' ]
+
+	self.developer 'Michael Granger', 'ged@FaerieMUD.org'
+
+	self.dependency 'pluginfactory', '~> 1.0'
+
+	self.dependency 'hoe-deveiate',  '~> 0.1', :developer
+	self.dependency 'simplecov',     '~> 0.6', :developer
+
+	self.spec_extras[:licenses] = ["Ruby"]
+	self.spec_extras[:rdoc_options] = ['-f', 'fivefish', '-t', 'Loggability Toolkit']
+	self.require_ruby_version( '>=1.9.3' )
+	self.hg_sign_tags = true if self.respond_to?( :hg_sign_tags= )
+	self.check_history_on_release = true if self.respond_to?( :check_history_on_release= )
+
+	self.rdoc_locations << "deveiate:/usr/local/www/public/code/#{remote_rdoc_dir}"
+end
+
+ENV['VERSION'] ||= hoespec.spec.version.to_s
+
+# Ensure the specs pass before checking in
+task 'hg:precheckin' => [ :check_history, :check_manifest, :spec ]
+
+
+desc "Build a coverage report"
+task :coverage do
+	ENV["COVERAGE"] = 'yes'
+	Rake::Task[:spec].invoke
+end
+

data/bin/loggability

@@ -0,0 +1,3 @@
+#!/usr/bin/env ruby
+
+abort "you need to write me"

data/lib/loggability.rb

@@ -0,0 +1,223 @@
+# -*- ruby -*-
+# vim: set nosta noet ts=4 sw=4:
+# encoding: utf-8
+
+require 'logger'
+require 'date'
+
+
+# A mixin that provides a top-level logging subsystem based on Logger.
+module Loggability
+
+	# Package version constant
+	VERSION = '0.0.1'
+
+	# VCS revision
+	REVISION = %q$Revision: 7b3fcf97718a $
+
+	# The key for the global logger (Loggability's own logger)
+	GLOBAL_KEY = :__global__
+
+	# The methods that are delegated across all loggers
+	AGGREGATE_METHODS = [ :level=, :output_to, :write_to, :format_with, :format_as, :formatter= ]
+
+
+	require 'loggability/constants'
+	include Loggability::Constants
+
+	require 'loggability/logger'
+
+
+	##
+	# The Hash of modules that have a Logger, keyed by the name they register with
+	class << self; attr_reader :log_hosts; end
+	@log_hosts = {}
+
+
+	### Return the library's version string
+	def self::version_string( include_buildnum=false )
+		vstring = "%s %s" % [ self.name, VERSION ]
+		vstring << " (build %s)" % [ REVISION[/: ([[:xdigit:]]+)/, 1] || '0' ] if include_buildnum
+		return vstring
+	end
+
+
+	### Register the specified +host+ as a log host. It should already have been extended
+	### with LogHostMethods.
+	def self::register_loghost( host )
+		key = host.log_host_key
+		if self.log_hosts.key?( key )
+			self.logger.warn "Replacing existing log host for %p (%p) with %p" %
+				[ key, self.log_hosts[key], host ]
+		end
+
+		self.logger.debug "Registering %p log host: %p" % [ key, host ] if self.logger
+		self.log_hosts[ key ] = host
+	end
+
+
+	### Return the Loggability::Logger for the loghost associated with +logclient+.
+	def self::[]( logclient )
+		key = logclient.log_host_key if logclient.respond_to?( :log_host_key )
+		key ||= GLOBAL_KEY
+
+		return self.log_hosts[ key ].logger
+	end
+
+
+	### Clear out all log hosts except for ones which start with '_'. This is intended
+	### to be used for testing.
+	def self::clear_loghosts
+		self.log_hosts.delete_if {|key,_| !key.to_s.start_with?('_') }
+	end
+
+
+	#
+	# :section: Aggregate Methods
+	#
+
+	### Call the method with the given +methodname+ across the loggers of all loghosts with
+	### the given +arg+ and/or +block+.
+	def self::aggregate( methodname, arg, &block )
+		Loggability.log_hosts.values.each do |loghost|
+			loghost.logger.send( methodname, arg, &block )
+		end
+	end
+
+
+	##
+	# :method: level=
+	# :call-seq:
+	#   level = newlevel
+	#
+	# Aggregate method: set the log level on all loggers to +newlevel+. See
+	# Loggability::Logger#level= for more info.
+
+	##
+	# :method: output_to
+	# :call-seq:
+	#   output_to( destination )
+	#   write_to( destination )
+	#
+	# Aggregate method: set all loggers to log to +destination+. See Loggability::Logger#output_to
+	# for more info.
+
+	##
+	# :method: format_with
+	# :call-seq:
+	#   format_with( formatter )
+	#   format_as( formatter )
+	#   formatter = formatter
+	#
+	# Aggregate method: set all loggers to log with the given +formatter+. See
+	# Loggability::Logger#format_with for more info.
+	AGGREGATE_METHODS.each do |meth|
+		block = self.method( :aggregate ).to_proc.curry[ meth ]
+		Loggability.singleton_class.send( :define_method, meth, &block )
+	end
+
+
+	# Extension for 'log hosts'. A <b>log host</b> is an object that hosts a Loggability::Logger
+	# object, and is typically the top of some kind of hierarchy, like a namespace
+	# module for a project:
+	#
+	#     module MyProject
+	#
+	#     end
+	#
+	# This module isn't mean to be used directly -- it's installed via the Loggability#log_as
+	# declaration, which also does some other initialization that you'll likely want.
+	#
+	#
+	module LogHost
+
+		# The logger that will be used when the logging subsystem is reset
+		attr_accessor :default_logger
+
+		# The logger that's currently in effect
+		attr_accessor :logger
+		alias_method :log, :logger
+		alias_method :log=, :logger=
+
+		# The key associated with the logger for this host
+		attr_accessor :log_host_key
+
+	end # module LogHost
+
+
+	#
+	# :section: LogHost API
+	#
+
+	### Register as a log host associated with the given +key+, add the methods from
+	### LogHost, and install a Loggability::Logger.
+	def log_as( key )
+		self.extend( Loggability::LogHost )
+		self.log_host_key = key.to_sym
+		self.logger = self.default_logger = Loggability::Logger.new
+		Loggability.register_loghost( self )
+	end
+
+	# Install a global logger in Loggability itself
+	extend( Loggability::LogHost )
+	self.log_host_key = GLOBAL_KEY
+	self.logger = self.default_logger = Loggability::Logger.new
+	Loggability.register_loghost( self )
+
+
+
+	# Methods to install for objects which call +log_to+.
+	module LogClient
+
+		##
+		# The key of the log host this client targets
+		attr_accessor :log_host_key
+
+		### Return the Loggability::Logger object associated with the log host the
+		### client is logging to.
+		### :TODO: Use delegation for efficiency.
+		def log
+			@__log ||= Loggability[ self ].proxy_for( self )
+		end
+
+		# Stuff that gets added to instances of Classes that are log hosts.
+		module InstanceMethods
+
+			### Fetch the key of the log host the instance of this client targets
+			def log_host_key
+				return self.class.log_host_key
+			end
+
+
+			### Delegate to the class's logger.
+			def log
+				@__log ||= Loggability[ self.class ].proxy_for( self )
+			end
+
+		end # module InstanceMethods
+
+	end # module LogClient
+
+
+	#
+	# :section: LogClient API
+	#
+
+	### Register as a <b>log client</b> that will log to to the given +loghost+, which can be
+	### either the +key+ the host registered with, or the log host object itself. Log messages
+	### can be written to the loghost via the LogClient API, which is automatically included.
+	def log_to( loghost )
+		self.extend( Loggability::LogClient )
+		self.log_host_key = if loghost.respond_to?( :log_host_key )
+				loghost.log_host_key
+			else
+				loghost.to_sym
+			end
+
+		# For objects that also can be instantiated
+		include( Loggability::LogClient::InstanceMethods ) if self.is_a?( Class )
+	end
+
+
+end # module Strelka
+