loggability 0.7.0 → 0.8.0.pre.65

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4cd7d81cde7a350d212b84b58c36a2b83d235da4
-  data.tar.gz: 5320e44d3b6264f03c5f524bd9791cdd8837342a
+  metadata.gz: 080af7dac1d884020028cd90faa021b2162279ed
+  data.tar.gz: 5030296da798cc5802812a0b1a7fcee1223161b7
 SHA512:
-  metadata.gz: 22ec6cf0983afc06ddbaa7d26db5fc1684fbfc4c8ce11f688ef64501da200d49b94607b43b9d84431985d49b9655361054b76c1ab981ce650857c51db78f69de
-  data.tar.gz: 3047401b261320512aa47dcd2d839648df9abc2a1def4b8bb3181efe957a09bd988ad0d8fe66198e125aa776fad87fb995a0190d9cd58119327c9a78df669958
+  metadata.gz: eed60ff758345f3996dd7ad517bbb4de4ea4d52ff8a4520eeaa380e01e1244df5cddf71784b76a5cf6dfc529a74a2a9c411823317b8cea28743f44020a6c4338
+  data.tar.gz: c65f9e7137429f584aad8cba285b437793df9461c977b36ab34c44e595b7306f9ef457c2db1347c080742c01add876c313476c66b58da6ede67916696b714072

data/Manifest.txt

@@ -9,11 +9,15 @@ lib/loggability/formatter.rb
 lib/loggability/formatter/color.rb
 lib/loggability/formatter/default.rb
 lib/loggability/formatter/html.rb
+lib/loggability/logclient.rb
 lib/loggability/logger.rb
+lib/loggability/loghost.rb
+lib/loggability/override.rb
 lib/loggability/spechelpers.rb
-spec/lib/helpers.rb
+spec/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/override_spec.rb
 spec/loggability_spec.rb

data/README.rdoc

@@ -206,6 +206,36 @@ methods on Loggability::Logger:
     Loggability.output_to( "/tmp/my_project_log.html" )
 
 
+=== Temporarily Overriding Logging  Behavior
+
+Sometimes you want to log one particular chunk of code at a different
+level, or to a different destination, and then restore everything back
+to the way it was afterwards.
+
+Loggability has a few ways of doing that:
+
+    # Log only fatal errors...
+    Loggability.with_level( :fatal ) do
+		    ...
+		end
+
+    # Log everything to an array for the block
+    logs = []
+		Loggability.outputting_to( logs ) do
+		    ...
+		end
+    
+		# Log using the HTML formatter
+		Loggability.formatted_with( :html ) do
+		    ...
+		end
+
+    # Or chain them together:
+    Loggability.with_level( :debug ).outputting_to( $stderr ).formatted_with( :color ) do
+		    Client.connect!
+		end
+
+
 == Contributing
 
 You can check out the current development source with

data/Rakefile

@@ -11,6 +11,7 @@ end
 Hoe.plugin :mercurial
 Hoe.plugin :signing
 Hoe.plugin :deveiate
+Hoe.plugin :bundler
 
 Hoe.plugins.delete :rubyforge
 
@@ -22,11 +23,12 @@ hoespec = Hoe.spec 'loggability' do
 	self.developer 'Michael Granger', 'ged@FaerieMUD.org'
 
 	self.dependency 'hoe-deveiate',    '~> 0.3', :developer
+	self.dependency 'hoe-bundler',     '~> 1.2', :developer
 	self.dependency 'simplecov',       '~> 0.7', :developer
 	self.dependency 'configurability', '~> 2.0', :developer
 
-	self.spec_extras[:licenses] = ["Ruby"]
-	self.require_ruby_version( '>=1.8.7' )
+	self.license "Ruby"
+	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= )
 
@@ -36,7 +38,7 @@ end
 ENV['VERSION'] ||= hoespec.spec.version.to_s
 
 # Ensure the specs pass before checking in
-task 'hg:precheckin' => [ :check_history, :check_manifest, :spec ]
+task 'hg:precheckin' => [ :check_history, 'bundler:gemfile', :check_manifest, :spec ]
 
 
 desc "Build a coverage report"

data/lib/loggability/logclient.rb

@@ -0,0 +1,48 @@
+# -*- ruby -*-
+#encoding: utf-8
+
+require 'loggability' unless defined?( Loggability )
+
+# Methods to install for objects which call +log_to+.
+module Loggability::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
+
+
+	### Inheritance hook -- set the log host key of subclasses to the same
+	### thing as the extended class.
+	def inherited( subclass )
+		super
+		Loggability.log.debug "Setting up subclass %p of %p to log to %p" %
+			[ subclass, self, self.log_host_key ]
+		subclass.log_host_key = self.log_host_key
+	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 Loggability::LogClient
+

data/lib/loggability/logger.rb

@@ -163,7 +163,7 @@ class Loggability::Logger < ::Logger
 		dev = if self.logdev.respond_to?( :dev )
 				self.logdev.dev.class
 			else
-				self.logdev.target.class
+				self.logdev
 			end
 
 		return "#<%p:%#x severity: %s, formatter: %s, outputting to: %p>" % [
@@ -185,6 +185,25 @@ class Loggability::Logger < ::Logger
 	end
 
 
+	### Return a Hash that contains its settings suitable for restoration via
+	### #restore_settings later.
+	def settings
+		return {
+			level:     self.level,
+			logdev:    self.logdev,
+			formatter: self.formatter,
+		}
+	end
+
+
+	### Restore the level, logdev, and formatter from the given +settings+.
+	def restore_settings( settings )
+		self.level = settings[:level]            if settings[ :level ]
+		self.output_to( settings[:logdev] )      if settings[ :logdev ]
+		self.format_with( settings[:formatter] ) if settings[ :formatter ]
+	end
+
+
 	#
 	# :section: Severity Level
 	#
@@ -196,8 +215,8 @@ class Loggability::Logger < ::Logger
 	end
 
 
-	### Set the logger level to +newlevel+, which can be a numeric level (e.g., Logger::DEBUG, etc.),
-	### or a symbolic level (e.g., :debug, :info, etc.)
+	### Set the logger level to +newlevel+, which can be a numeric level (e.g.,
+	### Logger::DEBUG, etc.), or a symbolic level (e.g., :debug, :info, etc.)
 	def level=( newlevel )
 		newlevel = LOG_LEVELS[ newlevel.to_sym ] if
 			newlevel.respond_to?( :to_sym ) && LOG_LEVELS.key?( newlevel.to_sym )
@@ -218,7 +237,10 @@ class Loggability::Logger < ::Logger
 	### logging to IO objects and files (given a filename in a String), this method can also
 	### set up logging to any object that responds to #<<.
 	def output_to( target, *args )
-		if target.respond_to?( :write ) || target.is_a?( String )
+		if target.is_a?( Logger::LogDevice ) ||
+		   target.is_a?( Loggability::Logger::AppendingLogDevice )
+			self.logdev = target
+		elsif target.respond_to?( :write ) || target.is_a?( String )
 			opts = { :shift_age => args.shift || 0, :shift_size => args.shift || 1048576 }
 			self.logdev = Logger::LogDevice.new( target, opts )
 		elsif target.respond_to?( :<< )

data/lib/loggability/loghost.rb

@@ -0,0 +1,40 @@
+# -*- ruby -*-
+#encoding: utf-8
+
+require 'loggability' unless defined?( Loggability )
+
+# 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 Loggability::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_reader :logger
+	alias_method :log, :logger
+
+	# The key associated with the logger for this host
+	attr_accessor :log_host_key
+
+
+	### Set the logger associated with the LogHost to +newlogger+. If +newlogger+ isn't a
+	### Loggability::Logger, it will be converted to one.
+	def logger=( newlogger )
+		@logger = Loggability::Logger( newlogger )
+	end
+	alias_method :log=, :logger=
+
+end # module Loggability::LogHost
+
+

data/lib/loggability/override.rb

@@ -0,0 +1,171 @@
+# -*- ruby -*-
+#encoding: utf-8
+
+require 'monitor'
+require 'loggability' unless defined?( Loggability )
+
+
+# A class which encapsulates the logic and data of temporarily overriding one or
+# more aspects of logging for the execution of one or more blocks of code.
+#
+# It's not meant to be used directly, but via one of the override aggregate methods
+# on Loggability:
+#
+# * Loggability.with_level
+# * Loggability.outputting_to
+# * Loggability.formatted_with
+#
+class Loggability::Override
+	include MonitorMixin
+
+
+	### Return an Override with its logging level set to +newlevel+.
+	def self::with_level( new_level )
+		return self.new( level: new_level )
+	end
+
+
+	### Return an Override with its logging output set to +new_destination+.
+	def self::outputting_to( new_destination )
+		return self.new( logdev: new_destination )
+	end
+
+
+	### Return an Override with its logging formatter set to +formatter+.
+	def self::formatted_with( new_formatter )
+		return self.new( formatter: new_formatter )
+	end
+
+
+	### Create a new Override with the specified +settings+ that will be applied
+	### during a call to #call, and then reverted when #call returns. Valid +settings+
+	### are:
+	###
+	### [:level]
+	###   Set the level of all Loggers to the value.
+	### [:logdev]
+	###   Set the destination log device of all Loggers to the value.
+	### [:formatter]
+	###   Set the formatter for all Loggers to the value (a Loggability::Formatter).
+	###
+	def initialize( settings={} )
+		super()
+
+		@settings = settings
+		@overridden_settings = {}
+	end
+
+
+	### Copy constructor -- make copies of the internal data structures
+	### when duplicated.
+	def initialize_copy( original )
+		@settings = original.settings.dup
+		@overridden_settings = {}
+	end
+
+
+	######
+	public
+	######
+
+	# The Override's settings Hash (the settings that will be applied during
+	# an overridden #call).
+	attr_reader :settings
+
+	# The original settings preserved by the Override during a call to #call,
+	# keyed by the logger they belong to.
+	attr_reader :overridden_settings
+
+
+	### Call the provided block with configured overrides applied, and then restore
+	### the previous settings before control is returned.
+	def call
+		self.apply_overrides
+		yield
+	ensure
+		self.restore_overridden_settings
+	end
+
+
+	#
+	# Mutator Methods
+	#
+
+	### Return a clone of the receiving Override with its logging level
+	### set to +newlevel+.
+	def with_level( new_level )
+		return self.clone_with( level: new_level )
+	end
+
+
+	### Return a clone of the receiving Override with its logging output
+	### set to +new_destination+.
+	def outputting_to( new_destination )
+		return self.clone_with( logdev: new_destination )
+	end
+
+
+	### Return a clone of the receiving Override with its logging formatter
+	### set to +formatter+.
+	def formatted_with( new_formatter )
+		return self.clone_with( formatter: new_formatter )
+	end
+
+
+	### Return the object as a human-readable string suitable for debugging.
+	def inspect
+		return "#<%p:%#016x formatter: %s, level: %s, output: %s>" % [
+			self.class,
+			self.object_id * 2,
+			self.settings[:formatter] || '-',
+			self.settings[:level] || '-',
+			self.settings[:logdev] ? self.settings[:logdev].class : '-',
+		]
+	end
+
+
+	#########
+	protected
+	#########
+
+	### Return a clone that has been modified with the specified +new_settings+.
+	def clone_with( new_settings )
+		newobj = self.dup
+		newobj.settings.merge!( new_settings )
+
+		return newobj
+	end
+
+
+	### Apply any configured overrides to all loggers.
+	def apply_overrides
+		self.synchronize do
+			raise LocalJumpError, "can't be called re-entrantly" unless
+				@overridden_settings.empty?
+			@overridden_settings = self.gather_current_settings
+		end
+
+		Loggability.log_hosts.each do |key, host|
+			host.logger.restore_settings( self.settings )
+		end
+	end
+
+
+	### Return a Hash of Loggers with the settings they currently have.
+	def gather_current_settings
+		return Loggability.log_hosts.values.each_with_object( {} ) do |host, hash|
+			hash[ host ] = host.logger.settings
+		end
+	end
+
+
+	### Restore the last settings saved by #apply_overrides to their corresponding
+	### loggers.
+	def restore_overridden_settings
+		@overridden_settings.each do |host, settings|
+			host.logger.restore_settings( settings )
+		end
+		@overridden_settings.clear
+	end
+
+end # class Loggability::Override

data/lib/loggability.rb

@@ -9,10 +9,10 @@ require 'date'
 module Loggability
 
 	# Package version constant
-	VERSION = '0.7.0'
+	VERSION = '0.8.0'
 
 	# VCS revision
-	REVISION = %q$Revision: 7e7b1c51eb3e $
+	REVISION = %q$Revision: 44b025b728e6 $
 
 	# The key for the global logger (Loggability's own logger)
 	GLOBAL_KEY = :__global__
@@ -53,6 +53,12 @@ module Loggability
 	@log_hosts = {}
 
 
+	# Automatically log the log host and log client mixins when they're referenced
+	autoload :LogHost, 'loggability/loghost'
+	autoload :LogClient, 'loggability/logclient'
+	autoload :Override, 'loggability/override'
+
+
 	### Return the library's version string
 	def self::version_string( include_buildnum=false )
 		vstring = "%s %s" % [ self.name, VERSION ]
@@ -145,6 +151,21 @@ module Loggability
 	end
 
 
+	### Aggregate method: set the log level on all loggers to +level+ for the duration
+	### of the +block+, restoring the original levels afterward. If no block is given, returns a
+	### Loggability::Override object that set the log level to +level+ while its +#call+
+	### method is being called.
+	def self::with_level( level, &block )
+		override = Loggability::Override.with_level( level )
+
+		if block
+			return override.call( &block )
+		else
+			return override
+		end
+	end
+
+
 	##
 	# :method: output_to
 	# :call-seq:
@@ -161,6 +182,21 @@ module Loggability
 	end
 
 
+	### Aggregate method: set all loggers to log to +destination+ for the duration of the
+	### +block+, restoring the original destination afterward. If no block is given, returns a
+	### Loggability::Override object that will log to +destination+ whenever its +#call+ method is
+	### called.
+	def self::outputting_to( newdevice, &block )
+		override = Loggability::Override.outputting_to( newdevice )
+
+		if block
+			return override.call( &block )
+		else
+			return override
+		end
+	end
+
+
 	##
 	# :method: format_with
 	# :call-seq:
@@ -179,83 +215,19 @@ module Loggability
 	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_reader :logger
-		alias_method :log, :logger
-
-		# The key associated with the logger for this host
-		attr_accessor :log_host_key
+	### Aggregate method: set all loggers to log with the given +formatter+ for the duration
+	### of the +block+, restoring the original formatters afterward. If no block is given,
+	### returns a Loggability::Override object that will override all formatters whenever its
+	### +#call+ method is called.
+	def self::formatted_with( formatter, &block )
+		override = Loggability::Override.formatted_with( formatter )
 
-
-		### Set the logger associated with the LogHost to +newlogger+. If +newlogger+ isn't a
-		### Loggability::Logger, it will be converted to one.
-		def logger=( newlogger )
-			@logger = Loggability::Logger( newlogger )
-		end
-		alias_method :log=, :logger=
-
-	end # module LogHost
-
-
-	# 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
-
-
-		### Inheritance hook -- set the log host key of subclasses to the same
-		### thing as the extended class.
-		def inherited( subclass )
-			super
-			Loggability.log.debug "Setting up subclass %p of %p to log to %p" %
-				[ subclass, self, self.log_host_key ]
-			subclass.log_host_key = self.log_host_key
+		if block
+			return override.call( &block )
+		else
+			return override
 		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
+	end
 
 
 	#

data/spec/helpers.rb

@@ -0,0 +1,116 @@
+#!/usr/bin/env ruby
+# vim: set nosta noet ts=4 sw=4:
+# encoding: utf-8
+
+BEGIN {
+	require 'pathname'
+	basedir = Pathname.new( __FILE__ ).dirname.parent
+
+	libdir = basedir + "lib"
+
+	$LOAD_PATH.unshift( libdir.to_s ) unless $LOAD_PATH.include?( libdir.to_s )
+}
+
+# SimpleCov test coverage reporting; enable this using the :coverage rake task
+if ENV['COVERAGE']
+	$stderr.puts "\n\n>>> Enabling coverage report.\n\n"
+	require 'simplecov'
+	SimpleCov.start do
+		add_filter 'spec'
+	end
+end
+
+begin
+	require 'configurability'
+rescue LoadError
+end
+
+require 'loggability'
+require 'loggability/spechelpers'
+
+
+# Helpers specific to Loggability specs
+module SpecHelpers
+
+    ### An object identity matcher for collections.
+	class AllBeMatcher
+
+		def initialize( expected )
+			@expected = expected
+		end
+
+		def matches?( collection )
+			@collection = collection
+			return collection.all? {|obj| obj.equal?(@expected) }
+		end
+
+		def description
+			"to all be %p" % [ @expected ]
+		end
+
+		def failure_message
+			"but they were: %p" % [ @collection ]
+		end
+
+	end # class AllBeMatcher
+
+
+	### An object kind matcher for collections
+	class AllBeAMatcher
+
+		def initialize( expected_class )
+			@expected_class = expected_class
+		end
+
+		def matches?( collection )
+			@collection = collection
+			return collection.all? {|obj| obj.is_a?(@expected_class) }
+		end
+
+		def description
+			"to all be a %p" % [ @expected_class ]
+		end
+
+		def failure_message
+			unmatched = @collection.find {|obj| !obj.is_a?(@expected_class) }
+			"but (at least) one was not. It was a %p (%s)" % [
+				unmatched.class,
+				unmatched.class.ancestors.map(&:inspect).join(' < '),
+			]
+		end
+
+	end # class AllBeAMatcher
+
+
+	###############
+	module_function
+	###############
+
+	### Return true if the actual value includes the specified +objects+.
+	def all_be( expected_object )
+		AllBeMatcher.new( expected_object )
+	end
+
+	### Returns +true+ if every object in the collection inherits from the +expected_class+.
+	def all_be_a( expected_class )
+		AllBeAMatcher.new( expected_class )
+	end
+
+end # module SpecHelpers
+
+
+### Mock with RSpec
+RSpec.configure do |c|
+	c.treat_symbols_as_metadata_keys_with_true_values = true
+	c.run_all_when_everything_filtered = true
+	c.filter_run :focus
+	c.order = 'random'
+	c.mock_with( :rspec ) do |mock|
+		mock.syntax = :expect
+	end
+
+	c.include( SpecHelpers )
+	c.include( Loggability::SpecHelpers )
+	c.filter_run_excluding( :configurability ) unless defined?( Configurability )
+end
+