.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Mail::Server::IMAP4::List 3pm"
.TH Mail::Server::IMAP4::List 3pm "2014-08-24" "perl v5.20.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Mail::Server::IMAP4::List \- folder related IMAP4 answers
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 5
\& my $imap = Mail::Server::IMAP4::List\->new
\&   ( folders   => $folders   # Mail::Box::Identity
\&   , inbox     => $inbox     # Mail::Box
\&   , delimiter => \*(Aq#\*(Aq
\&   );
\&
\& my $imap = Mail::Server::IMAP4::List\->new(user => $user);
\& print $imap\->list(...);        # for LIST command
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
.SH "METHODS"
.IX Header "METHODS"
.SS "Constructors"
.IX Subsection "Constructors"
.IP "Mail::Server::IMAP4::List\->\fBnew\fR($user)" 4
.IX Item "Mail::Server::IMAP4::List->new($user)"
Create a (temporary) object to handle the \s-1LIST\s0 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.
.Sp
.Vb 5
\& \-Option   \-\-Default
\&  delimeter  \*(Aq/\*(Aq
\&  folders    <from user>
\&  inbox      <from user>
\&  user       <undef>
.Ve
.RS 4
.IP "delimeter => STRING|CODE" 2
.IX 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 \fIdelimiter()\fR for an example.
.IP "folders => \s-1OBJECT\s0" 2
.IX Item "folders => OBJECT"
You need to specify either a set of folders explicitly or via the
user. Some Mail::Box::Identity \s-1OBJECT\s0 is needed.
.IP "inbox => \s-1BOOLEAN\s0" 2
.IX 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
\&\f(CW\*(C`$user\-\*(C'\fRinbox> is defined.
.IP "user => \s-1OBJECT\s0" 2
.IX Item "user => OBJECT"
A Mail::Box::Manage::User \s-1OBJECT,\s0 representing the user who's folders
must get reported.
.RE
.RS 4
.RE
.SS "Attributes"
.IX Subsection "Attributes"
.ie n .IP "$obj\->\fBdelimiter\fR( [$foldername] )" 4
.el .IP "\f(CW$obj\fR\->\fBdelimiter\fR( [$foldername] )" 4
.IX Item "$obj->delimiter( [$foldername] )"
Returns the delimiter string.  The foldername is only required when a
\&\s-1CODE\s0 reference was specified at initiation.
.Sp
example: setting-up an \s-1IMAP4\s0 delimeter
.Sp
.Vb 6
\& sub delim($)
\& {   my $path = shift;
\&     my ($delim, $root)
\&       = $path =~ m/^(#news\e.)/ ? (\*(Aq.\*(Aq, $1)
\&       = $path =~ m!^/!         ? (\*(Aq/\*(Aq, \*(Aq/\*(Aq)
\&       :                          (\*(Aq/\*(Aq, \*(Aq\*(Aq);
\&
\&     wantarray ? ($delim, $root) : $delim;
\& }
\&
\& my $list = Mail::Server::IMAP4::List\->new(delimiter => \e&delim, ...);
\& print $list\->delimiter(\*(Aqabc/xyz\*(Aq);      # returns a / (slash) and \*(Aq\*(Aq
\& print $list\->delimiter(\*(Aq#news.feed\*(Aq);   # returns a . (dot)   and $news.
\& print $list\->delimiter(\*(Aq\*(Aq);             # returns default delimiter
.Ve
.ie n .IP "$obj\->\fBfolders\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBfolders\fR()" 4
.IX Item "$obj->folders()"
Returns the Mail::Box::Identity of the toplevel folder.
.ie n .IP "$obj\->\fBinbox\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBinbox\fR()" 4
.IX Item "$obj->inbox()"
Returns the Mail::Box or filename of the \s-1INBOX.\s0
.ie n .IP "$obj\->\fBuser\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBuser\fR()" 4
.IX Item "$obj->user()"
Returns the Mail::Box::Manage::User object, if defined.
.SS "\s-1IMAP\s0 Commands"
.IX Subsection "IMAP Commands"
.ie n .IP "$obj\->\fBlist\fR($base, $pattern)" 4
.el .IP "\f(CW$obj\fR\->\fBlist\fR($base, \f(CW$pattern\fR)" 4
.IX Item "$obj->list($base, $pattern)"
\&\s-1IMAP\s0's \s-1LIST\s0 command.  The request must be partially decoded, the answer
will need to be encoded.
.Sp
example: using \s-1IMAP\s0 list
.Sp
.Vb 2
\& my $imap  = Mail::Server::IMAP4::List\->new(delimiter => \e&delim, ...);
\& local $"  = \*(Aq;\*(Aq;
\&
\& my @lines = $imap\->list(\*(Aq\*(Aq, \*(Aq\*(Aq);  # returns the default delimiter
\& print ">@{$lines[0]}<";           #  >(\eNoselect);/;<
\&
\& my @lines = $imap\->list(\*(Aq#news\*(Aq,\*(Aq\*(Aq); # specific delimiter
\& print ">@{$lines[0]}<";           #  >(\eNoselect);.;<
\&
\& my @lines = $imap\->list(\*(Aqtop/x/\*(Aq, \*(Aq%\*(Aq);
\& print ">@$_<," foreach @lines;    #  >();/;/tmp/x/y<,>(\eMarked);/;/tmp/x/z<
.Ve
.SH "DETAILS"
.IX Header "DETAILS"
See
.ie n .IP "\s-1RFC2060: \s0""Internet Message Access Protocol IMAP4v1""" 4
.el .IP "\s-1RFC2060: \s0``Internet Message Access Protocol IMAP4v1''" 4
.IX Item "RFC2060: Internet Message Access Protocol IMAP4v1"
sections 6.3.8 (\s-1LIST\s0 question) and 7.2.2 (\s-1LIST\s0 answer)
.SH "SEE ALSO"
.IX Header "SEE ALSO"
This module is part of Mail-Box distribution version 2.117,
built on August 24, 2014. Website: \fIhttp://perl.overmeer.net/mailbox/\fR
.SH "LICENSE"
.IX Header "LICENSE"
Copyrights 2001\-2014 by [Mark Overmeer]. For other contributors see ChangeLog.
.PP
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
See \fIhttp://www.perl.com/perl/misc/Artistic.html\fR