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->read(%options)
273           Inherited, see "Internals" in Mail::Box
274
275       $obj->readMessageFilenames($directory)
276           Inherited, see "Internals" in Mail::Box::Dir
277
278       $obj->readMessages(%options)
279           Inherited, see "Internals" in Mail::Box
280
281       $obj->storeMessage($message)
282           Inherited, see "Internals" in Mail::Box
283
284       $obj->toBeThreaded($messages)
285           Inherited, see "Internals" in Mail::Box
286
287       $obj->toBeUnthreaded($messages)
288           Inherited, see "Internals" in Mail::Box
289
290       $obj->updateMessages(%options)
291           Inherited, see "Internals" in Mail::Box
292
293       $obj->write(%options)
294           Inherited, see "Internals" in Mail::Box
295
296       $obj->writeMessages(%options)
297           Inherited, see "Internals" in Mail::Box
298
299   Other methods
300       Extends "Other methods" in Mail::Box::Dir.
301
302       $obj->timespan2seconds($time)
303       Mail::Box::Maildir->timespan2seconds($time)
304           Inherited, see "Other methods" in Mail::Box
305
306   Error handling
307       Extends "Error handling" in Mail::Box::Dir.
308
309       $obj->AUTOLOAD()
310           Inherited, see "Error handling" in Mail::Reporter
311
312       $obj->addReport($object)
313           Inherited, see "Error handling" in Mail::Reporter
314
315       $obj->defaultTrace( [$level]|[$loglevel, $tracelevel]|[$level,
316       $callback] )
317       Mail::Box::Maildir->defaultTrace( [$level]|[$loglevel,
318       $tracelevel]|[$level, $callback] )
319           Inherited, see "Error handling" in Mail::Reporter
320
321       $obj->errors()
322           Inherited, see "Error handling" in Mail::Reporter
323
324       $obj->log( [$level, [$strings]] )
325       Mail::Box::Maildir->log( [$level, [$strings]] )
326           Inherited, see "Error handling" in Mail::Reporter
327
328       $obj->logPriority($level)
329       Mail::Box::Maildir->logPriority($level)
330           Inherited, see "Error handling" in Mail::Reporter
331
332       $obj->logSettings()
333           Inherited, see "Error handling" in Mail::Reporter
334
335       $obj->notImplemented()
336           Inherited, see "Error handling" in Mail::Reporter
337
338       $obj->report( [$level] )
339           Inherited, see "Error handling" in Mail::Reporter
340
341       $obj->reportAll( [$level] )
342           Inherited, see "Error handling" in Mail::Reporter
343
344       $obj->trace( [$level] )
345           Inherited, see "Error handling" in Mail::Reporter
346
347       $obj->warnings()
348           Inherited, see "Error handling" in Mail::Reporter
349
350   Cleanup
351       Extends "Cleanup" in Mail::Box::Dir.
352
353       $obj->DESTROY()
354           Inherited, see "Cleanup" in Mail::Box
355

DETAILS

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

DIAGNOSTICS

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

SEE ALSO

473       This module is part of Mail-Box distribution version 3.007, built on
474       May 03, 2019. Website: http://perl.overmeer.net/CPAN/
475

LICENSE

477       Copyrights 2001-2019 by [Mark Overmeer]. For other contributors see
478       ChangeLog.
479
480       This program is free software; you can redistribute it and/or modify it
481       under the same terms as Perl itself.  See http://dev.perl.org/licenses/
482
483
484
485perl v5.30.0                      2019-07-26             Mail::Box::Maildir(3)
Impressum