1Mail::Box::Identity(3)User Contributed Perl DocumentationMail::Box::Identity(3)
2
6 Mail::Box::Identity - represents an unopened folder
7
9 Mail::Box::Identity
10 is an User::Identity::Item
11 Mail::Box::Identity
13 is a Mail::Reporter
14
16 use User::Identity;
17 use Mail::Box::Identity;
18 my $me = User::Identity->new(...);
19 my $mailbox = Mail::Box::Identity->new(...);
21 $me->add(folders => $mailbox);
22 # Simpler
24 use User::Identity;
26 my $me = User::Identity->new(...);
27 my $addr = $me->add(folders => ...);
28
30 The "Mail::Box::Identity" object contains the description of a single
31 mailbox. The mailboxes are collected by an Mail::Box::Collection
32 object. This corresponds with IMAP's "\NoSelect", for instance.
33 Nearly all methods can return undef.
35 Extends "DESCRIPTION" in Mail::Reporter.
37 Extends "DESCRIPTION" in User::Identity::Item.
39
41 Extends "METHODS" in Mail::Reporter.
42 Extends "METHODS" in User::Identity::Item.
44 Constructors
46 Extends "Constructors" in Mail::Reporter.
47 Extends "Constructors" in User::Identity::Item.
49 Mail::Box::Identity->new( [$name], %options )
51 -Option --Defined in --Default
52 deleted <false>
53 description User::Identity::Item undef
54 folder_type from parent
55 inferiors 1
56 location undef
57 log Mail::Reporter 'WARNINGS'
58 manager <from parent>
59 marked undef
60 name User::Identity::Item <required>
61 only_subs <foldertype and name dependent>
62 parent User::Identity::Item undef
63 subf_type <same as parent>
64 trace Mail::Reporter 'WARNINGS'
65 deleted => BOOLEAN
67 The folder is flagged for deletion. This not have any
68 implications yet, because it may still get undeleted.
69 description => STRING
71 folder_type => CLASS
72 inferiors => BOOLEAN
73 Can this folder have children? If not, this is cleared.
74 location => DIRECTORY|FILENAME
76 The location of this folder. Often, only the manager can figure-
77 out where this folder really is.
78 log => LEVEL
80 manager => OBJECT
81 Any Mail::Box::Manager or Mail::Box::Manage::User OBJECT.
82 marked => BOOLEAN|"undef"
84 Whether the folder is flagged for some reason, for instance
85 because new messages have arrived.
86 name => STRING
88 only_subs => BOOLEAN
89 Some folder types can have messages in their toplevel folder,
90 other cannot. That determines the default. See
91 Mail::Box::topFolderWithMessages()
92 parent => OBJECT
94 subf_type => CLASS
95 The type for a subfolder collection, must extend CLASS
96 Mail::Box::Collection.
97 trace => LEVEL
99 Attributes
101 Extends "Attributes" in User::Identity::Item.
102 $obj->deleted( [BOOLEAN] )
104 $obj->description()
105 Inherited, see "Attributes" in User::Identity::Item
106 $obj->folderType()
108 Returns the type of this folder.
109 $obj->fullname( [$delimeter] )
111 Returns the name of the folder, from the toplevel until this one,
112 with the $delimeter string between each level. $delimeter default
113 to a forward slash (a "/").
114 $obj->inferiors( [BOOLEAN] )
116 "Inferiors" are "subfolders". When this flag is set, it is
117 permitted to create subfolders.
118 $obj->location( [$filename|$directory|undef] )
120 Returns the directory or filename of the folder. If this is not
121 pre-defined, it is computed based on the knowledge about the folder
122 type. Be sure to set the location of the toplevel folder to the
123 folderdir of the user to get this to work.
124 $obj->manager()
126 Returns the manager (usually a Mail::Box::Manage::User which owns
127 the folders. May be undefined, by default from parent.
128 $obj->marked( [BOOLEAN|undef] )
130 When something special has happened with the folder, this flag can
131 be set (or cleared). The "undef" status is an "unknown". In the
132 IMAP4 protocol, 0 will result in a "\Unmarked", a 1 results in a
133 "\Marked", and "undef" in nothing.
134 $obj->name( [$newname] )
136 Inherited, see "Attributes" in User::Identity::Item
137 $obj->onlySubfolders( [BOOLEAN] )
139 Than this folder be opened (without trying) or not? The default
140 depends on the folder type, and whether this is the toplevel folder
141 or not. See Mail::Box::topFolderWithMessages()
142 $obj->topfolder()
144 Run up the tree to find the highest level folder.
145 Collections
147 Extends "Collections" in User::Identity::Item.
148 $obj->add($collection, $role)
150 Inherited, see "Collections" in User::Identity::Item
151 $obj->addCollection( $object | <[$type], %options> )
153 Inherited, see "Collections" in User::Identity::Item
154 $obj->collection($name)
156 Inherited, see "Collections" in User::Identity::Item
157 $obj->parent( [$parent] )
159 Inherited, see "Collections" in User::Identity::Item
160 $obj->removeCollection($object|$name)
162 Inherited, see "Collections" in User::Identity::Item
163 $obj->type()
165 Mail::Box::Identity->type()
166 Inherited, see "Collections" in User::Identity::Item
167 $obj->user()
169 Inherited, see "Collections" in User::Identity::Item
170 Searching
172 Extends "Searching" in User::Identity::Item.
173 $obj->find($collection, $role)
175 Inherited, see "Searching" in User::Identity::Item
176 Subfolders
178 $obj->addSubfolder($m<Mail::Box::Identity>|$data)
179 Add a new folder into the administration. With $data, a new object
180 will be instantiated first. The identity is returned on success.
181 $obj->folder( [..., $name] )
183 Returns the subfolder's object with $name or "undef" if it does not
184 exist. When multiple NAMEs are added, those super folders are
185 traverst first. Without any $name, the current object is returned
186 example: get some folder
188 my $a = $user->folders->folder('b', 'a');
190 my $name = "a:b:c";
192 my $delim = ":";
193 my $f = $user->folders->folder(split $delim, $name);
194 $obj->foreach(CODE)
196 For each of the subfolders found below this point call CODE. This
197 current folder is called first. Be warned that you may find
198 identities with the deleted() flag on.
199 $obj->open(%options)
201 Open the folder which is described by this identity. Returned is
202 some Mail::Box. The options are passed to
203 Mail::Box::Manager::open().
204 $obj->remove( [$name] )
206 Remove the folder (plus subfolders) with the $name. Without $name,
207 this "Mail::Box::Identity" itself is removed.
208 The removed structure is returned, which is "undef" if not found.
210 This is only an administrative remove, you still need a
211 Mail::Box::Manager::delete().
212 $obj->rename( $folder, [$newsubname] )
214 Move the folder to a different super-$folder, under a NEW SUBfolder
215 NAME.
216 example: renaming a folder
218 my $top = $user->topfolder;
220 my $new = $top->folder('xyz') or die;
221 my $f = $top->folder('abc', 'def')->rename($new, '123');
222 print $f->name; # 123
224 print $f->fullname; # =/xyz/123
225 $obj->subfolderNames()
227 Convenience method: returns the names of the collected subfolders.
228 $obj->subfolders()
230 Returns the subfolders or "undef" if there are none. This
231 information is lazy evaluated and cached. In LIST context, the
232 folder objects are returned (Mail::Box::Identity objects), in
233 SCALAR context the collection, the Mail::Box::Collection.
234 Error handling
236 Extends "Error handling" in Mail::Reporter.
237 $obj->AUTOLOAD()
239 Inherited, see "Error handling" in Mail::Reporter
240 $obj->addReport($object)
242 Inherited, see "Error handling" in Mail::Reporter
243 $obj->defaultTrace( [$level]|[$loglevel, $tracelevel]|[$level,
245 $callback] )
246 Mail::Box::Identity->defaultTrace( [$level]|[$loglevel,
247 $tracelevel]|[$level, $callback] )
248 Inherited, see "Error handling" in Mail::Reporter
249 $obj->errors()
251 Inherited, see "Error handling" in Mail::Reporter
252 $obj->log( [$level, [$strings]] )
254 Mail::Box::Identity->log( [$level, [$strings]] )
255 Inherited, see "Error handling" in Mail::Reporter
256 $obj->logPriority($level)
258 Mail::Box::Identity->logPriority($level)
259 Inherited, see "Error handling" in Mail::Reporter
260 $obj->logSettings()
262 Inherited, see "Error handling" in Mail::Reporter
263 $obj->notImplemented()
265 Inherited, see "Error handling" in Mail::Reporter
266 $obj->report( [$level] )
268 Inherited, see "Error handling" in Mail::Reporter
269 $obj->reportAll( [$level] )
271 Inherited, see "Error handling" in Mail::Reporter
272 $obj->trace( [$level] )
274 Inherited, see "Error handling" in Mail::Reporter
275 $obj->warnings()
277 Inherited, see "Error handling" in Mail::Reporter
278 Cleanup
280 Extends "Cleanup" in Mail::Reporter.
281 $obj->DESTROY()
283 Inherited, see "Cleanup" in Mail::Reporter
284
286 Error: $object is not a collection.
287 The first argument is an object, but not of a class which extends
288 User::Identity::Collection.
289 Error: Cannot load collection module for $type ($class).
291 Either the specified $type does not exist, or that module named
292 $class returns compilation errors. If the type as specified in the
293 warning is not the name of a package, you specified a nickname
294 which was not defined. Maybe you forgot the 'require' the package
295 which defines the nickname.
296 Error: Creation of a collection via $class failed.
298 The $class did compile, but it was not possible to create an object
299 of that class using the options you specified.
300 Error: Don't know what type of collection you want to add.
302 If you add a collection, it must either by a collection object or a
303 list of options which can be used to create a collection object.
304 In the latter case, the type of collection must be specified.
305 Error: It is not permitted to add subfolders to $name
307 The $m<inferiors()> flag prohibits the creation of subfolders to
308 this folder.
309 Warning: No collection $name
311 The collection with $name does not exist and can not be created.
312 Error: Package $package does not implement $method.
314 Fatal error: the specific package (or one of its superclasses) does
315 not implement this method where it should. This message means that
316 some other related classes do implement this method however the
317 class at hand does not. Probably you should investigate this and
318 probably inform the author of the package.
319 Error: The toplevel folder cannot be removed this way
321 The Mail::Box::Identity folder administration structure requires a
322 top directory. That top is registered somewhere (for instance by a
323 Mail::Box::Manage::User). If you need to remove the top, you have
324 to look for a method of that object.
325 Error: Toplevel directory requires explicit folder type
327 Error: Toplevel directory requires explicit location
328
330 This module is part of Mail-Box distribution version 3.007, built on
331 May 03, 2019. Website: http://perl.overmeer.net/CPAN/
332
334 Copyrights 2001-2019 by [Mark Overmeer]. For other contributors see
335 ChangeLog.
336 This program is free software; you can redistribute it and/or modify it
338 under the same terms as Perl itself. See http://dev.perl.org/licenses/
339perl v5.30.0 2019-07-26 Mail::Box::Identity(3)