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 a 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
37 Constructors
38 Mail::Box::Identity->new([NAME], OPTIONS)
39 -Option --Defined in --Default
40 deleted <false>
41 description User::Identity::Item undef
42 folder_type from parent
43 inferiors 1
44 location undef
45 log Mail::Reporter 'WARNINGS'
46 manager <from parent>
47 marked undef
48 name User::Identity::Item <required>
49 only_subs <foldertype and name dependent>
50 parent User::Identity::Item undef
51 subf_type <same as parent>
52 trace Mail::Reporter 'WARNINGS'
53 deleted => BOOLEAN
55 The folder is flagged for deletion. This not have any
56 implications yet, because it may still get undeleted.
57 description => STRING
59 folder_type => CLASS
60 inferiors => BOOLEAN
61 Can this folder have children? If not, this is cleared.
62 location => DIRECTORY|FILENAME
64 The location of this folder. Often, only the manager can figure-
65 out where this folder really is.
66 log => LEVEL
68 manager => OBJECT
69 Any Mail::Box::Manager or Mail::Box::Manage::User OBJECT.
70 marked => BOOLEAN|"undef"
72 Whether the folder is flagged for some reason, for instance
73 because new messages have arrived.
74 name => STRING
76 only_subs => BOOLEAN
77 Some folder types can have messages in their toplevel folder,
78 other cannot. That determines the default. See
79 Mail::Box::topFolderWithMessages()
80 parent => OBJECT
82 subf_type => CLASS
83 The type for a subfolder collection, must extend CLASS
84 Mail::Box::Collection.
85 trace => LEVEL
87 Attributes
89 $obj->description
90 See "Attributes" in User::Identity::Item
91 $obj->folderType
93 Returns the type of this folder.
94 $obj->fullname([DELIMETER])
96 Returns the name of the folder, from the toplevel until this one,
97 with the DELIMETER string between each level. DELIMETER default to
98 a forward slash (a "/").
99 $obj->inferiors([BOOLEAN])
101 "Inferiors" are "subfolders". When this flag is set, it is
102 permitted to create subfolders.
103 $obj->location([FILENAME|DIRECTORY|undef])
105 Returns the directory or filename of the folder. If this is not
106 pre-defined, it is computed based on the knowledge about the folder
107 type. Be sure to set the location of the toplevel folder to the
108 folderdir of the user to get this to work.
109 $obj->manager
111 Returns the manager (usually a Mail::Box::Manage::User which owns
112 the folders. May be undefined, by default from parent.
113 $obj->marked([BOOLEAN|undef])
115 When something special has happened with the folder, this flag can
116 be set (or cleared). The "undef" status is an "unknown". In the
117 IMAP4 protocol, 0 will result in a "\Unmarked", a 1 results in a
118 "\Marked", and "undef" in nothing.
119 $obj->name([NEWNAME])
121 See "Attributes" in User::Identity::Item
122 $obj->onlySubfolders([BOOLEAN])
124 Than this folder be opened (without trying) or not? The default
125 depends on the folder type, and whether this is the toplevel folder
126 or not. See Mail::Box::topFolderWithMessages()
127 $obj->topfolder
129 Run up the tree to find the highest level folder.
130 Collections
132 $obj->add(COLLECTION, ROLE)
133 See "Collections" in User::Identity::Item
134 $obj->addCollection(OBJECT | ([TYPE], OPTIONS))
136 See "Collections" in User::Identity::Item
137 $obj->collection(NAME)
139 See "Collections" in User::Identity::Item
140 $obj->find(COLLECTION, ROLE)
142 See "Collections" in User::Identity::Item
143 $obj->parent([PARENT])
145 See "Collections" in User::Identity::Item
146 $obj->removeCollection(OBJECT|NAME)
148 See "Collections" in User::Identity::Item
149 $obj->type
151 Mail::Box::Identity->type
152 See "Collections" in User::Identity::Item
154 $obj->user
156 See "Collections" in User::Identity::Item
157 Subfolders
159 $obj->addSubfolder(Mail::Box::Identity|DATA)
160 Add a new folder into the administration. With DATA, a new object
161 will be instantiated first. The identity is returned on success.
162 $obj->folder([[NAME, ...], NAME])
164 Returns the subfolder's object with NAME or "undef" if it does not
165 exist. When multiple NAMEs are added, those super folders are
166 traverst first. Without any NAME, the current object is returned
167 example: get some folder
169 my $a = $user->folders->folder('b', 'a');
171 my $name = "a:b:c";
173 my $delim = ":";
174 my $f = $user->folders->folder(split $delim, $name);
175 $obj->foreach(CODE)
177 For each of the subfolders found below this point call CODE. This
178 current folder is called first. Be warned that you may find
179 identities with the Mail::Box::Identity subroutine deleted flag on.
180 $obj->open(OPTIONS)
182 Open the folder which is described by this identity. Returned is
183 some Mail::Box. The options are passed to
184 Mail::Box::Manager::open().
185 $obj->remove([NAME])
187 Remove the folder (plus subfolders) with the NAME. Without NAME,
188 this "Mail::Box::Identity" itself is removed.
189 The removed structure is returned, which is "undef" if not found.
191 This is only an administrative remove, you still need a
192 Mail::Box::Manager::delete().
193 $obj->rename(FOLDER, [NEWSUBNAME])
195 Move the folder to a different super-FOLDER, under a NEW SUBfolder
196 NAME.
197 example: renaming a folder
199 my $top = $user->topfolder;
201 my $new = $top->folder('xyz') or die;
202 my $f = $top->folder('abc', 'def')->rename($new, '123');
203 print $f->name; # 123
205 print $f->fullname; # =/xyz/123
206 $obj->subfolderNames
208 Convenience method: returns the names of the collected subfolders.
209 $obj->subfolders
211 Returns the subfolders or "undef" if there are none. This
212 information is lazy evaluated and cached. In LIST context, the
213 folder objects are returned (Mail::Box::Identity objects), in
214 SCALAR context the collection, the Mail::Box::Collection.
215 Error handling
217 $obj->AUTOLOAD
218 See "Error handling" in Mail::Reporter
219 $obj->addReport(OBJECT)
221 See "Error handling" in Mail::Reporter
222 $obj->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK])
224 Mail::Box::Identity->defaultTrace([LEVEL]|[LOGLEVEL,
225 TRACELEVEL]|[LEVEL, CALLBACK])
226 See "Error handling" in Mail::Reporter
228 $obj->errors
230 See "Error handling" in Mail::Reporter
231 $obj->log([LEVEL [,STRINGS]])
233 Mail::Box::Identity->log([LEVEL [,STRINGS]])
234 See "Error handling" in Mail::Reporter
236 $obj->logPriority(LEVEL)
238 Mail::Box::Identity->logPriority(LEVEL)
239 See "Error handling" in Mail::Reporter
241 $obj->logSettings
243 See "Error handling" in Mail::Reporter
244 $obj->notImplemented
246 See "Error handling" in Mail::Reporter
247 $obj->report([LEVEL])
249 See "Error handling" in Mail::Reporter
250 $obj->reportAll([LEVEL])
252 See "Error handling" in Mail::Reporter
253 $obj->trace([LEVEL])
255 See "Error handling" in Mail::Reporter
256 $obj->warnings
258 See "Error handling" in Mail::Reporter
259 Cleanup
261 $obj->DESTROY
262 See "Cleanup" in Mail::Reporter
263 $obj->inGlobalDestruction
265 See "Cleanup" in Mail::Reporter
266
268 Error: $object is not a collection.
269 The first argument is an object, but not of a class which extends
270 User::Identity::Collection.
271 Error: Cannot load collection module for $type ($class).
273 Either the specified $type does not exist, or that module named
274 $class returns compilation errors. If the type as specified in the
275 warning is not the name of a package, you specified a nickname
276 which was not defined. Maybe you forgot the 'require' the package
277 which defines the nickname.
278 Error: Creation of a collection via $class failed.
280 The $class did compile, but it was not possible to create an object
281 of that class using the options you specified.
282 Error: Don't know what type of collection you want to add.
284 If you add a collection, it must either by a collection object or a
285 list of options which can be used to create a collection object.
286 In the latter case, the type of collection must be specified.
287 Error: It is not permitted to add subfolders to $name
289 The inferiors() flag prohibits the creation of subfolders to this
290 folder.
291 Warning: No collection $name
293 The collection with $name does not exist and can not be created.
294 Error: Package $package does not implement $method.
296 Fatal error: the specific package (or one of its superclasses) does
297 not implement this method where it should. This message means that
298 some other related classes do implement this method however the
299 class at hand does not. Probably you should investigate this and
300 probably inform the author of the package.
301 Error: The toplevel folder cannot be removed this way
303 The Mail::Box::Identity folder administration structure requires a
304 top directory. That top is registered somewhere (for instance by a
305 Mail::Box::Manage::User). If you need to remove the top, you have
306 to look for a method of that object.
307 Error: Toplevel directory requires explicit folder type
309 Error: Toplevel directory requires explicit location
310
312 This module is part of Mail-Box distribution version 2.097, built on
313 January 26, 2011. Website: http://perl.overmeer.net/mailbox/
314
316 Copyrights 2001-2011 by Mark Overmeer. For other contributors see
317 ChangeLog.
318 This program is free software; you can redistribute it and/or modify it
320 under the same terms as Perl itself. See
321 http://www.perl.com/perl/misc/Artistic.html
322perl v5.12.3 2011-01-26 Mail::Box::Identity(3)