Author: ceki Date: Wed Mar 19 16:03:53 2008 New Revision: 1648 Modified: logback/trunk/logback-site/src/site/pages/manual/layouts.html Log: - added blurb on parentheses in layout patterns Modified: logback/trunk/logback-site/src/site/pages/manual/layouts.html ============================================================================== --- logback/trunk/logback-site/src/site/pages/manual/layouts.html (original) +++ logback/trunk/logback-site/src/site/pages/manual/layouts.html Wed Mar 19 16:03:53 2008 @@ -1000,14 +1000,52 @@ <h3>Parentheses are special</h3> - <p>In logback, parentheses withing the pattern string are treated + <p>In logback, parentheses within the pattern string are treated as grouping tokens. Thus, it is possible to group a sub-pattern and apply formatting directives to that sub-pattern. </p> - <p>For example, + <p>For example, the pattern</p> - <span class="red"><b>XXXXXXXXXXXXXXXXXX</b></span> + <p class="source"><b>%-30(</b>%d{HH:mm:ss.SSS} [%thread]<b>)</b> %-5level %logger{32} - %msg%n</p> + + <p>will group the output generated by the sub-pattern + "%d{HH:mm:ss.SSS} [%thread]" so that it is right-padded if less + than 30 characters. + </p> + + <p>If without the grouping the output was</p> + + <p class="source">13:09:30 [main] DEBUG c.q.logback.demo.ContextListener - Classload hashcode is 13995234 +13:09:30 [main] DEBUG c.q.logback.demo.ContextListener - Initializing for ServletContext +13:09:30 [main] DEBUG c.q.logback.demo.ContextListener - Trying platform Mbean server +13:09:30 [pool-1-thread-1] INFO ch.qos.logback.demo.LoggingTask - Howdydy-diddly-ho - 0 +13:09:38 [btpool0-7] INFO c.q.l.demo.lottery.LotteryAction - Number: 50 was tried. +13:09:40 [btpool0-7] INFO c.q.l.d.prime.NumberCruncherImpl - Beginning to factor. +13:09:40 [btpool0-7] DEBUG c.q.l.d.prime.NumberCruncherImpl - Trying 2 as a factor. +13:09:40 [btpool0-7] INFO c.q.l.d.prime.NumberCruncherImpl - Found factor 2 + </p> + + <p>with the "%-30()" grouping applied it would be</p> + + <p class="source">13:09:30 [main] DEBUG c.q.logback.demo.ContextListener - Classload hashcode is 13995234 +13:09:30 [main] DEBUG c.q.logback.demo.ContextListener - Initializing for ServletContext +13:09:30 [main] DEBUG c.q.logback.demo.ContextListener - Trying platform Mbean server +13:09:30 [pool-1-thread-1] INFO ch.qos.logback.demo.LoggingTask - Howdydy-diddly-ho - 0 +13:09:38 [btpool0-7] INFO c.q.l.demo.lottery.LotteryAction - Number: 50 was tried. +13:09:40 [btpool0-7] INFO c.q.l.d.prime.NumberCruncherImpl - Beginning to factor. +13:09:40 [btpool0-7] DEBUG c.q.l.d.prime.NumberCruncherImpl - Trying 2 as a factor. +13:09:40 [btpool0-7] INFO c.q.l.d.prime.NumberCruncherImpl - Found factor 2 + </p> + + + <p>The latter form is more comfortable to read, especially for + long log files.</p> + + <p>If you need to treat the parenthesis character as a literal, it + needs to be escaped by preceding the parentheses with a + backslash. As in, <b>\(</b>%d{HH:mm:ss.SSS} [%thread]<b>\)</b>. + </p>