local-lib5/man/man3/Template::Plugin::Date.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "Template::Plugin::Date 3"
 132 .TH Template::Plugin::Date 3 "2009-06-30" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Template::Plugin::Date \- Plugin to generate formatted date strings
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 1
 138 \&    [% USE date %]
 139 .Ve
 140 .PP
 141 .Vb 2
 142 \&    # use current time and default format
 143 \&    [% date.format %]
 144 .Ve
 145 .PP
 146 .Vb 5
 147 \&    # specify time as seconds since epoch
 148 \&    # or as a 'h:m:s d\-m\-y' or 'y\-m\-d h:m:s' string
 149 \&    [% date.format(960973980) %]
 150 \&    [% date.format('4:20:36 21/12/2000') %]
 151 \&    [% date.format('2000/12/21 4:20:36') %]
 152 .Ve
 153 .PP
 154 .Vb 2
 155 \&    # specify format
 156 \&    [% date.format(mytime, '%H:%M:%S') %]
 157 .Ve
 158 .PP
 159 .Vb 2
 160 \&    # specify locale
 161 \&    [% date.format(date.now, '%a %d %b %y', 'en_GB') %]
 162 .Ve
 163 .PP
 164 .Vb 6
 165 \&    # named parameters
 166 \&    [% date.format(mytime, format = '%H:%M:%S') %]
 167 \&    [% date.format(locale = 'en_GB') %]
 168 \&    [% date.format(time   = date.now,
 169 \&                   format = '%H:%M:%S',
 170 \&                   locale = 'en_GB) %]
 171 .Ve
 172 .PP
 173 .Vb 2
 174 \&    # specify default format to plugin
 175 \&    [% USE date(format = '%H:%M:%S', locale = 'de_DE') %]
 176 .Ve
 177 .PP
 178 .Vb 2
 179 \&    [% date.format %]
 180 \&    ...
 181 .Ve
 182 .SH "DESCRIPTION"
 183 .IX Header "DESCRIPTION"
 184 The \f(CW\*(C`Date\*(C'\fR plugin provides an easy way to generate formatted time and date
 185 strings by delegating to the \f(CW\*(C`POSIX\*(C'\fR \f(CW\*(C`strftime()\*(C'\fR routine.
 186 .PP
 187 The plugin can be loaded via the familiar \s-1USE\s0 directive.
 188 .PP
 189 .Vb 1
 190 \&    [% USE date %]
 191 .Ve
 192 .PP
 193 This creates a plugin object with the default name of '\f(CW\*(C`date\*(C'\fR'.  An alternate
 194 name can be specified as such:
 195 .PP
 196 .Vb 1
 197 \&    [% USE myname = date %]
 198 .Ve
 199 .PP
 200 The plugin provides the \f(CW\*(C`format()\*(C'\fR method which accepts a time value, a
 201 format string and a locale name.  All of these parameters are optional
 202 with the current system time, default format ('\f(CW\*(C`%H:%M:%S %d\-%b\-%Y\*(C'\fR') and
 203 current locale being used respectively, if undefined.  Default values
 204 for the time, format and/or locale may be specified as named parameters
 205 in the \f(CW\*(C`USE\*(C'\fR directive.
 206 .PP
 207 .Vb 1
 208 \&    [% USE date(format = '%a %d\-%b\-%Y', locale = 'fr_FR') %]
 209 .Ve
 210 .PP
 211 When called without any parameters, the \f(CW\*(C`format()\*(C'\fR method returns a string
 212 representing the current system time, formatted by \f(CW\*(C`strftime()\*(C'\fR according
 213 to the default format and for the default locale (which may not be the
 214 current one, if locale is set in the \f(CW\*(C`USE\*(C'\fR directive).
 215 .PP
 216 .Vb 1
 217 \&    [% date.format %]
 218 .Ve
 219 .PP
 220 The plugin allows a time/date to be specified as seconds since the epoch,
 221 as is returned by \f(CW\*(C`time()\*(C'\fR.
 222 .PP
 223 .Vb 1
 224 \&    File last modified: [% date.format(filemod_time) %]
 225 .Ve
 226 .PP
 227 The time/date can also be specified as a string of the form \f(CW\*(C`h:m:s d/m/y\*(C'\fR
 228 or \f(CW\*(C`y/m/d h:m:s\*(C'\fR.  Any of the characters : / \- or space may be used to
 229 delimit fields.
 230 .PP
 231 .Vb 2
 232 \&    [% USE day = date(format => '%A', locale => 'en_GB') %]
 233 \&    [% day.format('4:20:00 9\-13\-2000') %]
 234 .Ve
 235 .PP
 236 Output:
 237 .PP
 238 .Vb 1
 239 \&    Tuesday
 240 .Ve
 241 .PP
 242 A format string can also be passed to the \f(CW\*(C`format()\*(C'\fR method, and a locale
 243 specification may follow that.
 244 .PP
 245 .Vb 2
 246 \&    [% date.format(filemod, '%d\-%b\-%Y') %]
 247 \&    [% date.format(filemod, '%d\-%b\-%Y', 'en_GB') %]
 248 .Ve
 249 .PP
 250 A fourth parameter allows you to force output in \s-1GMT\s0, in the case of
 251 seconds-since-the-epoch input:
 252 .PP
 253 .Vb 1
 254 \&    [% date.format(filemod, '%d\-%b\-%Y', 'en_GB', 1) %]
 255 .Ve
 256 .PP
 257 Note that in this case, if the local time is not \s-1GMT\s0, then also specifying
 258 \&'\f(CW%Z\fR' (time zone) in the format parameter will lead to an extremely
 259 misleading result.
 260 .PP
 261 Any or all of these parameters may be named.  Positional parameters
 262 should always be in the order \f(CW\*(C`($time, $format, $locale)\*(C'\fR.
 263 .PP
 264 .Vb 6
 265 \&    [% date.format(format => '%H:%M:%S') %]
 266 \&    [% date.format(time => filemod, format => '%H:%M:%S') %]
 267 \&    [% date.format(mytime, format => '%H:%M:%S') %]
 268 \&    [% date.format(mytime, format => '%H:%M:%S', locale => 'fr_FR') %]
 269 \&    [% date.format(mytime, format => '%H:%M:%S', gmt => 1) %]
 270 \&    ...etc...
 271 .Ve
 272 .PP
 273 The \f(CW\*(C`now()\*(C'\fR method returns the current system time in seconds since the
 274 epoch.
 275 .PP
 276 .Vb 1
 277 \&    [% date.format(date.now, '%A') %]
 278 .Ve
 279 .PP
 280 The \f(CW\*(C`calc()\*(C'\fR method can be used to create an interface to the \f(CW\*(C`Date::Calc\*(C'\fR
 281 module (if installed on your system).
 282 .PP
 283 .Vb 2
 284 \&    [% calc = date.calc %]
 285 \&    [% calc.Monday_of_Week(22, 2001).join('/') %]
 286 .Ve
 287 .PP
 288 The \f(CW\*(C`manip()\*(C'\fR method can be used to create an interface to the \f(CW\*(C`Date::Manip\*(C'\fR
 289 module (if installed on your system).
 290 .PP
 291 .Vb 2
 292 \&    [% manip = date.manip %]
 293 \&    [% manip.UnixDate("Noon Yesterday","%Y %b %d %H:%M") %]
 294 .Ve
 295 .SH "AUTHORS"
 296 .IX Header "AUTHORS"
 297 Thierry-Michel Barral wrote the original plugin.
 298 .PP
 299 Andy Wardley provided some minor
 300 fixups/enhancements, a test script and documentation.
 301 .PP
 302 Mark D. Mills cloned \f(CW\*(C`Date::Manip\*(C'\fR from the \f(CW\*(C`Date::Calc\*(C'\fR sub\-plugin.
 303 .SH "COPYRIGHT"
 304 .IX Header "COPYRIGHT"
 305 Copyright (C) 2000\-2007 Thierry-Michel Barral, Andy Wardley.
 306 .PP
 307 This module is free software; you can redistribute it and/or
 308 modify it under the same terms as Perl itself.
 309 .SH "SEE ALSO"
 310 .IX Header "SEE ALSO"
 311 Template::Plugin, \s-1POSIX\s0