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

DESCRIPTION

METHODS

  Constructors

$class->new(%options)
    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
      delimiter  '/'
      folders    <from user>
      inbox      <from user>
      user       undef

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

      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-IMAP4 version 4.01, built on December 13, 2025. Website: http://perl.overmeer.net/CPAN/

LICENSE
For contributors see file ChangeLog.

This software is copyright (c) 2001-2025 by Mark Overmeer.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.