// -*- C++ -*- // Module: Log4CPLUS // File: Layout.h // Created: 6/2001 // Author: Tad E. Smith // // // Copyright 2001-2017 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 #include #include namespace log4cplus { // Forward Declarations namespace pattern { class PatternConverter; } namespace helpers { class Properties; } 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. There are also * ThreadPrinting, CategoryPrefixing and * ContextPrinting properties to turn on and off thread name, * logger name and NDC context printing respectively. * * Here is an example TTCCLayout output: * * ~~~~ * 1 [0x60004dca0] WARN test.TestThread <> - Thread-3 TestThread.run()- Starting... * 1 [0x60004dca0] TRACE SlowObject - ENTER: SlowObject::doSomething() * 2 [0x60004b030] INFO SlowObject - Actually doing something...1, 2, 3, testing...DONE * 2 [0x60004b130] INFO SlowObject - Actually doing something... * 2 [0x60004b030] TRACE SlowObject - EXIT: SlowObject::doSomething() * 2 [0x60004b030] TRACE SlowObject - ENTER: SlowObject::doSomething() * 3 [0x60004b130] INFO SlowObject - Actually doing something...1, 2, 3, testing...DONE * 3 [0x60004cad0] INFO SlowObject - Actually doing something... * ~~~~ * * 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 value is the same as that of the `t` formatter * for PatternLayout.) * * 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: TTCCLayout(bool use_gmtime = false, bool thread_printing = true, bool category_prefixes = true, bool context_printing = true); TTCCLayout(const log4cplus::helpers::Properties& properties); virtual ~TTCCLayout(); virtual void formatAndAppend(log4cplus::tostream& output, const log4cplus::spi::InternalLoggingEvent& event); bool getThreadPrinting() const; void setThreadPrinting(bool); bool getCategoryPrefixing() const; void setCategoryPrefixing(bool); bool getContextPrinting() const; void setContextPrinting(bool); protected: log4cplus::tstring dateFormat; bool use_gmtime = false; bool thread_printing = true; bool category_prefixing = true; bool context_printing = true; 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 * * ~~~~{.c} * 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 Character	Effect
b	Used to output file name component of path name. * E.g. `main.cxx` from path `../../main.cxx`.
c	Used 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". * *
d	Used 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. *
D	Used to output the date of the logging event in local time. * * All of the above information applies. *
E	Used to output the value of a given environment variable. The * name of is supplied as an argument in brackets. If the variable does * exist then empty string will be used. * * For example, the pattern %E{HOME} will output the contents * of the HOME environment variable. *
F	Used to output the file name where the logging request was * issued. * * NOTE Unlike log4j, there is no performance penalty for * calling this method.
h	Used to output the hostname of this system (as returned * by gethostname(2)). * * NOTE The hostname is only retrieved once at * initialization. * *
H	Used 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. * *
l	Equivalent to using "%F:%L" * * NOTE: Unlike log4j, there is no performance penalty for * calling this method. * *
L	Used to output the line number from where the logging request * was issued. * * NOTE: Unlike log4j, there is no performance penalty for * calling this method. * *
m	Used to output the application supplied message associated with * the logging event.
M	Used 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.
n	Outputs the platform dependent line separator character or * characters. *
p	Used to output the LogLevel of the logging event.
r	Used to output miliseconds since program start * of the logging event.
t	Used to output the thread ID of the thread that generated * the logging event. (This is either `pthread_t` value returned * by `pthread_self()` on POSIX platforms or thread ID returned * by `GetCurrentThreadId()` on Windows.)
T	Used to output alternative name of the thread that generated the * logging event.
i	Used to output the process ID of the process that generated the * logging event.
x	Used to output the NDC (nested diagnostic context) associated * with the thread that generated the logging event. *
X	Used to output the MDC (mapped diagnostic context) * associated with the thread that generated the logging * event. It takes optional key parameter. Without the key * paramter (%%X), it outputs the whole MDC map. With the key * (%%X{key}), it outputs just the key's value. *
"%%"	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 modifier	left justify	minimum width	maximum width	comment
%20c	false	20	none	Left 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. *
%.30c	NA	none	30	Truncate from the beginning if the logger name is longer than 30 * characters. *
%20.30c	false	20	30	Left 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.30c	true	20	30	Right 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. * *

Properties

* *

NDCMaxDepth: This property limits how many deepest NDC components will * be printed by %%x specifier.
ConversionPattern: This property specifies conversion pattern.

* */ 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_