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::C
14 Mail::Box::Parser::Perl
15
17 # Not instatiatiated itself
18
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 There are two implementations of this module planned:
25 • Mail::Box::Parser::Perl
27 A slower parser which only uses plain Perl. This module is a bit
29 slower, and does less checking and less recovery.
30 • Mail::Box::Parser::C
32 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 Extends "DESCRIPTION" in Mail::Reporter.
40
42 Extends "METHODS" in Mail::Reporter.
43 Constructors
45 Extends "Constructors" in Mail::Reporter.
46 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 -Option --Defined in --Default
54 file undef
55 filename <required>
56 log Mail::Reporter 'WARNINGS'
57 mode 'r'
58 trace Mail::Reporter 'WARNINGS'
59 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 filename => FILENAME
66 The name of the file to be read.
67 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 trace => LEVEL
75 The parser
77 $obj->fileChanged()
78 Returns whether the file which is parsed has changed after the last
79 time takeFileInfo() was called.
80 $obj->filename()
82 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
86 has changed.
87 $obj->start(%options)
89 Start the parser by opening a file.
90 -Option--Default
92 file undef
93 file => FILEHANDLE|undef
95 The file is already open, for instance because the data must be
96 read from STDIN.
97 $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 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 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 $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 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 $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 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 $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 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 $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 $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 $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 $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 The specified STRING describes the start of the separator-line.
163 The Regexp can specify a more complicated format.
164 $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 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 example:
174 my ($where, @header) = $parser->readHeader;
176 $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 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 Internals
187 $obj->closeFile()
188 Close the file which was being parsed.
189 $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 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 $obj->openFile($args)
205 Open the file to be parsed. $args is a ref-hash of options.
206 -Option --Default
208 filename <required>
209 mode <required>
210 filename => FILENAME
212 mode => STRING
213 $obj->takeFileInfo()
214 Capture some data about the file being parsed, to be compared
215 later.
216 Error handling
218 Extends "Error handling" in Mail::Reporter.
219 $obj->AUTOLOAD()
221 Inherited, see "Error handling" in Mail::Reporter
222 $obj->addReport($object)
224 Inherited, see "Error handling" in Mail::Reporter
225 $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 $obj->errors()
233 Inherited, see "Error handling" in Mail::Reporter
234 $obj->log( [$level, [$strings]] )
236 Mail::Box::Parser->log( [$level, [$strings]] )
237 Inherited, see "Error handling" in Mail::Reporter
238 $obj->logPriority($level)
240 Mail::Box::Parser->logPriority($level)
241 Inherited, see "Error handling" in Mail::Reporter
242 $obj->logSettings()
244 Inherited, see "Error handling" in Mail::Reporter
245 $obj->notImplemented()
247 Inherited, see "Error handling" in Mail::Reporter
248 $obj->report( [$level] )
250 Inherited, see "Error handling" in Mail::Reporter
251 $obj->reportAll( [$level] )
253 Inherited, see "Error handling" in Mail::Reporter
254 $obj->trace( [$level] )
256 Inherited, see "Error handling" in Mail::Reporter
257 $obj->warnings()
259 Inherited, see "Error handling" in Mail::Reporter
260 Cleanup
262 Extends "Cleanup" in Mail::Reporter.
263 $obj->DESTROY()
265 Inherited, see "Cleanup" in Mail::Reporter
266
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 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 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 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
293 This module is part of Mail-Message distribution version 3.012, built
294 on February 11, 2022. Website: http://perl.overmeer.net/CPAN/
295
297 Copyrights 2001-2022 by [Mark Overmeer <markov@cpan.org>]. For other
298 contributors see ChangeLog.
299 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/
302perl v5.36.0 2023-01-20 Mail::Box::Parser(3)