1Mail::Box::Mbox(3) User Contributed Perl Documentation Mail::Box::Mbox(3)
2
6 Mail::Box::Mbox - handle folders in Mbox format
7
9 Mail::Box::Mbox
10 is a Mail::Box::File
11 is a Mail::Box
12 is a Mail::Reporter
13
15 use Mail::Box::Mbox;
16 my $folder = Mail::Box::Mbox->new(folder => $ENV{MAIL}, ...);
17
19 This documentation describes how Mbox mailboxes work, and also
20 describes what you can do with the Mbox folder object Mail::Box::Mbox.
21
23 overload: ""
24 See "OVERLOADED" in Mail::Box
25 overload: @{}
27 See "OVERLOADED" in Mail::Box
28 overload: cmp
30 See "OVERLOADED" in Mail::Box
31
33 Constructors
34 Mail::Box::Mbox->new(OPTIONS)
35 -Option --Defined in --Default
36 access Mail::Box 'r'
37 body_delayed_type Mail::Box Mail::Message::Body::Delayed
38 body_type Mail::Box::File <see description>
39 coerce_options Mail::Box []
40 create Mail::Box <false>
41 extract Mail::Box 10240
42 field_type Mail::Box undef
43 fix_headers Mail::Box <false>
44 folder Mail::Box $ENV{MAIL}
45 folderdir Mail::Box $ENV{HOME}.'/Mail'
46 head_delayed_type Mail::Box Mail::Message::Head::Delayed
47 head_type Mail::Box Mail::Message::Head::Complete
48 keep_dups Mail::Box <false>
49 lock_extension Mail::Box::File '.lock'
50 lock_file Mail::Box <foldername><lock-extension>
51 lock_timeout Mail::Box 1 hour
52 lock_type Mail::Box Mail::Box::Locker::DotLock
53 lock_wait Mail::Box 10 seconds
54 locker Mail::Box undef
55 log Mail::Reporter 'WARNINGS'
56 manager Mail::Box undef
57 message_type Mail::Box Mail::Box::Mbox::Message
58 multipart_type Mail::Box Mail::Message::Body::Multipart
59 remove_when_empty Mail::Box <true>
60 save_on_exit Mail::Box <true>
61 subfolder_extension '.d'
62 trace Mail::Reporter 'WARNINGS'
63 trusted Mail::Box <depends on folder location>
64 write_policy Mail::Box::File undef
65 access => MODE
67 body_delayed_type => CLASS
68 body_type => CLASS|CODE
69 coerce_options => ARRAY
70 create => BOOLEAN
71 extract => INTEGER | CODE | METHOD | 'LAZY'|'ALWAYS'
72 field_type => CLASS
73 fix_headers => BOOLEAN
74 folder => FOLDERNAME
75 folderdir => DIRECTORY
76 head_delayed_type => CLASS
77 head_type => CLASS
78 keep_dups => BOOLEAN
79 lock_extension => FILENAME|STRING
80 lock_file => FILENAME
81 lock_timeout => SECONDS
82 lock_type => CLASS|STRING|ARRAY
83 lock_wait => SECONDS
84 locker => OBJECT
85 log => LEVEL
86 manager => MANAGER
87 message_type => CLASS
88 multipart_type => CLASS
89 remove_when_empty => BOOLEAN
90 save_on_exit => BOOLEAN
91 subfolder_extension => STRING
92 Mbox folders do not support sub-folders. However, this module
93 can simulate sub-directories if the user wants it to. When a
94 subfolder of folder "xyz" is created, we create a directory which
95 is called "xyz.d" to contain them. This extension ".d" can be
96 changed using this option.
97 trace => LEVEL
99 trusted => BOOLEAN
100 write_policy => 'REPLACE'|'INPLACE'|undef
101 The folder
103 $obj->addMessage(MESSAGE, OPTIONS)
104 See "The folder" in Mail::Box
105 $obj->addMessages(MESSAGE [, MESSAGE, ...])
107 See "The folder" in Mail::Box
108 Mail::Box::Mbox->appendMessages(OPTIONS)
110 See "METHODS" in Mail::Box::File
111 $obj->close(OPTIONS)
113 See "The folder" in Mail::Box
114 $obj->copyTo(FOLDER, OPTIONS)
116 See "The folder" in Mail::Box
117 $obj->delete(OPTIONS)
119 See "The folder" in Mail::Box
120 $obj->filename
122 See "The folder" in Mail::Box::File
123 $obj->folderdir([DIRECTORY])
125 See "The folder" in Mail::Box
126 $obj->name
128 See "The folder" in Mail::Box
129 $obj->organization
131 See "The folder" in Mail::Box
132 $obj->size
134 See "The folder" in Mail::Box
135 $obj->type
137 See "The folder" in Mail::Box
138 $obj->update(OPTIONS)
140 See "The folder" in Mail::Box
141 $obj->url
143 See "The folder" in Mail::Box
144 Folder flags
146 $obj->access
147 See "Folder flags" in Mail::Box
148 $obj->isModified
150 See "Folder flags" in Mail::Box
151 $obj->modified([BOOLEAN])
153 See "Folder flags" in Mail::Box
154 $obj->writable
156 See "Folder flags" in Mail::Box
157 The messages
159 $obj->current([NUMBER|MESSAGE|MESSAGE-ID])
160 See "The messages" in Mail::Box
161 $obj->find(MESSAGE-ID)
163 See "The messages" in Mail::Box
164 $obj->findFirstLabeled(LABEL, [BOOLEAN, [ARRAY-OF-MSGS]])
166 See "The messages" in Mail::Box
167 $obj->message(INDEX [,MESSAGE])
169 See "The messages" in Mail::Box
170 $obj->messageId(MESSAGE-ID [,MESSAGE])
172 See "The messages" in Mail::Box
173 $obj->messageIds
175 See "The messages" in Mail::Box
176 $obj->messages(['ALL',RANGE,'ACTIVE','DELETED',LABEL,!LABEL,FILTER])
178 See "The messages" in Mail::Box
179 $obj->nrMessages(OPTIONS)
181 See "The messages" in Mail::Box
182 $obj->scanForMessages(MESSAGE, MESSAGE-IDS, TIMESPAN, WINDOW)
184 See "The messages" in Mail::Box
185 Sub-folders
187 $obj->listSubFolders(OPTIONS)
188 Mail::Box::Mbox->listSubFolders(OPTIONS)
189 -Option --Defined in --Default
191 check Mail::Box <false>
192 folder Mail::Box <from calling object>
193 folderdir Mail::Box <from folder>
194 skip_empty Mail::Box <false>
195 subfolder_extension <from object>
196 check => BOOLEAN
198 folder => FOLDERNAME
199 folderdir => DIRECTORY
200 skip_empty => BOOL
201 subfolder_extension => STRING
202 When the method is called on an open folder, the extension
203 defined by it is used to detect sub-folders by default.
204 Otherwise, '.d' is taken.
205 $obj->nameOfSubFolder(SUBNAME, [PARENTNAME])
207 Mail::Box::Mbox->nameOfSubFolder(SUBNAME, [PARENTNAME])
208 See "Sub-folders" in Mail::Box
210 $obj->openRelatedFolder(OPTIONS)
212 See "Sub-folders" in Mail::Box
213 $obj->openSubFolder(SUBNAME, OPTIONS)
215 See "Sub-folders" in Mail::Box
216 $obj->topFolderWithMessages
218 Mail::Box::Mbox->topFolderWithMessages
219 See "Sub-folders" in Mail::Box
221 Internals
223 $obj->coerce(MESSAGE, OPTIONS)
224 See "Internals" in Mail::Box
225 $obj->create(FOLDERNAME, OPTIONS)
227 Mail::Box::Mbox->create(FOLDERNAME, OPTIONS)
228 -Option --Defined in --Default
230 folderdir Mail::Box undef
231 subfolder_extension undef
232 folderdir => DIRECTORY
234 subfolder_extension => STRING
235 If a directory is found on the location of the folder to be
236 created, this STRING is used to extend that directory name with.
237 This will cause the directory to be seen as sub-folder for the
238 created folder. This argument is passed to folderToFilename().
239 $obj->determineBodyType(MESSAGE, HEAD)
241 See "Internals" in Mail::Box
242 $obj->folderToFilename(FOLDERNAME, FOLDERDIR, [EXTENSION])
244 Mail::Box::Mbox->folderToFilename(FOLDERNAME, FOLDERDIR,
245 [EXTENSION])
246 Translate a folder name into a filename, using the FOLDERDIR value
248 to replace a leading "=". If no EXTENSION is specified and this
249 method is called as instance method, new(subfolder_extension) is
250 used. Otherwise, the extension default to '.d'.
251 Mail::Box::Mbox->foundIn([FOLDERNAME], [OPTIONS])
253 If no FOLDERNAME is specified, then the value of the "folder"
254 option is taken. A mbox folder is a file which starts with a
255 separator line: a line with 'From ' as first characters. Blank
256 lines which start the file are ignored, which is not for all MUA's
257 acceptable.
258 -Option --Defined in --Default
260 folder undef
261 folderdir Mail::Box undef
262 subfolder_extension <from object>
263 folder => FOLDERNAME
265 folderdir => DIRECTORY
266 subfolder_extension => STRING
267 $obj->lineSeparator([STRING|'CR'|'LF'|'CRLF'])
268 See "Internals" in Mail::Box
269 $obj->locker
271 See "Internals" in Mail::Box
272 $obj->messageCreateOptions([TYPE, CONFIG])
274 See "Internals" in Mail::Box::File
275 $obj->moveAwaySubFolder(DIRECTORY, EXTENSION)
277 See "Internals" in Mail::Box::File
278 $obj->parser
280 See "Internals" in Mail::Box::File
281 $obj->read(OPTIONS)
283 See "Internals" in Mail::Box
284 $obj->readMessages(OPTIONS)
286 See "Internals" in Mail::Box
287 $obj->storeMessage(MESSAGE)
289 See "Internals" in Mail::Box
290 $obj->toBeThreaded(MESSAGES)
292 See "Internals" in Mail::Box
293 $obj->toBeUnthreaded(MESSAGES)
295 See "Internals" in Mail::Box
296 $obj->updateMessages(OPTIONS)
298 See "Internals" in Mail::Box::File
299 $obj->write(OPTIONS)
301 See "Internals" in Mail::Box::File
302 $obj->writeMessages(OPTIONS)
304 See "Internals" in Mail::Box
305 Other methods
307 $obj->timespan2seconds(TIME)
308 Mail::Box::Mbox->timespan2seconds(TIME)
309 See "Other methods" in Mail::Box
311 Error handling
313 $obj->AUTOLOAD
314 See "Error handling" in Mail::Reporter
315 $obj->addReport(OBJECT)
317 See "Error handling" in Mail::Reporter
318 $obj->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK])
320 Mail::Box::Mbox->defaultTrace([LEVEL]|[LOGLEVEL,
321 TRACELEVEL]|[LEVEL, CALLBACK])
322 See "Error handling" in Mail::Reporter
324 $obj->errors
326 See "Error handling" in Mail::Reporter
327 $obj->log([LEVEL [,STRINGS]])
329 Mail::Box::Mbox->log([LEVEL [,STRINGS]])
330 See "Error handling" in Mail::Reporter
332 $obj->logPriority(LEVEL)
334 Mail::Box::Mbox->logPriority(LEVEL)
335 See "Error handling" in Mail::Reporter
337 $obj->logSettings
339 See "Error handling" in Mail::Reporter
340 $obj->notImplemented
342 See "Error handling" in Mail::Reporter
343 $obj->report([LEVEL])
345 See "Error handling" in Mail::Reporter
346 $obj->reportAll([LEVEL])
348 See "Error handling" in Mail::Reporter
349 $obj->trace([LEVEL])
351 See "Error handling" in Mail::Reporter
352 $obj->warnings
354 See "Error handling" in Mail::Reporter
355 Cleanup
357 $obj->DESTROY
358 See "Cleanup" in Mail::Box
359 $obj->inGlobalDestruction
361 See "Cleanup" in Mail::Reporter
362 DETAILS
364 File based folders
365
367 Different kinds of folders
368 Available folder types
369 Folder class implementation
370 How MBOX folders work
371 MBOX folders store many messages in one file. Each message begins with
372 a line which starts with the string "From ". Lines inside a message
373 which accidentally start with "From" are, in the file, preceded by `>'.
374 This character is stripped when the message is read.
375 In this respect must be noted that the format of the MBOX files is not
377 strictly defined. The exact content of the separator lines differ
378 between Mail User Agents (MUA's). Besides, some MUAs (like mutt)
379 forget to encode the "From " lines within message bodies, breaking
380 other parsers....
381 Simulation of sub-folders
383 MBOX folders do not have a sub-folder concept as directory based
384 folders do, but this MBOX module tries to simulate them. In this
385 implementation a directory like
386 Mail/subject1/
388 is taken as an empty folder "Mail/subject1", with the folders in that
390 directory as sub-folders for it. You may also use
391 Mail/subject1
393 Mail/subject1.d/
394 where "Mail/subject1" is the folder, and the folders in the
396 "Mail/subject1.d" directory are used as sub-folders. If your situation
397 is similar to the first example and you want to put messages in that
398 empty folder, the directory is automatically (and transparently)
399 renamed, so that the second situation is reached.
400
402 Error: Cannot append messages to folder file $filename: $!
403 Appending messages to a not-opened file-organized folder may fail
404 when the operating system does not allow write access to the file
405 at hand.
406 Error: Cannot move away sub-folder $dir
408 Warning: Cannot remove folder $name file $filename: $!
409 Writing an empty folder will usually cause that folder to be
410 removed, which fails for the indicated reason.
411 new(remove_when_empty)
412 Warning: Cannot remove folder $name file $filename: $!
414 Writing an empty folder will usually cause that folder to be
415 removed, which fails for the indicated reason.
416 new(remove_when_empty) controls whether the empty folder will
417 removed; setting it to false (0) may be needed to avoid this
418 message.
419 Error: Cannot replace $filename by $tempname, to update folder $name:
421 $!
422 The replace policy wrote a new folder file to update the existing,
423 but was unable to give the final touch: replacing the old version
424 of the folder file for the indicated reason.
425 Warning: Changes not written to read-only folder $self.
427 You have opened the folder read-only --which is the default set by
428 new(access)--, made modifications, and now want to close it. Set
429 close(force) if you want to overrule the access mode, or close the
430 folder with close(write) set to "NEVER".
431 Error: Copying failed for one message.
433 For some reason, for instance disc full, removed by external
434 process, or read-protection, it is impossible to copy one of the
435 messages. Copying will proceed for the other messages.
436 Error: Destination folder $name is not writable.
438 The folder where the messages are copied to is not opened with
439 write access (see new(access)). This has no relation with write
440 permission to the folder which is controled by your operating
441 system.
442 Warning: Different messages with id $msgid
444 The message id is discovered more than once within the same folder,
445 but the content of the message seems to be different. This should
446 not be possible: each message must be unique.
447 Error: File too short to get write message $nr ($size, $need)
449 Mail::Box is lazy: it tries to leave messages in the folders until
450 they are used, which saves time and memory usage. When this
451 message appears, something is terribly wrong: some lazy message are
452 needed for updating the folder, but they cannot be retreived from
453 the original file anymore. In this case, messages can be lost.
454 This message does appear regularly on Windows systems when using
456 the 'replace' write policy. Please help to find the cause,
457 probably something to do with Windows incorrectly handling multiple
458 filehandles open in the same file.
459 Error: Folder $name not deleted: not writable.
461 The folder must be opened with write access via new(access),
462 otherwise removing it will be refused. So, you may have write-
463 access according to the operating system, but that will not
464 automatically mean that this "delete" method permits you to. The
465 reverse remark is valid as well.
466 Error: Invalid timespan '$timespan' specified.
468 The string does not follow the strict rules of the time span syntax
469 which is permitted as parameter.
470 Warning: Message-id '$msgid' does not contain a domain.
472 According to the RFCs, message-ids need to contain a unique random
473 part, then an "@", and then a domain name. This is made to avoid
474 the creation of two messages with the same id. The warning emerges
475 when the "@" is missing from the string.
476 Error: Package $package does not implement $method.
478 Fatal error: the specific package (or one of its superclasses) does
479 not implement this method where it should. This message means that
480 some other related classes do implement this method however the
481 class at hand does not. Probably you should investigate this and
482 probably inform the author of the package.
483 Error: Unable to create subfolder $name of $folder.
485 The copy includes the subfolders, but for some reason it was not
486 possible to copy one of these. Copying will proceed for all other
487 sub-folders.
488 Error: Unable to update folder $self.
490 When a folder is to be written, both replace and inplace write
491 policies are tried, If both fail, the whole update fails. You may
492 see other, related, error messages to indicate the real problem.
493
495 This module is part of Mail-Box distribution version 2.097, built on
496 January 26, 2011. Website: http://perl.overmeer.net/mailbox/
497
499 Copyrights 2001-2011 by Mark Overmeer. For other contributors see
500 ChangeLog.
501 This program is free software; you can redistribute it and/or modify it
503 under the same terms as Perl itself. See
504 http://www.perl.com/perl/misc/Artistic.html
505perl v5.12.3 2011-01-26 Mail::Box::Mbox(3)