1DateFormat(3)         User Contributed Perl Documentation        DateFormat(3)
2
3
4

NAME

6       Log::Log4perl::DateFormat - Log4perl advanced date formatter helper
7       class
8

SYNOPSIS

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
15             # ... 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
20             # ... 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

DESCRIPTION

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
32           http://download.oracle.com/javase/1.4.2/docs/api/java/text/SimpleDateFormat.html
33
34       It supports the following placeholders:
35
36           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
61           Presentation explanation:
62
63           (Text): 4 or more pattern letters--use full form, < 4--use short or
64                   abbreviated form if one exists.
65
66           (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
71           (Text & Number): 3 or over, use text, otherwise use number.
72
73       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
77           # 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
83       Same goes for Perl code defining a PatternLayout for Log4perl:
84
85           use Log::Log4perl::Layout::PatternLayout;
86           my $layout = Log::Log4perl::Layout::PatternLayout->new(
87               "%d{MM/dd HH:mm} %m");
88
89       Or, on a lower level, you can use the class directly:
90
91           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
96       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
102       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
105       Also, for your convenience, the following predefined formats are
106       available, just as outlined in the log4j spec:
107
108           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
114       So, instead of passing
115
116           Log::Log4perl::DateFormat->new("HH:mm:ss,SSS");
117
118       you could just as well say
119
120           Log::Log4perl::DateFormat->new("ABSOLUTE");
121
122       and get the same result later on.
123
124   Known Shortcomings
125       The following placeholders are currently not recognized, unless someone
126       (and that could be you :) implements them:
127
128           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
135       Also, "Log::Log4perl::DateFormat" just knows about English week and
136       month names, internationalization support has to be added.
137

Millisecond Times

139       More granular timestamps down to the millisecond are also supported,
140       just provide the millsecond count as a second argument:
141
142           # 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

LICENSE

149       Copyright 2002-2016 by Mike Schilli <m@perlmeister.com> and Kevin Goess
150       <cpan@goess.org>.
151
152       This library is free software; you can redistribute it and/or modify it
153       under the same terms as Perl itself.
154

AUTHOR

156       Please contribute patches to the project on Github:
157
158           http://github.com/mschilli/log4perl
159
160       Send bug reports or requests for enhancements to the authors via our
161
162       MAILING LIST (questions, bug reports, suggestions/patches):
163       log4perl-devel@lists.sourceforge.net
164
165       Authors (please contact them via the list above, not directly): Mike
166       Schilli <m@perlmeister.com>, Kevin Goess <cpan@goess.org>
167
168       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.
175
176
177
178perl v5.32.0                      2020-09-07                     DateFormat(3)
Impressum