| Subject: | is_parent() code doesn't match exactly the documentation. |
| Date: | Sun, 19 Apr 2015 15:41:36 +0200 |
| To: | bug-Mail-IMAPClient [...] rt.cpan.org |
| From: | Gilles LAMIRAL <gilles.lamiral [...] laposte.net> |
Hello Phil,
The code within is_parent() doesn't match exactly the documentation.
http://search.cpan.org/~plobbes/Mail-IMAPClient-3.35/lib/Mail/IMAPClient.pod#is_parent
The documentation says:
"It returns a value that indicates whether or not the folder has
children. The value it returns is either 1) a true value (indicating
that the folder has children), 2) 0 if the folder has no children at
this time, or 3) undef if the folder is not permitted to have
children."
The code says it return 0 if the folder is not permitted to have
children or if the folder has no children at this time, which is not
very useful.
RFC says:
7.2.2. LIST Response
Contents: name attributes
hierarchy delimiter
name
The LIST response occurs as a result of a LIST command. It
returns a single name that matches the LIST specification. There
can be multiple LIST responses for a single LIST command.
Four name attributes are defined:
\Noinferiors
It is not possible for any child levels of hierarchy to exist
under this name; no child levels exist now and none can be
created in the future.
The API described by the documentation makes sense with the RFC and
practical cases so I suggest to fix the code instead of the doc.
Thanks in advance Phil.
- return 0 if $rec->{attrs} =~ /\bNoInferior\b/i;
+ return undef if $rec->{attrs} =~ /\bNoInferior\b/i;
Current Mail-IMAPClient-3.35 gives:
sub is_parent {
my ( $self, $folder ) = ( shift, shift );
my $list = $self->list( undef, $folder ) or return undef;
my $attrs;
foreach my $resp (@$list) {
my $rec = $self->_list_or_lsub_response_parse($resp);
next unless defined $rec->{attrs};
return 0 if $rec->{attrs} =~ /\bNoInferior\b/i;
$attrs = $rec->{attrs};
}
if ($attrs) {
return 1 if $attrs =~ /HasChildren/i;
return 0 if $attrs =~ /HasNoChildren/i;
}
else {
$self->_debug( join( "\n\t", "no attrs for '$folder' in:", @$list ) );
}
# BUG? This may be overkill for normal use cases...
# flag not supported or not returned for some reason, try via folders()
my $sep = $self->separator($folder) || $self->separator(undef);
return undef unless defined $sep;
my $lead = $folder . $sep;
my $len = length $lead;
scalar grep { $lead eq substr( $_, 0, $len ) } $self->folders;
}
--
Au revoir, 09 51 84 42 42
Gilles Lamiral. France, Baulon (35580) 06 20 79 76 06