1Mail::Message::Field::SUtsreurctCuornetdr(i3b)uted PerlMDaoiclu:m:eMnetsastaigoen::Field::Structured(3)
2
6 Mail::Message::Field::Structured - one line of a structured message
7 header
8
10 Mail::Message::Field::Structured
11 is a Mail::Message::Field::Full
12 is a Mail::Message::Field
13 is a Mail::Reporter
14 Mail::Message::Field::Structured is extended by
16 Mail::Message::Field::Addresses
17 Mail::Message::Field::URIs
18
20 my $f = Mail::Message::Field::Full
21 ->new('Content-Type' => 'text/html');
22 my @encode = (charset => 'jp', use_continuations => 1);
24 $f->attribute('filename=passwd');
25 $f->attribute(filename => 'passwd', @encode);
26 my $attr = Mail::Message::Field::Attribute->new(...);
28 $f->attribute($attr);
29
31 overload: ""
32 See "OVERLOADED" in Mail::Message::Field
33 overload: +0
35 See "OVERLOADED" in Mail::Message::Field
36 overload: <=>
38 See "OVERLOADED" in Mail::Message::Field
39 overload: bool
41 See "OVERLOADED" in Mail::Message::Field
42 overload: cmp
44 See "OVERLOADED" in Mail::Message::Field
45 overload: stringification
47 See "OVERLOADED" in Mail::Message::Field::Full
48
50 Constructors
51 $obj->clone
52 See "Constructors" in Mail::Message::Field
53 Mail::Message::Field::Structured->from(FIELD, OPTIONS)
55 See "Constructors" in Mail::Message::Field::Full
56 Mail::Message::Field::Structured->new(DATA)
58 · new LINE
59 Pass a LINE as it could be found in a file: a (possibly folded)
61 line which is terminated by a new-line.
62 · new NAME, BODY, OPTIONS
64 A set of values which shape the line.
66 The NAME is a wellformed header name (you may use wellformedName())
68 to be sure about the casing. The BODY is a string, one object, or
69 an ref-array of objects. In case of objects, they must fit to the
70 constructor of the field: the types which are accepted may differ.
71 The optional ATTRIBUTE list contains
72 Mail::Message::Field::Attribute objects. Finally, there are some
73 OPTIONS.
74 -Option --Defined in --Default
76 attributes []
77 charset Mail::Message::Field::Full undef
78 datum undef
79 encoding Mail::Message::Field::Full 'q'
80 force Mail::Message::Field::Full false
81 language Mail::Message::Field::Full undef
82 log Mail::Reporter 'WARNINGS'
83 trace Mail::Reporter 'WARNINGS'
84 attributes => ATTRS
86 There are various ways to specify these attributes: pass a
87 reference to an array which list of key-value pairs representing
88 attributes, or reference to a hash containing these pairs, or an
89 array with Mail::Message::Field::Attribute objects.
90 charset => STRING
92 datum => STRING
93 The method name body is very confusing, even in the RFC. In
94 MailBox, for historical reasons, body() returns the past of the
95 field contents before the first semi-colon. foldedBody() and
96 unfoldedBody() address the whole field.
97 There is no common name for the piece of data before the
99 parameters (attributes) in the field-content mentioned in the
100 RFCs, so let's call it datum.
101 encoding => 'q'|'Q'|'b'|'B'
103 force => BOOLEAN
104 language => STRING
105 log => LEVEL
106 trace => LEVEL
107 example: of a structured field
109 my @attrs = (Mail::Message::Field::Attribute->new(...), ...);
111 my @options = (extra => 'the color blue');
112 my $t = Mail::Message::Field::Full->new(To => \@addrs, @attrs, @options);
113 The field
115 $obj->isStructured
116 Mail::Message::Field::Structured->isStructured
117 See "The field" in Mail::Message::Field
119 $obj->length
121 See "The field" in Mail::Message::Field
122 $obj->nrLines
124 See "The field" in Mail::Message::Field
125 $obj->print([FILEHANDLE])
127 See "The field" in Mail::Message::Field
128 $obj->size
130 See "The field" in Mail::Message::Field
131 $obj->string([WRAP])
133 See "The field" in Mail::Message::Field
134 $obj->toDisclose
136 See "The field" in Mail::Message::Field
137 Access to the name
139 $obj->Name
140 See "Access to the name" in Mail::Message::Field
141 $obj->name
143 See "Access to the name" in Mail::Message::Field
144 $obj->wellformedName([STRING])
146 See "Access to the name" in Mail::Message::Field
147 Access to the body
149 $obj->body
150 See "Access to the body" in Mail::Message::Field
151 $obj->decodedBody(OPTIONS)
153 See "Access to the body" in Mail::Message::Field::Full
154 $obj->folded
156 See "Access to the body" in Mail::Message::Field
157 $obj->foldedBody([BODY])
159 See "Access to the body" in Mail::Message::Field
160 $obj->stripCFWS([STRING])
162 Mail::Message::Field::Structured->stripCFWS([STRING])
163 See "Access to the body" in Mail::Message::Field
165 $obj->unfoldedBody([BODY, [WRAP]])
167 See "Access to the body" in Mail::Message::Field
168 Access to the content
170 $obj->addresses
171 See "Access to the content" in Mail::Message::Field
172 $obj->attribute(OBJECT|(STRING, OPTIONS)|(NAME,VALUE,OPTIONS))
174 Add an attribute to the field. The attributes are added left-to-
175 right into the string representation of the field, although the
176 order of the attributes is un-important, according to the RFCs.
177 You may pass a fully prepared Mail::Message::Field::Attribute
179 OBJECT, if you like to do all preparations for correct
180 representation of the data yourself. You may also pass one STRING,
181 which is a fully prepared attribute. This STRING will not be
182 changed, so be careful about quoting and encodings.
183 As third possibility, you can specify an attribute NAME and its
185 VALUE. An attribute object will be created for you implicitly in
186 both cases where such object is not supplied, passing the OPTIONS.
187 See Mail::Message::Field::Attribute::new() about the available
188 OPTIONS.
189 The attribute object is returned, however, when continuations are
191 used this may be an object you already know about. "undef" is
192 returned when construction fails (when the attribute is incorrect).
193 example:
195 $f->attribute(filename => 'passwd');
197 $f->attribute(filename => 'passwd', use_continuations => 0);
198 my $attr = Mail::Message::Field::Attribute->new(...);
200 $f->attribute($attr);
201 $obj->attributes
203 Returns a list with all attributes, which are all
204 Mail::Message::Field::Attribute objects. The attributes are not
205 ordered in any way. The list may be empty. Double attributes or
206 continuations are folded into one.
207 $obj->beautify
209 See "Access to the content" in Mail::Message::Field::Full
210 $obj->comment([STRING])
212 See "Access to the content" in Mail::Message::Field
213 $obj->createComment(STRING, OPTIONS)
215 Mail::Message::Field::Structured->createComment(STRING, OPTIONS)
216 See "Access to the content" in Mail::Message::Field::Full
218 $obj->createPhrase(STRING, OPTIONS)
220 Mail::Message::Field::Structured->createPhrase(STRING, OPTIONS)
221 See "Access to the content" in Mail::Message::Field::Full
223 $obj->study
225 See "Access to the content" in Mail::Message::Field
226 $obj->toDate([TIME])
228 Mail::Message::Field::Structured->toDate([TIME])
229 See "Access to the content" in Mail::Message::Field
231 $obj->toInt
233 See "Access to the content" in Mail::Message::Field
234 Other methods
236 $obj->dateToTimestamp(STRING)
237 Mail::Message::Field::Structured->dateToTimestamp(STRING)
238 See "Other methods" in Mail::Message::Field
240 Internals
242 $obj->consume(LINE | (NAME,BODY|OBJECTS))
243 See "Internals" in Mail::Message::Field
244 $obj->decode(STRING, OPTIONS)
246 Mail::Message::Field::Structured->decode(STRING, OPTIONS)
247 See "Internals" in Mail::Message::Field::Full
249 $obj->defaultWrapLength([LENGTH])
251 See "Internals" in Mail::Message::Field
252 $obj->encode(STRING, OPTIONS)
254 See "Internals" in Mail::Message::Field::Full
255 $obj->fold(NAME, BODY, [MAXCHARS])
257 Mail::Message::Field::Structured->fold(NAME, BODY, [MAXCHARS])
258 See "Internals" in Mail::Message::Field
260 $obj->setWrapLength([LENGTH])
262 See "Internals" in Mail::Message::Field
263 $obj->stringifyData(STRING|ARRAY|OBJECTS)
265 See "Internals" in Mail::Message::Field
266 $obj->unfold(STRING)
268 See "Internals" in Mail::Message::Field
269 Parsing
271 $obj->consumeComment(STRING)
272 Mail::Message::Field::Structured->consumeComment(STRING)
273 See "Parsing" in Mail::Message::Field::Full
275 $obj->consumeDotAtom(STRING)
277 See "Parsing" in Mail::Message::Field::Full
278 $obj->consumePhrase(STRING)
280 Mail::Message::Field::Structured->consumePhrase(STRING)
281 See "Parsing" in Mail::Message::Field::Full
283 $obj->datum([VALUE])
285 Equivalent to body(), but maybe less confusing.
286 $obj->parse(STRING)
288 See "Parsing" in Mail::Message::Field::Full
289 $obj->produceBody
291 See "Parsing" in Mail::Message::Field::Full
292 Error handling
294 $obj->AUTOLOAD
295 See "Error handling" in Mail::Reporter
296 $obj->addReport(OBJECT)
298 See "Error handling" in Mail::Reporter
299 $obj->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK])
301 Mail::Message::Field::Structured->defaultTrace([LEVEL]|[LOGLEVEL,
302 TRACELEVEL]|[LEVEL, CALLBACK])
303 See "Error handling" in Mail::Reporter
305 $obj->errors
307 See "Error handling" in Mail::Reporter
308 $obj->log([LEVEL [,STRINGS]])
310 Mail::Message::Field::Structured->log([LEVEL [,STRINGS]])
311 See "Error handling" in Mail::Reporter
313 $obj->logPriority(LEVEL)
315 Mail::Message::Field::Structured->logPriority(LEVEL)
316 See "Error handling" in Mail::Reporter
318 $obj->logSettings
320 See "Error handling" in Mail::Reporter
321 $obj->notImplemented
323 See "Error handling" in Mail::Reporter
324 $obj->report([LEVEL])
326 See "Error handling" in Mail::Reporter
327 $obj->reportAll([LEVEL])
329 See "Error handling" in Mail::Reporter
330 $obj->trace([LEVEL])
332 See "Error handling" in Mail::Reporter
333 $obj->warnings
335 See "Error handling" in Mail::Reporter
336 Cleanup
338 $obj->DESTROY
339 See "Cleanup" in Mail::Reporter
340 $obj->inGlobalDestruction
342 See "Cleanup" in Mail::Reporter
343
345 Warning: Field content is not numerical: $content
346 The numeric value of a field is requested (for instance the "Lines"
347 or "Content-Length" fields should be numerical), however the data
348 contains weird characters.
349 Warning: Illegal character in charset '$charset'
351 The field is created with an utf8 string which only contains data
352 from the specified character set. However, that character set can
353 never be a valid name because it contains characters which are not
354 permitted.
355 Warning: Illegal character in field name $name
357 A new field is being created which does contain characters not
358 permitted by the RFCs. Using this field in messages may break
359 other e-mail clients or transfer agents, and therefore mutulate or
360 extinguish your message.
361 Warning: Illegal character in language '$lang'
363 The field is created with data which is specified to be in a
364 certain language, however, the name of the language cannot be
365 valid: it contains characters which are not permitted by the RFCs.
366 Warning: Illegal encoding '$encoding', used 'q'
368 The RFCs only permit base64 ("b " or "B ") or quoted-printable ("q"
369 or "Q") encoding. Other than these four options are illegal.
370 Error: Package $package does not implement $method.
372 Fatal error: the specific package (or one of its superclasses) does
373 not implement this method where it should. This message means that
374 some other related classes do implement this method however the
375 class at hand does not. Probably you should investigate this and
376 probably inform the author of the package.
377
379 This module is part of Mail-Box distribution version 2.097, built on
380 January 26, 2011. Website: http://perl.overmeer.net/mailbox/
381
383 Copyrights 2001-2011 by Mark Overmeer. For other contributors see
384 ChangeLog.
385 This program is free software; you can redistribute it and/or modify it
387 under the same terms as Perl itself. See
388 http://www.perl.com/perl/misc/Artistic.html
389perl v5.12.3 2011-01-26Mail::Message::Field::Structured(3)