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->read(%options)
266 Inherited, see "Internals" in Mail::Box
267 $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 $obj->readMessages(%options)
274 Inherited, see "Internals" in Mail::Box
275 $obj->storeMessage($message)
277 Inherited, see "Internals" in Mail::Box
278 $obj->toBeThreaded($messages)
280 Inherited, see "Internals" in Mail::Box
281 $obj->toBeUnthreaded($messages)
283 Inherited, see "Internals" in Mail::Box
284 $obj->updateMessages(%options)
286 Inherited, see "Internals" in Mail::Box
287 $obj->write(%options)
289 Inherited, see "Internals" in Mail::Box
290 $obj->writeMessages(%options)
292 Inherited, see "Internals" in Mail::Box
293 Other methods
295 Extends "Other methods" in Mail::Box.
296 $obj->timespan2seconds($time)
298 Mail::Box::Dir->timespan2seconds($time)
299 Inherited, see "Other methods" in Mail::Box
300 Error handling
302 Extends "Error handling" in Mail::Box.
303 $obj->AUTOLOAD()
305 Inherited, see "Error handling" in Mail::Reporter
306 $obj->addReport($object)
308 Inherited, see "Error handling" in Mail::Reporter
309 $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 $obj->errors()
317 Inherited, see "Error handling" in Mail::Reporter
318 $obj->log( [$level, [$strings]] )
320 Mail::Box::Dir->log( [$level, [$strings]] )
321 Inherited, see "Error handling" in Mail::Reporter
322 $obj->logPriority($level)
324 Mail::Box::Dir->logPriority($level)
325 Inherited, see "Error handling" in Mail::Reporter
326 $obj->logSettings()
328 Inherited, see "Error handling" in Mail::Reporter
329 $obj->notImplemented()
331 Inherited, see "Error handling" in Mail::Reporter
332 $obj->report( [$level] )
334 Inherited, see "Error handling" in Mail::Reporter
335 $obj->reportAll( [$level] )
337 Inherited, see "Error handling" in Mail::Reporter
338 $obj->trace( [$level] )
340 Inherited, see "Error handling" in Mail::Reporter
341 $obj->warnings()
343 Inherited, see "Error handling" in Mail::Reporter
344 Cleanup
346 Extends "Cleanup" in Mail::Box.
347 $obj->DESTROY()
349 Inherited, see "Cleanup" in Mail::Box
350
352 Extends "DETAILS" in Mail::Box.
353
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 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 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 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 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 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 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 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 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 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 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 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
423 This module is part of Mail-Box distribution version 3.008, built on
424 October 04, 2019. Website: http://perl.overmeer.net/CPAN/
425
427 Copyrights 2001-2019 by [Mark Overmeer]. For other contributors see
428 ChangeLog.
429 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/
432perl v5.30.1 2020-01-30 Mail::Box::Dir(3)