1=encoding utf8
2
3=head1 NAME
4
5Mail::Message::Field::Date - message header field with uris
6
7=head1 INHERITANCE
8
9 Mail::Message::Field::Date
10   is a Mail::Message::Field::Structured
11   is a Mail::Message::Field::Full
12   is a Mail::Message::Field
13   is a Mail::Reporter
14
15=head1 SYNOPSIS
16
17 my $f = Mail::Message::Field->new(Date => time);
18
19=head1 DESCRIPTION
20
21Dates are a little more tricky than it should be: the formatting permits
22a few constructs more than other RFCs use for timestamps.  For instance,
23a small subset of timezone abbreviations are permitted.
24
25The studied date field will reformat the content into a standard
26form.
27
28Extends L<"DESCRIPTION" in Mail::Message::Field::Structured|Mail::Message::Field::Structured/"DESCRIPTION">.
29
30=head1 OVERLOADED
31
32Extends L<"OVERLOADED" in Mail::Message::Field::Structured|Mail::Message::Field::Structured/"OVERLOADED">.
33
34=over 4
35
36=item overload: B<"">
37
38Inherited, see L<Mail::Message::Field/"OVERLOADED">
39
40=item overload: B<0+>
41
42Inherited, see L<Mail::Message::Field/"OVERLOADED">
43
44=item overload: B<<=>>
45
46Inherited, see L<Mail::Message::Field/"OVERLOADED">
47
48=item overload: B<bool>
49
50Inherited, see L<Mail::Message::Field/"OVERLOADED">
51
52=item overload: B<cmp>
53
54Inherited, see L<Mail::Message::Field/"OVERLOADED">
55
56=item overload: B<stringification>
57
58Inherited, see L<Mail::Message::Field::Full/"OVERLOADED">
59
60=back
61
62=head1 METHODS
63
64Extends L<"METHODS" in Mail::Message::Field::Structured|Mail::Message::Field::Structured/"METHODS">.
65
66=head2 Constructors
67
68Extends L<"Constructors" in Mail::Message::Field::Structured|Mail::Message::Field::Structured/"Constructors">.
69
70=over 4
71
72=item $obj-E<gt>B<clone>()
73
74Inherited, see L<Mail::Message::Field/"Constructors">
75
76=item Mail::Message::Field::Date-E<gt>B<from>($field, %options)
77
78Inherited, see L<Mail::Message::Field::Full/"Constructors">
79
80=item Mail::Message::Field::Date-E<gt>B<new>($data)
81
82 -Option    --Defined in                      --Default
83  attributes  Mail::Message::Field::Structured  <ignored>
84  charset     Mail::Message::Field::Full        undef
85  datum       Mail::Message::Field::Structured  undef
86  encoding    Mail::Message::Field::Full        'q'
87  force       Mail::Message::Field::Full        false
88  language    Mail::Message::Field::Full        undef
89  log         Mail::Reporter                    'WARNINGS'
90  trace       Mail::Reporter                    'WARNINGS'
91
92=over 2
93
94=item attributes => ATTRS
95
96=item charset => STRING
97
98=item datum => STRING
99
100=item encoding => 'q'|'Q'|'b'|'B'
101
102=item force => BOOLEAN
103
104=item language => STRING
105
106=item log => LEVEL
107
108=item trace => LEVEL
109
110=back
111
112example:
113
114 my $mmfd = 'Mail::Message::Field::Date';
115 my $f = $mmfd->new(Date => time);
116
117=back
118
119=head2 The field
120
121Extends L<"The field" in Mail::Message::Field::Structured|Mail::Message::Field::Structured/"The field">.
122
123=over 4
124
125=item $obj-E<gt>B<isStructured>()
126
127=item Mail::Message::Field::Date-E<gt>B<isStructured>()
128
129Inherited, see L<Mail::Message::Field/"The field">
130
131=item $obj-E<gt>B<length>()
132
133Inherited, see L<Mail::Message::Field/"The field">
134
135=item $obj-E<gt>B<nrLines>()
136
137Inherited, see L<Mail::Message::Field/"The field">
138
139=item $obj-E<gt>B<print>( [$fh] )
140
141Inherited, see L<Mail::Message::Field/"The field">
142
143=item $obj-E<gt>B<size>()
144
145Inherited, see L<Mail::Message::Field/"The field">
146
147=item $obj-E<gt>B<string>( [$wrap] )
148
149Inherited, see L<Mail::Message::Field/"The field">
150
151=item $obj-E<gt>B<toDisclose>()
152
153Inherited, see L<Mail::Message::Field/"The field">
154
155=back
156
157=head2 Access to the name
158
159Extends L<"Access to the name" in Mail::Message::Field::Structured|Mail::Message::Field::Structured/"Access to the name">.
160
161=over 4
162
163=item $obj-E<gt>B<Name>()
164
165Inherited, see L<Mail::Message::Field/"Access to the name">
166
167=item $obj-E<gt>B<name>()
168
169Inherited, see L<Mail::Message::Field/"Access to the name">
170
171=item $obj-E<gt>B<wellformedName>( [STRING] )
172
173Inherited, see L<Mail::Message::Field/"Access to the name">
174
175=back
176
177=head2 Access to the body
178
179Extends L<"Access to the body" in Mail::Message::Field::Structured|Mail::Message::Field::Structured/"Access to the body">.
180
181=over 4
182
183=item $obj-E<gt>B<body>()
184
185Inherited, see L<Mail::Message::Field/"Access to the body">
186
187=item $obj-E<gt>B<decodedBody>(%options)
188
189Inherited, see L<Mail::Message::Field::Full/"Access to the body">
190
191=item $obj-E<gt>B<folded>()
192
193Inherited, see L<Mail::Message::Field/"Access to the body">
194
195=item $obj-E<gt>B<foldedBody>( [$body] )
196
197Inherited, see L<Mail::Message::Field/"Access to the body">
198
199=item $obj-E<gt>B<stripCFWS>( [STRING] )
200
201=item Mail::Message::Field::Date-E<gt>B<stripCFWS>( [STRING] )
202
203Inherited, see L<Mail::Message::Field/"Access to the body">
204
205=item $obj-E<gt>B<unfoldedBody>( [$body, [$wrap]] )
206
207Inherited, see L<Mail::Message::Field/"Access to the body">
208
209=back
210
211=head2 Access to the content
212
213Extends L<"Access to the content" in Mail::Message::Field::Structured|Mail::Message::Field::Structured/"Access to the content">.
214
215=over 4
216
217=item $obj-E<gt>B<addAttribute>(...)
218
219Attributes are not supported for date fields.
220
221=item $obj-E<gt>B<addresses>()
222
223Inherited, see L<Mail::Message::Field/"Access to the content">
224
225=item $obj-E<gt>B<attrPairs>()
226
227Inherited, see L<Mail::Message::Field::Structured/"Access to the content">
228
229=item $obj-E<gt>B<attribute>( $object|<STRING, %options>|<$name,$value,%options> )
230
231Inherited, see L<Mail::Message::Field::Structured/"Access to the content">
232
233=item $obj-E<gt>B<attributes>()
234
235Inherited, see L<Mail::Message::Field::Structured/"Access to the content">
236
237=item $obj-E<gt>B<beautify>()
238
239Inherited, see L<Mail::Message::Field::Full/"Access to the content">
240
241=item $obj-E<gt>B<comment>( [STRING] )
242
243Inherited, see L<Mail::Message::Field/"Access to the content">
244
245=item $obj-E<gt>B<createComment>(STRING, %options)
246
247=item Mail::Message::Field::Date-E<gt>B<createComment>(STRING, %options)
248
249Inherited, see L<Mail::Message::Field::Full/"Access to the content">
250
251=item $obj-E<gt>B<createPhrase>(STRING, %options)
252
253=item Mail::Message::Field::Date-E<gt>B<createPhrase>(STRING, %options)
254
255Inherited, see L<Mail::Message::Field::Full/"Access to the content">
256
257=item $obj-E<gt>B<study>()
258
259Inherited, see L<Mail::Message::Field/"Access to the content">
260
261=item $obj-E<gt>B<time>()
262
263Convert date into a timestamp, as produced with POSIX::time().
264
265=item $obj-E<gt>B<toDate>( [$time] )
266
267=item Mail::Message::Field::Date-E<gt>B<toDate>( [$time] )
268
269Inherited, see L<Mail::Message::Field/"Access to the content">
270
271=item $obj-E<gt>B<toInt>()
272
273Inherited, see L<Mail::Message::Field/"Access to the content">
274
275=back
276
277=head2 Other methods
278
279Extends L<"Other methods" in Mail::Message::Field::Structured|Mail::Message::Field::Structured/"Other methods">.
280
281=over 4
282
283=item $obj-E<gt>B<dateToTimestamp>(STRING)
284
285=item Mail::Message::Field::Date-E<gt>B<dateToTimestamp>(STRING)
286
287Inherited, see L<Mail::Message::Field/"Other methods">
288
289=back
290
291=head2 Internals
292
293Extends L<"Internals" in Mail::Message::Field::Structured|Mail::Message::Field::Structured/"Internals">.
294
295=over 4
296
297=item $obj-E<gt>B<consume>( $line | <$name,<$body|$objects>> )
298
299Inherited, see L<Mail::Message::Field/"Internals">
300
301=item $obj-E<gt>B<decode>(STRING, %options)
302
303=item Mail::Message::Field::Date-E<gt>B<decode>(STRING, %options)
304
305Inherited, see L<Mail::Message::Field::Full/"Internals">
306
307=item $obj-E<gt>B<defaultWrapLength>( [$length] )
308
309Inherited, see L<Mail::Message::Field/"Internals">
310
311=item $obj-E<gt>B<encode>(STRING, %options)
312
313Inherited, see L<Mail::Message::Field::Full/"Internals">
314
315=item $obj-E<gt>B<fold>( $name, $body, [$maxchars] )
316
317=item Mail::Message::Field::Date-E<gt>B<fold>( $name, $body, [$maxchars] )
318
319Inherited, see L<Mail::Message::Field/"Internals">
320
321=item $obj-E<gt>B<setWrapLength>( [$length] )
322
323Inherited, see L<Mail::Message::Field/"Internals">
324
325=item $obj-E<gt>B<stringifyData>(STRING|ARRAY|$objects)
326
327Inherited, see L<Mail::Message::Field/"Internals">
328
329=item $obj-E<gt>B<unfold>(STRING)
330
331Inherited, see L<Mail::Message::Field/"Internals">
332
333=back
334
335=head2 Parsing
336
337Extends L<"Parsing" in Mail::Message::Field::Structured|Mail::Message::Field::Structured/"Parsing">.
338
339=over 4
340
341=item $obj-E<gt>B<consumeComment>(STRING)
342
343=item Mail::Message::Field::Date-E<gt>B<consumeComment>(STRING)
344
345Inherited, see L<Mail::Message::Field::Full/"Parsing">
346
347=item $obj-E<gt>B<consumeDotAtom>(STRING)
348
349Inherited, see L<Mail::Message::Field::Full/"Parsing">
350
351=item $obj-E<gt>B<consumePhrase>(STRING)
352
353=item Mail::Message::Field::Date-E<gt>B<consumePhrase>(STRING)
354
355Inherited, see L<Mail::Message::Field::Full/"Parsing">
356
357=item $obj-E<gt>B<datum>( [$value] )
358
359Inherited, see L<Mail::Message::Field::Structured/"Parsing">
360
361=item $obj-E<gt>B<parse>(STRING)
362
363Inherited, see L<Mail::Message::Field::Full/"Parsing">
364
365=item $obj-E<gt>B<produceBody>()
366
367Inherited, see L<Mail::Message::Field::Full/"Parsing">
368
369=back
370
371=head2 Error handling
372
373Extends L<"Error handling" in Mail::Message::Field::Structured|Mail::Message::Field::Structured/"Error handling">.
374
375=over 4
376
377=item $obj-E<gt>B<AUTOLOAD>()
378
379Inherited, see L<Mail::Reporter/"Error handling">
380
381=item $obj-E<gt>B<addReport>($object)
382
383Inherited, see L<Mail::Reporter/"Error handling">
384
385=item $obj-E<gt>B<defaultTrace>( [$level]|[$loglevel, $tracelevel]|[$level, $callback] )
386
387=item Mail::Message::Field::Date-E<gt>B<defaultTrace>( [$level]|[$loglevel, $tracelevel]|[$level, $callback] )
388
389Inherited, see L<Mail::Reporter/"Error handling">
390
391=item $obj-E<gt>B<errors>()
392
393Inherited, see L<Mail::Reporter/"Error handling">
394
395=item $obj-E<gt>B<log>( [$level, [$strings]] )
396
397=item Mail::Message::Field::Date-E<gt>B<log>( [$level, [$strings]] )
398
399Inherited, see L<Mail::Reporter/"Error handling">
400
401=item $obj-E<gt>B<logPriority>($level)
402
403=item Mail::Message::Field::Date-E<gt>B<logPriority>($level)
404
405Inherited, see L<Mail::Reporter/"Error handling">
406
407=item $obj-E<gt>B<logSettings>()
408
409Inherited, see L<Mail::Reporter/"Error handling">
410
411=item $obj-E<gt>B<notImplemented>()
412
413Inherited, see L<Mail::Reporter/"Error handling">
414
415=item $obj-E<gt>B<report>( [$level] )
416
417Inherited, see L<Mail::Reporter/"Error handling">
418
419=item $obj-E<gt>B<reportAll>( [$level] )
420
421Inherited, see L<Mail::Reporter/"Error handling">
422
423=item $obj-E<gt>B<trace>( [$level] )
424
425Inherited, see L<Mail::Reporter/"Error handling">
426
427=item $obj-E<gt>B<warnings>()
428
429Inherited, see L<Mail::Reporter/"Error handling">
430
431=back
432
433=head2 Cleanup
434
435Extends L<"Cleanup" in Mail::Message::Field::Structured|Mail::Message::Field::Structured/"Cleanup">.
436
437=over 4
438
439=item $obj-E<gt>B<DESTROY>()
440
441Inherited, see L<Mail::Reporter/"Cleanup">
442
443=back
444
445=head1 DETAILS
446
447Extends L<"DETAILS" in Mail::Message::Field::Structured|Mail::Message::Field::Structured/"DETAILS">.
448
449=head1 DIAGNOSTICS
450
451=over 4
452
453=item Warning: Field content is not numerical: $content
454
455The numeric value of a field is requested (for instance the C<Lines> or
456C<Content-Length> fields should be numerical), however the data contains
457weird characters.
458
459=item Warning: Illegal character in charset '$charset'
460
461The field is created with an utf8 string which only contains data from the
462specified character set.  However, that character set can never be a valid
463name because it contains characters which are not permitted.
464
465=item Warning: Illegal character in field name $name
466
467A new field is being created which does contain characters not permitted
468by the RFCs.  Using this field in messages may break other e-mail clients
469or transfer agents, and therefore mutulate or extinguish your message.
470
471=item Warning: Illegal character in language '$lang'
472
473The field is created with data which is specified to be in a certain language,
474however, the name of the language cannot be valid: it contains characters
475which are not permitted by the RFCs.
476
477=item Warning: Illegal encoding '$encoding', used 'q'
478
479The RFCs only permit base64 (C<b > or C<B >) or quoted-printable
480(C<q> or C<Q>) encoding.  Other than these four options are illegal.
481
482=item Error: No attributes for date fields.
483
484It is not possible to add attributes to date fields: it is not permitted
485by the RFCs.
486
487=item Error: Package $package does not implement $method.
488
489Fatal error: the specific package (or one of its superclasses) does not
490implement this method where it should. This message means that some other
491related classes do implement this method however the class at hand does
492not.  Probably you should investigate this and probably inform the author
493of the package.
494
495=back
496
497=head1 SEE ALSO
498
499This module is part of Mail-Message distribution version 3.011,
500built on July 27, 2021. Website: F<http://perl.overmeer.net/CPAN/>
501
502=head1 LICENSE
503
504Copyrights 2001-2021 by [Mark Overmeer <markov@cpan.org>]. For other contributors see ChangeLog.
505
506This program is free software; you can redistribute it and/or modify it
507under the same terms as Perl itself.
508See F<http://dev.perl.org/licenses/>
509
510