// -*- C++ -*- // Module: Log4CPLUS // File: Layout.h // Created: 6/2001 // Author: Tad E. Smith // // // Copyright 2001-2010 Tad E. Smith // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. /** @file */ #ifndef LOG4CPLUS_LAYOUT_HEADER_ #define LOG4CPLUS_LAYOUT_HEADER_ #include #if defined (LOG4CPLUS_HAVE_PRAGMA_ONCE) #pragma once #endif #include #include #include #include namespace log4cplus { // Forward Declarations namespace pattern { class PatternConverter; } namespace helpers { class Properties; class Time; } namespace spi { class InternalLoggingEvent; } /** * This class is used to layout strings sent to an {@link * log4cplus::Appender}. */ class LOG4CPLUS_EXPORT Layout { public: Layout(); Layout(const helpers::Properties& properties); virtual ~Layout() = 0; virtual void formatAndAppend(log4cplus::tostream& output, const log4cplus::spi::InternalLoggingEvent& event) = 0; protected: LogLevelManager& llmCache; private: // Disable copy Layout(const Layout&); Layout& operator=(Layout const &); }; /** * SimpleLayout consists of the LogLevel of the log statement, * followed by " - " and then the log message itself. For example, * * 
     *         DEBUG - Hello world
     *
* * {@link PatternLayout} offers a much more powerful alternative. */ class LOG4CPLUS_EXPORT SimpleLayout : public Layout { public: SimpleLayout(); SimpleLayout(const log4cplus::helpers::Properties& properties); virtual ~SimpleLayout(); virtual void formatAndAppend(log4cplus::tostream& output, const log4cplus::spi::InternalLoggingEvent& event); private: // Disallow copying of instances of this class SimpleLayout(const SimpleLayout&); SimpleLayout& operator=(const SimpleLayout&); }; /** * TTCC layout format consists of time, thread, Logger and nested * diagnostic context information, hence the name. * * The time format depends on the DateFormat used. Use the * Use_gmtime to specify whether messages should be logged using * localtime or gmtime. * * Here is an example TTCCLayout output: * * 
     * 176 [main] INFO  org.apache.log4j.examples.Sort - Populating an array of 2 elements in reverse order.
     * 225 [main] INFO  org.apache.log4j.examples.SortAlgo - Entered the sort method.
     * 262 [main] DEBUG org.apache.log4j.examples.SortAlgo.OUTER i=1 - Outer loop.
     * 276 [main] DEBUG org.apache.log4j.examples.SortAlgo.SWAP i=1 j=0 - Swapping intArray[0] = 1 and intArray[1] = 0
     * 290 [main] DEBUG org.apache.log4j.examples.SortAlgo.OUTER i=0 - Outer loop.
     * 304 [main] INFO  org.apache.log4j.examples.SortAlgo.DUMP - Dump of interger array:
     * 317 [main] INFO  org.apache.log4j.examples.SortAlgo.DUMP - Element [0] = 0
     * 331 [main] INFO  org.apache.log4j.examples.SortAlgo.DUMP - Element [1] = 1
     * 343 [main] INFO  org.apache.log4j.examples.Sort - The next log statement should be an error message.
     * 346 [main] ERROR org.apache.log4j.examples.SortAlgo.DUMP - Tried to dump an uninitialized array.
     * 467 [main] INFO  org.apache.log4j.examples.Sort - Exiting main method.
     *
* * The first field is the number of milliseconds elapsed since the * start of the program. The second field is the thread outputting the * log statement. The third field is the LogLevel, the fourth field is * the logger to which the statement belongs. * * The fifth field (just before the '-') is the nested diagnostic * context. Note the nested diagnostic context may be empty as in the * first two statements. The text after the '-' is the message of the * statement. * * PatternLayout offers a much more flexible alternative. */ class LOG4CPLUS_EXPORT TTCCLayout : public Layout { public: // Ctor and dtor TTCCLayout(bool use_gmtime = false); TTCCLayout(const log4cplus::helpers::Properties& properties); virtual ~TTCCLayout(); virtual void formatAndAppend(log4cplus::tostream& output, const log4cplus::spi::InternalLoggingEvent& event); protected: log4cplus::tstring dateFormat; bool use_gmtime; private: // Disallow copying of instances of this class TTCCLayout(const TTCCLayout&); TTCCLayout& operator=(const TTCCLayout&); }; LOG4CPLUS_EXPORT helpers::Time const & getTTCCLayoutTimeBase (); /** * A flexible layout configurable with pattern string. * * The goal of this class is to format a InternalLoggingEvent 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 printf function in C. 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, LogLevel, date, thread name. 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 "%-5p [%t]: %m%n" and assume * that the log4cplus environment was set to use a PatternLayout. Then the * statements * 
     * Logger root = Logger.getRoot();
     * LOG4CPLUS_DEBUG(root, "Message 1");
     * LOG4CPLUS_WARN(root, "Message 2");
     *
* would yield the output * 
     * DEBUG [main]: Message 1
     * WARN  [main]: 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 * "%-5p" means the LogLevel of the logging event should be left * justified to a width of five characters. * * The recognized conversion characters are * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
Conversion CharacterEffect
bUsed to output file name component of path name. * E.g. main.cxx from path ../../main.cxx.
cUsed to output the logger of the logging event. The * logger conversion specifier can be optionally followed by * precision specifier, that is a decimal constant in * brackets. * * If a precision specifier is given, then only the corresponding * number of right most components of the logger name will be * printed. By default the logger name is printed in full. * * For example, for the logger name "a.b.c" the pattern * %c{2} will output "b.c". * *
dUsed to output the date of the logging event in UTC. * * The date conversion specifier may be followed by a date format * specifier enclosed between braces. For example, %%d{%%H:%%M:%%s} * or %%d{%%d %%b %%Y %%H:%%M:%%s}. If no date format * specifier is given then %%d{%%d %%m %%Y %%H:%%M:%%s} * is assumed. * * The Following format options are possible: *
    *
  • %%a -- Abbreviated weekday name
    • *
  • %%A -- Full weekday name
    • *
  • %%b -- Abbreviated month name
    • *
  • %%B -- Full month name
    • *
  • %%c -- Standard date and time string
    • *
  • %%d -- Day of month as a decimal(1-31)
    • *
  • %%H -- Hour(0-23)
    • *
  • %%I -- Hour(1-12)
    • *
  • %%j -- Day of year as a decimal(1-366)
    • *
  • %%m -- Month as decimal(1-12)
    • *
  • %%M -- Minute as decimal(0-59)
    • *
  • %%p -- Locale's equivalent of AM or PM
    • *
  • %%q -- milliseconds as decimal(0-999) -- Log4CPLUS specific *
  • %%Q -- fractional milliseconds as decimal(0-999.999) -- Log4CPLUS specific *
  • %%S -- Second as decimal(0-59)
    • *
  • %%U -- Week of year, Sunday being first day(0-53)
    • *
  • %%w -- Weekday as a decimal(0-6, Sunday being 0)
    • *
  • %%W -- Week of year, Monday being first day(0-53)
    • *
  • %%x -- Standard date string
    • *
  • %%X -- Standard time string
    • *
  • %%y -- Year in decimal without century(0-99)
    • *
  • %%Y -- Year including century as decimal
    • *
  • %%Z -- Time zone name
    • *
  • %% -- The percent sign
    • *
* * Lookup the documentation for the strftime() function * found in the <ctime> header for more information. *
DUsed to output the date of the logging event in local time. * * All of the above information applies. *
FUsed to output the file name where the logging request was * issued. * * NOTE Unlike log4j, there is no performance penalty for * calling this method.
hUsed to output the hostname of this system (as returned * by gethostname(2)). * * NOTE The hostname is only retrieved once at * initialization. * *
HUsed to output the fully-qualified domain name of this * system (as returned by gethostbyname(2) for the hostname * returned by gethostname(2)). * * NOTE The hostname is only retrieved once at * initialization. * *
lEquivalent to using "%F:%L" * * NOTE: Unlike log4j, there is no performance penalty for * calling this method. * *
LUsed to output the line number from where the logging request * was issued. * * NOTE: Unlike log4j, there is no performance penalty for * calling this method. * *
mUsed to output the application supplied message associated with * the logging event.
MUsed to output function name using * __FUNCTION__ or similar macro. * * NOTE The __FUNCTION__ macro is not * standard but it is common extension provided by all compilers * (as of 2010). In case it is missing or in case this feature * is disabled using the * LOG4CPLUS_DISABLE_FUNCTION_MACRO macro, %M * expands to an empty string.
nOutputs the platform dependent line separator character or * characters. *
pUsed to output the LogLevel of the logging event.
rUsed to output miliseconds since program start * of the logging event.
tUsed to output the name of the thread that generated the * logging event.
TUsed to output alternative name of the thread that generated the * logging event.
iUsed to output the process ID of the process that generated the * logging event.
xUsed to output the NDC (nested diagnostic context) associated * with the thread that generated the logging event. *
"%%"The sequence "%%" outputs a single percent sign. *
* * 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 * beginning of the data item and not from the end. For * example, it the maximum field width is eight and the data item is * ten characters long, then the first two characters of the data item * are dropped. This behavior deviates from the printf function in C * where truncation is done from the end. * * Below are various format modifier examples for the logger * conversion specifier. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
Format modifierleft justifyminimum widthmaximum widthcomment
%20cfalse20noneLeft pad with spaces if the logger name is less than 20 * characters long. *
%-20c true 20 none Right pad with * spaces if the logger name is less than 20 characters long. *
%.30cNAnone30Truncate from the beginning if the logger name is longer than 30 * characters. *
%20.30cfalse2030Left pad with spaces if the logger name is shorter than 20 * characters. However, if logger name is longer than 30 characters, * then truncate from the beginning. *
%-20.30ctrue2030Right pad with spaces if the logger name is shorter than 20 * characters. However, if logger name is longer than 30 characters, * then truncate from the beginning. *
* * Below are some examples of conversion patterns. * *
* *
"%r [%t] %-5p %c %x - %m%n" *
This is essentially the TTCC layout. * *
"%-6r [%15.15t] %-5p %30.30c %x - %m%n" * *
Similar to the TTCC layout except that the relative time is * right padded if less than 6 digits, thread name is right padded if * less than 15 characters and truncated if longer and the logger * name is left padded if shorter than 30 characters and truncated if * longer. * *
* * The above text is largely inspired from Peter A. Darnell and * Philip E. Margolis' highly recommended book "C -- a Software * Engineering Approach", ISBN 0-387-97389-3. */ class LOG4CPLUS_EXPORT PatternLayout : public Layout { public: // Ctors and dtor PatternLayout(const log4cplus::tstring& pattern); PatternLayout(const log4cplus::helpers::Properties& properties); virtual ~PatternLayout(); virtual void formatAndAppend(log4cplus::tostream& output, const log4cplus::spi::InternalLoggingEvent& event); protected: void init(const log4cplus::tstring& pattern, unsigned ndcMaxDepth = 0); // Data log4cplus::tstring pattern; std::vector parsedPattern; private: // Disallow copying of instances of this class PatternLayout(const PatternLayout&); PatternLayout& operator=(const PatternLayout&); }; } // end namespace log4cplus #endif // LOG4CPLUS_LAYOUT_HEADER_