Loggability Toolkit

Constants

DEFAULT_DEVICE: Default log ‘device’
DEFAULT_SHIFT_AGE: Default ‘shift age’
DEFAULT_SHIFT_SIZE: Default ‘shift size’

Public Class Methods

anchor

from_std_logger( logger )

Return an equivalent Loggability::Logger object for the given logger.

# File lib/loggability/logger.rb, line 129
def self::from_std_logger( logger )
        device = logger.instance_variable_get( :@logdev ) or
                raise ArgumentError, "%p doesn't appear to be a Logger (no @logdev)" % [ logger ]

        newlogger = self.new( device.dev )

        newlogger.level     = logger.level
        newlogger.formatter = logger.formatter

        return newlogger
end

anchor

new( logdev=DEFAULT_DEVICE, *args )

Create a new Logger wrapper that will output to the specified logdev.

# File lib/loggability/logger.rb, line 147
def initialize( logdev=DEFAULT_DEVICE, *args )
        super( nil )

        self.level = if $DEBUG then :debug else :warn end
        self.output_to( logdev, *args )

        @default_formatter = Loggability::Formatter.create( :default )
end

Public Instance Methods

anchor

inspect()

Return a human-readable representation of the object suitable for debugging.

# File lib/loggability/logger.rb, line 162
def inspect
        dev = if self.logdev.respond_to?( :dev )
                        self.logdev.dev.class
                else
                        self.logdev.target.class
                end

        return "#<%p:%#x severity: %s, formatter: %s, outputting to: %p>" % [
                self.class,
                self.object_id * 2,
                self.level,
                self.formatter.class.name.sub( %r.*::/, '' ).downcase,
                dev,
        ]
end

Output Device

↑ top

Attributes

logdev[RW]: The raw log device

Public Instance Methods

anchor

output_to( target, *args )

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 #<<.

# File lib/loggability/logger.rb, line 211
def output_to( target, *args )
        if 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?( :<< )
                self.logdev = AppendingLogDevice.new( target )
        else
                raise ArgumentError, "don't know how to output to %p (a %p)" % [ target, target.class ]
        end
end

Also aliased as: write_to

anchor

write_to( target, *args )

Alias for: output_to

Output Formatting API

↑ top

Public Instance Methods

anchor

format_as( formatter=nil )

Alias for: format_with

anchor

format_message( severity, datetime, progname, msg )

Format a log message using the current formatter and return it.

# File lib/loggability/logger.rb, line 235
def format_message( severity, datetime, progname, msg )
        self.formatter.call(severity, datetime, progname, msg)
end

anchor

format_with( formatter=nil ) { |severity, datetime, progname, msg| ... }

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 )

# File lib/loggability/logger.rb, line 256
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

Also aliased as: format_as , formatter=

anchor

formatter()

Return the current formatter used to format log messages.

# File lib/loggability/logger.rb, line 229
def formatter
        return ( @formatter || @default_formatter )
end

anchor

formatter=( formatter=nil )

Alias for: format_with

Progname Proxy

↑ top

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.

Public Instance Methods

anchor

proxy_for( object )

Create a logging proxy for object that will include its name as the ‘progname’ of each message.

# File lib/loggability/logger.rb, line 287
def proxy_for( object )
        return ObjectNameProxy.new( self, object )
end

Severity Level

↑ top

Public Instance Methods

anchor

level()

Return the logger’s level as a Symbol.

# File lib/loggability/logger.rb, line 184
def level
        numeric_level = super
        return LOG_LEVEL_NAMES[ numeric_level ]
end

anchor

level=( newlevel )

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.)

# File lib/loggability/logger.rb, line 192
def level=( newlevel )
        newlevel = LOG_LEVELS[ newlevel.to_sym ] if
                newlevel.respond_to?( :to_sym ) && LOG_LEVELS.key?( newlevel.to_sym )
        super( newlevel )
end