/usr/share/perl5/Mail/Server/IMAP4/List.pod is in libmail-box-perl 2.117-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 | =encoding utf8
=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
=over 4
=item Mail::Server::IMAP4::List-E<gt>B<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
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 --Default
delimeter '/'
folders <from user>
inbox <from user>
user <undef>
=over 2
=item 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 L<delimiter()|Mail::Server::IMAP4::List/"Attributes"> for an example.
=item folders => OBJECT
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.
=item 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
C<$user->inbox> is defined.
=item user => OBJECT
A L<Mail::Box::Manage::User|Mail::Box::Manage::User> OBJECT, representing the user who's folders
must get reported.
=back
=back
=head2 Attributes
=over 4
=item $obj-E<gt>B<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
=item $obj-E<gt>B<folders>()
Returns the L<Mail::Box::Identity|Mail::Box::Identity> of the toplevel folder.
=item $obj-E<gt>B<inbox>()
Returns the L<Mail::Box|Mail::Box> or filename of the INBOX.
=item $obj-E<gt>B<user>()
Returns the L<Mail::Box::Manage::User|Mail::Box::Manage::User> object, if defined.
=back
=head2 IMAP Commands
=over 4
=item $obj-E<gt>B<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<
=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 SEE ALSO
This module is part of Mail-Box distribution version 2.117,
built on August 24, 2014. Website: F<http://perl.overmeer.net/mailbox/>
=head1 LICENSE
Copyrights 2001-2014 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 F<http://www.perl.com/perl/misc/Artistic.html>
|