Class: Logging::Appender

### Home Classes Methods

### In Files

- lib/logging/appender.rb

### Parent

Object

### Methods

- ::new
- #<<
- #add_filters
- #allow
- #append
- #close
- #closed?
- #encoding
- #encoding=
- #filters=
- #flush
- #inspect
- #layout=
- #level=
- #off?
- #reopen

### Files

- History.txt

### Class/Module Index

Quicksearch

- Logging
- Logging::Appender
- Logging::Appenders
- Logging::Appenders::Buffering
- Logging::Appenders::File
- Logging::Appenders::IO
- Logging::Appenders::RollingFile
- Logging::Appenders::RollingFile::Roller
- Logging::Appenders::Stderr
- Logging::Appenders::Stdout
- Logging::Appenders::StringIo
- Logging::Appenders::Syslog
- Logging::ColorScheme
- Logging::Filter
- Logging::Filters
- Logging::Filters::Level
- Logging::Layout
- Logging::Layouts
- Logging::Layouts::Basic
- Logging::Layouts::Parseable
- Logging::Layouts::Pattern
- Logging::Logger
- Logging::MappedDiagnosticContext
- Logging::NestedDiagnosticContext
- Logging::Proxy
- Logging::RailsCompat
- Logging::Repository
- Logging::Repository::Singleton
- Logging::RootLogger
- RSpec
- RSpec::Core
- RSpec::Core::Configuration
- RSpec::LoggingHelper
- RSpec::LoggingHelper
- Spec
- Spec::Runner
- Spec::Runner::Configuration
- Object
- Object::LoggingHelper
- File
- FileUtils
- Module
- ReentrantMutex
- String

No matching classes.

# Logging::Appender

The `Appender` class is provides methods for appending log events to a logging destination. The log events are formatted into strings using a Layout.

All other Appenders inherit from this class which provides stub methods. Each subclass should provide a `write` method that will write log messages to the logging destination.

A private `sync` method is provided for use by subclasses. It is used to synchronize writes to the logging destination, and can be used by subclasses to synchronize the closing or flushing of the logging destination.

### Attributes

filters[R]
layout[R]
level[R]
name[R]

### Public Class Methods

new( name ) click to toggle source
new( name, :layout => layout )

Creates a new appender using the given name. If no Layout is specified, then a Basic layout will be used. Any logging header supplied by the layout will be written to the logging destination when the Appender is created.

Options:

    :layout   => the layout to use when formatting log events
    :level    => the level at which to log
    :encoding => encoding to use when writing messages (defaults to UTF-8)
    :filters  => filters to apply to events before processing

    # File lib/logging/appender.rb, line 37
    def initialize( name, opts = {} )
      ::Logging.init unless ::Logging.initialized?

      @name    = name.to_s
      @closed  = false
      @filters = []
      @mutex   = ReentrantMutex.new

      self.layout   = opts.fetch(:layout, ::Logging::Layouts::Basic.new)
      self.level    = opts.fetch(:level, nil)
      self.encoding = opts.fetch(:encoding, self.encoding)
      self.filters  = opts.fetch(:filters, nil)

      if opts.fetch(:header, true)
        header = @layout.header

        unless header.nil? || header.empty?
          begin
            write(header)
          rescue StandardError => err
            ::Logging.log_internal_error(err)
          end
        end
      end

      ::Logging::Appenders[@name] = self
    end

### Public Instance Methods

appender << string click to toggle source

Write the given string to the logging destination "as is" -- no layout formatting will be performed.

    # File lib/logging/appender.rb, line 96
    def <<( str )
      if @closed
        raise RuntimeError,
              "appender '<#{self.class.name}: #{@name}>' is closed"
      end

      unless off?
        begin
          write(str)
        rescue StandardError => err
          ::Logging.log_internal_error(err)
        end
      end
      self
    end

add_filters( *args ) click to toggle source

Sets the filter(s) to be used by this appender. The filters will be applied in the order that they are added to the appender.

Examples

    add_filters(Logging::Filters::Level.new(:warn, :error))

Returns this appender instance.

    # File lib/logging/appender.rb, line 185
    def add_filters( *args )
      args.flatten.each do |filter|
        next if filter.nil?
        unless filter.kind_of?(::Logging::Filter)
          raise TypeError, "#{filter.inspect} is not a kind of 'Logging::Filter'"
        end
        @filters << filter
      end
      self
    end

allow( event ) click to toggle source

Check to see if the event should be processed by the appender. An event will be rejected if the event level is lower than the configured level for the appender. Or it will be rejected if one of the filters rejects the event.

event - The LogEvent to check

Returns the event if it is allowed; returns `nil` if it is not allowed.

    # File lib/logging/appender.rb, line 299
    def allow( event )
      return nil if @level > event.level
      @filters.each do |filter|
        break unless event = filter.allow(event)
      end
      event
    end

append( event ) click to toggle source

Write the given event to the logging destination. The log event will be processed through the Layout associated with the Appender.

    # File lib/logging/appender.rb, line 71
    def append( event )
      if @closed
        raise RuntimeError,
              "appender '<#{self.class.name}: #{@name}>' is closed"
      end

      # only append if the event level is less than or equal to the configured
      # appender level and the filter does not disallow it
      if event = allow(event)
        begin
          write(event)
        rescue StandardError => err
          ::Logging.log_internal_error(err)
        end
      end

      self
    end

close( footer = true ) click to toggle source

Close the appender and writes the layout footer to the logging destination if the footer flag is set to `true`. Log events will no longer be written to the logging destination after the appender is closed.

    # File lib/logging/appender.rb, line 204
    def close( footer = true )
      return self if @closed
      ::Logging::Appenders.remove(@name)
      @closed = true

      flush

      if footer
        footer = @layout.footer
        unless footer.nil? || footer.empty?
          begin
            write(footer)
          rescue StandardError => err
            ::Logging.log_internal_error(err)
          end
        end
      end
      self
    end

closed? click to toggle source

Returns `true` if the appender has been closed; returns `false` otherwise. When an appender is closed, no more log events can be written to the logging destination.

    # File lib/logging/appender.rb, line 231
    def closed?
      @closed
    end

encoding() click to toggle source

Returns the current Encoding for the appender or nil if an encoding has not been set.

    # File lib/logging/appender.rb, line 270
    def encoding
      return @encoding if defined? @encoding
      @encoding = Object.const_defined?(:Encoding) ? Encoding.default_external : nil
    end

encoding=( value ) click to toggle source

Set the appender encoding to the given value. The value can either be an Encoding instance or a String or Symbol referring to a valid encoding.

This method only applies to Ruby 1.9 or later. The encoding will always be nil for older Rubies.

value - The encoding as a String, Symbol, or Encoding instance.

Raises ArgumentError if the value is not a valid encoding.

    # File lib/logging/appender.rb, line 284
    def encoding=( value )
      if value.nil?
        @encoding = nil
      else
        @encoding = Object.const_defined?(:Encoding) ? Encoding.find(value.to_s) : nil
      end
    end

filters=( args ) click to toggle source

Sets the filter(s) to be used by this appender. This method will clear the current filter set and add those passed to this setter method.

Examples

    appender.filters = Logging::Filters::Level.new(:warn, :error)

    # File lib/logging/appender.rb, line 173
    def filters=( args )
      @filters.clear
      add_filters(*args)
    end

flush click to toggle source

Call `flush` to force an appender to write out any buffered log events. Similar to IO#flush, so use in a similar fashion.

    # File lib/logging/appender.rb, line 250
    def flush
      self
    end

inspect => string click to toggle source

Returns a string representation of the appender.

    # File lib/logging/appender.rb, line 259
    def inspect
      "<%s:0x%x name=\"%s\">" % [
          self.class.name.sub(/^Logging::/, ''),
          self.object_id,
          self.name
      ]
    end

layout=( layout ) click to toggle source

call-seq

    appender.layout = Logging::Layouts::Basic.new

Sets the layout to be used by this appender.

    # File lib/logging/appender.rb, line 159
    def layout=( layout )
      unless layout.kind_of? ::Logging::Layout
        raise TypeError,
              "#{layout.inspect} is not a kind of 'Logging::Layout'"
      end
      @layout = layout
    end

level = :all click to toggle source

Set the level for this appender; log events below this level will be ignored by this appender. The level can be either a `String`, a `Symbol`, or a `Fixnum`. An `ArgumentError` is raised if this is not the case.

There are two special levels -- "all" and "off". The former will enable recording of all log events. The latter will disable the recording of all events.

Example:

    appender.level = :debug
    appender.level = "INFO"
    appender.level = 4
    appender.level = 'off'
    appender.level = :all

These produce an `ArgumentError`

    appender.level = Object
    appender.level = -1
    appender.level = 1_000_000_000_000

    # File lib/logging/appender.rb, line 138
    def level=( level )
      lvl = case level
            when String, Symbol; ::Logging::level_num(level)
            when Fixnum; level
            when nil; 0
            else
              raise ArgumentError,
                    "level must be a String, Symbol, or Integer"
            end
      if lvl.nil? or lvl < 0 or lvl > ::Logging::LEVELS.length
        raise ArgumentError, "unknown level was given '#{level}'"
      end

      @level = lvl
    end

off?() click to toggle source

Returns `true` if the appender has been turned off. This is useful for appenders that write data to a remote location (such as syslog or email), and that write encounters too many errors. The appender can turn itself off to and log an error via the `Logging` logger.

Set the appender's level to a valid value to turn it back on.

    # File lib/logging/appender.rb, line 313
    def off?
      @level >= ::Logging::LEVELS.length
    end

reopen() click to toggle source

Reopen the connection to the underlying logging destination. If the connection is currently closed then it will be opened. If the connection is currently open then it will be closed and immediately opened.

    # File lib/logging/appender.rb, line 239
    def reopen
      @closed = false
      self
    end

[Validate]

Generated with the Darkfish Rdoc Generator 2.