debian man page for mail::server::imap4::list

Mail::Server::IMAP4::List(3pm)				User Contributed Perl Documentation			    Mail::Server::IMAP4::List(3pm)

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

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

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
	     A Mail::Box::Manage::User OBJECT, representing the user who's folders must get reported.

   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()
	   Returns the Mail::Box::Identity of the toplevel folder.

       $obj->inbox()
	   Returns the Mail::Box or filename of the INBOX.

       $obj->user()
	   Returns the Mail::Box::Manage::User object, if defined.

   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.105, built on May 07, 2012. Website: http://perl.overmeer.net/mailbox/

LICENSE
       Copyrights 2001-2012 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

perl v5.14.2							    2012-05-07					    Mail::Server::IMAP4::List(3pm)