loggability 0.0.1

data/lib/loggability/constants.rb

@@ -0,0 +1,26 @@
+#!/usr/bin/env ruby
+# vim: set nosta noet ts=4 sw=4:
+# encoding: utf-8
+
+require 'logger'
+require 'loggability' unless defined?( Loggability )
+
+
+module Loggability::Constants
+
+	# Log level names and their Logger constant equivalents
+	LOG_LEVELS = {
+		debug: Logger::DEBUG,
+		info:  Logger::INFO,
+		warn:  Logger::WARN,
+		error: Logger::ERROR,
+		fatal: Logger::FATAL,
+	}.freeze
+
+	# Logger levels -> names
+	LOG_LEVEL_NAMES = LOG_LEVELS.invert.freeze
+
+
+end # module Loggability::Constants
+
+

data/lib/loggability/formatter.rb

@@ -0,0 +1,89 @@
+#!/usr/bin/env ruby
+# vim: set nosta noet ts=4 sw=4:
+# encoding: utf-8
+
+require 'pluginfactory'
+
+require 'loggability' unless defined?( Loggability )
+
+
+### An abstract base class for Loggability log formatters.
+class Loggability::Formatter
+	extend PluginFactory
+
+	# The default sprintf pattern
+	DEFAULT_DATETIME_FORMAT = '%Y-%m-%d %H:%M:%S'
+
+
+	### PluginFactory API -- return the Array of paths prefixes to use when searching
+	### formatter plugins.
+	def self::derivative_dirs
+		return ['loggability/formatter']
+	end
+
+
+	### Initialize a new Loggability::Formatter. The specified +logformat+ should
+	### be a sprintf pattern with positional placeholders:
+	###
+	### [<tt>%1$s</tt>] Time (pre-formatted using strftime with the +datetime_format+)
+	### [<tt>%2$d</tt>] Time microseconds
+	### [<tt>%3$d</tt>] PID
+	### [<tt>%4$s</tt>] Thread ID
+	### [<tt>%5$s</tt>] Severity
+	### [<tt>%6$s</tt>] Object/Program Name
+	### [<tt>%7$s</tt>] Message
+	###
+	def initialize( logformat, datetime_format=DEFAULT_DATETIME_FORMAT )
+		@format          = logformat.dup
+		@datetime_format = datetime_format.dup
+	end
+
+
+	######
+	public
+	######
+
+	# Main log sprintf format
+	attr_accessor :format
+
+	# Strftime format for log messages
+	attr_accessor :datetime_format
+
+
+	### Create a log message from the given +severity+, +time+, +progname+, and +message+
+	### and return it.
+	def call( severity, time, progname, message )
+		timeformat = self.datetime_format
+		args = [
+			time.strftime( timeformat ),                                  # %1$s
+			time.usec,                                                    # %2$d
+			Process.pid,                                                  # %3$d
+			Thread.current == Thread.main ? 'main' : Thread.object_id,    # %4$s
+			severity,                                                     # %5$s
+			progname,                                                     # %6$s
+			self.msg2str(message, severity)                               # %7$s
+		]
+
+		return self.format % args
+	end
+
+
+	#########
+	protected
+	#########
+
+	### Format the specified +msg+ for output to the log.
+	def msg2str( msg, severity )
+		case msg
+		when String
+			return msg
+		when Exception
+			bt = severity == 'DEBUG' ? msg.backtrace.join("\n") : msg.backtrace.first
+			return "%p: %s from %s" % [ msg.class, msg.message, bt ]
+		else
+			return msg.inspect
+		end
+	end
+
+end # class Loggability::Formatter
+

data/lib/loggability/formatter/color.rb

@@ -0,0 +1,52 @@
+#!/usr/bin/env ruby
+# vim: set nosta noet ts=4 sw=4:
+# encoding: utf-8
+
+require 'loggability' unless defined?( Loggability )
+require 'loggability/formatter' unless defined?( Loggability::Formatter )
+require 'loggability/formatter/default'
+
+
+# The default log formatter class.
+class Loggability::Formatter::Color < Loggability::Formatter::Default
+
+	# ANSI reset
+	RESET = "\e[0m"
+
+	# ANSI color escapes keyed by severity
+	LEVEL_CODES = {
+		debug: "\e[1;30m", # bold black
+		info:  "\e[37m",   # white
+		warn:  "\e[1;33m", # bold yellow
+		error: "\e[31m",   # red
+		fatal: "\e[1;31m", # bold red
+	}
+
+	# Pattern for matching color terminals
+	COLOR_TERMINAL_NAMES = /(?:vt10[03]|xterm(?:-color)?|linux|screen)/i
+
+
+	### Create a new formatter.
+	def initialize( * )
+		super
+		@color_enabled = COLOR_TERMINAL_NAMES.match( ENV['TERM'] ) ? true : false
+	end
+
+
+	######
+	public
+	######
+
+	### Format the specified +msg+ for output to the log.
+	def msg2str( msg, severity )
+		msg = super
+		if @color_enabled
+			color = severity.downcase.to_sym
+			msg = [ LEVEL_CODES[color], msg, RESET ].join( '' )
+		end
+
+		return msg
+	end
+
+end # class Loggability::Formatter::Color
+

data/lib/loggability/formatter/default.rb

@@ -0,0 +1,21 @@
+#!/usr/bin/env ruby
+# vim: set nosta noet ts=4 sw=4:
+# encoding: utf-8
+
+require 'loggability' unless defined?( Loggability )
+require 'loggability/formatter' unless defined?( Loggability::Formatter )
+
+
+# The default log formatter class.
+class Loggability::Formatter::Default < Loggability::Formatter
+
+	# The format to output unless debugging is turned on
+	FORMAT = "[%1$s.%2$06d %3$d/%4$s] %5$5s {%6$s} -- %7$s\n"
+
+	### Specify the format for the default formatter.
+	def initialize( format=FORMAT )
+		super
+	end
+
+end # class Loggability::Formatter::Default
+

data/lib/loggability/formatter/html.rb

@@ -0,0 +1,76 @@
+#!/usr/bin/env ruby
+# vim: set nosta noet ts=4 sw=4:
+# encoding: utf-8
+
+require 'loggability' unless defined?( Loggability )
+require 'loggability/formatter' unless defined?( Loggability::Formatter )
+
+
+# The default log formatter class.
+class Loggability::Formatter::HTML < Loggability::Formatter
+
+	# The default HTML fragment that'll be used as the template for each log message.
+	HTML_LOG_FORMAT = %q{
+	<div class="log-message %5$s-log-message">
+		<span class="log-time">%1$s.%2$06d</span>
+		[
+			<span class="log-pid">%3$d</span>
+			/
+			<span class="log-tid">%4$s</span>
+		]
+		<span class="log-level">%5$s</span>
+		:
+		<span class="log-name">%6$s</span>
+		<span class="log-message-text">%7$s</span>
+	</div>
+	}.gsub( /[\t\n]/, ' ' )
+
+	# The format for dumping exceptions
+	HTML_EXCEPTION_FORMAT = %Q{
+		<span class="log-exc">%1$p</span>:
+		<span class="log-exc-message">%2$s</span>
+		  from <span class="log-exc-firstframe">%3$s</span>
+	}.gsub( /[\t\n]/, ' ' )
+
+
+	### Override the logging formats with ones that generate HTML fragments
+	def initialize( format=HTML_LOG_FORMAT ) # :notnew:
+		super
+	end
+
+
+	#########
+	protected
+	#########
+
+	### Format the specified +object+ for output to the log.
+	def msg2str( object, severity )
+		case object
+		when String
+			return escape_html( object )
+		when Exception
+			return HTML_EXCEPTION_FORMAT % [
+				object.class,
+				escape_html(object.message),
+				escape_html(object.backtrace.first)
+			]
+		else
+			return escape_html(object.inspect)
+		end
+	end
+
+
+	#######
+	private
+	#######
+
+	### Escape any HTML special characters in +string+.
+	def escape_html( string )
+		return string.
+			gsub( '&', '&amp;' ).
+			gsub( '<', '&lt;'  ).
+			gsub( '>', '&gt;'  )
+	end
+
+end # class Loggability::Formatter::Default
+

data/lib/loggability/logger.rb

@@ -0,0 +1,244 @@
+#!/usr/bin/env ruby
+# vim: set nosta noet ts=4 sw=4:
+# encoding: utf-8
+
+require 'logger'
+require 'loggability' unless defined?( Loggability )
+require 'loggability/constants'
+require 'loggability/formatter'
+
+
+# A subclass of Logger that provides additional API for configuring outputters,
+# formatters, etc.
+class Loggability::Logger < ::Logger
+	include Loggability::Constants,
+	        Logger::Severity
+
+	# Default log 'device'
+	DEFAULT_DEVICE = $stderr
+
+	# Default 'shift age'
+	DEFAULT_SHIFT_AGE = 0
+
+	# Default 'shift size'
+	DEFAULT_SHIFT_SIZE = 1048576
+
+
+	# A log device that appends to the object it's constructed with instead of writing
+	# to a file descriptor or a file.
+	class AppendingLogDevice
+
+		### Create a new AppendingLogDevice that will append content to +array+.
+		def initialize( target )
+			@target = target
+		end
+
+		### Append the specified +message+ to the target.
+		def write( message )
+			@target << message
+		end
+
+		### No-op -- this is here just so Logger doesn't complain
+		def close; end
+
+	end # class AppendingLogDevice
+
+
+	# Proxy for the Logger that injects the name of the object it wraps as the 'progname'
+	# of each log message.
+	class ObjectNameProxy
+
+		### Create a proxy for the given +logger+ that will inject the name of the
+		### specified +object+ into the 'progname' of each log message.
+		def initialize( logger, object )
+			@logger = logger
+			@progname = make_progname( object )
+		end
+
+		######
+		public
+		######
+
+		# The Loggability::Logger this proxy is for.
+		attr_reader :logger
+
+		# The progname of the object the proxy is for.
+		attr_reader :progname
+
+
+		### Delegate debug messages
+		def debug( msg=nil, &block )
+			@logger.add( Logger::DEBUG, msg, @progname, &block )
+		end
+
+		### Delegate info messages
+		def info( msg=nil, &block )
+			@logger.add( Logger::INFO, msg, @progname, &block )
+		end
+
+		### Delegate warn messages
+		def warn( msg=nil, &block )
+			@logger.add( Logger::WARN, msg, @progname, &block )
+		end
+
+		### Delegate error messages
+		def error( msg=nil, &block )
+			@logger.add( Logger::ERROR, msg, @progname, &block )
+		end
+
+		### Delegate fatal messages
+		def fatal( msg=nil, &block )
+			@logger.add( Logger::FATAL, msg, @progname, &block )
+		end
+
+
+		### Return a human-readable string representation of the object, suitable for debugging.
+		def inspect
+			return "#<%p:%#016x for %s>" % [ self.class, self.object_id * 2, @progname ]
+		end
+
+
+		#######
+		private
+		#######
+
+		### Make a progname for the specified object.
+		def make_progname( object )
+			case object
+			when Class
+				object.inspect
+			else
+				"%p:%#x" % [ object.class, object.object_id * 2 ]
+			end
+		end
+
+
+	end # class ObjectNameProxy
+
+
+	### Create a new Logger wrapper that will output to the specified +logdev+.
+	def initialize( logdev=DEFAULT_DEVICE, *args )
+		super
+		self.level = ($DEBUG ? DEBUG : WARN)
+		@default_formatter = Loggability::Formatter.create( :default )
+	end
+
+
+	######
+	public
+	######
+
+	#
+	# :section: Severity Level
+	#
+
+	### Return the logger's level as a Symbol.
+	def level
+		numeric_level = super
+		return LOG_LEVEL_NAMES[ numeric_level ]
+	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.)
+	def level=( newlevel )
+		newlevel = LOG_LEVELS[ newlevel.to_sym ] if newlevel.respond_to?( :to_sym )
+		super( newlevel )
+	end
+
+
+	#
+	# :section: Output Device
+	#
+
+	# The raw log device
+	attr_accessor :logdev
+
+
+	### Change the log device to log to +target+ instead of what it was before. Any additional
+	### +args+ are passed to the LogDevice's constructor. In addition to Logger's support for
+	### 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 )
+			opts = { shift_age: args.shift, shift_size: args.shift }
+			self.logdev = Logger::LogDevice.new( target, opts )
+		elsif target.respond_to?( :<< )
+			self.logdev = AppendingLogDevice.new( target )
+		else
+			raise ArgumentError, "don't know how to output to %p (a %p)" % [ target, target.class ]
+		end
+	end
+	alias_method :write_to, :output_to
+
+
+	#
+	# :section: Output Formatting API
+	#
+
+	### Return the current formatter used to format log messages.
+	def formatter
+		return ( @formatter || @default_formatter )
+	end
+
+
+	### Format a log message using the current formatter and return it.
+	def format_message( severity, datetime, progname, msg )
+		self.formatter.call(severity, datetime, progname, msg)
+	end
+
+
+	### Set a new +formatter+ for the logger. If +formatter+ is +nil+ or +:default+, this causes the
+	### logger to fall back to its default formatter. If it's a Symbol other than +:default+, it looks
+	### for a similarly-named formatter under loggability/formatter/ and uses that. If +formatter+ is
+	### an object that responds to #call (e.g., a Proc or a Method object), that object is used directly.
+	###
+	### Procs and methods should have the method signature: (severity, datetime, progname, msg).
+	###
+	###     # Load and use the HTML formatter
+	###     MyProject.logger.format_with( :html )
+	###
+	###     # Call self.format_logmsg(...) to format messages
+	###     MyProject.logger.format_with( self.method(:format_logmsg) )
+	###
+	###     # Reset to the default
+	###     MyProject.logger.format_with( :default )
+	###
+	def format_with( formatter=nil, &block ) # :yield: severity, datetime, progname, msg
+		formatter ||= block
+
+		if formatter.nil? || formatter == :default
+			@formatter = nil
+
+		elsif formatter.respond_to?( :call )
+			@formatter = formatter
+
+		elsif formatter.respond_to?( :to_sym )
+			@formatter = Loggability::Formatter.create( formatter )
+
+		else
+			raise ArgumentError, "don't know what to do with a %p formatter (%p)" %
+				[ formatter.class, formatter ]
+		end
+	end
+	alias_method :format_as, :format_with
+	alias_method :formatter=, :format_with
+
+
+	#
+	# :section: Progname Proxy
+	# Rather than require that the caller provide the 'progname' part of the log message
+	# on every call, you can grab a Proxy object for a particular object and Logger combination
+	# that will include the object's name with every log message.
+	#
+
+
+	### Create a logging proxy for +object+ that will include its name as the 'progname' of
+	### each message.
+	def proxy_for( object )
+		return ObjectNameProxy.new( self, object )
+	end
+
+
+end # class Loggability::Logger
+