Class: Logging::Layouts::Pattern

### Home Classes Methods

### In Files

- lib/logging/layouts/pattern.rb

### Parent

Logging::Layout

### Namespace

- CLASS Logging::Layouts::Pattern::FormatMethodBuilder

### Methods

- ::new
- #date_method=
- #date_pattern=
- #pattern=

### 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::Layouts::Pattern

A flexible layout configurable via a conversion pattern string.

The goal of this class is to format a LogEvent and return the results as a String. The results depend on the conversion pattern.

The conversion pattern is closely related to the conversion pattern of the sprintf function. A conversion pattern is composed of literal text and format control expressions called conversion specifiers.

You are free to insert any literal text within the conversion pattern.

Each conversion specifier starts with a percent sign (%) and is followed by optional format modifiers and a conversion character. The conversion character specifies the type of data, e.g. logger, level, date, thread ID. The format modifiers control such things as field width, padding, left and right justification. The following is a simple example.

Let the conversion pattern be "%-5l [%c]: %mn" and assume that the logging environment was set to use a Pattern layout. Then the statements

    root = Logging.logger[:root]
    root.debug("Message 1")
    root.warn("Message 2")

would yield the output

    DEBUG [root]: Message 1
    WARN  [root]: Message 2

Note that there is no explicit separator between text and conversion specifiers. The pattern parser knows when it has reached the end of a conversion specifier when it reads a conversion character. In the example above the conversion specifier %-5l means the level of the logging event should be left justified to a width of five characters. The recognized conversion characters are

    [c]  Used to output the name of the logger that generated the log
         event. Supports an optional "precision" described further below.
    [d]  Used to output the date of the log event. The format of the
         date is specified using the :date_pattern option when the Layout
         is created. ISO8601 format is assumed if not date pattern is given.
    [F]  Used to output the file name where the logging request was issued.
    [l]  Used to output the level of the log event.
    [L]  Used to output the line number where the logging request was
         issued.
    [m]  Used to output the application supplied message associated with
         the log event.
    [M]  Used to output the method name where the logging request was
         issued.
    [h]  Used to output the hostname
    [p]  Used to output the process ID of the currently running program.
    [r]  Used to output the number of milliseconds elapsed from the
         construction of the Layout until creation of the log event.
    [t]  Used to output the object ID of the thread that generated the
         log event.
    [T]  Used to output the name of the thread that generated the log event.
         Name can be specified using Thread.current[:name] notation. Output
         empty string if name not specified. This option helps to create
         more human readable output for multi-threaded application logs.
    [X]  Used to output values from the Mapped Diagnostic Context. Requires
         a key name to lookup the value from the context. More details are
         listed below.
    [x]  Used to output values from the Nested Diagnostic Context. Supports
         an optional context separator string. More details are listed below.
    [%]  The sequence '%%' outputs a single percent sign.

The logger name directive 'c' accepts an optional precision that will only print the rightmost number of name space identifiers for the logger. By default the logger name is printed in full. For example, for the logger name "Foo::Bar::Baz" the pattern %c{2} will output "Bar::Baz".

The directives F, L, and M will only work if the Logger generating the events is configured to generate tracing information. If this is not the case these fields will always be empty.

The directives for include diagnostic context information in the log messages are X and x. For the Mapped Diagnostic Context the directive must be accompanied by the key identifying the value to insert into the log message. The X directive can appear multiple times to include multiple values from the mapped context.

    %X{Cookie}      Insert the current session cookie
    %X{X-Session}   Insert a session identifier

For the Nested Diagnostic Context you need only include the directive once. All contexts currently in the stack will be added to the log message separated by spaces. If spaces are not your style, a separator string can be given, too.

    %x      Insert all contexts separated by spaces
    %x{, }  Insert all contexts separate by a comma and a space

By default the relevant information is output as is. However, with the aid of format modifiers it is possible to change the minimum field width, the maximum field width and justification.

The optional format modifier is placed between the percent sign and the conversion character.

The first optional format modifier is the left justification flag which is just the minus (-) character. Then comes the optional minimum field width modifier. This is a decimal constant that represents the minimum number of characters to output. If the data item requires fewer characters, it is padded on either the left or the right until the minimum width is reached. The default is to pad on the left (right justify) but you can specify right padding with the left justification flag. The padding character is space. If the data item is larger than the minimum field width, the field is expanded to accommodate the data. The value is never truncated.

This behavior can be changed using the maximum field width modifier which is designated by a period followed by a decimal constant. If the data item is longer than the maximum field, then the extra characters are removed from the end of the data item.

Below are various format modifier examples for the category conversion specifier.

    %20c       Left pad with spaces if the logger name is less than 20
               characters long
    %-20c      Right pad with spaces if the logger name is less than 20
               characters long
    %.30c      Truncates the logger name if it is longer than 30 characters
    %20.30c    Left pad with spaces if the logger name is shorter than
               20 characters. However, if the logger name is longer than
               30 characters, then truncate the name.
    %-20.30c   Right pad with spaces if the logger name is shorter than
               20 characters. However, if the logger name is longer than
               30 characters, then truncate the name.

Below are examples of some conversion patterns.

    %.1l, [%d] %5l -- %c: %m\n

This is how the Logger class in the Ruby standard library formats messages. The main difference will be in the date format (the Pattern Layout uses the ISO8601 date format). Set the :date_method on the Pattern Layout to be 'to_s' and then the date formats will agree.

### Attributes

color_scheme[R]
date_method[R]
date_pattern[R]
pattern[R]

### Public Class Methods

new( opts ) click to toggle source

Creates a new Pattern layout using the following options.

    :pattern       =>  "[%d] %-5l -- %c : %m\n"
    :date_pattern  =>  "%Y-%m-%d %H:%M:%S"
    :date_method   =>  'usec' or 'to_s'
    :color_scheme  =>  :default

If used, :date_method will supersede :date_pattern.

The :color_scheme is used to apply color formatting to the log messages. Individual tokens can be colorized witch the level token [%l] receiving distinct colors based on the level of the log event. The entire generated log message can also be colorized based on the level of the log event. See the ColorScheme documentation for more details.

    # File lib/logging/layouts/pattern.rb, line 220
    def initialize( opts = {} )
      super
      @created_at = Time.now

      @date_pattern = opts.fetch(:date_pattern, nil)
      @date_method = opts.fetch(:date_method, nil)
      @date_pattern = ISO8601 if @date_pattern.nil? && @date_method.nil?

      @pattern = opts.fetch(:pattern,
          "[%d] %-#{::Logging::MAX_LEVEL_LENGTH}l -- %c : %m\n")

      cs_name = opts.fetch(:color_scheme, nil)
      @color_scheme =
          case cs_name
          when false, nil; nil
          when true; ::Logging::ColorScheme[:default]
          else ::Logging::ColorScheme[cs_name] end

      self.class.create_date_format_methods(self)
      self.class.create_format_method(self)
    end

### Public Instance Methods

date_method = 'to_s' click to toggle source
date_method = :usec

Set the date method to be used when outputting timestamps in the log messages. If a date method is configured, the output of that method will be used in leu of the date pattern.

    # File lib/logging/layouts/pattern.rb, line 273
    def date_method=( var )
      @date_method = var
      Pattern.create_date_format_methods(self)
    end

date_pattern = "%Y-%m-%d %H:%M:%S" click to toggle source

Set the date formatting pattern to be used when outputting timestamps in the log messages.

    # File lib/logging/layouts/pattern.rb, line 260
    def date_pattern=( var )
      @date_pattern = var
      Pattern.create_date_format_methods(self)
    end

pattern = "[%d] %-5l -- %c : %m\n" click to toggle source

Set the message formatting pattern to be used by the layout.

    # File lib/logging/layouts/pattern.rb, line 249
    def pattern=( var )
      @pattern = var
      Pattern.create_format_method(self)
    end

[Validate]

Generated with the Darkfish Rdoc Generator 2.