Mail::Box::Identity(3pm)

1Mail::Box::Identity(3)User Contributed Perl DocumentationMail::Box::Identity(3)
2
3
4

NAME

6       Mail::Box::Identity - represents an unopened folder
7

INHERITANCE

9        Mail::Box::Identity
10          is an User::Identity::Item
11
12        Mail::Box::Identity
13          is a Mail::Reporter
14

SYNOPSIS

16        use User::Identity;
17        use Mail::Box::Identity;
18        my $me   = User::Identity->new(...);
19
20        my $mailbox = Mail::Box::Identity->new(...);
21        $me->add(folders => $mailbox);
22
23        # Simpler
24
25        use User::Identity;
26        my $me   = User::Identity->new(...);
27        my $addr = $me->add(folders => ...);
28

DESCRIPTION

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
34       Nearly all methods can return undef.
35

METHODS

37       Constructors
38
39       Mail::Box::Identity->new([NAME], OPTIONS)
40
41        Option     --Defined in     --Default
42        deleted                       <false>
43        description  User::Identity::Item  undef
44        folder_type                   from parent
45        inferiors                     1
46        location                      undef
47        log          Mail::Reporter   'WARNINGS'
48        manager                       <from parent>
49        marked                        undef
50        name         User::Identity::Item  <required>
51        only_subs                     <foldertype and name dependent>
52        parent       User::Identity::Item  undef
53        subf_type                     <same as parent>
54        trace        Mail::Reporter   'WARNINGS'
55
56           . deleted BOOLEAN
57
58               The folder is flagged for deletion.  This not have any implica‐
59               tions yet, because it may still get undeleted.
60
61           . description STRING
62
63           . folder_type CLASS
64
65           . inferiors BOOLEAN
66
67               Can this folder have childs?  If not, this is cleared.
68
69           . location DIRECTORY⎪FILENAME
70
71               The location of this folder.  Often, only the manager can fig‐
72               ure-out where this folder really is.
73
74           . log LEVEL
75
76           . manager OBJECT
77
78               Any Mail::Box::Manager or Mail::Box::Manage::User OBJECT.
79
80           . marked BOOLEAN⎪"undef"
81
82               Whether the folder is flagged for some reason, for instance
83               because new messages have arrived.
84
85           . name STRING
86
87           . only_subs BOOLEAN
88
89               Some folder types can have messages in their toplevel folder,
90               other cannot. That determines the default.  See Mail::Box::top‐
91               FolderWithMessages()
92
93           . parent OBJECT
94
95           . subf_type CLASS
96
97               The type for a subfolder collection, must extend CLASS
98               Mail::Box::Collection.
99
100           . trace LEVEL
101
102       Attributes
103
104       $obj->deleted({BOOLEAN])
105
106       $obj->description
107
108           See "Attributes" in User::Identity::Item
109
110       $obj->folderType
111
112           Returns the type of this folder.
113
114       $obj->fullname([DELIMETER])
115
116           Returns the name of the folder, from the toplevel until this one,
117           with the DELIMETER string between each level.  DELIMETER default to
118           a forward slash (a "/").
119
120       $obj->inferiors([BOOLEAN])
121
122           "Inferiors" are "subfolders".  When this flag is set, it is permit‐
123           ted to create subfolders.
124
125       $obj->location([FILENAME⎪DIRECTORY⎪undef])
126
127           Returns the directory or filename of the folder.  If this is not
128           pre-defined, it is computed based on the knowledge about the folder
129           type.  Be sure to set the location of the toplevel folder to the
130           folderdir of the user to get this to work.
131
132       $obj->manager
133
134           Returns the manager (usually a Mail::Box::Manage::User which owns
135           the folders.  May be undefined, by default from parent.
136
137       $obj->marked([BOOLEAN⎪undef])
138
139           When something special has happened with the folder, this flag can
140           be set (or cleared).  The "undef" status is an "unknown".  In the
141           IMAP4 protocol, 0 will result in a "\Unmarked", a 1 results in a
142           "\Marked", and "undef" in nothing.
143
144       $obj->name([NEWNAME])
145
146           See "Attributes" in User::Identity::Item
147
148       $obj->onlySubfolders([BOOLEAN])
149
150           Than this folder be opened (without trying) or not?  The default
151           depends on the folder type, and whether this is the toplevel folder
152           or not.  See Mail::Box::topFolderWithMessages()
153
154       $obj->topfolder
155
156           Run up the tree to find the highest level folder.
157
158       Collections
159
160       $obj->add(COLLECTION, ROLE)
161
162           See "Collections" in User::Identity::Item
163
164       $obj->addCollection(OBJECT ⎪ ([TYPE], OPTIONS))
165
166           See "Collections" in User::Identity::Item
167
168       $obj->collection(NAME)
169
170           See "Collections" in User::Identity::Item
171
172       $obj->find(COLLECTION, ROLE)
173
174           See "Collections" in User::Identity::Item
175
176       $obj->parent([PARENT])
177
178           See "Collections" in User::Identity::Item
179
180       $obj->removeCollection(OBJECT⎪NAME)
181
182           See "Collections" in User::Identity::Item
183
184       $obj->type
185
186       Mail::Box::Identity->type
187
188           See "Collections" in User::Identity::Item
189
190       $obj->user
191
192           See "Collections" in User::Identity::Item
193
194       Attributes
195
196       Subfolders
197
198       $obj->addSubfolder(Mail::Box::Identity⎪DATA)
199
200           Add a new folder into the administration.  With DATA, a new object
201           will be instantiated first.  The identity is returned on success.
202
203       $obj->folder([[NAME, ...], NAME])
204
205           Returns the subfolder's object with NAME or "undef" if it does not
206           exist.  When multiple NAMEs are added, those super folders are
207           traverst first.  Without any NAME, the current object is returned
208
209           Example: get some folder
210
211            my $a = $user->folders->folder('b', 'a');
212
213            my $name  = "a:b:c";
214            my $delim = ":";
215            my $f = $user->folders->folder(split $delim, $name);
216
217       $obj->foreach(CODE)
218
219           For each of the subfolders found below this point call CODE.  This
220           current folder is called first.  Be warned that you may find iden‐
221           tities with the deleted() flag on.
222
223       $obj->open(OPTIONS)
224
225           Open the folder which is described by this identity.  Returned is
226           some Mail::Box.  The options are passed to Mail::Box::Man‐
227           ager::open().
228
229       $obj->remove([NAME])
230
231           Remove the folder (plus subfolders) with the NAME.  Without NAME,
232           this "Mail::Box::Identity" itself is removed.
233
234           The removed structure is returned, which is "undef" if not found.
235           This is only an administrative remove, you still need a
236           Mail::Box::Manager::delete().
237
238       $obj->rename(FOLDER, [NEWSUBNAME])
239
240           Move the folder to a different super-FOLDER, under a NEW SUBfolder
241           NAME.
242
243           Example: renaming a folder
244
245            my $top = $user->topfolder;
246            my $new = $top->folder('xyz') or die;
247            my $f   = $top->folder('abc', 'def')->rename($new, '123');
248
249            print $f->name;      # 123
250            print $f->fullname;  # =/xyz/123
251
252       $obj->subfolderNames
253
254           Convenience method: returns the names of the collected subfolders.
255
256       $obj->subfolders
257
258           Returns the subfolders or "undef" if there are none.  This informa‐
259           tion is lazy evaluated and cached.  In LIST context, the folder
260           objects are returned (Mail::Box::Identity objects), in SCALAR con‐
261           text the collection, the Mail::Box::Collection.
262
263       Error handling
264
265       $obj->AUTOLOAD
266
267           See "Error handling" in Mail::Reporter
268
269       $obj->addReport(OBJECT)
270
271           See "Error handling" in Mail::Reporter
272
273       $obj->defaultTrace([LEVEL]⎪[LOGLEVEL, TRACELEVEL]⎪[LEVEL, CALLBACK])
274
275       Mail::Box::Identity->defaultTrace([LEVEL]⎪[LOGLEVEL,
276       TRACELEVEL]⎪[LEVEL, CALLBACK])
277
278           See "Error handling" in Mail::Reporter
279
280       $obj->errors
281
282           See "Error handling" in Mail::Reporter
283
284       $obj->log([LEVEL [,STRINGS]])
285
286       Mail::Box::Identity->log([LEVEL [,STRINGS]])
287
288           See "Error handling" in Mail::Reporter
289
290       $obj->logPriority(LEVEL)
291
292       Mail::Box::Identity->logPriority(LEVEL)
293
294           See "Error handling" in Mail::Reporter
295
296       $obj->logSettings
297
298           See "Error handling" in Mail::Reporter
299
300       $obj->notImplemented
301
302           See "Error handling" in Mail::Reporter
303
304       $obj->report([LEVEL])
305
306           See "Error handling" in Mail::Reporter
307
308       $obj->reportAll([LEVEL])
309
310           See "Error handling" in Mail::Reporter
311
312       $obj->trace([LEVEL])
313
314           See "Error handling" in Mail::Reporter
315
316       $obj->warnings
317
318           See "Error handling" in Mail::Reporter
319
320       Cleanup
321
322       $obj->DESTROY
323
324           See "Cleanup" in Mail::Reporter
325
326       $obj->inGlobalDestruction
327
328           See "Cleanup" in Mail::Reporter
329

DIAGNOSTICS

331       Error: $object is not a collection.
332
333       The first argument is an object, but not of a class which extends
334       User::Identity::Collection.
335
336       Error: Cannot load collection module for $type ($class).
337
338       Either the specified $type does not exist, or that module named $class
339       returns compilation errors.  If the type as specified in the warning is
340       not the name of a package, you specified a nickname which was not
341       defined.  Maybe you forgot the 'require' the package which defines the
342       nickname.
343
344       Error: Creation of a collection via $class failed.
345
346       The $class did compile, but it was not possible to create an object of
347       that class using the options you specified.
348
349       Error: Don't know what type of collection you want to add.
350
351       If you add a collection, it must either by a collection object or a
352       list of options which can be used to create a collection object.  In
353       the latter case, the type of collection must be specified.
354
355       Error: It is not permitted to add subfolders to $name
356
357       The inferiors() flag prohibits the creation of subfolders to this
358       folder.
359
360       Warning: No collection $name
361
362       The collection with $name does not exist and can not be created.
363
364       Error: Package $package does not implement $method.
365
366       Fatal error: the specific package (or one of its superclasses) does not
367       implement this method where it should. This message means that some
368       other related classes do implement this method however the class at
369       hand does not.  Probably you should investigate this and probably
370       inform the author of the package.
371
372       Error: The toplevel folder cannot be removed this way
373
374       The Mail::Box::Identity folder administration structure requires a top
375       directory.  That top is registered somewhere (for instance by a
376       Mail::Box::Manage::User).  If you need to remove the top, you have to
377       look for a method of that object.
378
379       Error: Toplevel directory requires explicit folder type
380
381       Error: Toplevel directory requires explicit location
382

LICENSE

388       Copyrights 2001-2007 by Mark Overmeer.For other contributors see
389       ChangeLog.
390
391       This program is free software; you can redistribute it and/or modify it
392       under the same terms as Perl itself.  See
393       http://www.perl.com/perl/misc/Artistic.html
394
395
396
397perl v5.8.8                       2007-03-25            Mail::Box::Identity(3)