local-lib5/man/man3/DateTime::Format::Mail.3pm

   1 .\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 'br\}
  42 .\"
  43 .\" Escape single quotes in literal strings from groff's Unicode transform.
  44 .ie \n(.g .ds Aq \(aq
  45 .el       .ds Aq '
  46 .\"
  47 .\" If the F register is turned on, we'll generate index entries on stderr for
  48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  49 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  50 .\" output yourself in some meaningful fashion.
  51 .ie \nF \{\
  52 .    de IX
  53 .    tm Index:\\$1\t\\n%\t"\\$2"
  54 ..
  55 .    nr % 0
  56 .    rr F
  57 .\}
  58 .el \{\
  59 .    de IX
  60 ..
  61 .\}
  62 .\"
  63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  64 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  65 .    \" fudge factors for nroff and troff
  66 .if n \{\
  67 .    ds #H 0
  68 .    ds #V .8m
  69 .    ds #F .3m
  70 .    ds #[ \f1
  71 .    ds #] \fP
  72 .\}
  73 .if t \{\
  74 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  75 .    ds #V .6m
  76 .    ds #F 0
  77 .    ds #[ \&
  78 .    ds #] \&
  79 .\}
  80 .    \" simple accents for nroff and troff
  81 .if n \{\
  82 .    ds ' \&
  83 .    ds ` \&
  84 .    ds ^ \&
  85 .    ds , \&
  86 .    ds ~ ~
  87 .    ds /
  88 .\}
  89 .if t \{\
  90 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  91 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  92 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  93 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  94 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
  95 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
  96 .\}
  97 .    \" troff and (daisy-wheel) nroff accents
  98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
  99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 105 .ds ae a\h'-(\w'a'u*4/10)'e
 106 .ds Ae A\h'-(\w'A'u*4/10)'E
 107 .    \" corrections for vroff
 108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 110 .    \" for low resolution devices (crt and lpr)
 111 .if \n(.H>23 .if \n(.V>19 \
 112 \{\
 113 .    ds : e
 114 .    ds 8 ss
 115 .    ds o a
 116 .    ds d- d\h'-1'\(ga
 117 .    ds D- D\h'-1'\(hy
 118 .    ds th \o'bp'
 119 .    ds Th \o'LP'
 120 .    ds ae ae
 121 .    ds Ae AE
 122 .\}
 123 .rm #[ #] #H #V #F C
 124 .\" ========================================================================
 125 .\"
 126 .IX Title "DateTime::Format::Mail 3"
 127 .TH DateTime::Format::Mail 3 "2009-12-09" "perl v5.8.7" "User Contributed Perl Documentation"
 128 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 129 .\" way too many mistakes in technical documents.
 130 .if n .ad l
 131 .nh
 132 .SH "NAME"
 133 DateTime::Format::Mail \- Convert between DateTime and RFC2822/822 formats
 134 .SH "SYNOPSIS"
 135 .IX Header "SYNOPSIS"
 136 .Vb 1
 137 \&    use DateTime::Format::Mail;
 138 \&
 139 \&    # From RFC2822 via class method:
 140 \&
 141 \&    my $datetime = DateTime::Format::Mail\->parse_datetime(
 142 \&        "Sat, 29 Mar 2003 22:11:18 \-0800"
 143 \&    );
 144 \&    print $datetime\->ymd(\*(Aq.\*(Aq); # "2003.03.29"
 145 \&
 146 \&    #  or via an object
 147 \&
 148 \&    my $pf = DateTime::Format::Mail\->new();
 149 \&    print $pf\->parse_datetime(
 150 \&        "Fri, 23 Nov 2001 21:57:24 \-0600"
 151 \&    )\->ymd; # "2001\-11\-23"
 152 \&
 153 \&    # Back to RFC2822 date
 154 \&
 155 \&    use DateTime;
 156 \&    my $dt = DateTime\->new(
 157 \&        year => 1979, month => 7, day => 16,
 158 \&        hour => 16, minute => 45, second => 20,
 159 \&        time_zone => "Australia/Sydney"
 160 \&    );
 161 \&    my $str = DateTime::Format::Mail\->format_datetime( $dt );
 162 \&    print $str; # "Mon, 16 Jul 1979 16:45:20 +1000"
 163 \&
 164 \&    # or via an object
 165 \&    $str = $pf\->format_datetime( $dt );
 166 \&    print $str; # "Mon, 16 Jul 1979 16:45:20 +1000"
 167 .Ve
 168 .SH "DESCRIPTION"
 169 .IX Header "DESCRIPTION"
 170 RFCs 2822 and 822 specify date formats to be used by email. This
 171 module parses and emits such dates.
 172 .PP
 173 \&\s-1RFC2822\s0 (April 2001) introduces a slightly different format of
 174 date than that used by \s-1RFC822\s0 (August 1982). The main correction
 175 is that the preferred format is more limited, and thus easier to
 176 parse programmatically.
 177 .PP
 178 Despite the ease of generating and parsing perfectly valid \s-1RFC822\s0 and
 179 \&\s-1RFC2822\s0 people still get it wrong. So this module provides four things
 180 for those handling mail dates:
 181 .IP "1." 4
 182 A strict parser that will only accept \s-1RFC2822\s0 dates, so you can
 183 see where you're right.
 184 .IP "2." 4
 185 A strict formatter, so you can generate the right stuff
 186 to begin with.
 187 .IP "3." 4
 188 A \fIloose\fR parser, so you can take the misbegotten output
 189 from other programs and turn it into something useful.
 190 This includes various minor errors as well as some somewhat more
 191 bizarre mistakes. The file \fIt/sample_dates\fR in this module's
 192 distribution should give you an idea of what's valid, while
 193 \&\fIt/invalid.t\fR should do the same for what's not. Those regarded
 194 as invalid are just a bit \fBtoo\fR strange to allow.
 195 .IP "4." 4
 196 Interoperation with the rest of the DateTime suite. These are
 197 a collection of modules to handle dates in a modern and accurate
 198 fashion. In particular, they make it trivial to parse, manipulate
 199 and then format dates. Shifting timezones is a doddle, and
 200 converting between formats is a cinch.
 201 .PP
 202 As a future direction, I'm contemplating an even stricter
 203 parser that will only accept dates with no obsolete elements.
 204 .SH "CONSTRUCTORS"
 205 .IX Header "CONSTRUCTORS"
 206 .SS "new"
 207 .IX Subsection "new"
 208 Creates a new \f(CW\*(C`DateTime::Format::Mail\*(C'\fR instance. This is
 209 generally not required for simple operations. If you wish to use
 210 a different parsing style from the default, strict, parser then
 211 you'll need to create an object.
 212 .PP
 213 .Vb 2
 214 \&   my $parser = DateTime::Format::Mail\->new()
 215 \&   my $copy = $parser\->new();
 216 .Ve
 217 .PP
 218 If called on an existing object then it clones the object.
 219 .PP
 220 It has two optional named parameters.
 221 .IP "\(bu" 4
 222 \&\f(CW\*(C`loose\*(C'\fR should be a true value if you want a loose parser,
 223 else either don't specify it or give it a false value.
 224 .IP "\(bu" 4
 225 \&\f(CW\*(C`year_cutoff\*(C'\fR should be an integer greater than or equal to zero
 226 specifying the cutoff year. See \*(L"set_year_cutoff\*(R" for details.
 227 .PP
 228 .Vb 1
 229 \&    my $loose = DateTime::Format::Mail\->new( loose => 1 );
 230 \&
 231 \&    my $post_2049 = DateTime::Format::Mail\->new(
 232 \&        year_cutoff => 60
 233 \&    );
 234 .Ve
 235 .SS "clone"
 236 .IX Subsection "clone"
 237 For those who prefer to explicitly clone via a method called \f(CW\*(C`clone()\*(C'\fR.
 238 If called as a class method it will die.
 239 .PP
 240 .Vb 1
 241 \&   my $clone = $original\->clone();
 242 .Ve
 243 .SH "PARSING METHODS"
 244 .IX Header "PARSING METHODS"
 245 These methods work on either our objects or as class methods.
 246 .SS "loose, strict"
 247 .IX Subsection "loose, strict"
 248 These methods set the parsing strictness.
 249 .PP
 250 .Vb 3
 251 \&    my $parser = DateTime::Format::Mail\->new;
 252 \&    $parser\->loose;
 253 \&    $parser\->strict; # (the default)
 254 \&
 255 \&    my $p = DateTime::Format::Mail\->new\->loose;
 256 .Ve
 257 .SS "parse_datetime"
 258 .IX Subsection "parse_datetime"
 259 Given an \s-1RFC2822\s0 or 822 datetime string, return a \f(CW\*(C`DateTime\*(C'\fR object
 260 representing that date and time. Unparseable strings will cause
 261 the method to die.
 262 .PP
 263 See the synopsis for examples.
 264 .SS "set_year_cutoff"
 265 .IX Subsection "set_year_cutoff"
 266 Two digit years are treated as valid in the loose translation and are
 267 translated up to a 19xx or 20xx figure. By default, following the
 268 specification of \s-1RFC2822\s0, if the year is
 269 greater than '49', it's treated as being in the 20th century (19xx).
 270 If lower, or equal, then the 21st (20xx). That is, 50 becomes
 271 1950 while 49 is 2049.
 272 .PP
 273 \&\f(CW\*(C`set_year_cutoff()\*(C'\fR allows you to modify this behaviour by specifying
 274 a different cutoff.
 275 .PP
 276 The return value is the object itself.
 277 .PP
 278 .Vb 1
 279 \&    $parser\->set_year_cutoff( 60 );
 280 .Ve
 281 .SS "year_cutoff"
 282 .IX Subsection "year_cutoff"
 283 Returns the current cutoff. Can be used as either a class or object method.
 284 .PP
 285 .Vb 1
 286 \&    my $cutoff = $parser\->set_year_cutoff;
 287 .Ve
 288 .SS "default_cutoff"
 289 .IX Subsection "default_cutoff"
 290 Returns the default cutoff. A useful method to override for
 291 subclasses.
 292 .PP
 293 .Vb 1
 294 \&    my $default = $parser\->default_cutoff;
 295 .Ve
 296 .SS "fix_year"
 297 .IX Subsection "fix_year"
 298 Takes a year and returns it normalized.
 299 .PP
 300 .Vb 1
 301 \&   my $fixed = $parser\->fix_year( 3 );
 302 .Ve
 303 .SH "FORMATTING METHODS"
 304 .IX Header "FORMATTING METHODS"
 305 .SS "format_datetime"
 306 .IX Subsection "format_datetime"
 307 Given a \f(CW\*(C`DateTime\*(C'\fR object, return it as an \s-1RFC2822\s0 compliant string.
 308 .PP
 309 .Vb 7
 310 \&    use DateTime;
 311 \&    use DateTime::Format::Mail;
 312 \&    my $dt = DateTime\->new(
 313 \&        year => 1979, month => 7, day => 16, time_zone => \*(AqUTC\*(Aq
 314 \&    );
 315 \&    my $mail = DateTime::Format::Mail\->format_datetime( $dt );
 316 \&    print $mail, "\en";
 317 \&
 318 \&    # or via an object
 319 \&    my $formatter = DateTime::Format::Mail\->new();
 320 \&    my $rfcdate = $formatter\->format_datetime( $dt );
 321 \&    print $rfcdate, "\en";
 322 .Ve
 323 .SH "THANKS"
 324 .IX Header "THANKS"
 325 Dave Rolsky (\s-1DROLSKY\s0) for kickstarting the DateTime project.
 326 .PP
 327 Roderick A. Anderson for noting where the documentation was incomplete
 328 in places.
 329 .PP
 330 Joshua Hoblitt (\s-1JHOBLITT\s0) for inspiring me to check what the
 331 standard said about interpreting two digit years.
 332 .SH "SUPPORT"
 333 .IX Header "SUPPORT"
 334 Support for this module is provided via the datetime@perl.org email
 335 list. See <http://datetime.perl.org/mailing_list.html> for more details.
 336 .PP
 337 Alternatively, log them via the \s-1CPAN\s0 \s-1RT\s0 system via the web or email:
 338 .PP
 339 .Vb 2
 340 \&    http://rt.cpan.org/NoAuth/ReportBug.html?Queue=DateTime%3A%3AFormat%3A%3AMail
 341 \&    bug\-datetime\-format\-mail@rt.cpan.org
 342 .Ve
 343 .PP
 344 This makes it much easier for me to track things and thus means
 345 your problem is less likely to be neglected.
 346 .SH "LICENCE AND COPYRIGHT"
 347 .IX Header "LICENCE AND COPYRIGHT"
 348 Copyright X Iain Truskett, 2003. All rights reserved.
 349 .PP
 350 This library is free software; you can redistribute it and/or modify
 351 it under the same terms as Perl itself.
 352 .PP
 353 The full text of the licences can be found in the \fIArtistic\fR and
 354 \&\fI\s-1COPYING\s0\fR files included with this module, or in perlartistic and
 355 perlgpl in Perl 5.8.1 or later.
 356 .SH "AUTHOR"
 357 .IX Header "AUTHOR"
 358 Originally written by Iain Truskett <spoon@cpan.org>, who died on
 359 December 29, 2003.
 360 .PP
 361 Maintained by Dave Rolsky <autarch@urth.org>.
 362 .SH "SEE ALSO"
 363 .IX Header "SEE ALSO"
 364 \&\f(CW\*(C`datetime@perl.org\*(C'\fR mailing list.
 365 .PP
 366 <http://datetime.perl.org/>
 367 .PP
 368 perl, DateTime
 369 .PP
 370 RFCs 2822 and 822.