/ 
Mail-Box-2.087
River stage one • 8 direct dependents • 8 total dependents
/ Mail::Server::IMAP4::List

NAME

Mail::Server::IMAP4::List - folder related IMAP4 answers

INHERITANCE

SYNOPSIS

my $imap = Mail::Server::IMAP4::List->new
  ( folders   => $folders   # Mail::Box::Identity
  , inbox     => $inbox     # Mail::Box
  , delimiter => '#'
  );

my $imap = Mail::Server::IMAP4::List->new(user => $user);
print $imap->list(...);        # for LIST command

DESCRIPTION

METHODS

Constructors

Mail::Server::IMAP4::List->new(USER)

    Create a (temporary) object to handle the LIST requests for a certain user, based upon a set of folders. The data is kept by Mail::Box::Identity and Mail::Box::Collection objects, which mean that the folders will not be opened to answer these questions.

    Option   --Default
delimeter  '/'
folders    <from user>
inbox      <from user>
user       <undef>

    . delimeter => STRING|CODE

      Either the constant delimiter, or a code reference which will get passed a folder name and should return the delimiter string used in that name. If that folder name is empty, the default delimiter must be reported. See delimiter() for an example.

    . folders => OBJECT

      You need to specify either a set of folders explicitly or via the user. Some Mail::Box::Identity OBJECT is needed.

    . inbox => BOOLEAN

      For now, only used to see whether there is an inbox, so a truth value will do. This may change in the future. By default, the flag is set if $user-inbox> is defined.

    . user => OBJECT

Attributes

$obj->delimiter([FOLDERNAME])

    Returns the delimiter string. The foldername is only required when a CODE reference was specified at initiation.

    example: setting-up an IMAP4 delimeter

    sub delim($)
{   my $path = shift;
    my ($delim, $root)
      = $path =~ m/^(#news\.)/ ? ('.', $1)
      = $path =~ m!^/!         ? ('/', '/')
      :                          ('/', '');

    wantarray ? ($delim, $root) : $delim;
}

my $list = Mail::Server::IMAP4::List->new(delimiter => \&delim, ...);
print $list->delimiter('abc/xyz');      # returns a / (slash) and ''
print $list->delimiter('#news.feed');   # returns a . (dot)   and $news.
print $list->delimiter('');             # returns default delimiter

$obj->folders

$obj->inbox

    Returns the Mail::Box or filename of the INBOX.

$obj->user

IMAP Commands

$obj->list(BASE, PATTERN)

    IMAP's LIST command. The request must be partially decoded, the answer will need to be encoded.

    example: using IMAP list

    my $imap  = Mail::Server::IMAP4::List->new(delimiter => \&delim, ...);
local $"  = ';';

my @lines = $imap->list('', '');  # returns the default delimiter
print ">@{$lines[0]}<";           #  >(\Noselect);/;<

my @lines = $imap->list('#news',''); # specific delimiter
print ">@{$lines[0]}<";           #  >(\Noselect);.;<

my @lines = $imap->list('top/x/', '%');
print ">@$_<," foreach @lines;    #  >();/;/tmp/x/y<,>(\Marked);/;/tmp/x/z<

DETAILS

See

RFC2060: "Internet Message Access Protocol IMAP4v1"

sections 6.3.8 (LIST question) and 7.2.2 (LIST answer)

SEE ALSO

This module is part of Mail-Box distribution version 2.087, built on February 03, 2009. Website: http://perl.overmeer.net/mailbox/

LICENSE

Copyrights 2001-2009 by Mark Overmeer. For other contributors see ChangeLog.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See http://www.perl.com/perl/misc/Artistic.html