Allow host to be passed as an option instead of the first arg

4 files changed, 71 insertions, 15 deletions

diff --git a/Net/FTP.pm b/Net/FTP.pm
index 991d004..f871de4 100644
--- a/Net/FTP.pm
+++ b/Net/FTP.pm
@@ -50,8 +50,14 @@ BEGIN {
 sub new
 {
  my $pkg  = shift;
- my $peer = shift;
- my %arg  = @_; 
+ my ($peer,%arg);
+ if (@_ % 2) {
+   $peer = shift ;
+   %arg  = @_;
+ } else {
+   %arg = @_;
+   $peer=delete $arg{Host};
+ }
 
  my $host = $peer;
  my $fire = undef;
@@ -124,6 +130,13 @@ sub new
 ## User interface methods
 ##
 
+
+sub host {
+ my $me = shift;
+ ${*$me}{'net_ftp_host'};
+}
+
+
 sub hash {
     my $ftp = shift;                # self
 
@@ -1279,14 +1292,23 @@ this if you really know what you're doing).
 
 =over 4
 
-=item new (HOST [,OPTIONS])
+=item new ([ HOST ] [, OPTIONS ])
 
 This is the constructor for a new Net::FTP object. C<HOST> is the
 name of the remote host to which an FTP connection is required.
 
+C<HOST> is optional. If C<HOST> is not given then it may instead be
+passed as the C<Host> option described below. 
+
 C<OPTIONS> are passed in a hash like fashion, using key and value pairs.
 Possible options are:
 
+B<Host> - FTP host to connect to. It may be a single scalar, as defined for
+the C<PeerAddr> option in L<IO::Socket::INET>, or a reference to
+an array with hosts to try in turn. The L</host> method will return the value
+which was used to connect to the host.
+
+
 B<Firewall> - The name of a machine which acts as an FTP firewall. This can be
 overridden by an environment variable C<FTP_FIREWALL>. If specified, and the
 given host cannot be directly connected to, then the
diff --git a/Net/NNTP.pm b/Net/NNTP.pm
index 79261f8..b682a68 100644
--- a/Net/NNTP.pm
+++ b/Net/NNTP.pm
@@ -14,15 +14,21 @@ use Carp;
 use Time::Local;
 use Net::Config;
 
-$VERSION = "2.22"; # $Id: //depot/libnet/Net/NNTP.pm#18 $
+$VERSION = "2.23";
 @ISA     = qw(Net::Cmd IO::Socket::INET);
 
 sub new
 {
  my $self = shift;
  my $type = ref($self) || $self;
- my $host = shift if @_ % 2;
- my %arg  = @_;
+ my ($host,%arg);
+ if (@_ % 2) {
+   $host = shift ;
+   %arg  = @_;
+ } else {
+   %arg = @_;
+   $host=delete $arg{Host};
+ }
  my $obj;
 
  $host ||= $ENV{NNTPSERVER} || $ENV{NEWSHOST};
@@ -81,6 +87,11 @@ sub new
  $obj;
 }
 
+sub host {
+ my $me = shift;
+ ${*$me}{'net_nntp_host'};
+}
+
 sub debug_text
 {
  my $nntp = shift;
@@ -712,13 +723,19 @@ in RFC977. C<Net::NNTP> inherits its communication methods from C<Net::Cmd>
 
 This is the constructor for a new Net::NNTP object. C<HOST> is the
 name of the remote host to which a NNTP connection is required. If not
-given two environment variables are checked, first C<NNTPSERVER> then
+given then it may be passed as the C<Host> option described below. If no host is passed
+then two environment variables are checked, first C<NNTPSERVER> then
 C<NEWSHOST>, then C<Net::Config> is checked, and if a host is not found
 then C<news> is used.
 
 C<OPTIONS> are passed in a hash like fashion, using key and value pairs.
 Possible options are:
 
+B<Host> - NNTP host to connect to. It may be a single scalar, as defined for
+the C<PeerAddr> option in L<IO::Socket::INET>, or a reference to
+an array with hosts to try in turn. The L</host> method will return the value
+which was used to connect to the host.
+
 B<Timeout> - Maximum time, in seconds, to wait for a response from the
 NNTP server, a value of zero will cause all IO operations to block.
 (default: 120)
diff --git a/Net/POP3.pm b/Net/POP3.pm
index b12682e..aa4fd5f 100644
--- a/Net/POP3.pm
+++ b/Net/POP3.pm
@@ -13,7 +13,7 @@ use Net::Cmd;
 use Carp;
 use Net::Config;
 
-$VERSION = "2.25";
+$VERSION = "2.26";
 
 @ISA = qw(Net::Cmd IO::Socket::INET);
 
@@ -21,8 +21,14 @@ sub new
 {
  my $self = shift;
  my $type = ref($self) || $self;
- my $host = shift if @_ % 2;
- my %arg  = @_; 
+ my ($host,%arg);
+ if (@_ % 2) {
+   $host = shift ;
+   %arg  = @_;
+ } else {
+   %arg = @_;
+   $host=delete $arg{Host};
+ }
  my $hosts = defined $host ? [ $host ] : $NetConfig{pop3_hosts};
  my $obj;
  my @localport = exists $arg{ResvPort} ? ( LocalPort => $arg{ResvPort} ): ();
@@ -59,6 +65,11 @@ sub new
  $obj;
 }
 
+sub host {
+ my $me = shift;
+ ${*$me}{'net_pop3_host'};
+}
+
 ##
 ## We don't want people sending me their passwords when they report problems
 ## now do we :-)
@@ -483,17 +494,23 @@ on the object.
 
 =over 4
 
-=item new ( [ HOST, ] [ OPTIONS ] )
+=item new ( [ HOST ] [, OPTIONS ] 0
 
 This is the constructor for a new Net::POP3 object. C<HOST> is the
-name of the remote host to which a POP3 connection is required.
+name of the remote host to which an POP3 connection is required.
 
-If C<HOST> is not given, then the C<POP3_Host> specified in C<Net::Config>
-will be used.
+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.
 Possible options are:
 
+B<Host> - POP3 host to connect to. It may be a single scalar, as defined for
+the C<PeerAddr> option in L<IO::Socket::INET>, or a reference to
+an array with hosts to try in turn. The L</host> method will return the value
+which was used to connect to the host.
+
 B<ResvPort> - If given then the socket for the C<Net::POP3> object
 will be bound to the local port given using C<bind> when the socket is
 created.
diff --git a/Net/SMTP.pm b/Net/SMTP.pm
index 8219e8a..1e01645 100644
--- a/Net/SMTP.pm
+++ b/Net/SMTP.pm
@@ -576,7 +576,7 @@ known as mailhost:
 
 =over 4
 
-=item new Net::SMTP [ HOST, ] [ OPTIONS ]
+=item new ( [ HOST ] [, OPTIONS ] )
 
 This is the constructor for a new Net::SMTP object. C<HOST> is the
 name of the remote host to which an SMTP connection is required.