1Mail::Box::Parser(3)  User Contributed Perl Documentation Mail::Box::Parser(3)
2
3
4

NAME

6       Mail::Box::Parser - reading and writing messages
7

INHERITANCE

9        Mail::Box::Parser
10          is a Mail::Reporter
11
12        Mail::Box::Parser is extended by
13          Mail::Box::Parser::C
14          Mail::Box::Parser::Perl
15

SYNOPSIS

17        # Not instatiatiated itself
18

DESCRIPTION

20       The "Mail::Box::Parser" manages the parsing of folders.  Usually, you
21       won't need to know anything about this module, except the options which
22       are involved with this code.
23
24       There are two implementations of this module planned:
25
26       •   Mail::Box::Parser::Perl
27
28           A slower parser which only uses plain Perl.  This module is a bit
29           slower, and does less checking and less recovery.
30
31       •   Mail::Box::Parser::C
32
33           A fast parser written in "C".  This package is released as separate
34           module on CPAN, because the module distribution via CPAN can not
35           handle XS files which are not located in the root directory of the
36           module tree.  If a C compiler is available on your system, it will
37           be used automatically.
38
39       Extends "DESCRIPTION" in Mail::Reporter.
40

METHODS

42       Extends "METHODS" in Mail::Reporter.
43
44   Constructors
45       Extends "Constructors" in Mail::Reporter.
46
47       Mail::Box::Parser->new(%options)
48           Create a parser object which can handle one file.  For mbox-like
49           mailboxes, this object can be used to read a whole folder.  In case
50           of MH-like mailboxes, each message is contained in a single file,
51           so each message has its own parser object.
52
53            -Option  --Defined in     --Default
54             file                       undef
55             filename                   <required>
56             log       Mail::Reporter   'WARNINGS'
57             mode                       'r'
58             trace     Mail::Reporter   'WARNINGS'
59
60           file => FILE-HANDLE
61             Any "IO::File" or "GLOB" which can be used to read the data from.
62             In case this option is specified, the "filename" is informational
63             only.
64
65           filename => FILENAME
66             The name of the file to be read.
67
68           log => LEVEL
69           mode => OPENMODE
70             File-open mode, which defaults to 'r', which means `read-only'.
71             See "perldoc -f open" for possible modes.  Only applicable when
72             no "file" is specified.
73
74           trace => LEVEL
75
76   The parser
77       $obj->fileChanged()
78           Returns whether the file which is parsed has changed after the last
79           time takeFileInfo() was called.
80
81       $obj->filename()
82           Returns the name of the file this parser is working on.
83
84       $obj->restart()
85           Restart the parser on a certain file, usually because the content
86           has changed.
87
88       $obj->start(%options)
89           Start the parser by opening a file.
90
91            -Option--Default
92             file    undef
93
94           file => FILEHANDLE|undef
95             The file is already open, for instance because the data must be
96             read from STDIN.
97
98       $obj->stop()
99           Stop the parser, which will include a close of the file.  The lock
100           on the folder will not be removed (is not the responsibility of the
101           parser).
102
103   Parsing
104       $obj->bodyAsFile( $fh [$chars, [$lines]] )
105           Try to read one message-body from the file, and immediately write
106           it to the specified file-handle.  Optionally, the predicted number
107           of CHARacterS and/or $lines to be read can be supplied.  These
108           values may be "undef" and may be wrong.
109
110           The return is a list of three scalars: the location of the body
111           (begin and end) and the number of lines in the body.
112
113       $obj->bodyAsList( [$chars, [$lines]] )
114           Try to read one message-body from the file.  Optionally, the
115           predicted number of CHARacterS and/or $lines to be read can be
116           supplied.  These values may be "undef" and may be wrong.
117
118           The return is a list of scalars, each containing one line
119           (including line terminator), preceded by two integers representing
120           the location in the file where this body started and ended.
121
122       $obj->bodyAsString( [$chars, [$lines]] )
123           Try to read one message-body from the file.  Optionally, the
124           predicted number of CHARacterS and/or $lines to be read can be
125           supplied.  These values may be "undef" and may be wrong.
126
127           The return is a list of three scalars, the location in the file
128           where the body starts, where the body ends, and the string
129           containing the whole body.
130
131       $obj->bodyDelayed( [$chars, [$lines]] )
132           Try to read one message-body from the file, but the data is
133           skipped.  Optionally, the predicted number of CHARacterS and/or
134           $lines to be skipped can be supplied.  These values may be "undef"
135           and may be wrong.
136
137           The return is a list of four scalars: the location of the body
138           (begin and end), the size of the body, and the number of lines in
139           the body.  The number of lines may be "undef".
140
141       $obj->filePosition( [$position] )
142           Returns the location of the next byte to be used in the file which
143           is parsed.  When a $position is specified, the location in the file
144           is moved to the indicated spot first.
145
146       $obj->lineSeparator()
147           Returns the character or characters which are used to separate
148           lines in the folder file.  This is based on the first line of the
149           file.  UNIX systems use a single LF to separate lines.  Windows
150           uses a CR and a LF.  Mac uses CR.
151
152       $obj->popSeparator()
153           Remove the last-pushed separator from the list which is maintained
154           by the parser.  This will return "undef" when there is none left.
155
156       $obj->pushSeparator(STRING|Regexp)
157           Add a boundary line.  Separators tell the parser where to stop
158           reading.  A famous separator is the "From"-line, which is used in
159           Mbox-like folders to separate messages.  But also parts
160           (attachments) is a message are divided by separators.
161
162           The specified STRING describes the start of the separator-line.
163           The Regexp can specify a more complicated format.
164
165       $obj->readHeader()
166           Read the whole message-header and return it as list of field-value
167           pairs.  Mind that some fields will appear more than once.
168
169           The first element will represent the position in the file where the
170           header starts.  The follows the list of header field names and
171           bodies.
172
173           example:
174
175            my ($where, @header) = $parser->readHeader;
176
177       $obj->readSeparator(%options)
178           Read the currently active separator (the last one which was
179           pushed).  The line (or "undef") is returned.  Blank-lines before
180           the separator lines are ignored.
181
182           The return are two scalars, where the first gives the location of
183           the separator in the file, and the second the line which is found
184           as separator.  A new separator is activated using pushSeparator().
185
186   Internals
187       $obj->closeFile()
188           Close the file which was being parsed.
189
190       $obj->defaultParserType( [$class] )
191       Mail::Box::Parser->defaultParserType( [$class] )
192           Returns the parser to be used to parse all subsequent messages,
193           possibly first setting the parser using the optional argument.
194           Usually, the parser is autodetected; the "C"-based parser will be
195           used when it can be, and the Perl-based parser will be used
196           otherwise.
197
198           The $class argument allows you to specify a package name to force a
199           particular parser to be used (such as your own custom parser). You
200           have to "use" or "require" the package yourself before calling this
201           method with an argument. The parser must be a sub-class of
202           "Mail::Box::Parser".
203
204       $obj->openFile($args)
205           Open the file to be parsed.  $args is a ref-hash of options.
206
207            -Option  --Default
208             filename  <required>
209             mode      <required>
210
211           filename => FILENAME
212           mode => STRING
213       $obj->takeFileInfo()
214           Capture some data about the file being parsed, to be compared
215           later.
216
217   Error handling
218       Extends "Error handling" in Mail::Reporter.
219
220       $obj->AUTOLOAD()
221           Inherited, see "Error handling" in Mail::Reporter
222
223       $obj->addReport($object)
224           Inherited, see "Error handling" in Mail::Reporter
225
226       $obj->defaultTrace( [$level]|[$loglevel, $tracelevel]|[$level,
227       $callback] )
228       Mail::Box::Parser->defaultTrace( [$level]|[$loglevel,
229       $tracelevel]|[$level, $callback] )
230           Inherited, see "Error handling" in Mail::Reporter
231
232       $obj->errors()
233           Inherited, see "Error handling" in Mail::Reporter
234
235       $obj->log( [$level, [$strings]] )
236       Mail::Box::Parser->log( [$level, [$strings]] )
237           Inherited, see "Error handling" in Mail::Reporter
238
239       $obj->logPriority($level)
240       Mail::Box::Parser->logPriority($level)
241           Inherited, see "Error handling" in Mail::Reporter
242
243       $obj->logSettings()
244           Inherited, see "Error handling" in Mail::Reporter
245
246       $obj->notImplemented()
247           Inherited, see "Error handling" in Mail::Reporter
248
249       $obj->report( [$level] )
250           Inherited, see "Error handling" in Mail::Reporter
251
252       $obj->reportAll( [$level] )
253           Inherited, see "Error handling" in Mail::Reporter
254
255       $obj->trace( [$level] )
256           Inherited, see "Error handling" in Mail::Reporter
257
258       $obj->warnings()
259           Inherited, see "Error handling" in Mail::Reporter
260
261   Cleanup
262       Extends "Cleanup" in Mail::Reporter.
263
264       $obj->DESTROY()
265           Inherited, see "Cleanup" in Mail::Reporter
266

DIAGNOSTICS

268       Warning: File $filename changed during access.
269           When a message parser starts working, it takes size and
270           modification time of the file at hand.  If the folder is written,
271           it checks whether there were changes in the file made by external
272           programs.
273
274           Calling Mail::Box::update() on a folder before it being closed will
275           read these new messages.  But the real source of this problem is
276           locking: some external program (for instance the mail transfer
277           agent, like sendmail) uses a different locking mechanism as you do
278           and therefore violates your rights.
279
280       Error: Filename or handle required to create a parser.
281           A message parser needs to know the source of the message at
282           creation.  These sources can be a filename (string), file handle
283           object or GLOB.  See new(filename) and new(file).
284
285       Error: Package $package does not implement $method.
286           Fatal error: the specific package (or one of its superclasses) does
287           not implement this method where it should. This message means that
288           some other related classes do implement this method however the
289           class at hand does not.  Probably you should investigate this and
290           probably inform the author of the package.
291

SEE ALSO

293       This module is part of Mail-Message distribution version 3.011, built
294       on July 27, 2021. Website: http://perl.overmeer.net/CPAN/
295

LICENSE

297       Copyrights 2001-2021 by [Mark Overmeer <markov@cpan.org>]. For other
298       contributors see ChangeLog.
299
300       This program is free software; you can redistribute it and/or modify it
301       under the same terms as Perl itself.  See http://dev.perl.org/licenses/
302
303
304
305perl v5.34.0                      2021-07-27              Mail::Box::Parser(3)
Impressum