Author: tschoening
Date: Tue Jan 28 08:17:01 2014
New Revision: 1561985
URL: http://svn.apache.org/r1561985
Log:
fixed indentation
Modified:
incubator/log4cxx/trunk/src/main/include/log4cxx/patternlayout.h
Modified: incubator/log4cxx/trunk/src/main/include/log4cxx/patternlayout.h
URL:
http://svn.apache.org/viewvc/incubator/log4cxx/trunk/src/main/include/log4cxx/patternlayout.h?rev=1561985&r1=1561984&r2=1561985&view=diff
==============================================================================
--- incubator/log4cxx/trunk/src/main/include/log4cxx/patternlayout.h (original)
+++ incubator/log4cxx/trunk/src/main/include/log4cxx/patternlayout.h Tue Jan 28
08:17:01 2014
@@ -35,302 +35,302 @@ namespace log4cxx
/**
- A flexible layout configurable with pattern string.
+ * A flexible layout configurable with pattern string.
- <p>
- The goal of this class is to #format a {@link
spi::LoggingEvent LoggingEvent} and
- return the results as a string. The results depend on
the <em>conversion pattern</em>.
- </p>
-
- <p>
- 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 <em>conversion specifiers</em>.
- </p>
-
- <p>
- <i>You are free to insert any literal text within the
conversion pattern.</i>
- </p>
-
- <p>
- Each conversion specifier starts with a percent sign
(%) and is followed by optional
- <em>format modifiers</em> and a <em>conversion
character</em>. The conversion character
- specifies the type of data, e.g. logger, level, date,
thread name. The format modifiers
- control such things as field width, padding, left and
right justification. The
- following is a simple example.
- </p>
-
- <p>
- Let the conversion pattern be <strong>"%-5p [%t]:
%m%n"</strong> and assume that the log4cxx
- environment was set to use a PatternLayout. Then the
statements
- <pre>
- LoggerPtr root = Logger::getRoot();
- root->debug("Message 1");
- root->warn("Message 2");</pre>
- would yield the output
- <pre>
- DEBUG [main]: Message 1
- WARN [main]: Message 2</pre>
- </p>
-
- <p>
- 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 <strong>%-5p</strong>
- means the level of the logging event should be left
justified to a width of five
- characters.
- </p>
-
- <p>The recognized conversion characters are:</p>
-
- <table border="1" cellpadding="8">
- <tr>
- <th align="center"><strong>Conversion
Character</strong></th>
- <th align="center"><strong>Effect</strong></th>
- </tr>
- <tr>
- <td align="center"><strong>c</strong></td>
- <td>
- Used to output the logger of the
logging event. The logger conversion specifier
- can be optionally followed by
<em>precision specifier</em>, that is a decimal
- constant in brackets.
- <p>
- 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.
- </p>
- <p>
- For example, for the logger
name "a.b.c" the pattern <strong>\%c{2}</strong> will
- output "b.c".
- </p>
- </td>
- </tr>
- <tr>
- <td align="center">
- <p><strong>C</strong></p>
- <p><strong>class</strong></p>
- </td>
- <td>
- Used to output the class of the issuer
of the logging event if the compiler
- used supports a macro to retrieve the
method of the currently compiled line and
- if the LOG4CXX_TRACE-like macros are
used to issue a logging request. In this
- case the macro LOG4CXX_* is expanded at
compile time to generate location info
- of the logging event and adds the
method name, besides file and line, if
- available. In most cases the provided
method contains the classname and can
- therefore be retrieved form the
location info as needed.
- <p>
- Currently supported compilers
are those from Microsoft, GNU-C and Borland.
- </p>
- </td>
- </tr>
- <tr>
- <td align="center"><strong>d</strong></td>
- <td>
- Used to output the date of the logging
event. The date conversion specifier may
- be followed by a set of braces
containing a date and time pattern string
- compatible with
java.text.SimpleDateFormat, <em>ABSOLUTE</em>, <em>DATE</em> or
- <em>ISO8601</em>. For example,
<strong>%d{HH:mm:ss,SSS}</strong>,
-
<strong>%d{dd MMM yyyy HH:mm:ss,SSS}</strong> or
<strong>%d{DATE}</strong>. If no
- date format specifier is given then
ISO8601 format is assumed.
- </td>
- </tr>
- <tr>
- <td align="center"><strong>F</strong></td>
- <td>
- Used to output the file name where the
logging request was issued.
- </td>
- </tr>
- <tr>
- <td align="center"><strong>l</strong></td>
- <td>
- Used to output location information of
the caller which generated the logging
- event.
- </td>
- </tr>
- <tr>
- <td align="center"><strong>L</strong></td>
- <td>
- Used to output the line number from
where the logging request was issued.
- </td>
- </tr>
- <tr>
- <td align="center"><strong>m</strong></td>
- <td>
- Used to output the application supplied
message associated with the logging
- event.
- </td>
- </tr>
- <tr>
- <td align="center">
- <strong>M</strong>
- <p><strong>method</strong></p>
- </td>
- <td>
- Used to output the method of the issuer
of the logging event if the compiler
- used supports a macro to retrieve the
method of the currently compiled line
- and if the LOG4CXX_TRACE-like macros
are used to issue a logging request. In
- this case the macro LOG4CXX_* is
expanded at compile time to generate location
- info of the logging event and adds the
method name, besides file and line, if
- available. In most cases the provided
method contains the classname which is
- ignored in every attempt to retrieve
the method from the location info.
- <p>
- Currently supported compilers
are those from Microsoft, GNU-C and Borland.
- </p>
- </td>
- </tr>
- <tr>
- <td align="center"><strong>n</strong></td>
- <td>
- Outputs the platform dependent line
separator character or characters.
- <p>
- This conversion character
offers practically the same performance as using
- non-portable line separator
strings such as "\n", or "\r\n". Thus, it is the
- preferred way of specifying a
line separator.
- </p>
- </td>
- </tr>
- <tr>
- <td align="center"><strong>p</strong></td>
- <td>Used to output the level of the logging
event.</td>
- </tr>
- <tr>
- <td align="center"><strong>r</strong></td>
- <td>
- Used to output the number of
milliseconds elapsed since the start of the
- application until the creation of the
logging event.
- </td>
- </tr>
- <tr>
- <td align="center"><strong>t</strong></td>
- <td>Used to output the name of the thread that
generated the logging event.</td>
- </tr>
- <tr>
- <td align="center"><strong>x</strong></td>
- <td>
- Used to output the NDC (nested
diagnostic context) associated with the thread that
- generated the logging event.
- </td>
- </tr>
- <tr>
- <td align="center"><strong>X</strong></td>
- <td>
- Used to output the MDC (mapped
diagnostic context) associated with the thread that
- generated the logging event. The
<strong>X</strong> conversion character <em>must</em> be
- followed by the key for the map placed
between braces, as in <strong>\%X{clientNumber}</strong>
- where <code>clientNumber</code> is the
key. The value in the MDC corresponding to
- the key will be output.
- <p>See MDC class for more details.</p>
- </td>
- </tr>
- <tr>
- <td align="center"><strong>\%</strong></td>
- <td>The sequence \%\% outputs a single percent
sign.</td>
- </tr>
- </table>
-
- <p>
- 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.
- </p>
-
- <p>
- The optional format modifier is placed between the
percent sign and the conversion
- character.
- </p>
-
- <p>
- The first optional format modifier is the <em>left
justification flag</em> which is
- just the minus (-) character. Then comes the optional
<em>minimum field width</em>
- 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.
- </p>
-
- <p>
- This behavior can be changed using the <em>maximum
field width</em> 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 <em>beginning</em> 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.
- </p>
-
- <p>Below are various format modifier examples for the logger
conversion specifier.</p>
-
- <table border="1" cellpadding="8">
- <tr>
- <th align="center"><strong>Format
modifier</strong></th>
- <th align="center"><strong>left
justify</strong></th>
- <th align="center"><strong>minimum
width</strong></th>
- <th align="center"><strong>maximum
width</strong></th>
- <th align="center"><strong>comment</strong></th>
- </tr>
- <tr>
- <td align="center">%20c</td>
- <td align="center">false</td>
- <td align="center">20</td>
- <td align="center">none</td>
- <td>Left pad with spaces if the logger name is
less than 20 characters long.</td>
- </tr>
- <tr>
- <td align="center">%-20c</td>
- <td align="center">true</td>
- <td align="center">20</td>
- <td align="center">none</td>
- <td>Right pad with spaces if the logger name is
less than 20 characters long.</td>
- </tr>
- <tr>
- <td align="center">%.30c</td>
- <td align="center">NA</td>
- <td align="center">none</td>
- <td align="center">30</td>
- <td>Truncate from the beginning if the logger
name is longer than 30 characters.</td>
- </tr>
- <tr>
- <td align="center">%20.30c</td>
- <td align="center">false</td>
- <td align="center">20</td>
- <td align="center">30</td>
- <td>
- 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.
- </td>
- </tr>
- <tr>
- <td align="center">%-20.30c</td>
- <td align="center">true</td>
- <td align="center">20</td>
- <td align="center">30</td>
- <td>
- 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.
- </td>
- </tr>
- </table>
-
- <p>Below are some examples of conversion patterns.</p>
-
- <p><strong>%r [%t] %-5p %c %x - %m\n</strong></p>
- <p>This is essentially the TTCC layout.</p>
-
- <p><strong>%-6r [%15.15t] %-5p %30.30c %x - %m\n</strong></p>
-
- <p>
- 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.
- </p>
-
- <p>
- 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.
- </p>
+ * <p>
+ * The goal of this class is to #format a {@link spi::LoggingEvent
LoggingEvent} and
+ * return the results as a string. The results depend on the
<em>conversion pattern</em>.
+ * </p>
+
+ * <p>
+ * 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 <em>conversion specifiers</em>.
+ * </p>
+
+ * <p>
+ * <i>You are free to insert any literal text within the
conversion pattern.</i>
+ * </p>
+
+ * <p>
+ * Each conversion specifier starts with a percent sign (%) and is
followed by optional
+ * <em>format modifiers</em> and a <em>conversion character</em>.
The conversion character
+ * specifies the type of data, e.g. logger, level, date, thread
name. The format modifiers
+ * control such things as field width, padding, left and right
justification. The
+ * following is a simple example.
+ * </p>
+
+ * <p>
+ * Let the conversion pattern be <strong>"%-5p [%t]:
%m%n"</strong> and assume that the log4cxx
+ * environment was set to use a PatternLayout. Then the statements
+ * <pre>
+ * LoggerPtr root = Logger::getRoot();
+ * root->debug("Message 1");
+ * root->warn("Message 2");</pre>
+ * would yield the output
+ * <pre>
+ * DEBUG [main]: Message 1
+ * WARN [main]: Message 2</pre>
+ * </p>
+
+ * <p>
+ * 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 <strong>%-5p</strong>
+ * means the level of the logging event should be left justified
to a width of five
+ * characters.
+ * </p>
+
+ * <p>The recognized conversion characters are:</p>
+
+ * <table border="1" cellpadding="8">
+ * <tr>
+ * <th align="center"><strong>Conversion
Character</strong></th>
+ * <th align="center"><strong>Effect</strong></th>
+ * </tr>
+ * <tr>
+ * <td align="center"><strong>c</strong></td>
+ * <td>
+ * Used to output the logger of the logging event.
The logger conversion specifier
+ * can be optionally followed by <em>precision
specifier</em>, that is a decimal
+ * constant in brackets.
+ * <p>
+ * 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.
+ * </p>
+ * <p>
+ * For example, for the logger name
"a.b.c" the pattern <strong>\%c{2}</strong> will
+ * output "b.c".
+ * </p>
+ * </td>
+ * </tr>
+ * <tr>
+ * <td align="center">
+ * <p><strong>C</strong></p>
+ * <p><strong>class</strong></p>
+ * </td>
+ * <td>
+ * Used to output the class of the issuer of the
logging event if the compiler
+ * used supports a macro to retrieve the method of
the currently compiled line and
+ * if the LOG4CXX_TRACE-like macros are used to
issue a logging request. In this
+ * case the macro LOG4CXX_* is expanded at compile
time to generate location info
+ * of the logging event and adds the method name,
besides file and line, if
+ * available. In most cases the provided method
contains the classname and can
+ * therefore be retrieved form the location info
as needed.
+ * <p>
+ * Currently supported compilers are those
from Microsoft, GNU-C and Borland.
+ * </p>
+ * </td>
+ * </tr>
+ * <tr>
+ * <td align="center"><strong>d</strong></td>
+ * <td>
+ * Used to output the date of the logging event.
The date conversion specifier may
+ * be followed by a set of braces containing a
date and time pattern string
+ * compatible with java.text.SimpleDateFormat,
<em>ABSOLUTE</em>, <em>DATE</em> or
+ * <em>ISO8601</em>. For example,
<strong>%d{HH:mm:ss,SSS}</strong>,
+ *
<strong>%d{dd MMM yyyy HH:mm:ss,SSS}</strong> or
<strong>%d{DATE}</strong>. If no
+ * date format specifier is given then ISO8601
format is assumed.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td align="center"><strong>F</strong></td>
+ * <td>
+ * Used to output the file name where the logging
request was issued.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td align="center"><strong>l</strong></td>
+ * <td>
+ * Used to output location information of the
caller which generated the logging
+ * event.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td align="center"><strong>L</strong></td>
+ * <td>
+ * Used to output the line number from where the
logging request was issued.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td align="center"><strong>m</strong></td>
+ * <td>
+ * Used to output the application supplied message
associated with the logging
+ * event.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td align="center">
+ * <strong>M</strong>
+ * <p><strong>method</strong></p>
+ * </td>
+ * <td>
+ * Used to output the method of the issuer of the
logging event if the compiler
+ * used supports a macro to retrieve the method of
the currently compiled line
+ * and if the LOG4CXX_TRACE-like macros are used
to issue a logging request. In
+ * this case the macro LOG4CXX_* is expanded at
compile time to generate location
+ * info of the logging event and adds the method
name, besides file and line, if
+ * available. In most cases the provided method
contains the classname which is
+ * ignored in every attempt to retrieve the method
from the location info.
+ * <p>
+ * Currently supported compilers are those
from Microsoft, GNU-C and Borland.
+ * </p>
+ * </td>
+ * </tr>
+ * <tr>
+ * <td align="center"><strong>n</strong></td>
+ * <td>
+ * Outputs the platform dependent line separator
character or characters.
+ * <p>
+ * This conversion character offers
practically the same performance as using
+ * non-portable line separator strings
such as "\n", or "\r\n". Thus, it is the
+ * preferred way of specifying a line
separator.
+ * </p>
+ * </td>
+ * </tr>
+ * <tr>
+ * <td align="center"><strong>p</strong></td>
+ * <td>Used to output the level of the logging event.</td>
+ * </tr>
+ * <tr>
+ * <td align="center"><strong>r</strong></td>
+ * <td>
+ * Used to output the number of milliseconds
elapsed since the start of the
+ * application until the creation of the logging
event.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td align="center"><strong>t</strong></td>
+ * <td>Used to output the name of the thread that
generated the logging event.</td>
+ * </tr>
+ * <tr>
+ * <td align="center"><strong>x</strong></td>
+ * <td>
+ * Used to output the NDC (nested diagnostic
context) associated with the thread that
+ * generated the logging event.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td align="center"><strong>X</strong></td>
+ * <td>
+ * Used to output the MDC (mapped diagnostic
context) associated with the thread that
+ * generated the logging event. The
<strong>X</strong> conversion character <em>must</em> be
+ * followed by the key for the map placed between
braces, as in <strong>\%X{clientNumber}</strong>
+ * where <code>clientNumber</code> is the key. The
value in the MDC corresponding to
+ * the key will be output.
+ * <p>See MDC class for more details.</p>
+ * </td>
+ * </tr>
+ * <tr>
+ * <td align="center"><strong>\%</strong></td>
+ * <td>The sequence \%\% outputs a single percent
sign.</td>
+ * </tr>
+ * </table>
+
+ * <p>
+ * 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.
+ * </p>
+
+ * <p>
+ * The optional format modifier is placed between the percent sign
and the conversion
+ * character.
+ * </p>
+
+ * <p>
+ * The first optional format modifier is the <em>left
justification flag</em> which is
+ * just the minus (-) character. Then comes the optional
<em>minimum field width</em>
+ * 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.
+ * </p>
+
+ * <p>
+ * This behavior can be changed using the <em>maximum field
width</em> 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 <em>beginning</em> 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.
+ * </p>
+
+ * <p>Below are various format modifier examples for the logger
conversion specifier.</p>
+
+ * <table border="1" cellpadding="8">
+ * <tr>
+ * <th align="center"><strong>Format modifier</strong></th>
+ * <th align="center"><strong>left justify</strong></th>
+ * <th align="center"><strong>minimum width</strong></th>
+ * <th align="center"><strong>maximum width</strong></th>
+ * <th align="center"><strong>comment</strong></th>
+ * </tr>
+ * <tr>
+ * <td align="center">%20c</td>
+ * <td align="center">false</td>
+ * <td align="center">20</td>
+ * <td align="center">none</td>
+ * <td>Left pad with spaces if the logger name is less
than 20 characters long.</td>
+ * </tr>
+ * <tr>
+ * <td align="center">%-20c</td>
+ * <td align="center">true</td>
+ * <td align="center">20</td>
+ * <td align="center">none</td>
+ * <td>Right pad with spaces if the logger name is less
than 20 characters long.</td>
+ * </tr>
+ * <tr>
+ * <td align="center">%.30c</td>
+ * <td align="center">NA</td>
+ * <td align="center">none</td>
+ * <td align="center">30</td>
+ * <td>Truncate from the beginning if the logger name is
longer than 30 characters.</td>
+ * </tr>
+ * <tr>
+ * <td align="center">%20.30c</td>
+ * <td align="center">false</td>
+ * <td align="center">20</td>
+ * <td align="center">30</td>
+ * <td>
+ * 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.
+ * </td>
+ * </tr>
+ * <tr>
+ * <td align="center">%-20.30c</td>
+ * <td align="center">true</td>
+ * <td align="center">20</td>
+ * <td align="center">30</td>
+ * <td>
+ * 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.
+ * </td>
+ * </tr>
+ * </table>
+
+ * <p>Below are some examples of conversion patterns.</p>
+
+ * <p><strong>%r [%t] %-5p %c %x - %m\n</strong></p>
+ * <p>This is essentially the TTCC layout.</p>
+
+ * <p><strong>%-6r [%15.15t] %-5p %30.30c %x - %m\n</strong></p>
+
+ * <p>
+ * 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.
+ * </p>
+
+ * <p>
+ * 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.
+ * </p>
*/
class LOG4CXX_EXPORT PatternLayout : public Layout
{
