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
36       Extends "DESCRIPTION" in Mail::Reporter.
37
38       Extends "DESCRIPTION" in User::Identity::Item.
39

METHODS

41       Extends "METHODS" in Mail::Reporter.
42
43       Extends "METHODS" in User::Identity::Item.
44
45   Constructors
46       Extends "Constructors" in Mail::Reporter.
47
48       Extends "Constructors" in User::Identity::Item.
49
50       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
66           deleted => BOOLEAN
67             The folder is flagged for deletion.  This not have any
68             implications yet, because it may still get undeleted.
69
70           description => STRING
71           folder_type => CLASS
72           inferiors => BOOLEAN
73             Can this folder have children?  If not, this is cleared.
74
75           location => DIRECTORY|FILENAME
76             The location of this folder.  Often, only the manager can figure-
77             out where this folder really is.
78
79           log => LEVEL
80           manager => OBJECT
81             Any Mail::Box::Manager or Mail::Box::Manage::User OBJECT.
82
83           marked => BOOLEAN|"undef"
84             Whether the folder is flagged for some reason, for instance
85             because new messages have arrived.
86
87           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
93           parent => OBJECT
94           subf_type => CLASS
95             The type for a subfolder collection, must extend CLASS
96             Mail::Box::Collection.
97
98           trace => LEVEL
99
100   Attributes
101       Extends "Attributes" in User::Identity::Item.
102
103       $obj->deleted( [BOOLEAN] )
104       $obj->description()
105           Inherited, see "Attributes" in User::Identity::Item
106
107       $obj->folderType()
108           Returns the type of this folder.
109
110       $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
115       $obj->inferiors( [BOOLEAN] )
116           "Inferiors" are "subfolders".  When this flag is set, it is
117           permitted to create subfolders.
118
119       $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
125       $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
129       $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
135       $obj->name( [$newname] )
136           Inherited, see "Attributes" in User::Identity::Item
137
138       $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
143       $obj->topfolder()
144           Run up the tree to find the highest level folder.
145
146   Collections
147       Extends "Collections" in User::Identity::Item.
148
149       $obj->add($collection, $role)
150           Inherited, see "Collections" in User::Identity::Item
151
152       $obj->addCollection( $object | <[$type], %options> )
153           Inherited, see "Collections" in User::Identity::Item
154
155       $obj->collection($name)
156           Inherited, see "Collections" in User::Identity::Item
157
158       $obj->parent( [$parent] )
159           Inherited, see "Collections" in User::Identity::Item
160
161       $obj->removeCollection($object|$name)
162           Inherited, see "Collections" in User::Identity::Item
163
164       $obj->type()
165       Mail::Box::Identity->type()
166           Inherited, see "Collections" in User::Identity::Item
167
168       $obj->user()
169           Inherited, see "Collections" in User::Identity::Item
170
171   Searching
172       Extends "Searching" in User::Identity::Item.
173
174       $obj->find($collection, $role)
175           Inherited, see "Searching" in User::Identity::Item
176
177   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
182       $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
187           example: get some folder
188
189            my $a = $user->folders->folder('b', 'a');
190
191            my $name  = "a:b:c";
192            my $delim = ":";
193            my $f = $user->folders->folder(split $delim, $name);
194
195       $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
200       $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
205       $obj->remove( [$name] )
206           Remove the folder (plus subfolders) with the $name.  Without $name,
207           this "Mail::Box::Identity" itself is removed.
208
209           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
213       $obj->rename( $folder, [$newsubname] )
214           Move the folder to a different super-$folder, under a NEW SUBfolder
215           NAME.
216
217           example: renaming a folder
218
219            my $top = $user->topfolder;
220            my $new = $top->folder('xyz') or die;
221            my $f   = $top->folder('abc', 'def')->rename($new, '123');
222
223            print $f->name;      # 123
224            print $f->fullname;  # =/xyz/123
225
226       $obj->subfolderNames()
227           Convenience method: returns the names of the collected subfolders.
228
229       $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
235   Error handling
236       Extends "Error handling" in Mail::Reporter.
237
238       $obj->AUTOLOAD()
239           Inherited, see "Error handling" in Mail::Reporter
240
241       $obj->addReport($object)
242           Inherited, see "Error handling" in Mail::Reporter
243
244       $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
250       $obj->errors()
251           Inherited, see "Error handling" in Mail::Reporter
252
253       $obj->log( [$level, [$strings]] )
254       Mail::Box::Identity->log( [$level, [$strings]] )
255           Inherited, see "Error handling" in Mail::Reporter
256
257       $obj->logPriority($level)
258       Mail::Box::Identity->logPriority($level)
259           Inherited, see "Error handling" in Mail::Reporter
260
261       $obj->logSettings()
262           Inherited, see "Error handling" in Mail::Reporter
263
264       $obj->notImplemented()
265           Inherited, see "Error handling" in Mail::Reporter
266
267       $obj->report( [$level] )
268           Inherited, see "Error handling" in Mail::Reporter
269
270       $obj->reportAll( [$level] )
271           Inherited, see "Error handling" in Mail::Reporter
272
273       $obj->trace( [$level] )
274           Inherited, see "Error handling" in Mail::Reporter
275
276       $obj->warnings()
277           Inherited, see "Error handling" in Mail::Reporter
278
279   Cleanup
280       Extends "Cleanup" in Mail::Reporter.
281
282       $obj->DESTROY()
283           Inherited, see "Cleanup" in Mail::Reporter
284

DIAGNOSTICS

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
290       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
297       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
301       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
306       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
310       Warning: No collection $name
311           The collection with $name does not exist and can not be created.
312
313       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
320       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
326       Error: Toplevel directory requires explicit folder type
327       Error: Toplevel directory requires explicit location
328

SEE ALSO

330       This module is part of Mail-Box distribution version 3.009, built on
331       August 18, 2020. Website: http://perl.overmeer.net/CPAN/
332

LICENSE

334       Copyrights 2001-2020 by [Mark Overmeer]. For other contributors see
335       ChangeLog.
336
337       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/
339
340
341
342perl v5.36.0                      2022-07-22            Mail::Box::Identity(3)
Impressum