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->messageInFile($filename)
266           Returns the folder message which is found the indicated "filename".
267           This may be useful when some external tool reports filename to be
268           opened.
269
270       $obj->read(%options)
271           Inherited, see "Internals" in Mail::Box
272
273       $obj->readMessageFilenames($directory)
274           Returns a list of all filenames which are found in this folder
275           directory and represent a message.  The filenames are returned as
276           relative path.
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.
301
302       $obj->timespan2seconds($time)
303       Mail::Box::Dir->timespan2seconds($time)
304           Inherited, see "Other methods" in Mail::Box
305
306   Error handling
307       Extends "Error handling" in Mail::Box.
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::Dir->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::Dir->log( [$level, [$strings]] )
326           Inherited, see "Error handling" in Mail::Reporter
327
328       $obj->logPriority($level)
329       Mail::Box::Dir->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.
352
353       $obj->DESTROY()
354           Inherited, see "Cleanup" in Mail::Box
355

DETAILS

357       Extends "DETAILS" in Mail::Box.
358

DIAGNOSTICS

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

SEE ALSO

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

LICENSE

432       Copyrights 2001-2020 by [Mark Overmeer]. For other contributors see
433       ChangeLog.
434
435       This program is free software; you can redistribute it and/or modify it
436       under the same terms as Perl itself.  See http://dev.perl.org/licenses/
437
438
439
440perl v5.36.0                      2023-01-20                 Mail::Box::Dir(3)
Impressum