
=head1 NAME

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



=head1 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


=head1 DESCRIPTION




=head1 METHODS


=head2 Constructors


Mail::Server::IMAP4::List-E<gt>B<new>(USER)

=over 4

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

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

. delimeter STRING|CODE

=over 4

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 L<delimiter()|Mail::Server::IMAP4::List/"Attributes"> for an example.

=back

. folders OBJECT

=over 4

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

=back

. inbox BOOLEAN

=over 4

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
C<$user->inbox> is defined.

=back

. user OBJECT

=over 4

A L<Mail::Box::Manage::User|Mail::Box::Manage::User> OBJECT, representing the user who's folders
must get reported.

=back

=back

=head2 Attributes


$obj-E<gt>B<delimiter>([FOLDERNAME])

=over 4

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

I<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 $imap = Mail::Server::IMAP4::List->new(delimiter => \&delim, ...);
 print $imap->delimiter('abc/xyz');      # returns a / (slash) and ''
 print $imap->delimiter('#news.feed');   # returns a . (dot)   and $news.
 print $imap->delimiter('');             # returns default delimiter

=back

$obj-E<gt>B<folders>

=over 4

Returns the L<Mail::Box::Identity|Mail::Box::Identity> of the toplevel folder.

=back

$obj-E<gt>B<inbox>

=over 4

Returns the L<Mail::Box|Mail::Box> or filename of the INBOX.

=back

$obj-E<gt>B<user>

=over 4

Returns the L<Mail::Box::Manage::User|Mail::Box::Manage::User> object, if defined.

=back

=head2 IMAP Commands


$obj-E<gt>B<list>(BASE, PATTERN)

=over 4

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

I<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<

=back




=head1 DETAILS

See

=over 4
=item RFC2060: "Internet Message Access Protocol IMAP4v1"

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





=head1 REFERENCES

See the MailBox website at L<http://perl.overmeer.net/mailbox/> for more details.

=head1 COPYRIGHTS

Distribution version 2.058.
Written by Mark Overmeer (mark@overmeer.net).  See the ChangeLog for
other contributors.

Copyright (c) 2001-2003 by the author(s). All rights reserved.
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.


