1Mail::Box::Parser(3) User Contributed Perl Documentation Mail::Box::Parser(3)
2
6 Mail::Box::Parser - reading and writing messages
7
9 Mail::Box::Parser
10 is a Mail::Reporter
11 Mail::Box::Parser is extended by
13 Mail::Box::Parser::Perl
14
16 # Not instatiatiated itself
17
19 The "Mail::Box::Parser" manages the parsing of folders. Usually, you
20 won't need to know anything about this module, except the options which
21 are involved with this code.
22 There are two implementations of this module planned:
24 * Mail::Box::Parser::Perl
26 A slower parser which only uses plain Perl. This module is a bit
27 slower, and does less checking and less recovery.
28 * Mail::Box::Parser::C
30 A fast parser written in "C". This package is released as separate
31 module on CPAN, because the module distribution via CPAN can not
32 handle XS files which are not located in the root directory of the
33 module tree. If a C compiler is available on your system, it will
34 be used automatically.
35
37 Constructors
38 Mail::Box::Parser->new(OPTIONS)
40 Create a parser object which can handle one file. For mbox-like
42 mailboxes, this object can be used to read a whole folder. In case
43 of MH-like mailboxes, each message is contained in a single file,
44 so each message has its own parser object.
45 Option --Defined in --Default
47 file undef
48 filename <required>
49 log Mail::Reporter 'WARNINGS'
50 mode 'r'
51 trace Mail::Reporter 'WARNINGS'
52 . file FILE-HANDLE
54 Any "IO::File" or "GLOB" which can be used to read the data
56 from. In case this option is specified, the "filename" is
57 informational only.
58 . filename FILENAME
60 The name of the file to be read.
62 . log LEVEL
64 . mode OPENMODE
66 File-open mode, which defaults to 'r', which means `read-only'.
68 See "perldoc -f open" for possible modes. Only applicable when
69 no "file" is specified.
70 . trace LEVEL
72 The parser
74 $obj->fileChanged
76 Returns whether the file which is parsed has changed after the last
78 time takeFileInfo() was called.
79 $obj->filename
81 Returns the name of the file this parser is working on.
83 $obj->restart
85 Restart the parser on a certain file, usually because the content
87 has changed.
88 $obj->start(OPTIONS)
90 Start the parser by opening a file.
92 Option--Default
94 file undef
95 . file FILEHANDLE⎪undef
97 The file is already open, for instance because the data must be
99 read from STDIN.
100 $obj->stop
102 Stop the parser, which will include a close of the file. The lock
104 on the folder will not be removed (is not the responsibility of the
105 parser).
106 Parsing
108 $obj->bodyAsFile(FILEHANDLE [,CHARS [,LINES]])
110 Try to read one message-body from the file, and immediately write
112 it to the specified file-handle. Optionally, the predicted number
113 of CHARacterS and/or LINES to be read can be supplied. These val‐
114 ues may be "undef" and may be wrong.
115 The return is a list of three scalars: the location of the body
117 (begin and end) and the number of lines in the body.
118 $obj->bodyAsList([,CHARS [,LINES]])
120 Try to read one message-body from the file. Optionally, the pre‐
122 dicted number of CHARacterS and/or LINES to be read can be sup‐
123 plied. These values may be "undef" and may be wrong.
124 The return is a list of scalars, each containing one line (includ‐
126 ing line terminator), preceded by two integers representing the
127 location in the file where this body started and ended.
128 $obj->bodyAsString([,CHARS [,LINES]])
130 Try to read one message-body from the file. Optionally, the pre‐
132 dicted number of CHARacterS and/or LINES to be read can be sup‐
133 plied. These values may be "undef" and may be wrong.
134 The return is a list of three scalars, the location in the file
136 where the body starts, where the body ends, and the string contain‐
137 ing the whole body.
138 $obj->bodyDelayed([,CHARS [,LINES]])
140 Try to read one message-body from the file, but the data is
142 skipped. Optionally, the predicted number of CHARacterS and/or
143 LINES to be skipped can be supplied. These values may be "undef"
144 and may be wrong.
145 The return is a list of four scalars: the location of the body
147 (begin and end), the size of the body, and the number of lines in
148 the body. The number of lines may be "undef".
149 $obj->filePosition([POSITION])
151 Returns the location of the next byte to be used in the file which
153 is parsed. When a POSITION is specified, the location in the file
154 is moved to the indicated spot first.
155 $obj->lineSeparator
157 Returns the character or characters which are used to separate
159 lines in the folder file. This is based on the first line of the
160 file. UNIX systems use a single LF to separate lines. Windows
161 uses a CR and a LF. Mac uses CR.
162 $obj->popSeparator
164 Remove the last-pushed separator from the list which is maintained
166 by the parser. This will return "undef" when there is none left.
167 $obj->pushSeparator(STRING⎪REGEXP)
169 Add a boundary line. Separators tell the parser where to stop
171 reading. A famous separator is the "From"-line, which is used in
172 Mbox-like folders to separate messages. But also parts (attach‐
173 ments) is a message are divided by separators.
174 The specified STRING describes the start of the separator-line.
176 The REGEXP can specify a more complicated format.
177 $obj->readHeader
179 Read the whole message-header and return it as list of field-value
181 pairs. Mind that some fields will appear more than once.
182 The first element will represent the position in the file where the
184 header starts. The follows the list of header field names and bod‐
185 ies.
186 Example:
188 my ($where, @header) = $parser->readHeader;
190 $obj->readSeparator(OPTIONS)
192 Read the currently active separator (the last one which was
194 pushed). The line (or "undef") is returned. Blank-lines before
195 the separator lines are ignored.
196 The return are two scalars, where the first gives the location of
198 the separator in the file, and the second the line which is found
199 as separator. A new separator is activated using pushSeparator().
200 Internals
202 $obj->closeFile
204 Close the file which was being parsed.
206 $obj->defaultParserType([CLASS])
208 Mail::Box::Parser->defaultParserType([CLASS])
210 Returns the parser to be used to parse all subsequent messages,
212 possibly first setting the parser using the optional argument.
213 Usually, the parser is autodetected; the "C"-based parser will be
214 used when it can be, and the Perl-based parser will be used other‐
215 wise.
216 The CLASS argument allows you to specify a package name to force a
218 particular parser to be used (such as your own custom parser). You
219 have to "use" or "require" the package yourself before calling this
220 method with an argument. The parser must be a sub-class of
221 "Mail::Box::Parser".
222 $obj->openFile(ARGS)
224 Open the file to be parsed. ARGS is a ref-hash of options.
226 Option --Default
228 filename <required>
229 mode <required>
230 . filename FILENAME
232 . mode STRING
234 $obj->takeFileInfo
236 Capture some data about the file being parsed, to be compared
238 later.
239 Error handling
241 $obj->AUTOLOAD
243 See "Error handling" in Mail::Reporter
245 $obj->addReport(OBJECT)
247 See "Error handling" in Mail::Reporter
249 $obj->defaultTrace([LEVEL]⎪[LOGLEVEL, TRACELEVEL]⎪[LEVEL, CALLBACK])
251 Mail::Box::Parser->defaultTrace([LEVEL]⎪[LOGLEVEL, TRACELEVEL]⎪[LEVEL,
253 CALLBACK])
254 See "Error handling" in Mail::Reporter
256 $obj->errors
258 See "Error handling" in Mail::Reporter
260 $obj->log([LEVEL [,STRINGS]])
262 Mail::Box::Parser->log([LEVEL [,STRINGS]])
264 See "Error handling" in Mail::Reporter
266 $obj->logPriority(LEVEL)
268 Mail::Box::Parser->logPriority(LEVEL)
270 See "Error handling" in Mail::Reporter
272 $obj->logSettings
274 See "Error handling" in Mail::Reporter
276 $obj->notImplemented
278 See "Error handling" in Mail::Reporter
280 $obj->report([LEVEL])
282 See "Error handling" in Mail::Reporter
284 $obj->reportAll([LEVEL])
286 See "Error handling" in Mail::Reporter
288 $obj->trace([LEVEL])
290 See "Error handling" in Mail::Reporter
292 $obj->warnings
294 See "Error handling" in Mail::Reporter
296 Cleanup
298 $obj->DESTROY
300 See "Cleanup" in Mail::Reporter
302 $obj->inGlobalDestruction
304 See "Cleanup" in Mail::Reporter
306
308 Warning: File $filename changed during access.
309 When a message parser starts working, it takes size and modification
311 time of the file at hand. If the folder is written, it checks wether
312 there were changes in the file made by external programs.
313 Calling Mail::Box::update() on a folder before it being closed will
315 read these new messages. But the real source of this problem is lock‐
316 ing: some external program (for instance the mail transfer agent, like
317 sendmail) uses a different locking mechanism as you do and therefore
318 violates your rights.
319 Error: Filename or handle required to create a parser.
321 A message parser needs to know the source of the message at creation.
323 These sources can be a filename (string), file handle object or GLOB.
324 See new(filename) and new(file).
325 Error: Package $package does not implement $method.
327 Fatal error: the specific package (or one of its superclasses) does not
329 implement this method where it should. This message means that some
330 other related classes do implement this method however the class at
331 hand does not. Probably you should investigate this and probably
332 inform the author of the package.
333
335 This module is part of Mail-Box distribution version 2.070, built on
336 March 25, 2007. Website: http://perl.overmeer.net/mailbox/
337
339 Copyrights 2001-2007 by Mark Overmeer.For other contributors see
340 ChangeLog.
341 This program is free software; you can redistribute it and/or modify it
343 under the same terms as Perl itself. See
344 http://www.perl.com/perl/misc/Artistic.html
345perl v5.8.8 2007-03-25 Mail::Box::Parser(3)