summaryrefslogtreecommitdiff
path: root/systems/texlive/tlnet/tlpkg/tlperl/lib/Net/POP3.pm
diff options
context:
space:
mode:
Diffstat (limited to 'systems/texlive/tlnet/tlpkg/tlperl/lib/Net/POP3.pm')
-rw-r--r--systems/texlive/tlnet/tlpkg/tlperl/lib/Net/POP3.pm141
1 files changed, 80 insertions, 61 deletions
diff --git a/systems/texlive/tlnet/tlpkg/tlperl/lib/Net/POP3.pm b/systems/texlive/tlnet/tlpkg/tlperl/lib/Net/POP3.pm
index 0811025b0a..55f7be1342 100644
--- a/systems/texlive/tlnet/tlpkg/tlperl/lib/Net/POP3.pm
+++ b/systems/texlive/tlnet/tlpkg/tlperl/lib/Net/POP3.pm
@@ -1,7 +1,7 @@
# Net::POP3.pm
#
# Copyright (C) 1995-2004 Graham Barr. All rights reserved.
-# Copyright (C) 2013-2016 Steve Hay. All rights reserved.
+# Copyright (C) 2013-2016, 2020 Steve Hay. All rights reserved.
# This module is free software; you can redistribute it and/or modify it under
# the same terms as Perl itself, i.e. under the terms of either the GNU General
# Public License or the Artistic License, as specified in the F<LICENCE> file.
@@ -18,7 +18,7 @@ use IO::Socket;
use Net::Cmd;
use Net::Config;
-our $VERSION = "3.11";
+our $VERSION = "3.13";
# Code for detecting if we can use SSL
my $ssl_class = eval {
@@ -124,7 +124,7 @@ sub debug_text { $_[2] =~ /^(pass|rpop)/i ? "$1 ....\n" : $_[2]; }
sub login {
- @_ >= 1 && @_ <= 3 or croak 'usage: $pop3->login( USER, PASS )';
+ @_ >= 1 && @_ <= 3 or croak 'usage: $pop3->login([$user[, $pass]])';
my ($me, $user, $pass) = @_;
if (@_ <= 2) {
@@ -147,7 +147,7 @@ sub starttls {
}
sub apop {
- @_ >= 1 && @_ <= 3 or croak 'usage: $pop3->apop( USER, PASS )';
+ @_ >= 1 && @_ <= 3 or croak 'usage: $pop3->apop([$user[, $pass]])';
my ($me, $user, $pass) = @_;
my $banner;
my $md;
@@ -180,13 +180,13 @@ sub apop {
sub user {
- @_ == 2 or croak 'usage: $pop3->user( USER )';
+ @_ == 2 or croak 'usage: $pop3->user($user)';
$_[0]->_USER($_[1]) ? 1 : undef;
}
sub pass {
- @_ == 2 or croak 'usage: $pop3->pass( PASS )';
+ @_ == 2 or croak 'usage: $pop3->pass($pass)';
my ($me, $pass) = @_;
@@ -225,7 +225,7 @@ sub last {
sub top {
- @_ == 2 || @_ == 3 or croak 'usage: $pop3->top( MSGNUM [, NUMLINES ])';
+ @_ == 2 || @_ == 3 or croak 'usage: $pop3->top($msgnum[, $numlines])';
my $me = shift;
return
@@ -247,7 +247,7 @@ sub popstat {
sub list {
- @_ == 1 || @_ == 2 or croak 'usage: $pop3->list( [ MSGNUM ] )';
+ @_ == 1 || @_ == 2 or croak 'usage: $pop3->list([$msgnum])';
my $me = shift;
return
@@ -268,7 +268,7 @@ sub list {
sub get {
- @_ == 2 or @_ == 3 or croak 'usage: $pop3->get( MSGNUM [, FH ])';
+ @_ == 2 or @_ == 3 or croak 'usage: $pop3->get($msgnum[, $fh])';
my $me = shift;
return
@@ -279,7 +279,7 @@ sub get {
sub getfh {
- @_ == 2 or croak 'usage: $pop3->getfh( MSGNUM )';
+ @_ == 2 or croak 'usage: $pop3->getfh($msgnum)';
my $me = shift;
return unless $me->_RETR(shift);
@@ -288,7 +288,7 @@ sub getfh {
sub delete {
- @_ == 2 or croak 'usage: $pop3->delete( MSGNUM )';
+ @_ == 2 or croak 'usage: $pop3->delete($msgnum)';
my $me = shift;
return 0 unless $me->_DELE(@_);
${*$me}{'net_pop3_deleted'} = 1;
@@ -296,7 +296,7 @@ sub delete {
sub uidl {
- @_ == 1 || @_ == 2 or croak 'usage: $pop3->uidl( [ MSGNUM ] )';
+ @_ == 1 || @_ == 2 or croak 'usage: $pop3->uidl([$msgnum])';
my $me = shift;
my $uidl;
@@ -319,7 +319,7 @@ sub uidl {
sub ping {
- @_ == 2 or croak 'usage: $pop3->ping( USER )';
+ @_ == 2 or croak 'usage: $pop3->ping($user)';
my $me = shift;
return () unless $me->_PING(@_) && $me->message =~ /(\d+)\D+(\d+)/;
@@ -635,21 +635,20 @@ on the object.
The Net::POP3 class is a subclass of Net::Cmd and (depending on avaibility) of
IO::Socket::IP, IO::Socket::INET6 or IO::Socket::INET.
-
-=head1 CONSTRUCTOR
+=head2 Class Methods
=over 4
-=item new ( [ HOST ] [, OPTIONS ] )
+=item C<new([$host][, %options])>
-This is the constructor for a new Net::POP3 object. C<HOST> is the
+This is the constructor for a new Net::POP3 object. C<$host> is the
name of the remote host to which an POP3 connection is required.
-C<HOST> is optional. If C<HOST> is not given then it may instead be
+C<$host> is optional. If C<$host> is not given then it may instead be
passed as the C<Host> option described below. If neither is given then
the C<POP3_Hosts> specified in C<Net::Config> will be used.
-C<OPTIONS> are passed in a hash like fashion, using key and value pairs.
+C<%options> are passed in a hash like fashion, using key and value pairs.
Possible options are:
B<Host> - POP3 host to connect to. It may be a single scalar, as defined for
@@ -681,7 +680,7 @@ B<Debug> - Enable debugging information
=back
-=head1 METHODS
+=head2 Object Methods
Unless otherwise stated all methods return either a I<true> or I<false>
value, with I<true> meaning that the operation was a success. When a method
@@ -694,26 +693,26 @@ documented here.
=over 4
-=item host ()
+=item C<host()>
Returns the value used by the constructor, and passed to IO::Socket::INET,
to connect to the host.
-=item auth ( USERNAME, PASSWORD )
+=item C<auth($username, $password)>
Attempt SASL authentication.
-=item user ( USER )
+=item C<user($user)>
Send the USER command.
-=item pass ( PASS )
+=item C<pass($pass)>
Send the PASS command. Returns the number of messages in the mailbox.
-=item login ( [ USER [, PASS ]] )
+=item C<login([$user[, $pass]])>
-Send both the USER and PASS commands. If C<PASS> is not given the
+Send both the USER and PASS commands. If C<$pass> is not given the
C<Net::POP3> uses C<Net::Netrc> to lookup the password using the host
and username. If the username is not specified then the current user name
will be used.
@@ -724,25 +723,25 @@ will give a true value in a boolean context, but zero in a numeric context.
If there was an error authenticating the user then I<undef> will be returned.
-=item starttls ( SSLARGS )
+=item C<starttls(%sslargs)>
Upgrade existing plain connection to SSL.
You can use SSL arguments as documented in L<IO::Socket::SSL>, but it will
usually use the right arguments already.
-=item apop ( [ USER [, PASS ]] )
+=item C<apop([$user[, $pass]])>
-Authenticate with the server identifying as C<USER> with password C<PASS>.
+Authenticate with the server identifying as C<$user> with password C<$pass>.
Similar to L</login>, but the password is not sent in clear text.
To use this method you must have the Digest::MD5 or the MD5 module installed,
otherwise this method will return I<undef>.
-=item banner ()
+=item C<banner()>
Return the sever's connection banner
-=item capa ()
+=item C<capa()>
Return a reference to a hash of the capabilities of the server. APOP
is added as a pseudo capability. Note that I've been unable to
@@ -750,109 +749,117 @@ find a list of the standard capability values, and some appear to
be multi-word and some are not. We make an attempt at intelligently
parsing them, but it may not be correct.
-=item capabilities ()
+=item C<capabilities()>
Just like capa, but only uses a cache from the last time we asked
the server, so as to avoid asking more than once.
-=item top ( MSGNUM [, NUMLINES ] )
+=item C<top($msgnum[, $numlines])>
-Get the header and the first C<NUMLINES> of the body for the message
-C<MSGNUM>. Returns a reference to an array which contains the lines of text
+Get the header and the first C<$numlines> of the body for the message
+C<$msgnum>. Returns a reference to an array which contains the lines of text
read from the server.
-=item list ( [ MSGNUM ] )
+=item C<list([$msgnum])>
If called with an argument the C<list> returns the size of the message
in octets.
If called without arguments a reference to a hash is returned. The
-keys will be the C<MSGNUM>'s of all undeleted messages and the values will
+keys will be the C<$msgnum>'s of all undeleted messages and the values will
be their size in octets.
-=item get ( MSGNUM [, FH ] )
+=item C<get($msgnum[, $fh])>
-Get the message C<MSGNUM> from the remote mailbox. If C<FH> is not given
+Get the message C<$msgnum> from the remote mailbox. If C<$fh> is not given
then get returns a reference to an array which contains the lines of
-text read from the server. If C<FH> is given then the lines returned
-from the server are printed to the filehandle C<FH>.
+text read from the server. If C<$fh> is given then the lines returned
+from the server are printed to the filehandle C<$fh>.
-=item getfh ( MSGNUM )
+=item C<getfh($msgnum)>
As per get(), but returns a tied filehandle. Reading from this
filehandle returns the requested message. The filehandle will return
EOF at the end of the message and should not be reused.
-=item last ()
+=item C<last()>
-Returns the highest C<MSGNUM> of all the messages accessed.
+Returns the highest C<$msgnum> of all the messages accessed.
-=item popstat ()
+=item C<popstat()>
Returns a list of two elements. These are the number of undeleted
elements and the size of the mbox in octets.
-=item ping ( USER )
+=item C<ping($user)>
Returns a list of two elements. These are the number of new messages
-and the total number of messages for C<USER>.
+and the total number of messages for C<$user>.
-=item uidl ( [ MSGNUM ] )
+=item C<uidl([$msgnum])>
-Returns a unique identifier for C<MSGNUM> if given. If C<MSGNUM> is not
+Returns a unique identifier for C<$msgnum> if given. If C<$msgnum> is not
given C<uidl> returns a reference to a hash where the keys are the
message numbers and the values are the unique identifiers.
-=item delete ( MSGNUM )
+=item C<delete($msgnum)>
-Mark message C<MSGNUM> to be deleted from the remote mailbox. All messages
+Mark message C<$msgnum> to be deleted from the remote mailbox. All messages
that are marked to be deleted will be removed from the remote mailbox
when the server connection closed.
-=item reset ()
+=item C<reset()>
Reset the status of the remote POP3 server. This includes resetting the
status of all messages to not be deleted.
-=item quit ()
+=item C<quit()>
Quit and close the connection to the remote POP3 server. Any messages marked
as deleted will be deleted from the remote mailbox.
-=item can_inet6 ()
+=item C<can_inet6()>
Returns whether we can use IPv6.
-=item can_ssl ()
+=item C<can_ssl()>
Returns whether we can use SSL.
=back
-=head1 NOTES
+=head2 Notes
If a C<Net::POP3> object goes out of scope before C<quit> method is called
then the C<reset> method will called before the connection is closed. This
means that any messages marked to be deleted will not be.
+=head1 EXPORTS
+
+I<None>.
+
+=head1 KNOWN BUGS
+
+See L<https://rt.cpan.org/Dist/Display.html?Status=Active&Queue=libnet>.
+
=head1 SEE ALSO
L<Net::Netrc>,
L<Net::Cmd>,
-L<IO::Socket::SSL>
+L<IO::Socket::SSL>.
=head1 AUTHOR
-Graham Barr E<lt>F<gbarr@pobox.com>E<gt>.
+Graham Barr E<lt>L<gbarr@pobox.com|mailto:gbarr@pobox.com>E<gt>.
-Steve Hay E<lt>F<shay@cpan.org>E<gt> is now maintaining libnet as of version
-1.22_02.
+Steve Hay E<lt>L<shay@cpan.org|mailto:shay@cpan.org>E<gt> is now maintaining
+libnet as of version 1.22_02.
=head1 COPYRIGHT
Copyright (C) 1995-2004 Graham Barr. All rights reserved.
-Copyright (C) 2013-2016 Steve Hay. All rights reserved.
+Copyright (C) 2013-2016, 2020 Steve Hay. All rights reserved.
=head1 LICENCE
@@ -860,4 +867,16 @@ This module is free software; you can redistribute it and/or modify it under the
same terms as Perl itself, i.e. under the terms of either the GNU General Public
License or the Artistic License, as specified in the F<LICENCE> file.
+=head1 VERSION
+
+Version 3.13
+
+=head1 DATE
+
+23 Dec 2020
+
+=head1 HISTORY
+
+See the F<Changes> file.
+
=cut