Gecko [ fernandoquevedodop.com ]

Name	Size	Permission
Dir	[ DIR ]	drwxr-xr-x
File	[ DIR ]	drwxr-xr-x
Locker	[ DIR ]	drwxr-xr-x
MH	[ DIR ]	drwxr-xr-x
Maildir	[ DIR ]	drwxr-xr-x
Manage	[ DIR ]	drwxr-xr-x
Mbox	[ DIR ]	drwxr-xr-x
Message	[ DIR ]	drwxr-xr-x
Net	[ DIR ]	drwxr-xr-x
Parser	[ DIR ]	drwxr-xr-x
Search	[ DIR ]	drwxr-xr-x
Thread	[ DIR ]	drwxr-xr-x
Tie	[ DIR ]	drwxr-xr-x
Collection.pm	1.81 KB	-rw-r--r--
Collection.pod	8.81 KB	-rw-r--r--
Dir.pm	3.03 KB	-rw-r--r--
Dir.pod	14.62 KB	-rw-r--r--
FastScalar.pm	4.13 KB	-rw-r--r--
FastScalar.pod	969 B	-rw-r--r--
File.pm	13.08 KB	-rw-r--r--
File.pod	21.55 KB	-rw-r--r--
Identity.pm	5.66 KB	-rw-r--r--
Identity.pod	12.12 KB	-rw-r--r--
Locker.pm	3.3 KB	-rw-r--r--
Locker.pod	8.57 KB	-rw-r--r--
MH.pm	11.23 KB	-rw-r--r--
MH.pod	19.9 KB	-rw-r--r--
Maildir.pm	10.3 KB	-rw-r--r--
Maildir.pod	17.54 KB	-rw-r--r--
Manager.pm	15.14 KB	-rw-r--r--
Manager.pod	21.18 KB	-rw-r--r--
Mbox.pm	5.72 KB	-rw-r--r--
Mbox.pod	19.23 KB	-rw-r--r--
Message.pm	2.6 KB	-rw-r--r--
Message.pod	17.92 KB	-rw-r--r--
Net.pm	2.55 KB	-rw-r--r--
Net.pod	13.55 KB	-rw-r--r--
Parser.pm	3.77 KB	-rw-r--r--
Parser.pod	10.76 KB	-rw-r--r--
Search.pm	5.06 KB	-rw-r--r--
Search.pod	9.12 KB	-rw-r--r--
Test.pm	8.36 KB	-rw-r--r--
Tie.pm	923 B	-rw-r--r--
Tie.pod	1.4 KB	-rw-r--r--

Code Editor : Identity.pod

=encoding utf8

=head1 NAME

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

=head1 INHERITANCE

Mail::Box::Identity
   is an User::Identity::Item

Mail::Box::Identity
   is a Mail::Reporter

=head1 SYNOPSIS

use User::Identity;
 use Mail::Box::Identity;
 my $me   = User::Identity->new(...);

my $mailbox = Mail::Box::Identity->new(...);
 $me->add(folders => $mailbox);

# Simpler

use User::Identity;
 my $me   = User::Identity->new(...);
 my $addr = $me->add(folders => ...);

=head1 DESCRIPTION

The C<Mail::Box::Identity> object contains the description of a
single mailbox.  The mailboxes are collected by an L<Mail::Box::Collection|Mail::Box::Collection>
object.  This corresponds with IMAP's C<\NoSelect>, for instance.

Nearly all methods can return undef.

Extends L<"DESCRIPTION" in Mail::Reporter|Mail::Reporter/"DESCRIPTION">.
 
Extends L<"DESCRIPTION" in User::Identity::Item|User::Identity::Item/"DESCRIPTION">.
 
=head1 METHODS

Extends L<"METHODS" in Mail::Reporter|Mail::Reporter/"METHODS">.
 
Extends L<"METHODS" in User::Identity::Item|User::Identity::Item/"METHODS">.
 
=head2 Constructors

Extends L<"Constructors" in Mail::Reporter|Mail::Reporter/"Constructors">.
 
Extends L<"Constructors" in User::Identity::Item|User::Identity::Item/"Constructors">.
 
=over 4

=item Mail::Box::Identity-E<gt>B<new>( [$name], %options )

-Option     --Defined in          --Default
  deleted                            <false>
  description  User::Identity::Item  undef
  folder_type                        from parent
  inferiors                          1
  location                           undef
  log          Mail::Reporter        'WARNINGS'
  manager                            <from parent>
  marked                             undef
  name         User::Identity::Item  <required>
  only_subs                          <foldertype and name dependent>
  parent       User::Identity::Item  undef
  subf_type                          <same as parent>
  trace        Mail::Reporter        'WARNINGS'

=over 2

=item deleted => BOOLEAN

The folder is flagged for deletion.  This not have any implications yet,
because it may still get undeleted.

=item description => STRING

=item folder_type => CLASS

=item inferiors => BOOLEAN

Can this folder have children?  If not, this is cleared.

=item location => DIRECTORY|FILENAME

The location of this folder.  Often, only the manager can figure-out
where this folder really is.

=item log => LEVEL

=item manager => OBJECT

Any L<Mail::Box::Manager|Mail::Box::Manager> or L<Mail::Box::Manage::User|Mail::Box::Manage::User> OBJECT.

=item marked => BOOLEAN|C<undef>

Whether the folder is flagged for some reason, for instance because
new messages have arrived.

=item name => STRING

=item only_subs => BOOLEAN

Some folder types can have messages in their toplevel folder, other
cannot. That determines the default.
See L<Mail::Box::topFolderWithMessages()|Mail::Box/"Sub-folders">

=item parent => OBJECT

=item subf_type => CLASS

The type for a subfolder collection, must extend CLASS
L<Mail::Box::Collection|Mail::Box::Collection>.

=item trace => LEVEL

=back

=head2 Attributes

Extends L<"Attributes" in User::Identity::Item|User::Identity::Item/"Attributes">.
 
=over 4

=item $obj-E<gt>B<deleted>( [BOOLEAN] )

=item $obj-E<gt>B<description>()

Inherited, see L<User::Identity::Item/"Attributes">

=item $obj-E<gt>B<folderType>()

Returns the type of this folder.

=item $obj-E<gt>B<fullname>( [$delimeter] )

Returns the name of the folder, from the toplevel until this one, with
the $delimeter string between each level.  $delimeter default to a forward
slash (a C</>).

=item $obj-E<gt>B<inferiors>( [BOOLEAN] )

C<Inferiors> are C<subfolders>.  When this flag is set, it is permitted
to create subfolders.

=item $obj-E<gt>B<location>( [$filename|$directory|undef] )

Returns the directory or filename of the folder.  If this is not pre-defined,
it is computed based on the knowledge about the folder type.  Be sure to set
the location of the toplevel folder to the folderdir of the user to get
this to work.

=item $obj-E<gt>B<manager>()

Returns the manager (usually a L<Mail::Box::Manage::User|Mail::Box::Manage::User> which owns
the folders.  May be undefined, by default from parent.

=item $obj-E<gt>B<marked>( [BOOLEAN|undef] )

When something special has happened with the folder, this flag can
be set (or cleared).  The C<undef> status is an "unknown".  In the
IMAP4 protocol, C<0> will result in a C<\Unmarked>, a C<1> results
in a C<\Marked>, and C<undef> in nothing.

=item $obj-E<gt>B<name>( [$newname] )

Inherited, see L<User::Identity::Item/"Attributes">

=item $obj-E<gt>B<onlySubfolders>( [BOOLEAN] )

Than this folder be opened (without trying) or not?  The default
depends on the folder type, and whether this is the toplevel folder
or not.  See L<Mail::Box::topFolderWithMessages()|Mail::Box/"Sub-folders">

=item $obj-E<gt>B<topfolder>()

Run up the tree to find the highest level folder.

=back

=head2 Collections

Extends L<"Collections" in User::Identity::Item|User::Identity::Item/"Collections">.
 
=over 4

=item $obj-E<gt>B<add>($collection, $role)

Inherited, see L<User::Identity::Item/"Collections">

=item $obj-E<gt>B<addCollection>( $object | <[$type], %options> )

Inherited, see L<User::Identity::Item/"Collections">

=item $obj-E<gt>B<collection>($name)

Inherited, see L<User::Identity::Item/"Collections">

=item $obj-E<gt>B<parent>( [$parent] )

Inherited, see L<User::Identity::Item/"Collections">

=item $obj-E<gt>B<removeCollection>($object|$name)

Inherited, see L<User::Identity::Item/"Collections">

=item $obj-E<gt>B<type>()

=item Mail::Box::Identity-E<gt>B<type>()

Inherited, see L<User::Identity::Item/"Collections">

=item $obj-E<gt>B<user>()

Inherited, see L<User::Identity::Item/"Collections">

=back

=head2 Searching

Extends L<"Searching" in User::Identity::Item|User::Identity::Item/"Searching">.
 
=over 4

=item $obj-E<gt>B<find>($collection, $role)

Inherited, see L<User::Identity::Item/"Searching">

=back

=head2 Subfolders

=over 4

=item $obj-E<gt>B<addSubfolder>($m<Mail::Box::Identity>|$data)

Add a new folder into the administration.  With $data, a new object
will be instantiated first.  The identity is returned on success.

=item $obj-E<gt>B<folder>( [..., $name] )

Returns the subfolder's object with $name or C<undef> if it does not
exist.  When multiple NAMEs are added, those super folders are traverst
first.  Without any $name, the current object is returned

example: get some folder

my $a = $user->folders->folder('b', 'a');

my $name  = "a:b:c";
 my $delim = ":";
 my $f = $user->folders->folder(split $delim, $name);

=item $obj-E<gt>B<foreach>(CODE)

For each of the subfolders found below this point call CODE.  This current
folder is called first.  Be warned that you may find identities with
the L<deleted()|Mail::Box::Identity/"Attributes"> flag on.

=item $obj-E<gt>B<open>(%options)

Open the folder which is described by this identity.  Returned is some
L<Mail::Box|Mail::Box>.  The options are passed to L<Mail::Box::Manager::open()|Mail::Box::Manager/"Manage open folders">.

=item $obj-E<gt>B<remove>( [$name] )

Remove the folder (plus subfolders) with the $name.  Without $name, this
C<Mail::Box::Identity> itself is removed.

The removed structure is returned, which is C<undef> if not
found.  This is only an administrative remove, you still need a
L<Mail::Box::Manager::delete()|Mail::Box::Manager/"Manage existing folders">.

=item $obj-E<gt>B<rename>( $folder, [$newsubname] )

Move the folder to a different super-$folder, under a NEW SUBfolder NAME.

example: renaming a folder

my $top = $user->topfolder;
 my $new = $top->folder('xyz') or die;
 my $f   = $top->folder('abc', 'def')->rename($new, '123');

print $f->name;      # 123
 print $f->fullname;  # =/xyz/123

=item $obj-E<gt>B<subfolderNames>()

Convenience method: returns the names of the collected subfolders.

=item $obj-E<gt>B<subfolders>()

Returns the subfolders or C<undef> if there are none.  This
information is lazy evaluated and cached.  In LIST context, the folder
objects are returned (L<Mail::Box::Identity|Mail::Box::Identity> objects), in SCALAR context
the collection, the L<Mail::Box::Collection|Mail::Box::Collection>.

=back

=head2 Error handling

Extends L<"Error handling" in Mail::Reporter|Mail::Reporter/"Error handling">.
 
=over 4

=item $obj-E<gt>B<AUTOLOAD>()