1Mail::Box::Dir(3) User Contributed Perl Documentation Mail::Box::Dir(3)
2
6 Mail::Box::Dir - handle folders with a file per message.
7
9 Mail::Box::Dir
10 is a Mail::Box
11 is a Mail::Reporter
12 Mail::Box::Dir is extended by
14 Mail::Box::MH
15 Mail::Box::Maildir
16
18 # Do not instantiate this object
19
21 This documentation describes the way directory organized mailboxes
22 work. At the moment, this object is extended by
23 • Mail::Box::MH
25 MH folders, which are represented by a directory containing files
27 which are sequentially numbered.
28 • Mail::Box::Maildir
30 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 • Mail::Box::Netzwert
37 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 Extends "DESCRIPTION" in Mail::Box.
43
45 Extends "OVERLOADED" in Mail::Box.
46 overload: ""
48 Inherited, see "OVERLOADED" in Mail::Box
49 overload: @{}
51 Inherited, see "OVERLOADED" in Mail::Box
52 overload: cmp
54 Inherited, see "OVERLOADED" in Mail::Box
55
57 Extends "METHODS" in Mail::Box.
58 Constructors
60 Extends "Constructors" in Mail::Box.
61 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 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 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 The folder
124 Extends "The folder" in Mail::Box.
125 $obj->addMessage($message, %options)
127 Inherited, see "The folder" in Mail::Box
128 $obj->addMessages(@messages)
130 Inherited, see "The folder" in Mail::Box
131 Mail::Box::Dir->appendMessages(%options)
133 Inherited, see "The folder" in Mail::Box
134 $obj->close(%options)
136 Inherited, see "The folder" in Mail::Box
137 $obj->copyTo($folder, %options)
139 Inherited, see "The folder" in Mail::Box
140 $obj->delete(%options)
142 Inherited, see "The folder" in Mail::Box
143 $obj->directory()
145 Returns the directory related to this folder.
146 example:
148 print $folder->directory;
150 $obj->folderdir( [$directory] )
152 Inherited, see "The folder" in Mail::Box
153 $obj->name()
155 Inherited, see "The folder" in Mail::Box
156 $obj->organization()
158 Inherited, see "The folder" in Mail::Box
159 $obj->size()
161 Inherited, see "The folder" in Mail::Box
162 $obj->type()
164 Inherited, see "The folder" in Mail::Box
165 $obj->update(%options)
167 Inherited, see "The folder" in Mail::Box
168 $obj->url()
170 Inherited, see "The folder" in Mail::Box
171 Folder flags
173 Extends "Folder flags" in Mail::Box.
174 $obj->access()
176 Inherited, see "Folder flags" in Mail::Box
177 $obj->isModified()
179 Inherited, see "Folder flags" in Mail::Box
180 $obj->modified( [BOOLEAN] )
182 Inherited, see "Folder flags" in Mail::Box
183 $obj->writable()
185 Inherited, see "Folder flags" in Mail::Box
186 The messages
188 Extends "The messages" in Mail::Box.
189 $obj->current( [$number|$message|$message_id] )
191 Inherited, see "The messages" in Mail::Box
192 $obj->find($message_id)
194 Inherited, see "The messages" in Mail::Box
195 $obj->findFirstLabeled( $label, [BOOLEAN, [$msgs]] )
197 Inherited, see "The messages" in Mail::Box
198 $obj->message( $index, [$message] )
200 Inherited, see "The messages" in Mail::Box
201 $obj->messageId( $message_id, [$message] )
203 Inherited, see "The messages" in Mail::Box
204 $obj->messageIds()
206 Inherited, see "The messages" in Mail::Box
207 $obj->messages( <'ALL'|$range|'ACTIVE'|'DELETED'|$label|
209 !$label|$filter> )
210 Inherited, see "The messages" in Mail::Box
211 $obj->nrMessages(%options)
213 Inherited, see "The messages" in Mail::Box
214 $obj->scanForMessages($message, $message_ids, $timespan, $window)
216 Inherited, see "The messages" in Mail::Box
217 Sub-folders
219 Extends "Sub-folders" in Mail::Box.
220 $obj->listSubFolders(%options)
222 Mail::Box::Dir->listSubFolders(%options)
223 Inherited, see "Sub-folders" in Mail::Box
224 $obj->nameOfSubFolder( $subname, [$parentname] )
226 Mail::Box::Dir->nameOfSubFolder( $subname, [$parentname] )
227 Inherited, see "Sub-folders" in Mail::Box
228 $obj->openRelatedFolder(%options)
230 Inherited, see "Sub-folders" in Mail::Box
231 $obj->openSubFolder($subname, %options)
233 Inherited, see "Sub-folders" in Mail::Box
234 $obj->topFolderWithMessages()
236 Mail::Box::Dir->topFolderWithMessages()
237 Inherited, see "Sub-folders" in Mail::Box
238 Internals
240 Extends "Internals" in Mail::Box.
241 $obj->coerce($message, %options)
243 Inherited, see "Internals" in Mail::Box
244 $obj->create($foldername, %options)
246 Mail::Box::Dir->create($foldername, %options)
247 Inherited, see "Internals" in Mail::Box
248 $obj->determineBodyType($message, $head)
250 Inherited, see "Internals" in Mail::Box
251 $obj->folderToDirectory($foldername, $folderdir)
253 (class method) Translate a foldername into a filename, with use of
254 the $folderdir to replace a leading "=".
255 Mail::Box::Dir->foundIn( [$foldername], %options )
257 Inherited, see "Internals" in Mail::Box
258 $obj->lineSeparator( [<STRING|'CR'|'LF'|'CRLF'>] )
260 Inherited, see "Internals" in Mail::Box
261 $obj->locker()
263 Inherited, see "Internals" in Mail::Box
264 $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 $obj->read(%options)
271 Inherited, see "Internals" in Mail::Box
272 $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 $obj->readMessages(%options)
279 Inherited, see "Internals" in Mail::Box
280 $obj->storeMessage($message)
282 Inherited, see "Internals" in Mail::Box
283 $obj->toBeThreaded($messages)
285 Inherited, see "Internals" in Mail::Box
286 $obj->toBeUnthreaded($messages)
288 Inherited, see "Internals" in Mail::Box
289 $obj->updateMessages(%options)
291 Inherited, see "Internals" in Mail::Box
292 $obj->write(%options)
294 Inherited, see "Internals" in Mail::Box
295 $obj->writeMessages(%options)
297 Inherited, see "Internals" in Mail::Box
298 Other methods
300 Extends "Other methods" in Mail::Box.
301 $obj->timespan2seconds($time)
303 Mail::Box::Dir->timespan2seconds($time)
304 Inherited, see "Other methods" in Mail::Box
305 Error handling
307 Extends "Error handling" in Mail::Box.
308 $obj->AUTOLOAD()
310 Inherited, see "Error handling" in Mail::Reporter
311 $obj->addReport($object)
313 Inherited, see "Error handling" in Mail::Reporter
314 $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 $obj->errors()
322 Inherited, see "Error handling" in Mail::Reporter
323 $obj->log( [$level, [$strings]] )
325 Mail::Box::Dir->log( [$level, [$strings]] )
326 Inherited, see "Error handling" in Mail::Reporter
327 $obj->logPriority($level)
329 Mail::Box::Dir->logPriority($level)
330 Inherited, see "Error handling" in Mail::Reporter
331 $obj->logSettings()
333 Inherited, see "Error handling" in Mail::Reporter
334 $obj->notImplemented()
336 Inherited, see "Error handling" in Mail::Reporter
337 $obj->report( [$level] )
339 Inherited, see "Error handling" in Mail::Reporter
340 $obj->reportAll( [$level] )
342 Inherited, see "Error handling" in Mail::Reporter
343 $obj->trace( [$level] )
345 Inherited, see "Error handling" in Mail::Reporter
346 $obj->warnings()
348 Inherited, see "Error handling" in Mail::Reporter
349 Cleanup
351 Extends "Cleanup" in Mail::Box.
352 $obj->DESTROY()
354 Inherited, see "Cleanup" in Mail::Box
355
357 Extends "DETAILS" in Mail::Box.
358
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 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 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 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 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 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 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 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 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 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 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 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
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
432 Copyrights 2001-2020 by [Mark Overmeer]. For other contributors see
433 ChangeLog.
434 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/
437perl v5.36.0 2023-01-20 Mail::Box::Dir(3)