|
|
|
Log4g Reference Manual | |
|---|---|---|---|---|
| Top | Description | ||||
Log4gPatternLayout; Log4gPatternLayoutClass; Log4gPatternParser * log4g_pattern_layout_create_pattern_parser (Log4gLayout *base,const gchar *pattern); Log4gPatternParser (*Log4gPatternLayoutCreatePatternParser) (Log4gLayout *base,const gchar *pattern);
This class formats a log event and returns the results as a string. The result of the formatting depends on the value of a conversion pattern.
Pattern layouts accept a single property:
conversion-pattern
The conversion pattern is similar in concept to the printf conversion pattern. A conversion pattern is composed of literal text and format control expressions called conversion specifiers.
Literal text can be inserted within the conversion pattern.
Conversion specifiers start with a percent sign (%) and optional format modifiers followed by a conversion character. The conversion character specifies the type of data that should be formatted, e.g. category, level, date, thread name, etc. Format modifiers control field width, padding and left/right justification.
The following is a simple example:
Let the conversion pattern be "%-5p [%t]: %m%n".
Assume the following messages have been logged to the root logger from the main thread:
log4g_debug("Message 1");
log4g_warn("Message 2");
The following output would appear in the log file:
DEBUG [main]: Message 1 WARN [main]: Message 2
There is no explicit separator between text and conversion specifiers. The pattern parser knows it has reached the end of a conversion specifier when it reads a conversion character. In the above example the conversion specifier %-5p means the priority of the log event should be left justified to a width of five characters.
Table 1. Recognized Conversion Characters
| Conversion Character | Effect |
|---|---|
| c |
Output the logger category of a log event. The category conversion specifier may be optionally followed by a precision specifier (a decimal in constant brackets). If the precision specifier is given then only the corresponding number of right most components of the category name will be printed. By default the category name is printed in full. For example, the logger category name "a.b.c" the pattern %c{2} will output "b.c". |
| d |
Ouput the date of the logging event. The date conversion specifier may be followed by a date format specifier enclosed in braces. For example: %d{%H:%M:%S} or %d{%l:%M:%S %P - %B %e, %G}. The date format specifier accepts the same syntax as the strftime(3) standard library function.
|
| F |
Output the filename where the event was logged. |
| l |
Output the full location information where the event was logged. |
| L |
Output the line number where the event was logged. |
| m |
Output the application supplied message associated with a log event. |
| M |
Output the function (method) name where the event was logged. |
| n |
Output the platform independent line separater character(s). Use this conversion character in place of non-portable line separator strings such as "\n" or "\r\n". |
| p |
Output the level (also known as the priority) of a log event. |
| r |
Output the number of milliseconds elapsed from the initialization of the Log4g environment until the create of the log event. |
| t |
Output the name of the thread that generated the log event.
|
| x |
Output the NDC (nested diagnostic context) associated with the thread that generated the log event.
|
| X |
Output the MDC (mapped data context) associated with the thread that generated the log event. The X conversion character must be followed by the key for the map, placed between braces. For example, %X{count} where count is the key. The value in the MDC of the corresponding key will be output. See: log4g/mdc.h
|
| % |
The sequence % outputs a single percent sign. |
The default behavior is to output the information as-is. If the aid of format modifiers it is possible to change the minimum field width, the maximum field with and justification.
The optional format modifier is placed between the percent sign and the conversion character.
The left justification flag is a minus (-) character. Justification may be followed by a minimum field width modifier (an integer), indicating the minimum number of characters to output. The default is to pad on the left, however you may specify right-padding with the left justification flag. The space character is used to perform padding. If the data item is larger than the minimum field width the field is expanded to accomodate the data (the value is never truncated).
The truncation behavior can be changed using the maximum field width modifier, designated by a period followed with an integer. If the data item is larger than the maximum field width the extra characters are removed from the beginning of the data item.
Table 2. Format Modifier Examples
| Format Modifier | Left Justify | Minimum Width | Maximum Width | Comment |
|---|---|---|---|---|
| %20c | No | 20 | None | Left pad with spaces if the logger name is less than 20 characers long. |
| %-20c | Yes | 20 | None | Right pad with spaces if the logger name is less than 20 characters long. |
| %.30c | N/A | None | 30 | Truncate from the beginning if the logger name is longer than 30 characters. |
| %20.30c | No | 20 | 30 | Left pad with spaces if the category name is shorter than 20 characters. If the category name is longer than 30 characters then truncate from the beginning. |
| %-20.30c | Yes | 20 | 30 | Right pad with spaces if the category name is shorter than 20 characters. If the category 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 Log4gTTCCLayout.
%-6r [%15.15t] %-5p %30.30c %x - %m%n
Similar to the TTCC layout except:
The relative time is right-padded if less than six digits
The thread name is right padded if less than fifteen characters
The thread name is truncated if longer than fifteen characters
The log level is right-padded if less than 5 characters
The logger name is left padded if shorter than thirty characters
The logger name is truncated if longer than thirty characters
typedef struct {
} Log4gPatternLayout;
The Log4gPatternLayout structure does not have any public members.
typedef struct {
Log4gPatternLayoutCreatePatternParser create_pattern_parser;
} Log4gPatternLayoutClass;
Log4gPatternLayoutCreatePatternParser |
Create a new pattern parser object. |
Log4gPatternParser * log4g_pattern_layout_create_pattern_parser (Log4gLayout *base,const gchar *pattern);
Call the create_pattern_parser function from the Log4gPatternLayoutClass
of base.
|
A conversion pattern object. |
|
The conversion pattern to use. |
Returns : |
A new pattern parser object. |
Since 0.1
Log4gPatternParser (*Log4gPatternLayoutCreatePatternParser) (Log4gLayout *base,const gchar *pattern);
Sub-classes may override this function to return a subclass of Log4gPatternParser which recognize custom conversion characters.
See: pattern-parser.h
|
A conversion pattern object. |
|
The conversion pattern to use. |
Returns : |
A new pattern parser object. |
Since 0.1