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