Mail::Message::Field::Structured(3pm)

1Mail::Message::Field::SUtsreurctCuornetdr(i3b)uted PerlMDaoiclu:m:eMnetsastaigoen::Field::Structured(3)
2
3
4

NAME

6       Mail::Message::Field::Structured - one line of a structured message
7       header
8

INHERITANCE

10        Mail::Message::Field::Structured
11          is a Mail::Message::Field::Full
12          is a Mail::Message::Field
13          is a Mail::Reporter
14
15        Mail::Message::Field::Structured is extended by
16          Mail::Message::Field::Addresses
17          Mail::Message::Field::AuthResults
18          Mail::Message::Field::DKIM
19          Mail::Message::Field::Date
20          Mail::Message::Field::URIs
21

SYNOPSIS

23        my $f = Mail::Message::Field::Full
24                   ->new('Content-Type' => 'text/html');
25
26        my @encode = (charset => 'jp', use_continuations => 1);
27        $f->attribute('filename=passwd');
28        $f->attribute(filename => 'passwd', @encode);
29
30        my $attr = Mail::Message::Field::Attribute->new(...);
31        $f->attribute($attr);
32

DESCRIPTION

34       Extends "DESCRIPTION" in Mail::Message::Field::Full.
35

OVERLOADED

37       Extends "OVERLOADED" in Mail::Message::Field::Full.
38
39       overload: ""
40           Inherited, see "OVERLOADED" in Mail::Message::Field
41
42       overload: 0+
43           Inherited, see "OVERLOADED" in Mail::Message::Field
44
45       overload: <=>
46           Inherited, see "OVERLOADED" in Mail::Message::Field
47
48       overload: bool
49           Inherited, see "OVERLOADED" in Mail::Message::Field
50
51       overload: cmp
52           Inherited, see "OVERLOADED" in Mail::Message::Field
53
54       overload: stringification
55           Inherited, see "OVERLOADED" in Mail::Message::Field::Full
56

METHODS

58       Extends "METHODS" in Mail::Message::Field::Full.
59
60   Constructors
61       Extends "Constructors" in Mail::Message::Field::Full.
62
63       $obj->clone()
64           Inherited, see "Constructors" in Mail::Message::Field
65
66       Mail::Message::Field::Structured->from($field, %options)
67           Inherited, see "Constructors" in Mail::Message::Field::Full
68
69       Mail::Message::Field::Structured->new($data)
70           •   new LINE
71
72               Pass a LINE as it could be found in a file: a (possibly folded)
73               line which is terminated by a new-line.
74
75           •   new NAME, BODY, OPTIONS
76
77               A set of values which shape the line.
78
79           The NAME is a wellformed header name (you may use wellformedName())
80           to be sure about the casing.  The BODY is a string, one object, or
81           an ref-array of objects.  In case of objects, they must fit to the
82           constructor of the field: the types which are accepted may differ.
83           The optional ATTRIBUTE list contains
84           Mail::Message::Field::Attribute objects.  Finally, there are some
85           OPTIONS.
86
87            -Option    --Defined in                --Default
88             attributes                              []
89             charset     Mail::Message::Field::Full  undef
90             datum                                   undef
91             encoding    Mail::Message::Field::Full  'q'
92             force       Mail::Message::Field::Full  false
93             language    Mail::Message::Field::Full  undef
94             log         Mail::Reporter              'WARNINGS'
95             trace       Mail::Reporter              'WARNINGS'
96
97           attributes => ATTRS
98             There are various ways to specify these attributes: pass a
99             reference to an array which list of key-value pairs representing
100             attributes, or reference to a hash containing these pairs, or an
101             array with Mail::Message::Field::Attribute objects.
102
103           charset => STRING
104           datum => STRING
105             The method name body is very confusing, even in the RFC.  In
106             MailBox, for historical reasons, body() returns the part of the
107             field contents before the first semi-colon.  foldedBody() and
108             unfoldedBody() address the whole field.
109
110             There is no common name for the piece of data before the
111             parameters (attributes) in the field-content mentioned in the
112             RFCs, so let's call it datum.
113
114           encoding => 'q'|'Q'|'b'|'B'
115           force => BOOLEAN
116           language => STRING
117           log => LEVEL
118           trace => LEVEL
119
120           example: of a structured field
121
122            my @attrs   = (Mail::Message::Field::Attribute->new(...), ...);
123            my @options = (extra => 'the color blue');
124            my $t = Mail::Message::Field::Full->new(To => \@addrs, @attrs, @options);
125
126   The field
127       Extends "The field" in Mail::Message::Field::Full.
128
129       $obj->isStructured()
130       Mail::Message::Field::Structured->isStructured()
131           Inherited, see "The field" in Mail::Message::Field
132
133       $obj->length()
134           Inherited, see "The field" in Mail::Message::Field
135
136       $obj->nrLines()
137           Inherited, see "The field" in Mail::Message::Field
138
139       $obj->print( [$fh] )
140           Inherited, see "The field" in Mail::Message::Field
141
142       $obj->size()
143           Inherited, see "The field" in Mail::Message::Field
144
145       $obj->string( [$wrap] )
146           Inherited, see "The field" in Mail::Message::Field
147
148       $obj->toDisclose()
149           Inherited, see "The field" in Mail::Message::Field
150
151   Access to the name
152       Extends "Access to the name" in Mail::Message::Field::Full.
153
154       $obj->Name()
155           Inherited, see "Access to the name" in Mail::Message::Field
156
157       $obj->name()
158           Inherited, see "Access to the name" in Mail::Message::Field
159
160       $obj->wellformedName( [STRING] )
161           Inherited, see "Access to the name" in Mail::Message::Field
162
163   Access to the body
164       Extends "Access to the body" in Mail::Message::Field::Full.
165
166       $obj->body()
167           Inherited, see "Access to the body" in Mail::Message::Field
168
169       $obj->decodedBody(%options)
170           Inherited, see "Access to the body" in Mail::Message::Field::Full
171
172       $obj->folded()
173           Inherited, see "Access to the body" in Mail::Message::Field
174
175       $obj->foldedBody( [$body] )
176           Inherited, see "Access to the body" in Mail::Message::Field
177
178       $obj->stripCFWS( [STRING] )
179       Mail::Message::Field::Structured->stripCFWS( [STRING] )
180           Inherited, see "Access to the body" in Mail::Message::Field
181
182       $obj->unfoldedBody( [$body, [$wrap]] )
183           Inherited, see "Access to the body" in Mail::Message::Field
184
185   Access to the content
186       Extends "Access to the content" in Mail::Message::Field::Full.
187
188       $obj->addresses()
189           Inherited, see "Access to the content" in Mail::Message::Field
190
191       $obj->attrPairs()
192           Returns a list with attribute name and value pairs.
193
194       $obj->attribute( $object|<STRING, %options>|<$name,$value,%options> )
195           Add an attribute to the field.  The attributes are added left-to-
196           right into the string representation of the field, although the
197           order of the attributes is un-important, according to the RFCs.
198
199           You may pass a fully prepared Mail::Message::Field::Attribute
200           $object, if you like to do all preparations for correct
201           representation of the data yourself.  You may also pass one STRING,
202           which is a fully prepared attribute.  This STRING will not be
203           changed, so be careful about quoting and encodings.
204
205           As third possibility, you can specify an attribute $name and its
206           $value.  An attribute object will be created for you implicitly in
207           both cases where such object is not supplied, passing the %options.
208           See Mail::Message::Field::Attribute::new() about the available
209           %options.
210
211           The attribute object is returned, however, when continuations are
212           used this may be an object you already know about.  "undef" is
213           returned when construction fails (when the attribute is incorrect).
214
215           example:
216
217            $f->attribute(filename => 'passwd');
218            $f->attribute(filename => 'passwd', use_continuations => 0);
219
220            my $attr = Mail::Message::Field::Attribute->new(...);
221            $f->attribute($attr);
222
223       $obj->attributes()
224           Returns a list with all attributes, which are all
225           Mail::Message::Field::Attribute objects.  The attributes are not
226           ordered in any way.  The list may be empty.  Double attributes or
227           continuations are folded into one.
228
229       $obj->beautify()
230           Inherited, see "Access to the content" in
231           Mail::Message::Field::Full
232
233       $obj->comment( [STRING] )
234           Inherited, see "Access to the content" in Mail::Message::Field
235
236       $obj->createComment(STRING, %options)
237       Mail::Message::Field::Structured->createComment(STRING, %options)
238           Inherited, see "Access to the content" in
239           Mail::Message::Field::Full
240
241       $obj->createPhrase(STRING, %options)
242       Mail::Message::Field::Structured->createPhrase(STRING, %options)
243           Inherited, see "Access to the content" in
244           Mail::Message::Field::Full
245
246       $obj->study()
247           Inherited, see "Access to the content" in Mail::Message::Field
248
249       $obj->toDate( [$time] )
250       Mail::Message::Field::Structured->toDate( [$time] )
251           Inherited, see "Access to the content" in Mail::Message::Field
252
253       $obj->toInt()
254           Inherited, see "Access to the content" in Mail::Message::Field
255
256   Other methods
257       Extends "Other methods" in Mail::Message::Field::Full.
258
259       $obj->dateToTimestamp(STRING)
260       Mail::Message::Field::Structured->dateToTimestamp(STRING)
261           Inherited, see "Other methods" in Mail::Message::Field
262
263   Internals
264       Extends "Internals" in Mail::Message::Field::Full.
265
266       $obj->consume( $line | <$name,<$body|$objects>> )
267           Inherited, see "Internals" in Mail::Message::Field
268
269       $obj->decode(STRING, %options)
270       Mail::Message::Field::Structured->decode(STRING, %options)
271           Inherited, see "Internals" in Mail::Message::Field::Full
272
273       $obj->defaultWrapLength( [$length] )
274           Inherited, see "Internals" in Mail::Message::Field
275
276       $obj->encode(STRING, %options)
277           Inherited, see "Internals" in Mail::Message::Field::Full
278
279       $obj->fold( $name, $body, [$maxchars] )
280       Mail::Message::Field::Structured->fold( $name, $body, [$maxchars] )
281           Inherited, see "Internals" in Mail::Message::Field
282
283       $obj->setWrapLength( [$length] )
284           Inherited, see "Internals" in Mail::Message::Field
285
286       $obj->stringifyData(STRING|ARRAY|$objects)
287           Inherited, see "Internals" in Mail::Message::Field
288
289       $obj->unfold(STRING)
290           Inherited, see "Internals" in Mail::Message::Field
291
292   Parsing
293       Extends "Parsing" in Mail::Message::Field::Full.
294
295       $obj->consumeComment(STRING)
296       Mail::Message::Field::Structured->consumeComment(STRING)
297           Inherited, see "Parsing" in Mail::Message::Field::Full
298
299       $obj->consumeDotAtom(STRING)
300           Inherited, see "Parsing" in Mail::Message::Field::Full
301
302       $obj->consumePhrase(STRING)
303       Mail::Message::Field::Structured->consumePhrase(STRING)
304           Inherited, see "Parsing" in Mail::Message::Field::Full
305
306       $obj->datum( [$value] )
307           The part of the field before the semi-colon (";").
308
309       $obj->parse(STRING)
310           Inherited, see "Parsing" in Mail::Message::Field::Full
311
312       $obj->produceBody()
313           Inherited, see "Parsing" in Mail::Message::Field::Full
314
315   Error handling
316       Extends "Error handling" in Mail::Message::Field::Full.
317
318       $obj->AUTOLOAD()
319           Inherited, see "Error handling" in Mail::Reporter
320
321       $obj->addReport($object)
322           Inherited, see "Error handling" in Mail::Reporter
323
324       $obj->defaultTrace( [$level]|[$loglevel, $tracelevel]|[$level,
325       $callback] )
326       Mail::Message::Field::Structured->defaultTrace( [$level]|[$loglevel,
327       $tracelevel]|[$level, $callback] )
328           Inherited, see "Error handling" in Mail::Reporter
329
330       $obj->errors()
331           Inherited, see "Error handling" in Mail::Reporter
332
333       $obj->log( [$level, [$strings]] )
334       Mail::Message::Field::Structured->log( [$level, [$strings]] )
335           Inherited, see "Error handling" in Mail::Reporter
336
337       $obj->logPriority($level)
338       Mail::Message::Field::Structured->logPriority($level)
339           Inherited, see "Error handling" in Mail::Reporter
340
341       $obj->logSettings()
342           Inherited, see "Error handling" in Mail::Reporter
343
344       $obj->notImplemented()
345           Inherited, see "Error handling" in Mail::Reporter
346
347       $obj->report( [$level] )
348           Inherited, see "Error handling" in Mail::Reporter
349
350       $obj->reportAll( [$level] )
351           Inherited, see "Error handling" in Mail::Reporter
352
353       $obj->trace( [$level] )
354           Inherited, see "Error handling" in Mail::Reporter
355
356       $obj->warnings()
357           Inherited, see "Error handling" in Mail::Reporter
358
359   Cleanup
360       Extends "Cleanup" in Mail::Message::Field::Full.
361
362       $obj->DESTROY()
363           Inherited, see "Cleanup" in Mail::Reporter
364

DETAILS

366       Extends "DETAILS" in Mail::Message::Field::Full.
367

DIAGNOSTICS

369       Warning: Field content is not numerical: $content
370           The numeric value of a field is requested (for instance the "Lines"
371           or "Content-Length" fields should be numerical), however the data
372           contains weird characters.
373
374       Warning: Illegal character in charset '$charset'
375           The field is created with an utf8 string which only contains data
376           from the specified character set.  However, that character set can
377           never be a valid name because it contains characters which are not
378           permitted.
379
380       Warning: Illegal character in field name $name
381           A new field is being created which does contain characters not
382           permitted by the RFCs.  Using this field in messages may break
383           other e-mail clients or transfer agents, and therefore mutulate or
384           extinguish your message.
385
386       Warning: Illegal character in language '$lang'
387           The field is created with data which is specified to be in a
388           certain language, however, the name of the language cannot be
389           valid: it contains characters which are not permitted by the RFCs.
390
391       Warning: Illegal encoding '$encoding', used 'q'
392           The RFCs only permit base64 ("b " or "B ") or quoted-printable ("q"
393           or "Q") encoding.  Other than these four options are illegal.
394
395       Error: Package $package does not implement $method.
396           Fatal error: the specific package (or one of its superclasses) does
397           not implement this method where it should. This message means that
398           some other related classes do implement this method however the
399           class at hand does not.  Probably you should investigate this and
400           probably inform the author of the package.
401

LICENSE

407       Copyrights 2001-2022 by [Mark Overmeer <markov@cpan.org>]. For other
408       contributors see ChangeLog.
409
410       This program is free software; you can redistribute it and/or modify it
411       under the same terms as Perl itself.  See http://dev.perl.org/licenses/
412
413
414
415perl v5.36.0                      2023-01-20Mail::Message::Field::Structured(3)