1DateFormat(3) User Contributed Perl Documentation DateFormat(3)
2
6 Log::Log4perl::DateFormat - Log4perl advanced date formatter helper
7 class
8
10 # Either in a log4j.conf file ...
11 log4perl.appender.Logfile.layout = \
12 Log::Log4perl::Layout::PatternLayout
13 log4perl.appender.Logfile.layout.ConversionPattern = %d{MM/dd HH:mm} %m
14 # ... or via the PatternLayout class ...
16 use Log::Log4perl::Layout::PatternLayout;
17 my $layout = Log::Log4perl::Layout::PatternLayout->new(
18 "%d{HH:mm:ss,SSS} %m");
19 # ... or even directly with this helper class:
21 use Log::Log4perl::DateFormat;
22 my $format = Log::Log4perl::DateFormat->new("HH:mm:ss,SSS");
23 my $time = time();
24 print $format->format($time), "\n";
25 # => "17:02:39,000"
26
28 "Log::Log4perl::DateFormat" is a helper class for the advanced date
29 formatting functions in "Log::Log4perl::Layout::PatternLayout", and
30 adheres (mostly) to the log4j SimpleDateFormat spec available on
31 http://download.oracle.com/javase/1.4.2/docs/api/java/text/SimpleDateFormat.html
33 It supports the following placeholders:
35 Symbol Meaning Presentation Example
37 ------ ------- ------------ -------
38 G era designator (Text) AD
39 e epoch seconds (Number) 1315011604
40 y year (Number) 1996
41 M month in year (Text & Number) July & 07
42 d day in month (Number) 10
43 h hour in am/pm (1~12) (Number) 12
44 H hour in day (0~23) (Number) 0
45 m minute in hour (Number) 30
46 s second in minute (Number) 55
47 S millisecond (Number) 978
48 E day in week (Text) Tuesday
49 D day in year (Number) 189
50 F day of week in month (Number) 2 (2nd Wed in July)
51 w week in year (Number) 27
52 W week in month (Number) 2
53 a am/pm marker (Text) PM
54 k hour in day (1~24) (Number) 24
55 K hour in am/pm (0~11) (Number) 0
56 z time zone (Text) Pacific Standard Time
57 Z RFC 822 time zone (Text) -0800
58 ' escape for text (Delimiter)
59 '' single quote (Literal) '
60 Presentation explanation:
62 (Text): 4 or more pattern letters--use full form, < 4--use short or
64 abbreviated form if one exists.
65 (Number): the minimum number of digits. Shorter numbers are
67 zero-padded to this amount. Year is handled
68 specially; that is, if the count of 'y' is 2, the
69 Year will be truncated to 2 digits.
70 (Text & Number): 3 or over, use text, otherwise use number.
72 For example, if you want to format the current Unix time in "MM/dd
74 HH:mm" format, all you have to do is specify it in the %d{...} section
75 of the PatternLayout in a Log4perl configuration file:
76 # log4j.conf
78 # ...
79 log4perl.appender.Logfile.layout = \
80 Log::Log4perl::Layout::PatternLayout
81 log4perl.appender.Logfile.layout.ConversionPattern = %d{MM/dd HH:mm} %m
82 Same goes for Perl code defining a PatternLayout for Log4perl:
84 use Log::Log4perl::Layout::PatternLayout;
86 my $layout = Log::Log4perl::Layout::PatternLayout->new(
87 "%d{MM/dd HH:mm} %m");
88 Or, on a lower level, you can use the class directly:
90 use Log::Log4perl::DateFormat;
92 my $format = Log::Log4perl::DateFormat->new("MM/dd HH:mm");
93 my $time = time();
94 print $format->format($time), "\n";
95 While the "new()" method is expensive, because it parses the format
97 strings and sets up all kinds of structures behind the scenes, followup
98 calls to "format()" are fast, because "DateFormat" will just call
99 "localtime()" and "sprintf()" once to return the formatted date/time
100 string.
101 So, typically, you would initialize the formatter once and then reuse
103 it over and over again to display all kinds of time values.
104 Also, for your convenience, the following predefined formats are
106 available, just as outlined in the log4j spec:
107 Format Equivalent Example
109 ABSOLUTE "HH:mm:ss,SSS" "15:49:37,459"
110 DATE "dd MMM yyyy HH:mm:ss,SSS" "06 Nov 1994 15:49:37,459"
111 ISO8601 "yyyy-MM-dd HH:mm:ss,SSS" "1999-11-27 15:49:37,459"
112 APACHE "[EEE MMM dd HH:mm:ss yyyy]" "[Wed Mar 16 15:49:37 2005]"
113 So, instead of passing
115 Log::Log4perl::DateFormat->new("HH:mm:ss,SSS");
117 you could just as well say
119 Log::Log4perl::DateFormat->new("ABSOLUTE");
121 and get the same result later on.
123 Known Shortcomings
125 The following placeholders are currently not recognized, unless someone
126 (and that could be you :) implements them:
127 F day of week in month
129 w week in year
130 W week in month
131 k hour in day
132 K hour in am/pm
133 z timezone (but we got 'Z' for the numeric time zone value)
134 Also, "Log::Log4perl::DateFormat" just knows about English week and
136 month names, internationalization support has to be added.
137
139 More granular timestamps down to the millisecond are also supported,
140 just provide the millsecond count as a second argument:
141 # Advanced time, resultion in milliseconds
143 use Time::HiRes;
144 my ($secs, $msecs) = Time::HiRes::gettimeofday();
145 print $format->format($secs, $msecs), "\n";
146 # => "17:02:39,959"
147
149 Copyright 2002-2016 by Mike Schilli <m@perlmeister.com> and Kevin Goess
150 <cpan@goess.org>.
151 This library is free software; you can redistribute it and/or modify it
153 under the same terms as Perl itself.
154
156 Please contribute patches to the project on Github:
157 http://github.com/mschilli/log4perl
159 Send bug reports or requests for enhancements to the authors via our
161 MAILING LIST (questions, bug reports, suggestions/patches):
163 log4perl-devel@lists.sourceforge.net
164 Authors (please contact them via the list above, not directly): Mike
166 Schilli <m@perlmeister.com>, Kevin Goess <cpan@goess.org>
167 Contributors (in alphabetical order): Ateeq Altaf, Cory Bennett, Jens
169 Berthold, Jeremy Bopp, Hutton Davidson, Chris R. Donnelly, Matisse
170 Enzer, Hugh Esco, Anthony Foiani, James FitzGibbon, Carl Franks, Dennis
171 Gregorovic, Andy Grundman, Paul Harrington, Alexander Hartmaier David
172 Hull, Robert Jacobson, Jason Kohles, Jeff Macdonald, Markus Peter,
173 Brett Rann, Peter Rabbitson, Erik Selberg, Aaron Straup Cope, Lars
174 Thegler, David Viner, Mac Yang.
175perl v5.32.1 2021-02-08 DateFormat(3)