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
26 overload: @{}
28 See "OVERLOADED" in Mail::Box
30 overload: cmp
32 See "OVERLOADED" in Mail::Box
34
36 Constructors
37 Mail::Box::Mbox->new(OPTIONS)
39 Option --Defined in --Default
41 access Mail::Box 'r'
42 body_delayed_type Mail::Box Mail::Message::Body::Delayed
43 body_type Mail::Box::File <see description>
44 coerce_options Mail::Box []
45 create Mail::Box <false>
46 extract Mail::Box 10240
47 field_type Mail::Box undef
48 fix_headers Mail::Box <false>
49 folder Mail::Box $ENV{MAIL}
50 folderdir Mail::Box $ENV{HOME}.'/Mail'
51 head_delayed_type Mail::Box Mail::Message::Head::Delayed
52 head_type Mail::Box Mail::Message::Head::Complete
53 keep_dups Mail::Box <false>
54 lock_extension Mail::Box::File '.lock'
55 lock_file Mail::Box <foldername><lock-extension>
56 lock_timeout Mail::Box 1 hour
57 lock_type Mail::Box Mail::Box::Locker::DotLock
58 lock_wait Mail::Box 10 seconds
59 locker Mail::Box undef
60 log Mail::Reporter 'WARNINGS'
61 manager Mail::Box undef
62 message_type Mail::Box Mail::Box::Mbox::Message
63 multipart_type Mail::Box Mail::Message::Body::Multipart
64 remove_when_empty Mail::Box <true>
65 save_on_exit Mail::Box <true>
66 subfolder_extension '.d'
67 trace Mail::Reporter 'WARNINGS'
68 trusted Mail::Box <depends on folder location>
69 write_policy Mail::Box::File undef
70 . access MODE
72 . body_delayed_type CLASS
74 . body_type CLASS⎪CODE
76 . coerce_options ARRAY
78 . create BOOLEAN
80 . extract INTEGER ⎪ CODE ⎪ METHOD ⎪ 'LAZY'⎪'ALWAYS'
82 . field_type CLASS
84 . fix_headers BOOLEAN
86 . folder FOLDERNAME
88 . folderdir DIRECTORY
90 . head_delayed_type CLASS
92 . head_type CLASS
94 . keep_dups BOOLEAN
96 . lock_extension FILENAME⎪STRING
98 . lock_file FILENAME
100 . lock_timeout SECONDS
102 . lock_type CLASS⎪STRING⎪ARRAY
104 . lock_wait SECONDS
106 . locker OBJECT
108 . log LEVEL
110 . manager MANAGER
112 . message_type CLASS
114 . multipart_type CLASS
116 . remove_when_empty BOOLEAN
118 . save_on_exit BOOLEAN
120 . subfolder_extension STRING
122 Mbox folders do not support sub-folders. However, this module
124 can simulate sub-directories if the user wants it to. When a
125 subfolder of folder "xyz" is created, we create a directory
126 which is called "xyz.d" to contain them. This extension ".d"
127 can be changed using this option.
128 . trace LEVEL
130 . trusted BOOLEAN
132 . write_policy 'REPLACE'⎪'INPLACE'⎪undef
134 The folder
136 $obj->addMessage(MESSAGE, OPTIONS)
138 See "The folder" in Mail::Box
140 $obj->addMessages(MESSAGE [, MESSAGE, ...])
142 See "The folder" in Mail::Box
144 Mail::Box::Mbox->appendMessages(OPTIONS)
146 See "METHODS" in Mail::Box::File
148 $obj->close(OPTIONS)
150 See "The folder" in Mail::Box
152 $obj->copyTo(FOLDER, OPTIONS)
154 See "The folder" in Mail::Box
156 $obj->delete(OPTIONS)
158 See "The folder" in Mail::Box
160 $obj->filename
162 See "The folder" in Mail::Box::File
164 $obj->folderdir([DIRECTORY])
166 See "The folder" in Mail::Box
168 $obj->name
170 See "The folder" in Mail::Box
172 $obj->organization
174 See "The folder" in Mail::Box
176 $obj->size
178 See "The folder" in Mail::Box
180 $obj->type
182 See "The folder" in Mail::Box
184 $obj->update(OPTIONS)
186 See "The folder" in Mail::Box
188 $obj->url
190 See "The folder" in Mail::Box
192 Folder flags
194 $obj->access
196 See "Folder flags" in Mail::Box
198 $obj->isModified
200 See "Folder flags" in Mail::Box
202 $obj->modified([BOOLEAN])
204 See "Folder flags" in Mail::Box
206 $obj->writable
208 See "Folder flags" in Mail::Box
210 The messages
212 $obj->current([NUMBER⎪MESSAGE⎪MESSAGE-ID])
214 See "The messages" in Mail::Box
216 $obj->find(MESSAGE-ID)
218 See "The messages" in Mail::Box
220 $obj->findFirstLabeled(LABEL, [BOOLEAN, [ARRAY-OF-MSGS]])
222 See "The messages" in Mail::Box
224 $obj->message(INDEX [,MESSAGE])
226 See "The messages" in Mail::Box
228 $obj->messageId(MESSAGE-ID [,MESSAGE])
230 See "The messages" in Mail::Box
232 $obj->messageIds
234 See "The messages" in Mail::Box
236 $obj->messages(['ALL',RANGE,'ACTIVE','DELETED',LABEL,!LABEL,FILTER])
238 See "The messages" in Mail::Box
240 $obj->nrMessages(OPTIONS)
242 See "The messages" in Mail::Box
244 $obj->scanForMessages(MESSAGE, MESSAGE-IDS, TIMESPAN, WINDOW)
246 See "The messages" in Mail::Box
248 Sub-folders
250 $obj->listSubFolders(OPTIONS)
252 Mail::Box::Mbox->listSubFolders(OPTIONS)
254 Option --Defined in --Default
256 check Mail::Box <false>
257 folder Mail::Box <from calling object>
258 folderdir Mail::Box <from folder>
259 skip_empty Mail::Box <false>
260 subfolder_extension <from object>
261 . check BOOLEAN
263 . folder FOLDERNAME
265 . folderdir DIRECTORY
267 . skip_empty BOOL
269 . subfolder_extension STRING
271 When the method is called on an open folder, the extension
273 defined by it is used to detect sub-folders by default. Other‐
274 wise, '.d' is taken.
275 $obj->nameOfSubFolder(SUBNAME, [PARENTNAME])
277 Mail::Box::Mbox->nameOfSubFolder(SUBNAME, [PARENTNAME])
279 See "Sub-folders" in Mail::Box
281 $obj->openRelatedFolder(OPTIONS)
283 See "Sub-folders" in Mail::Box
285 $obj->openSubFolder(SUBNAME, OPTIONS)
287 See "Sub-folders" in Mail::Box
289 $obj->topFolderWithMessages
291 Mail::Box::Mbox->topFolderWithMessages
293 See "Sub-folders" in Mail::Box
295 Internals
297 $obj->coerce(MESSAGE, OPTIONS)
299 See "Internals" in Mail::Box
301 $obj->create(FOLDERNAME, OPTIONS)
303 Mail::Box::Mbox->create(FOLDERNAME, OPTIONS)
305 Option --Defined in --Default
307 folderdir Mail::Box undef
308 subfolder_extension undef
309 . folderdir DIRECTORY
311 . subfolder_extension STRING
313 If a directory is found on the location of the folder to be
315 created, this STRING is used to extend that directory name
316 with. This will cause the directory to be seen as sub-folder
317 for the created folder. This argument is passed to fold‐
318 erToFilename().
319 $obj->determineBodyType(MESSAGE, HEAD)
321 See "Internals" in Mail::Box
323 $obj->folderToFilename(FOLDERNAME, FOLDERDIR, [EXTENSION])
325 Mail::Box::Mbox->folderToFilename(FOLDERNAME, FOLDERDIR, [EXTENSION])
327 Translate a folder name into a filename, using the FOLDERDIR value
329 to replace a leading "=". If no EXTENSION is specified and this
330 method is called as instance method, new(subfolder_extension) is
331 used. Otherwise, the extension default to '.d'.
332 Mail::Box::Mbox->foundIn([FOLDERNAME], [OPTIONS])
334 If no FOLDERNAME is specified, then the value of the "folder"
336 option is taken. A mbox folder is a file which starts with a sepa‐
337 rator line: a line with 'From ' as first characters. Blank lines
338 which start the file are ignored, which is not for all MUA's
339 acceptable.
340 Option --Defined in --Default
342 folder undef
343 folderdir Mail::Box undef
344 subfolder_extension <from object>
345 . folder FOLDERNAME
347 . folderdir DIRECTORY
349 . subfolder_extension STRING
351 $obj->lineSeparator([STRING⎪'CR'⎪'LF'⎪'CRLF'])
353 See "Internals" in Mail::Box
355 $obj->locker
357 See "Internals" in Mail::Box
359 $obj->messageCreateOptions([TYPE, CONFIG])
361 See "Internals" in Mail::Box::File
363 $obj->moveAwaySubFolder(DIRECTORY, EXTENSION)
365 See "Internals" in Mail::Box::File
367 $obj->parser
369 See "Internals" in Mail::Box::File
371 $obj->read(OPTIONS)
373 See "Internals" in Mail::Box
375 $obj->readMessages(OPTIONS)
377 See "Internals" in Mail::Box
379 $obj->storeMessage(MESSAGE)
381 See "Internals" in Mail::Box
383 $obj->toBeThreaded(MESSAGES)
385 See "Internals" in Mail::Box
387 $obj->toBeUnthreaded(MESSAGES)
389 See "Internals" in Mail::Box
391 $obj->updateMessages(OPTIONS)
393 See "Internals" in Mail::Box::File
395 $obj->write(OPTIONS)
397 See "Internals" in Mail::Box::File
399 $obj->writeMessages(OPTIONS)
401 See "Internals" in Mail::Box
403 File based folders
405 Other methods
407 $obj->timespan2seconds(TIME)
409 Mail::Box::Mbox->timespan2seconds(TIME)
411 See "Other methods" in Mail::Box
413 Error handling
415 $obj->AUTOLOAD
417 See "Error handling" in Mail::Reporter
419 $obj->addReport(OBJECT)
421 See "Error handling" in Mail::Reporter
423 $obj->defaultTrace([LEVEL]⎪[LOGLEVEL, TRACELEVEL]⎪[LEVEL, CALLBACK])
425 Mail::Box::Mbox->defaultTrace([LEVEL]⎪[LOGLEVEL, TRACELEVEL]⎪[LEVEL,
427 CALLBACK])
428 See "Error handling" in Mail::Reporter
430 $obj->errors
432 See "Error handling" in Mail::Reporter
434 $obj->log([LEVEL [,STRINGS]])
436 Mail::Box::Mbox->log([LEVEL [,STRINGS]])
438 See "Error handling" in Mail::Reporter
440 $obj->logPriority(LEVEL)
442 Mail::Box::Mbox->logPriority(LEVEL)
444 See "Error handling" in Mail::Reporter
446 $obj->logSettings
448 See "Error handling" in Mail::Reporter
450 $obj->notImplemented
452 See "Error handling" in Mail::Reporter
454 $obj->report([LEVEL])
456 See "Error handling" in Mail::Reporter
458 $obj->reportAll([LEVEL])
460 See "Error handling" in Mail::Reporter
462 $obj->trace([LEVEL])
464 See "Error handling" in Mail::Reporter
466 $obj->warnings
468 See "Error handling" in Mail::Reporter
470 Cleanup
472 $obj->DESTROY
474 See "Cleanup" in Mail::Box
476 $obj->inGlobalDestruction
478 See "Cleanup" in Mail::Reporter
480
482 How MBOX folders work
483 MBOX folders store many messages in one file. Each message begins with
485 a line which starts with the string "From ". Lines inside a message
486 which accidentally start with "From" are, in the file, preceded by `>'.
487 This character is stripped when the message is read.
488 In this respect must be noted that the format of the MBOX files is not
490 strictly defined. The exact content of the separator lines differ
491 between Mail User Agents (MUA's). Besides, some MUAs (like mutt) for‐
492 get to encode the "From " lines within message bodies, breaking other
493 parsers....
494 Simulation of sub-folders
496 MBOX folders do not have a sub-folder concept as directory based fold‐
498 ers do, but this MBOX module tries to simulate them. In this implemen‐
499 tation a directory like
500 Mail/subject1/
502 is taken as an empty folder "Mail/subject1", with the folders in that
504 directory as sub-folders for it. You may also use
505 Mail/subject1
507 Mail/subject1.d/
508 where "Mail/subject1" is the folder, and the folders in the "Mail/sub‐
510 ject1.d" directory are used as sub-folders. If your situation is simi‐
511 lar to the first example and you want to put messages in that empty
512 folder, the directory is automatically (and transparently) renamed, so
513 that the second situation is reached.
514
516 Error: Cannot append messages to folder file $filename: $!
517 Appending messages to a not-opened file-organized folder may fail when
519 the operating system does not allow write access to the file at hand.
520 Error: Cannot move away sub-folder $dir
522 Warning: Cannot remove folder $name file $filename: $!
524 Writing an empty folder will usually cause that folder to be removed,
526 which fails for the indicated reason. new(remove_when_empty)
527 Warning: Cannot remove folder $name file $filename: $!
529 Writing an empty folder will usually cause that folder to be removed,
531 which fails for the indicated reason. new(remove_when_empty) controls
532 whether the empty folder will removed; setting it to false (0) may be
533 needed to avoid this message.
534 Error: Cannot replace $filename by $tempname, to update folder $name:
536 $!
537 The replace policy wrote a new folder file to update the existing, but
539 was unable to give the final touch: replacing the old version of the
540 folder file for the indicated reason.
541 Warning: Changes not written to read-only folder $self.
543 You have opened the folder read-only --which is the default set by
545 new(access)--, made modifications, and now want to close it. Set
546 close(force) if you want to overrule the access mode, or close the
547 folder with close(write) set to "NEVER".
548 Error: Copying failed for one message.
550 For some reason, for instance disc full, removed by external process,
552 or read-protection, it is impossible to copy one of the messages.
553 Copying will proceed for the other messages.
554 Error: Destination folder $name is not writable.
556 The folder where the messages are copied to is not opened with write
558 access (see new(access)). This has no relation with write permission
559 to the folder which is controled by your operating system.
560 Warning: Different messages with id $msgid
562 The message id is discovered more than once within the same folder, but
564 the content of the message seems to be different. This should not be
565 possible: each message must be unique.
566 Error: File too short to get write message $nr ($size, $need)
568 Mail::Box is lazy: it tries to leave messages in the folders until they
570 are used, which saves time and memory usage. When this message
571 appears, something is terribly wrong: some lazy message are needed for
572 updating the folder, but they cannot be retreived from the original
573 file anymore. In this case, messages can be lost.
574 This message does appear regularly on Windows systems when using the
576 'replace' write policy. Please help to find the cause, probably some‐
577 thing to do with Windows incorrectly handling multiple filehandles open
578 in the same file.
579 Error: Folder $name not deleted: not writable.
581 The folder must be opened with write access via new(access), otherwise
583 removing it will be refused. So, you may have write-access according
584 to the operating system, but that will not automatically mean that this
585 "delete" method permits you to. The reverse remark is valid as well.
586 Error: Invalid timespan '$timespan' specified.
588 The string does not follow the strict rules of the time span syntax
590 which is permitted as parameter.
591 Warning: Message-id '$msgid' does not contain a domain.
593 According to the RFCs, message-ids need to contain a unique random
595 part, then an "@", and then a domain name. This is made to avoid the
596 creation of two messages with the same id. The warning emerges when
597 the "@" is missing from the string.
598 Error: Package $package does not implement $method.
600 Fatal error: the specific package (or one of its superclasses) does not
602 implement this method where it should. This message means that some
603 other related classes do implement this method however the class at
604 hand does not. Probably you should investigate this and probably
605 inform the author of the package.
606 Error: Unable to create subfolder $name of $folder.
608 The copy includes the subfolders, but for some reason it was not possi‐
610 ble to copy one of these. Copying will proceed for all other sub-fold‐
611 ers.
612 Error: Unable to update folder $self.
614 When a folder is to be written, both replace and inplace write policies
616 are tried, If both fail, the whole update fails. You may see other,
617 related, error messages to indicate the real problem.
618
620 This module is part of Mail-Box distribution version 2.070, built on
621 March 25, 2007. Website: http://perl.overmeer.net/mailbox/
622
624 Copyrights 2001-2007 by Mark Overmeer.For other contributors see
625 ChangeLog.
626 This program is free software; you can redistribute it and/or modify it
628 under the same terms as Perl itself. See
629 http://www.perl.com/perl/misc/Artistic.html
630perl v5.8.8 2007-03-25 Mail::Box::Mbox(3)