1Mail::Box::Maildir(3) User Contributed Perl DocumentationMail::Box::Maildir(3)
2
3
4

NAME

6       Mail::Box::Maildir - handle Maildir folders
7

INHERITANCE

9        Mail::Box::Maildir
10          is a Mail::Box::Dir
11          is a Mail::Box
12          is a Mail::Reporter
13

SYNOPSIS

15        use Mail::Box::Maildir;
16        my $folder = new Mail::Box::Maildir folder => $ENV{MAIL}, ...;
17

DESCRIPTION

19       This documentation describes how Maildir mailboxes work, and what you
20       can do with the Maildir folder object "Mail::Box::Maildir".
21
22       Maildir is not supported for Windows, because it create filenames which
23       are not accepted by the Windows system.
24
25       Extends "DESCRIPTION" in Mail::Box::Dir.
26

OVERLOADED

28       Extends "OVERLOADED" in Mail::Box::Dir.
29
30       overload: ""
31           Inherited, see "OVERLOADED" in Mail::Box
32
33       overload: @{}
34           Inherited, see "OVERLOADED" in Mail::Box
35
36       overload: cmp
37           Inherited, see "OVERLOADED" in Mail::Box
38

METHODS

40       Extends "METHODS" in Mail::Box::Dir.
41
42   Constructors
43       Extends "Constructors" in Mail::Box::Dir.
44
45       Mail::Box::Maildir->new(%options)
46            -Option           --Defined in     --Default
47             accept_new                          <false>
48             access             Mail::Box        'r'
49             body_delayed_type  Mail::Box        Mail::Message::Body::Delayed
50             body_type          Mail::Box        Mail::Message::Body::Lines
51             coerce_options     Mail::Box        []
52             create             Mail::Box        <false>
53             directory          Mail::Box::Dir   <derived from folder name>
54             extract            Mail::Box        10240
55             field_type         Mail::Box        undef
56             fix_headers        Mail::Box        <false>
57             folder             Mail::Box        $ENV{MAIL}
58             folderdir          Mail::Box        $ENV{HOME}/.maildir
59             head_delayed_type  Mail::Box        Mail::Message::Head::Delayed
60             head_type          Mail::Box        Mail::Message::Head::Complete
61             keep_dups          Mail::Box        <false>
62             lock_file          Mail::Box        <not used>
63             lock_timeout       Mail::Box        <not used>
64             lock_type          Mail::Box        'NONE' (constant)
65             lock_wait          Mail::Box        <not used>
66             locker             Mail::Box        undef
67             log                Mail::Reporter   'WARNINGS'
68             manager            Mail::Box        undef
69             message_type       Mail::Box        <folder-class>::Message
70             multipart_type     Mail::Box        Mail::Message::Body::Multipart
71             remove_when_empty  Mail::Box        <true>
72             save_on_exit       Mail::Box        <true>
73             trace              Mail::Reporter   'WARNINGS'
74             trusted            Mail::Box        <depends on folder location>
75
76           accept_new => BOOLEAN
77             When the folder is open, some messages may be stored in the "new"
78             sub-directory.  By default, these messages are immediately moved
79             to the "cur" directory when the folder is opened.  Otherwise, you
80             have to call acceptMessages() or
81             Mail::Box::Maildir::Message::accept().
82
83           access => MODE
84           body_delayed_type => CLASS
85           body_type => CLASS|CODE
86           coerce_options => ARRAY
87           create => BOOLEAN
88           directory => DIRECTORY
89           extract => INTEGER | CODE | METHOD | 'LAZY'|'ALWAYS'
90           field_type => CLASS
91           fix_headers => BOOLEAN
92           folder => FOLDERNAME
93           folderdir => DIRECTORY
94           head_delayed_type => CLASS
95           head_type => CLASS
96           keep_dups => BOOLEAN
97           lock_file => FILENAME
98           lock_timeout => SECONDS
99           lock_type => CLASS|STRING|ARRAY
100           lock_wait => SECONDS
101           locker => OBJECT
102           log => LEVEL
103           manager => MANAGER
104           message_type => CLASS
105           multipart_type => CLASS
106           remove_when_empty => BOOLEAN
107           save_on_exit => BOOLEAN
108           trace => LEVEL
109           trusted => BOOLEAN
110
111   The folder
112       Extends "The folder" in Mail::Box::Dir.
113
114       $obj->addMessage($message, %options)
115           Inherited, see "The folder" in Mail::Box
116
117       $obj->addMessages(@messages)
118           Inherited, see "The folder" in Mail::Box
119
120       Mail::Box::Maildir->appendMessages(%options)
121           Inherited, see "The folder" in Mail::Box
122
123       $obj->close(%options)
124           Inherited, see "The folder" in Mail::Box
125
126       $obj->copyTo($folder, %options)
127           Inherited, see "The folder" in Mail::Box
128
129       $obj->delete(%options)
130           Inherited, see "The folder" in Mail::Box
131
132       $obj->directory()
133           Inherited, see "The folder" in Mail::Box::Dir
134
135       $obj->folderdir( [$directory] )
136           Inherited, see "The folder" in Mail::Box
137
138       $obj->name()
139           Inherited, see "The folder" in Mail::Box
140
141       $obj->organization()
142           Inherited, see "The folder" in Mail::Box
143
144       $obj->size()
145           Inherited, see "The folder" in Mail::Box
146
147       $obj->type()
148           Inherited, see "The folder" in Mail::Box
149
150       $obj->update(%options)
151           Inherited, see "The folder" in Mail::Box
152
153       $obj->url()
154           Inherited, see "The folder" in Mail::Box
155
156   Folder flags
157       Extends "Folder flags" in Mail::Box::Dir.
158
159       $obj->access()
160           Inherited, see "Folder flags" in Mail::Box
161
162       $obj->isModified()
163           Inherited, see "Folder flags" in Mail::Box
164
165       $obj->modified( [BOOLEAN] )
166           Inherited, see "Folder flags" in Mail::Box
167
168       $obj->writable()
169           Inherited, see "Folder flags" in Mail::Box
170
171   The messages
172       Extends "The messages" in Mail::Box::Dir.
173
174       $obj->current( [$number|$message|$message_id] )
175           Inherited, see "The messages" in Mail::Box
176
177       $obj->find($message_id)
178           Inherited, see "The messages" in Mail::Box
179
180       $obj->findFirstLabeled( $label, [BOOLEAN, [$msgs]] )
181           Inherited, see "The messages" in Mail::Box
182
183       $obj->message( $index, [$message] )
184           Inherited, see "The messages" in Mail::Box
185
186       $obj->messageId( $message_id, [$message] )
187           Inherited, see "The messages" in Mail::Box
188
189       $obj->messageIds()
190           Inherited, see "The messages" in Mail::Box
191
192       $obj->messages( <'ALL'|$range|'ACTIVE'|'DELETED'|$label|
193       !$label|$filter> )
194           Inherited, see "The messages" in Mail::Box
195
196       $obj->nrMessages(%options)
197           Inherited, see "The messages" in Mail::Box
198
199       $obj->scanForMessages($message, $message_ids, $timespan, $window)
200           Inherited, see "The messages" in Mail::Box
201
202   Sub-folders
203       Extends "Sub-folders" in Mail::Box::Dir.
204
205       $obj->listSubFolders(%options)
206       Mail::Box::Maildir->listSubFolders(%options)
207           Inherited, see "Sub-folders" in Mail::Box
208
209       $obj->nameOfSubFolder( $subname, [$parentname] )
210       Mail::Box::Maildir->nameOfSubFolder( $subname, [$parentname] )
211           Inherited, see "Sub-folders" in Mail::Box
212
213       $obj->openRelatedFolder(%options)
214           Inherited, see "Sub-folders" in Mail::Box
215
216       $obj->openSubFolder($subname, %options)
217           Inherited, see "Sub-folders" in Mail::Box
218
219       $obj->topFolderWithMessages()
220       Mail::Box::Maildir->topFolderWithMessages()
221           Inherited, see "Sub-folders" in Mail::Box
222
223   Internals
224       Extends "Internals" in Mail::Box::Dir.
225
226       $obj->acceptMessages()
227           Accept all messages which are waiting in the "new" directory to be
228           moved to the "cur" directory.  This will not rescan the directory
229           for newly arrived messages, because that's a task for update().
230
231       Mail::Box::Maildir->appendMessage(%options)
232       $obj->coerce($message, %options)
233       $obj->create($foldername, %options)
234       Mail::Box::Maildir->create($foldername, %options)
235            -Option   --Defined in--Default
236             folderdir  Mail::Box   undef
237
238           folderdir => DIRECTORY
239       $obj->createDirs($folderdir)
240       Mail::Box::Maildir->createDirs($folderdir)
241           The $folderdir contains the absolute path of the location where the
242           messages are kept.  Maildir folders contain a "tmp", "new", and
243           "cur" sub-directory within that folder directory as well.  This
244           method will ensure that all directories exist.  Returns false on
245           failure.
246
247       $obj->determineBodyType($message, $head)
248           Inherited, see "Internals" in Mail::Box
249
250       $obj->folderIsEmpty($folderdir)
251       Mail::Box::Maildir->folderIsEmpty($folderdir)
252           Checks whether the folder whose directory is specified as absolute
253           $folderdir is empty or not.  A folder is empty when the "tmp",
254           "new", and "cur" subdirectories are empty and some files which are
255           left there by application programs.  The maildir spec explicitly
256           states: ".qmail", "bulletintime", "bulletinlock" and "seriallock".
257           If any other files are found, the directory is considered not-
258           empty.
259
260       $obj->folderToDirectory($foldername, $folderdir)
261           Inherited, see "Internals" in Mail::Box::Dir
262
263       Mail::Box::Maildir->foundIn( [$foldername], %options )
264           Inherited, see "Internals" in Mail::Box
265
266       $obj->lineSeparator( [<STRING|'CR'|'LF'|'CRLF'>] )
267           Inherited, see "Internals" in Mail::Box
268
269       $obj->locker()
270           Inherited, see "Internals" in Mail::Box
271
272       $obj->messageInFile($filename)
273           Inherited, see "Internals" in Mail::Box::Dir
274
275       $obj->read(%options)
276           Inherited, see "Internals" in Mail::Box
277
278       $obj->readMessageFilenames($directory)
279           Inherited, see "Internals" in Mail::Box::Dir
280
281       $obj->readMessages(%options)
282           Inherited, see "Internals" in Mail::Box
283
284       $obj->storeMessage($message)
285           Inherited, see "Internals" in Mail::Box
286
287       $obj->toBeThreaded($messages)
288           Inherited, see "Internals" in Mail::Box
289
290       $obj->toBeUnthreaded($messages)
291           Inherited, see "Internals" in Mail::Box
292
293       $obj->updateMessages(%options)
294           Inherited, see "Internals" in Mail::Box
295
296       $obj->write(%options)
297           Inherited, see "Internals" in Mail::Box
298
299       $obj->writeMessages(%options)
300           Inherited, see "Internals" in Mail::Box
301
302   Other methods
303       Extends "Other methods" in Mail::Box::Dir.
304
305       $obj->timespan2seconds($time)
306       Mail::Box::Maildir->timespan2seconds($time)
307           Inherited, see "Other methods" in Mail::Box
308
309   Error handling
310       Extends "Error handling" in Mail::Box::Dir.
311
312       $obj->AUTOLOAD()
313           Inherited, see "Error handling" in Mail::Reporter
314
315       $obj->addReport($object)
316           Inherited, see "Error handling" in Mail::Reporter
317
318       $obj->defaultTrace( [$level]|[$loglevel, $tracelevel]|[$level,
319       $callback] )
320       Mail::Box::Maildir->defaultTrace( [$level]|[$loglevel,
321       $tracelevel]|[$level, $callback] )
322           Inherited, see "Error handling" in Mail::Reporter
323
324       $obj->errors()
325           Inherited, see "Error handling" in Mail::Reporter
326
327       $obj->log( [$level, [$strings]] )
328       Mail::Box::Maildir->log( [$level, [$strings]] )
329           Inherited, see "Error handling" in Mail::Reporter
330
331       $obj->logPriority($level)
332       Mail::Box::Maildir->logPriority($level)
333           Inherited, see "Error handling" in Mail::Reporter
334
335       $obj->logSettings()
336           Inherited, see "Error handling" in Mail::Reporter
337
338       $obj->notImplemented()
339           Inherited, see "Error handling" in Mail::Reporter
340
341       $obj->report( [$level] )
342           Inherited, see "Error handling" in Mail::Reporter
343
344       $obj->reportAll( [$level] )
345           Inherited, see "Error handling" in Mail::Reporter
346
347       $obj->trace( [$level] )
348           Inherited, see "Error handling" in Mail::Reporter
349
350       $obj->warnings()
351           Inherited, see "Error handling" in Mail::Reporter
352
353   Cleanup
354       Extends "Cleanup" in Mail::Box::Dir.
355
356       $obj->DESTROY()
357           Inherited, see "Cleanup" in Mail::Box
358

DETAILS

360       The explanation is complicated, but for normal use you should bother
361       yourself with all details.
362
363       Extends "DETAILS" in Mail::Box::Dir.
364
365   Different kinds of folders
366       Extends "Different kinds of folders" in Mail::Box::Dir.
367
368   Available folder types
369       Extends "Available folder types" in Mail::Box::Dir.
370
371   Folder class implementation
372       Extends "Folder class implementation" in Mail::Box::Dir.
373
374   How MAILDIR folders work
375       Maildir-type folders use a directory to store the messages of one
376       folder.  Each message is stored in a separate file.  This seems useful,
377       because changes in a folder change only a few of these small files, in
378       contrast with file-based folders where changes in a folder cause
379       rewrites of huge folder-files.
380
381       However, Maildir based folders perform very bad if you need header
382       information of all messages.  For instance, if you want to have full
383       knowledge about all message-threads (see Mail::Box::Thread::Manager) in
384       the folder, it requires to read all header lines in all message files.
385       And usually, reading your messages as threads is desired.  Maildir
386       maintains a tiny amount of info visible in the filename, which may make
387       it perform just a little bit faster than MH.
388

DIAGNOSTICS

390       Error: Cannot append Maildir message in $new to folder $self.
391           The message (or messages) could not be stored in the right
392           directories for the Maildir folder.
393
394       Error: Cannot create Maildir directory $dir: $!
395           A Maildir folder is represented by a directory, with some sub-
396           directories.  The top folder directory could not be created for the
397           reason indicated.
398
399       Error: Cannot create Maildir folder $name.
400           One or more of the directories required to administer a Maildir
401           folder could not be created.
402
403       Error: Cannot create Maildir message file $new.
404           A message is converted from some other message format into a
405           Maildir format by writing it to a file with a name which contains
406           the status flags of the message.  Apparently, creating this file
407           failed.
408
409       Error: Cannot create Maildir subdir $dir: $!
410           Each Maildir folder has three sub-directories for administration:
411           "new", "tmp", and "cur".  The mentioned directory could not be
412           created for the indicated reason.
413
414       Warning: Changes not written to read-only folder $self.
415           You have opened the folder read-only --which is the default set by
416           new(access)--, made modifications, and now want to close it.  Set
417           close(force) if you want to overrule the access mode, or close the
418           folder with close(write) set to "NEVER".
419
420       Error: Copying failed for one message.
421           For some reason, for instance disc full, removed by external
422           process, or read-protection, it is impossible to copy one of the
423           messages.  Copying will proceed for the other messages.
424
425       Error: Destination folder $name is not writable.
426           The folder where the messages are copied to is not opened with
427           write access (see new(access)).  This has no relation with write
428           permission to the folder which is controlled by your operating
429           system.
430
431       Warning: Different messages with id $msgid
432           The message id is discovered more than once within the same folder,
433           but the content of the message seems to be different.  This should
434           not be possible: each message must be unique.
435
436       Error: Folder $name is opened read-only
437           You can not write to this folder unless you have opened the folder
438           to write or append with new(access), or the "force" option is set
439           true.
440
441       Error: Folder $name not deleted: not writable.
442           The folder must be opened with write access via new(access),
443           otherwise removing it will be refused.  So, you may have write-
444           access according to the operating system, but that will not
445           automatically mean that this "delete" method permits you to.  The
446           reverse remark is valid as well.
447
448       Error: Invalid timespan '$timespan' specified.
449           The string does not follow the strict rules of the time span syntax
450           which is permitted as parameter.
451
452       Warning: Message-id '$msgid' does not contain a domain.
453           According to the RFCs, message-ids need to contain a unique random
454           part, then an "@", and then a domain name.  This is made to avoid
455           the creation of two messages with the same id.  The warning emerges
456           when the "@" is missing from the string.
457
458       Error: Package $package does not implement $method.
459           Fatal error: the specific package (or one of its superclasses) does
460           not implement this method where it should. This message means that
461           some other related classes do implement this method however the
462           class at hand does not.  Probably you should investigate this and
463           probably inform the author of the package.
464
465       Error: Unable to create subfolder $name of $folder.
466           The copy includes the subfolders, but for some reason it was not
467           possible to copy one of these.  Copying will proceed for all other
468           sub-folders.
469
470       Error: Writing folder $name failed
471           For some reason (you probably got more error messages about this
472           problem) it is impossible to write the folder, although you should
473           because there were changes made.
474

SEE ALSO

476       This module is part of Mail-Box distribution version 3.009, built on
477       August 18, 2020. Website: http://perl.overmeer.net/CPAN/
478

LICENSE

480       Copyrights 2001-2020 by [Mark Overmeer]. For other contributors see
481       ChangeLog.
482
483       This program is free software; you can redistribute it and/or modify it
484       under the same terms as Perl itself.  See http://dev.perl.org/licenses/
485
486
487
488perl v5.34.0                      2022-01-21             Mail::Box::Maildir(3)
Impressum