1Mail::Box::Dir(3)     User Contributed Perl Documentation    Mail::Box::Dir(3)
2
3
4

NAME

6       Mail::Box::Dir - handle folders with a file per message.
7

INHERITANCE

9        Mail::Box::Dir
10          is a Mail::Box
11          is a Mail::Reporter
12
13        Mail::Box::Dir is extended by
14          Mail::Box::MH
15          Mail::Box::Maildir
16

SYNOPSIS

18        # Do not instantiate this object
19

DESCRIPTION

21       This documentation describes the way directory organized mailboxes
22       work.  At the moment, this object is extended by
23
24       ·   Mail::Box::MH
25
26           MH folders, which are represented by a directory containing files
27           which are sequentially numbered.
28
29       ·   Mail::Box::Maildir
30
31           Maildir folders, which are located in a directory which has sub-
32           directories named "tmp", "new", and "cur".  Each of these
33           directories may contain files with names which are a combination of
34           a numeric timestamp and some status flags.
35
36       ·   Mail::Box::Netzwert
37
38           This folder type was especially developed for Netzwert AG,
39           optimized to run on a cluster of servers with folders on NFS.  The
40           code is not publicly available (yet).
41
42       Extends "DESCRIPTION" in Mail::Box.
43

OVERLOADED

45       Extends "OVERLOADED" in Mail::Box.
46
47       overload: ""
48           Inherited, see "OVERLOADED" in Mail::Box
49
50       overload: @{}
51           Inherited, see "OVERLOADED" in Mail::Box
52
53       overload: cmp
54           Inherited, see "OVERLOADED" in Mail::Box
55

METHODS

57       Extends "METHODS" in Mail::Box.
58
59   Constructors
60       Extends "Constructors" in Mail::Box.
61
62       Mail::Box::Dir->new(%options)
63            -Option           --Defined in     --Default
64             access             Mail::Box        'r'
65             body_delayed_type  Mail::Box        Mail::Message::Body::Delayed
66             body_type          Mail::Box        Mail::Message::Body::Lines
67             coerce_options     Mail::Box        []
68             create             Mail::Box        <false>
69             directory                           <derived from folder name>
70             extract            Mail::Box        10240
71             field_type         Mail::Box        undef
72             fix_headers        Mail::Box        <false>
73             folder             Mail::Box        $ENV{MAIL}
74             folderdir          Mail::Box        undef
75             head_delayed_type  Mail::Box        Mail::Message::Head::Delayed
76             head_type          Mail::Box        Mail::Message::Head::Complete
77             keep_dups          Mail::Box        <false>
78             lock_file          Mail::Box        <folder>/.lock
79             lock_timeout       Mail::Box        1 hour
80             lock_type          Mail::Box        Mail::Box::Locker::DotLock
81             lock_wait          Mail::Box        10 seconds
82             locker             Mail::Box        undef
83             log                Mail::Reporter   'WARNINGS'
84             manager            Mail::Box        undef
85             message_type       Mail::Box        <folder-class>::Message
86             multipart_type     Mail::Box        Mail::Message::Body::Multipart
87             remove_when_empty  Mail::Box        <true>
88             save_on_exit       Mail::Box        <true>
89             trace              Mail::Reporter   'WARNINGS'
90             trusted            Mail::Box        <depends on folder location>
91
92           access => MODE
93           body_delayed_type => CLASS
94           body_type => CLASS|CODE
95           coerce_options => ARRAY
96           create => BOOLEAN
97           directory => DIRECTORY
98             For rare folder types, the directory name may differ from the
99             folder name.
100
101           extract => INTEGER | CODE | METHOD | 'LAZY'|'ALWAYS'
102           field_type => CLASS
103           fix_headers => BOOLEAN
104           folder => FOLDERNAME
105           folderdir => DIRECTORY
106           head_delayed_type => CLASS
107           head_type => CLASS
108           keep_dups => BOOLEAN
109           lock_file => FILENAME
110           lock_timeout => SECONDS
111           lock_type => CLASS|STRING|ARRAY
112           lock_wait => SECONDS
113           locker => OBJECT
114           log => LEVEL
115           manager => MANAGER
116           message_type => CLASS
117           multipart_type => CLASS
118           remove_when_empty => BOOLEAN
119           save_on_exit => BOOLEAN
120           trace => LEVEL
121           trusted => BOOLEAN
122
123   The folder
124       Extends "The folder" in Mail::Box.
125
126       $obj->addMessage($message, %options)
127           Inherited, see "The folder" in Mail::Box
128
129       $obj->addMessages(@messages)
130           Inherited, see "The folder" in Mail::Box
131
132       Mail::Box::Dir->appendMessages(%options)
133           Inherited, see "The folder" in Mail::Box
134
135       $obj->close(%options)
136           Inherited, see "The folder" in Mail::Box
137
138       $obj->copyTo($folder, %options)
139           Inherited, see "The folder" in Mail::Box
140
141       $obj->delete(%options)
142           Inherited, see "The folder" in Mail::Box
143
144       $obj->directory()
145           Returns the directory related to this folder.
146
147           example:
148
149            print $folder->directory;
150
151       $obj->folderdir( [$directory] )
152           Inherited, see "The folder" in Mail::Box
153
154       $obj->name()
155           Inherited, see "The folder" in Mail::Box
156
157       $obj->organization()
158           Inherited, see "The folder" in Mail::Box
159
160       $obj->size()
161           Inherited, see "The folder" in Mail::Box
162
163       $obj->type()
164           Inherited, see "The folder" in Mail::Box
165
166       $obj->update(%options)
167           Inherited, see "The folder" in Mail::Box
168
169       $obj->url()
170           Inherited, see "The folder" in Mail::Box
171
172   Folder flags
173       Extends "Folder flags" in Mail::Box.
174
175       $obj->access()
176           Inherited, see "Folder flags" in Mail::Box
177
178       $obj->isModified()
179           Inherited, see "Folder flags" in Mail::Box
180
181       $obj->modified( [BOOLEAN] )
182           Inherited, see "Folder flags" in Mail::Box
183
184       $obj->writable()
185           Inherited, see "Folder flags" in Mail::Box
186
187   The messages
188       Extends "The messages" in Mail::Box.
189
190       $obj->current( [$number|$message|$message_id] )
191           Inherited, see "The messages" in Mail::Box
192
193       $obj->find($message_id)
194           Inherited, see "The messages" in Mail::Box
195
196       $obj->findFirstLabeled( $label, [BOOLEAN, [$msgs]] )
197           Inherited, see "The messages" in Mail::Box
198
199       $obj->message( $index, [$message] )
200           Inherited, see "The messages" in Mail::Box
201
202       $obj->messageId( $message_id, [$message] )
203           Inherited, see "The messages" in Mail::Box
204
205       $obj->messageIds()
206           Inherited, see "The messages" in Mail::Box
207
208       $obj->messages( <'ALL'|$range|'ACTIVE'|'DELETED'|$label|
209       !$label|$filter> )
210           Inherited, see "The messages" in Mail::Box
211
212       $obj->nrMessages(%options)
213           Inherited, see "The messages" in Mail::Box
214
215       $obj->scanForMessages($message, $message_ids, $timespan, $window)
216           Inherited, see "The messages" in Mail::Box
217
218   Sub-folders
219       Extends "Sub-folders" in Mail::Box.
220
221       $obj->listSubFolders(%options)
222       Mail::Box::Dir->listSubFolders(%options)
223           Inherited, see "Sub-folders" in Mail::Box
224
225       $obj->nameOfSubFolder( $subname, [$parentname] )
226       Mail::Box::Dir->nameOfSubFolder( $subname, [$parentname] )
227           Inherited, see "Sub-folders" in Mail::Box
228
229       $obj->openRelatedFolder(%options)
230           Inherited, see "Sub-folders" in Mail::Box
231
232       $obj->openSubFolder($subname, %options)
233           Inherited, see "Sub-folders" in Mail::Box
234
235       $obj->topFolderWithMessages()
236       Mail::Box::Dir->topFolderWithMessages()
237           Inherited, see "Sub-folders" in Mail::Box
238
239   Internals
240       Extends "Internals" in Mail::Box.
241
242       $obj->coerce($message, %options)
243           Inherited, see "Internals" in Mail::Box
244
245       $obj->create($foldername, %options)
246       Mail::Box::Dir->create($foldername, %options)
247           Inherited, see "Internals" in Mail::Box
248
249       $obj->determineBodyType($message, $head)
250           Inherited, see "Internals" in Mail::Box
251
252       $obj->folderToDirectory($foldername, $folderdir)
253           (class method)  Translate a foldername into a filename, with use of
254           the $folderdir to replace a leading "=".
255
256       Mail::Box::Dir->foundIn( [$foldername], %options )
257           Inherited, see "Internals" in Mail::Box
258
259       $obj->lineSeparator( [<STRING|'CR'|'LF'|'CRLF'>] )
260           Inherited, see "Internals" in Mail::Box
261
262       $obj->locker()
263           Inherited, see "Internals" in Mail::Box
264
265       $obj->read(%options)
266           Inherited, see "Internals" in Mail::Box
267
268       $obj->readMessageFilenames($directory)
269           Returns a list of all filenames which are found in this folder
270           directory and represent a message.  The filenames are returned as
271           relative path.
272
273       $obj->readMessages(%options)
274           Inherited, see "Internals" in Mail::Box
275
276       $obj->storeMessage($message)
277           Inherited, see "Internals" in Mail::Box
278
279       $obj->toBeThreaded($messages)
280           Inherited, see "Internals" in Mail::Box
281
282       $obj->toBeUnthreaded($messages)
283           Inherited, see "Internals" in Mail::Box
284
285       $obj->updateMessages(%options)
286           Inherited, see "Internals" in Mail::Box
287
288       $obj->write(%options)
289           Inherited, see "Internals" in Mail::Box
290
291       $obj->writeMessages(%options)
292           Inherited, see "Internals" in Mail::Box
293
294   Other methods
295       Extends "Other methods" in Mail::Box.
296
297       $obj->timespan2seconds($time)
298       Mail::Box::Dir->timespan2seconds($time)
299           Inherited, see "Other methods" in Mail::Box
300
301   Error handling
302       Extends "Error handling" in Mail::Box.
303
304       $obj->AUTOLOAD()
305           Inherited, see "Error handling" in Mail::Reporter
306
307       $obj->addReport($object)
308           Inherited, see "Error handling" in Mail::Reporter
309
310       $obj->defaultTrace( [$level]|[$loglevel, $tracelevel]|[$level,
311       $callback] )
312       Mail::Box::Dir->defaultTrace( [$level]|[$loglevel,
313       $tracelevel]|[$level, $callback] )
314           Inherited, see "Error handling" in Mail::Reporter
315
316       $obj->errors()
317           Inherited, see "Error handling" in Mail::Reporter
318
319       $obj->log( [$level, [$strings]] )
320       Mail::Box::Dir->log( [$level, [$strings]] )
321           Inherited, see "Error handling" in Mail::Reporter
322
323       $obj->logPriority($level)
324       Mail::Box::Dir->logPriority($level)
325           Inherited, see "Error handling" in Mail::Reporter
326
327       $obj->logSettings()
328           Inherited, see "Error handling" in Mail::Reporter
329
330       $obj->notImplemented()
331           Inherited, see "Error handling" in Mail::Reporter
332
333       $obj->report( [$level] )
334           Inherited, see "Error handling" in Mail::Reporter
335
336       $obj->reportAll( [$level] )
337           Inherited, see "Error handling" in Mail::Reporter
338
339       $obj->trace( [$level] )
340           Inherited, see "Error handling" in Mail::Reporter
341
342       $obj->warnings()
343           Inherited, see "Error handling" in Mail::Reporter
344
345   Cleanup
346       Extends "Cleanup" in Mail::Box.
347
348       $obj->DESTROY()
349           Inherited, see "Cleanup" in Mail::Box
350

DETAILS

352       Extends "DETAILS" in Mail::Box.
353

DIAGNOSTICS

355       Warning: Changes not written to read-only folder $self.
356           You have opened the folder read-only --which is the default set by
357           new(access)--, made modifications, and now want to close it.  Set
358           close(force) if you want to overrule the access mode, or close the
359           folder with close(write) set to "NEVER".
360
361       Error: Copying failed for one message.
362           For some reason, for instance disc full, removed by external
363           process, or read-protection, it is impossible to copy one of the
364           messages.  Copying will proceed for the other messages.
365
366       Error: Destination folder $name is not writable.
367           The folder where the messages are copied to is not opened with
368           write access (see new(access)).  This has no relation with write
369           permission to the folder which is controlled by your operating
370           system.
371
372       Warning: Different messages with id $msgid
373           The message id is discovered more than once within the same folder,
374           but the content of the message seems to be different.  This should
375           not be possible: each message must be unique.
376
377       Error: Folder $name is opened read-only
378           You can not write to this folder unless you have opened the folder
379           to write or append with new(access), or the "force" option is set
380           true.
381
382       Error: Folder $name not deleted: not writable.
383           The folder must be opened with write access via new(access),
384           otherwise removing it will be refused.  So, you may have write-
385           access according to the operating system, but that will not
386           automatically mean that this "delete" method permits you to.  The
387           reverse remark is valid as well.
388
389       Warning: Folder directory $directory is write-protected.
390           The folder directory does already exist and is write protected,
391           which may interfere with the requested write access.  Change
392           new(access) or the permissions on the directory.
393
394       Error: Invalid timespan '$timespan' specified.
395           The string does not follow the strict rules of the time span syntax
396           which is permitted as parameter.
397
398       Warning: Message-id '$msgid' does not contain a domain.
399           According to the RFCs, message-ids need to contain a unique random
400           part, then an "@", and then a domain name.  This is made to avoid
401           the creation of two messages with the same id.  The warning emerges
402           when the "@" is missing from the string.
403
404       Warning: No directory $name for folder of $class
405       Error: Package $package does not implement $method.
406           Fatal error: the specific package (or one of its superclasses) does
407           not implement this method where it should. This message means that
408           some other related classes do implement this method however the
409           class at hand does not.  Probably you should investigate this and
410           probably inform the author of the package.
411
412       Error: Unable to create subfolder $name of $folder.
413           The copy includes the subfolders, but for some reason it was not
414           possible to copy one of these.  Copying will proceed for all other
415           sub-folders.
416
417       Error: Writing folder $name failed
418           For some reason (you probably got more error messages about this
419           problem) it is impossible to write the folder, although you should
420           because there were changes made.
421

SEE ALSO

423       This module is part of Mail-Box distribution version 3.006, built on
424       February 15, 2019. Website: http://perl.overmeer.net/CPAN/
425

LICENSE

427       Copyrights 2001-2019 by [Mark Overmeer]. For other contributors see
428       ChangeLog.
429
430       This program is free software; you can redistribute it and/or modify it
431       under the same terms as Perl itself.  See http://dev.perl.org/licenses/
432
433
434
435perl v5.28.1                      2019-02-15                 Mail::Box::Dir(3)
Impressum