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 Extends "DESCRIPTION" in Mail::Box::File.
23
25 Extends "OVERLOADED" in Mail::Box::File.
26 overload: ""
28 Inherited, see "OVERLOADED" in Mail::Box
29 overload: @{}
31 Inherited, see "OVERLOADED" in Mail::Box
32 overload: cmp
34 Inherited, see "OVERLOADED" in Mail::Box
35
37 Extends "METHODS" in Mail::Box::File.
38 Constructors
40 Extends "Constructors" in Mail::Box::File.
41 Mail::Box::Mbox->new(%options)
43 -Option --Defined in --Default
44 access Mail::Box 'r'
45 body_delayed_type Mail::Box Mail::Message::Body::Delayed
46 body_type Mail::Box::File <see description>
47 coerce_options Mail::Box []
48 create Mail::Box <false>
49 extract Mail::Box 10240
50 field_type Mail::Box undef
51 fix_headers Mail::Box <false>
52 folder Mail::Box $ENV{MAIL}
53 folderdir Mail::Box $ENV{HOME}.'/Mail'
54 head_delayed_type Mail::Box Mail::Message::Head::Delayed
55 head_type Mail::Box Mail::Message::Head::Complete
56 keep_dups Mail::Box <false>
57 lock_extension Mail::Box::File '.lock'
58 lock_file Mail::Box <foldername><lock-extension>
59 lock_timeout Mail::Box 1 hour
60 lock_type Mail::Box Mail::Box::Locker::DotLock
61 lock_wait Mail::Box 10 seconds
62 locker Mail::Box undef
63 log Mail::Reporter 'WARNINGS'
64 manager Mail::Box undef
65 message_type Mail::Box Mail::Box::Mbox::Message
66 multipart_type Mail::Box Mail::Message::Body::Multipart
67 remove_when_empty Mail::Box <true>
68 save_on_exit Mail::Box <true>
69 subfolder_extension '.d'
70 trace Mail::Reporter 'WARNINGS'
71 trusted Mail::Box <depends on folder location>
72 write_policy Mail::Box::File undef
73 access => MODE
75 body_delayed_type => CLASS
76 body_type => CLASS|CODE
77 coerce_options => ARRAY
78 create => BOOLEAN
79 extract => INTEGER | CODE | METHOD | 'LAZY'|'ALWAYS'
80 field_type => CLASS
81 fix_headers => BOOLEAN
82 folder => FOLDERNAME
83 folderdir => DIRECTORY
84 head_delayed_type => CLASS
85 head_type => CLASS
86 keep_dups => BOOLEAN
87 lock_extension => FILENAME|STRING
88 lock_file => FILENAME
89 lock_timeout => SECONDS
90 lock_type => CLASS|STRING|ARRAY
91 lock_wait => SECONDS
92 locker => OBJECT
93 log => LEVEL
94 manager => MANAGER
95 message_type => CLASS
96 multipart_type => CLASS
97 remove_when_empty => BOOLEAN
98 save_on_exit => BOOLEAN
99 subfolder_extension => STRING
100 Mbox folders do not support sub-folders. However, this module
101 can simulate sub-directories if the user wants it to. When a
102 subfolder of folder "xyz" is created, we create a directory which
103 is called "xyz.d" to contain them. This extension ".d" can be
104 changed using this option.
105 trace => LEVEL
107 trusted => BOOLEAN
108 write_policy => 'REPLACE'|'INPLACE'|undef
109 The folder
111 Extends "The folder" in Mail::Box::File.
112 $obj->addMessage($message, %options)
114 Inherited, see "The folder" in Mail::Box
115 $obj->addMessages(@messages)
117 Inherited, see "The folder" in Mail::Box
118 Mail::Box::Mbox->appendMessages(%options)
120 Inherited, see "METHODS" in Mail::Box::File
121 $obj->close(%options)
123 Inherited, see "The folder" in Mail::Box
124 $obj->copyTo($folder, %options)
126 Inherited, see "The folder" in Mail::Box
127 $obj->delete(%options)
129 Inherited, see "The folder" in Mail::Box
130 $obj->filename()
132 Inherited, see "The folder" in Mail::Box::File
133 $obj->folderdir( [$directory] )
135 Inherited, see "The folder" in Mail::Box
136 $obj->name()
138 Inherited, see "The folder" in Mail::Box
139 $obj->organization()
141 Inherited, see "The folder" in Mail::Box
142 $obj->size()
144 Inherited, see "The folder" in Mail::Box
145 $obj->type()
147 Inherited, see "The folder" in Mail::Box
148 $obj->update(%options)
150 Inherited, see "The folder" in Mail::Box
151 $obj->url()
153 Inherited, see "The folder" in Mail::Box
154 Folder flags
156 Extends "Folder flags" in Mail::Box::File.
157 $obj->access()
159 Inherited, see "Folder flags" in Mail::Box
160 $obj->isModified()
162 Inherited, see "Folder flags" in Mail::Box
163 $obj->modified( [BOOLEAN] )
165 Inherited, see "Folder flags" in Mail::Box
166 $obj->writable()
168 Inherited, see "Folder flags" in Mail::Box
169 The messages
171 Extends "The messages" in Mail::Box::File.
172 $obj->current( [$number|$message|$message_id] )
174 Inherited, see "The messages" in Mail::Box
175 $obj->find($message_id)
177 Inherited, see "The messages" in Mail::Box
178 $obj->findFirstLabeled( $label, [BOOLEAN, [$msgs]] )
180 Inherited, see "The messages" in Mail::Box
181 $obj->message( $index, [$message] )
183 Inherited, see "The messages" in Mail::Box
184 $obj->messageId( $message_id, [$message] )
186 Inherited, see "The messages" in Mail::Box
187 $obj->messageIds()
189 Inherited, see "The messages" in Mail::Box
190 $obj->messages( <'ALL'|$range|'ACTIVE'|'DELETED'|$label|
192 !$label|$filter> )
193 Inherited, see "The messages" in Mail::Box
194 $obj->nrMessages(%options)
196 Inherited, see "The messages" in Mail::Box
197 $obj->scanForMessages($message, $message_ids, $timespan, $window)
199 Inherited, see "The messages" in Mail::Box
200 Sub-folders
202 Extends "Sub-folders" in Mail::Box::File.
203 $obj->listSubFolders(%options)
205 Mail::Box::Mbox->listSubFolders(%options)
206 -Option --Defined in --Default
207 check Mail::Box <false>
208 folder Mail::Box <from calling object>
209 folderdir Mail::Box <from folder>
210 skip_empty Mail::Box <false>
211 subfolder_extension <from object>
212 check => BOOLEAN
214 folder => FOLDERNAME
215 folderdir => DIRECTORY
216 skip_empty => BOOL
217 subfolder_extension => STRING
218 When the method is called on an open folder, the extension
219 defined by it is used to detect sub-folders by default.
220 Otherwise, '.d' is taken.
221 $obj->nameOfSubFolder( $subname, [$parentname] )
223 Mail::Box::Mbox->nameOfSubFolder( $subname, [$parentname] )
224 Inherited, see "Sub-folders" in Mail::Box
225 $obj->openRelatedFolder(%options)
227 Inherited, see "Sub-folders" in Mail::Box
228 $obj->openSubFolder($subname, %options)
230 Inherited, see "Sub-folders" in Mail::Box
231 $obj->topFolderWithMessages()
233 Mail::Box::Mbox->topFolderWithMessages()
234 Inherited, see "Sub-folders" in Mail::Box
235 Internals
237 Extends "Internals" in Mail::Box::File.
238 $obj->coerce($message, %options)
240 Inherited, see "Internals" in Mail::Box
241 $obj->create($foldername, %options)
243 Mail::Box::Mbox->create($foldername, %options)
244 -Option --Defined in --Default
245 folderdir Mail::Box undef
246 subfolder_extension undef
247 folderdir => DIRECTORY
249 subfolder_extension => STRING
250 If a directory is found on the location of the folder to be
251 created, this STRING is used to extend that directory name with.
252 This will cause the directory to be seen as sub-folder for the
253 created folder. This argument is passed to folderToFilename().
254 $obj->determineBodyType($message, $head)
256 Inherited, see "Internals" in Mail::Box
257 $obj->folderToFilename( $foldername, $folderdir, [$extension] )
259 Mail::Box::Mbox->folderToFilename( $foldername, $folderdir,
260 [$extension] )
261 Translate a folder name into a filename, using the $folderdir value
262 to replace a leading "=". If no $extension is specified and this
263 method is called as instance method, new(subfolder_extension) is
264 used. Otherwise, the extension default to '.d'.
265 Mail::Box::Mbox->foundIn( [$foldername], %options )
267 If no $foldername is specified, then the value of the "folder"
268 option is taken. A mbox folder is a file which starts with a
269 separator line: a line with 'From ' as first characters. Blank
270 lines which start the file are ignored, which is not for all MUA's
271 acceptable.
272 -Option --Defined in --Default
274 folder undef
275 folderdir Mail::Box undef
276 subfolder_extension <from object>
277 folder => FOLDERNAME
279 folderdir => DIRECTORY
280 subfolder_extension => STRING
281 $obj->lineSeparator( [<STRING|'CR'|'LF'|'CRLF'>] )
282 Inherited, see "Internals" in Mail::Box
283 $obj->locker()
285 Inherited, see "Internals" in Mail::Box
286 $obj->messageCreateOptions( [$type, $config] )
288 Inherited, see "Internals" in Mail::Box::File
289 $obj->moveAwaySubFolder($directory, $extension)
291 Inherited, see "Internals" in Mail::Box::File
292 $obj->parser()
294 Inherited, see "Internals" in Mail::Box::File
295 $obj->read(%options)
297 Inherited, see "Internals" in Mail::Box
298 $obj->readMessages(%options)
300 Inherited, see "Internals" in Mail::Box
301 $obj->storeMessage($message)
303 Inherited, see "Internals" in Mail::Box
304 $obj->toBeThreaded($messages)
306 Inherited, see "Internals" in Mail::Box
307 $obj->toBeUnthreaded($messages)
309 Inherited, see "Internals" in Mail::Box
310 $obj->updateMessages(%options)
312 Inherited, see "Internals" in Mail::Box::File
313 $obj->write(%options)
315 Inherited, see "Internals" in Mail::Box::File
316 $obj->writeMessages(%options)
318 Inherited, see "Internals" in Mail::Box
319 Other methods
321 Extends "Other methods" in Mail::Box::File.
322 $obj->timespan2seconds($time)
324 Mail::Box::Mbox->timespan2seconds($time)
325 Inherited, see "Other methods" in Mail::Box
326 Error handling
328 Extends "Error handling" in Mail::Box::File.
329 $obj->AUTOLOAD()
331 Inherited, see "Error handling" in Mail::Reporter
332 $obj->addReport($object)
334 Inherited, see "Error handling" in Mail::Reporter
335 $obj->defaultTrace( [$level]|[$loglevel, $tracelevel]|[$level,
337 $callback] )
338 Mail::Box::Mbox->defaultTrace( [$level]|[$loglevel,
339 $tracelevel]|[$level, $callback] )
340 Inherited, see "Error handling" in Mail::Reporter
341 $obj->errors()
343 Inherited, see "Error handling" in Mail::Reporter
344 $obj->log( [$level, [$strings]] )
346 Mail::Box::Mbox->log( [$level, [$strings]] )
347 Inherited, see "Error handling" in Mail::Reporter
348 $obj->logPriority($level)
350 Mail::Box::Mbox->logPriority($level)
351 Inherited, see "Error handling" in Mail::Reporter
352 $obj->logSettings()
354 Inherited, see "Error handling" in Mail::Reporter
355 $obj->notImplemented()
357 Inherited, see "Error handling" in Mail::Reporter
358 $obj->report( [$level] )
360 Inherited, see "Error handling" in Mail::Reporter
361 $obj->reportAll( [$level] )
363 Inherited, see "Error handling" in Mail::Reporter
364 $obj->trace( [$level] )
366 Inherited, see "Error handling" in Mail::Reporter
367 $obj->warnings()
369 Inherited, see "Error handling" in Mail::Reporter
370 Cleanup
372 Extends "Cleanup" in Mail::Box::File.
373 $obj->DESTROY()
375 Inherited, see "Cleanup" in Mail::Box
376 DETAILS
378 Extends "DETAILS" in Mail::Box::File.
379
381 Extends "DETAILS" in Mail::Box::File.
382 Different kinds of folders
384 Extends "Different kinds of folders" in Mail::Box::File.
385 Available folder types
387 Extends "Available folder types" in Mail::Box::File.
388 Folder class implementation
390 Extends "Folder class implementation" in Mail::Box::File.
391 How MBOX folders work
393 MBOX folders store many messages in one file. Each message begins with
394 a line which starts with the string "From ". Lines inside a message
395 which accidentally start with "From" are, in the file, preceded by `>'.
396 This character is stripped when the message is read.
397 In this respect must be noted that the format of the MBOX files is not
399 strictly defined. The exact content of the separator lines differ
400 between Mail User Agents (MUA's). Besides, some MUAs (like mutt)
401 forget to encode the "From " lines within message bodies, breaking
402 other parsers....
403 Simulation of sub-folders
405 MBOX folders do not have a sub-folder concept as directory based
406 folders do, but this MBOX module tries to simulate them. In this
407 implementation a directory like
408 Mail/subject1/
410 is taken as an empty folder "Mail/subject1", with the folders in that
412 directory as sub-folders for it. You may also use
413 Mail/subject1
415 Mail/subject1.d/
416 where "Mail/subject1" is the folder, and the folders in the
418 "Mail/subject1.d" directory are used as sub-folders. If your situation
419 is similar to the first example and you want to put messages in that
420 empty folder, the directory is automatically (and transparently)
421 renamed, so that the second situation is reached.
422
424 Error: Cannot append messages to folder file $filename: $!
425 Appending messages to a not-opened file-organized folder may fail
426 when the operating system does not allow write access to the file
427 at hand.
428 Error: Cannot move away sub-folder $dir
430 Warning: Cannot remove folder $name file $filename: $!
431 Writing an empty folder will usually cause that folder to be
432 removed, which fails for the indicated reason.
433 new(remove_when_empty)
434 Warning: Cannot remove folder $name file $filename: $!
436 Writing an empty folder will usually cause that folder to be
437 removed, which fails for the indicated reason.
438 new(remove_when_empty) controls whether the empty folder will
439 removed; setting it to false (0) may be needed to avoid this
440 message.
441 Error: Cannot replace $filename by $tempname, to update folder $name:
443 $!
444 The replace policy wrote a new folder file to update the existing,
445 but was unable to give the final touch: replacing the old version
446 of the folder file for the indicated reason.
447 Warning: Changes not written to read-only folder $self.
449 You have opened the folder read-only --which is the default set by
450 new(access)--, made modifications, and now want to close it. Set
451 close(force) if you want to overrule the access mode, or close the
452 folder with close(write) set to "NEVER".
453 Error: Copying failed for one message.
455 For some reason, for instance disc full, removed by external
456 process, or read-protection, it is impossible to copy one of the
457 messages. Copying will proceed for the other messages.
458 Error: Destination folder $name is not writable.
460 The folder where the messages are copied to is not opened with
461 write access (see new(access)). This has no relation with write
462 permission to the folder which is controlled by your operating
463 system.
464 Warning: Different messages with id $msgid
466 The message id is discovered more than once within the same folder,
467 but the content of the message seems to be different. This should
468 not be possible: each message must be unique.
469 Error: File too short to get write message $nr ($size, $need)
471 Mail::Box is lazy: it tries to leave messages in the folders until
472 they are used, which saves time and memory usage. When this
473 message appears, something is terribly wrong: some lazy message are
474 needed for updating the folder, but they cannot be retrieved from
475 the original file anymore. In this case, messages can be lost.
476 This message does appear regularly on Windows systems when using
478 the 'replace' write policy. Please help to find the cause,
479 probably something to do with Windows incorrectly handling multiple
480 filehandles open in the same file.
481 Error: Folder $name not deleted: not writable.
483 The folder must be opened with write access via new(access),
484 otherwise removing it will be refused. So, you may have write-
485 access according to the operating system, but that will not
486 automatically mean that this "delete" method permits you to. The
487 reverse remark is valid as well.
488 Error: Invalid timespan '$timespan' specified.
490 The string does not follow the strict rules of the time span syntax
491 which is permitted as parameter.
492 Warning: Message-id '$msgid' does not contain a domain.
494 According to the RFCs, message-ids need to contain a unique random
495 part, then an "@", and then a domain name. This is made to avoid
496 the creation of two messages with the same id. The warning emerges
497 when the "@" is missing from the string.
498 Error: Package $package does not implement $method.
500 Fatal error: the specific package (or one of its superclasses) does
501 not implement this method where it should. This message means that
502 some other related classes do implement this method however the
503 class at hand does not. Probably you should investigate this and
504 probably inform the author of the package.
505 Error: Unable to create subfolder $name of $folder.
507 The copy includes the subfolders, but for some reason it was not
508 possible to copy one of these. Copying will proceed for all other
509 sub-folders.
510 Error: Unable to update folder $self.
512 When a folder is to be written, both replace and inplace write
513 policies are tried, If both fail, the whole update fails. You may
514 see other, related, error messages to indicate the real problem.
515
517 This module is part of Mail-Box distribution version 3.009, built on
518 August 18, 2020. Website: http://perl.overmeer.net/CPAN/
519
521 Copyrights 2001-2020 by [Mark Overmeer]. For other contributors see
522 ChangeLog.
523 This program is free software; you can redistribute it and/or modify it
525 under the same terms as Perl itself. See http://dev.perl.org/licenses/
526perl v5.36.0 2023-01-20 Mail::Box::Mbox(3)