METHODS

See METHODS in Mail::Reporter

Constructors

$class->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'

deleted => BOOLEAN
The folder is flagged for deletion. This not have any implications yet, because it may still get undeleted.
description => STRING
folder_type => CLASS
inferiors => BOOLEAN
Can this folder have children? If not, this is cleared.
location => DIRECTORY|FILENAME
The location of this folder. Often, only the manager can figure-out where this folder really is.
log => LEVEL
manager => OBJECT
Any Mail::Box::Manager or Mail::Box::Manage::User OBJECT.
marked => BOOLEAN|undef
Whether the folder is flagged for some reason, for instance because new messages have arrived.
name => STRING
only_subs => BOOLEAN
Some folder types can have messages in their toplevel folder, other cannot. That determines the default. See Mail::Box::topFolderWithMessages()
parent => OBJECT
subf_type => CLASS
The type for a subfolder collection, must extend CLASS Mail::Box::Collection.
trace => LEVEL

Attributes

$obj->deleted( [BOOLEAN] )
$obj->description
See description in User::Identity::Item.
$obj->folderType

Returns the type of this folder.

» Error: Toplevel directory requires explicit folder type
$obj->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 /).

$obj->inferiors( [BOOLEAN] )

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

$obj->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.

» Error: Toplevel directory requires explicit location
$obj->manager

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

$obj->marked( [BOOLEAN|undef] )

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

$obj->name( [NEWNAME] )
See name in User::Identity::Item.
$obj->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 Mail::Box::topFolderWithMessages()

$obj->topfolder

Run up the tree to find the highest level folder.

Collections

$obj->add( COLLECTION, ROLE )
See add in User::Identity::Item.
$obj->addCollection( OBJECT | ([TYPE], OPTIONS) )
See addCollection in User::Identity::Item.
$obj->collection( NAME )
See collection in User::Identity::Item.
$obj->parent( [PARENT] )
See parent in User::Identity::Item.
$obj->removeCollection( OBJECT|NAME )
See removeCollection in User::Identity::Item.
$obj->type
$class->type
See type in User::Identity::Item.
$obj->user
See user in User::Identity::Item.

Searching

$obj->find( COLLECTION, ROLE )
See find in User::Identity::Item.

Subfolders

$obj->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.

» Error: It is not permitted to add subfolders to $name

The $m<inferiors()> flag prohibits the creation of subfolders to this folder.

$obj->folder( [..., $name] )

Returns the subfolder's object with $name or 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);
$obj->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 deleted() flag on.

$obj->open( %options )

Open the folder which is described by this identity. Returned is some Mail::Box. The options are passed to Mail::Box::Manager::open().

$obj->remove( [$name] )

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

The removed structure is returned, which is undef if not found. This is only an administrative remove, you still need a Mail::Box::Manager::delete().

» Error: The toplevel folder cannot be removed this way

The Mail::Box::Identity folder administration structure requires a top directory. That top is registered somewhere (for instance by a Mail::Box::Manage::User). If you need to remove the top, you have to look for a method of that object.

$obj->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
$obj->subfolderNames

Convenience method: returns the names of the collected subfolders.

$obj->subfolders

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

Error handling

$obj->AUTOLOAD
See AUTOLOAD in Mail::Reporter.
$obj->addReport( $object )
See addReport in Mail::Reporter.
$obj->defaultTrace( [$level]|[$loglevel, $tracelevel]|[$level, $callback] )
$class->defaultTrace( [$level]|[$loglevel, $tracelevel]|[$level, $callback] )
See defaultTrace in Mail::Reporter.
$obj->errors
See errors in Mail::Reporter.
$obj->log( [$level, [$strings]] )
$class->log( [$level, [$strings]] )
See log in Mail::Reporter.
$obj->logPriority( $level )
$class->logPriority( $level )
See logPriority in Mail::Reporter.
$obj->logSettings
See logSettings in Mail::Reporter.
$obj->notImplemented
See notImplemented in Mail::Reporter.
$obj->report( [$level] )
See report in Mail::Reporter.
$obj->reportAll( [$level] )
See reportAll in Mail::Reporter.
$obj->trace( [$level] )
See trace in Mail::Reporter.
$obj->warnings
See warnings in Mail::Reporter.

Cleanup

$obj->DESTROY
See DESTROY in Mail::Reporter.