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
28 slower, and does less checking and less recovery.
29 · Mail::Box::Parser::C
31 A fast parser written in "C". This package is released as separate
33 module on CPAN, because the module distribution via CPAN can not
34 handle XS files which are not located in the root directory of the
35 module tree. If a C compiler is available on your system, it will
36 be used automatically.
37
39 Constructors
40 Mail::Box::Parser->new(OPTIONS)
41 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 from.
55 In case this option is specified, the "filename" is informational
56 only.
57 filename => FILENAME
59 The name of the file to be read.
60 log => LEVEL
62 mode => OPENMODE
63 File-open mode, which defaults to 'r', which means `read-only'.
64 See "perldoc -f open" for possible modes. Only applicable when
65 no "file" is specified.
66 trace => LEVEL
68 The parser
70 $obj->fileChanged
71 Returns whether the file which is parsed has changed after the last
72 time takeFileInfo() was called.
73 $obj->filename
75 Returns the name of the file this parser is working on.
76 $obj->restart
78 Restart the parser on a certain file, usually because the content
79 has changed.
80 $obj->start(OPTIONS)
82 Start the parser by opening a file.
83 -Option--Default
85 file undef
86 file => FILEHANDLE|undef
88 The file is already open, for instance because the data must be
89 read from STDIN.
90 $obj->stop
92 Stop the parser, which will include a close of the file. The lock
93 on the folder will not be removed (is not the responsibility of the
94 parser).
95 Parsing
97 $obj->bodyAsFile(FILEHANDLE [,CHARS [,LINES]])
98 Try to read one message-body from the file, and immediately write
99 it to the specified file-handle. Optionally, the predicted number
100 of CHARacterS and/or LINES to be read can be supplied. These
101 values may be "undef" and may be wrong.
102 The return is a list of three scalars: the location of the body
104 (begin and end) and the number of lines in the body.
105 $obj->bodyAsList([,CHARS [,LINES]])
107 Try to read one message-body from the file. Optionally, the
108 predicted number of CHARacterS and/or LINES to be read can be
109 supplied. These values may be "undef" and may be wrong.
110 The return is a list of scalars, each containing one line
112 (including line terminator), preceded by two integers representing
113 the location in the file where this body started and ended.
114 $obj->bodyAsString([,CHARS [,LINES]])
116 Try to read one message-body from the file. Optionally, the
117 predicted number of CHARacterS and/or LINES to be read can be
118 supplied. These values may be "undef" and may be wrong.
119 The return is a list of three scalars, the location in the file
121 where the body starts, where the body ends, and the string
122 containing the whole body.
123 $obj->bodyDelayed([,CHARS [,LINES]])
125 Try to read one message-body from the file, but the data is
126 skipped. Optionally, the predicted number of CHARacterS and/or
127 LINES to be skipped can be supplied. These values may be "undef"
128 and may be wrong.
129 The return is a list of four scalars: the location of the body
131 (begin and end), the size of the body, and the number of lines in
132 the body. The number of lines may be "undef".
133 $obj->filePosition([POSITION])
135 Returns the location of the next byte to be used in the file which
136 is parsed. When a POSITION is specified, the location in the file
137 is moved to the indicated spot first.
138 $obj->lineSeparator
140 Returns the character or characters which are used to separate
141 lines in the folder file. This is based on the first line of the
142 file. UNIX systems use a single LF to separate lines. Windows
143 uses a CR and a LF. Mac uses CR.
144 $obj->popSeparator
146 Remove the last-pushed separator from the list which is maintained
147 by the parser. This will return "undef" when there is none left.
148 $obj->pushSeparator(STRING|REGEXP)
150 Add a boundary line. Separators tell the parser where to stop
151 reading. A famous separator is the "From"-line, which is used in
152 Mbox-like folders to separate messages. But also parts
153 (attachments) is a message are divided by separators.
154 The specified STRING describes the start of the separator-line.
156 The REGEXP can specify a more complicated format.
157 $obj->readHeader
159 Read the whole message-header and return it as list of field-value
160 pairs. Mind that some fields will appear more than once.
161 The first element will represent the position in the file where the
163 header starts. The follows the list of header field names and
164 bodies.
165 example:
167 my ($where, @header) = $parser->readHeader;
169 $obj->readSeparator(OPTIONS)
171 Read the currently active separator (the last one which was
172 pushed). The line (or "undef") is returned. Blank-lines before
173 the separator lines are ignored.
174 The return are two scalars, where the first gives the location of
176 the separator in the file, and the second the line which is found
177 as separator. A new separator is activated using pushSeparator().
178 Internals
180 $obj->closeFile
181 Close the file which was being parsed.
182 $obj->defaultParserType([CLASS])
184 Mail::Box::Parser->defaultParserType([CLASS])
185 Returns the parser to be used to parse all subsequent messages,
187 possibly first setting the parser using the optional argument.
188 Usually, the parser is autodetected; the "C"-based parser will be
189 used when it can be, and the Perl-based parser will be used
190 otherwise.
191 The CLASS argument allows you to specify a package name to force a
193 particular parser to be used (such as your own custom parser). You
194 have to "use" or "require" the package yourself before calling this
195 method with an argument. The parser must be a sub-class of
196 "Mail::Box::Parser".
197 $obj->openFile(ARGS)
199 Open the file to be parsed. ARGS is a ref-hash of options.
200 -Option --Default
202 filename <required>
203 mode <required>
204 filename => FILENAME
206 mode => STRING
207 $obj->takeFileInfo
208 Capture some data about the file being parsed, to be compared
209 later.
210 Error handling
212 $obj->AUTOLOAD
213 See "Error handling" in Mail::Reporter
214 $obj->addReport(OBJECT)
216 See "Error handling" in Mail::Reporter
217 $obj->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK])
219 Mail::Box::Parser->defaultTrace([LEVEL]|[LOGLEVEL,
220 TRACELEVEL]|[LEVEL, CALLBACK])
221 See "Error handling" in Mail::Reporter
223 $obj->errors
225 See "Error handling" in Mail::Reporter
226 $obj->log([LEVEL [,STRINGS]])
228 Mail::Box::Parser->log([LEVEL [,STRINGS]])
229 See "Error handling" in Mail::Reporter
231 $obj->logPriority(LEVEL)
233 Mail::Box::Parser->logPriority(LEVEL)
234 See "Error handling" in Mail::Reporter
236 $obj->logSettings
238 See "Error handling" in Mail::Reporter
239 $obj->notImplemented
241 See "Error handling" in Mail::Reporter
242 $obj->report([LEVEL])
244 See "Error handling" in Mail::Reporter
245 $obj->reportAll([LEVEL])
247 See "Error handling" in Mail::Reporter
248 $obj->trace([LEVEL])
250 See "Error handling" in Mail::Reporter
251 $obj->warnings
253 See "Error handling" in Mail::Reporter
254 Cleanup
256 $obj->DESTROY
257 See "Cleanup" in Mail::Reporter
258 $obj->inGlobalDestruction
260 See "Cleanup" in Mail::Reporter
261
263 Warning: File $filename changed during access.
264 When a message parser starts working, it takes size and
265 modification time of the file at hand. If the folder is written,
266 it checks wether there were changes in the file made by external
267 programs.
268 Calling Mail::Box::update() on a folder before it being closed will
270 read these new messages. But the real source of this problem is
271 locking: some external program (for instance the mail transfer
272 agent, like sendmail) uses a different locking mechanism as you do
273 and therefore violates your rights.
274 Error: Filename or handle required to create a parser.
276 A message parser needs to know the source of the message at
277 creation. These sources can be a filename (string), file handle
278 object or GLOB. See new(filename) and new(file).
279 Error: Package $package does not implement $method.
281 Fatal error: the specific package (or one of its superclasses) does
282 not implement this method where it should. This message means that
283 some other related classes do implement this method however the
284 class at hand does not. Probably you should investigate this and
285 probably inform the author of the package.
286
288 This module is part of Mail-Box distribution version 2.097, built on
289 January 26, 2011. Website: http://perl.overmeer.net/mailbox/
290
292 Copyrights 2001-2011 by Mark Overmeer. For other contributors see
293 ChangeLog.
294 This program is free software; you can redistribute it and/or modify it
296 under the same terms as Perl itself. See
297 http://www.perl.com/perl/misc/Artistic.html
298perl v5.12.3 2011-01-26 Mail::Box::Parser(3)