net-netrc 0.1.0 → 0.2.0

data/lib/net/ftp-netrc.rb

@@ -0,0 +1,76 @@
+# = net/ftp-netrc.rb - Net::FTP / Net::Netrc integration
+#
+# Copyright (c) 2005 Robert J. Showalter
+#
+# This library is distributed under the terms of the Ruby license.
+# You may freely distribute or modify this library.
+#
+# This module extends the Net::FTP#login method to use Net::Netrc
+# to lookup login information if a nil username is passed.
+#
+# Example:
+#
+#   require 'net/ftp-netrc'     # (brings in net/ftp and net/netrc)
+#
+#   ftp = Net::FTP.new('myhost')
+#   ftp.login(nil)
+#   ftp.last_response
+#   => 230 User myuser logged in.
+#
+# $Id: ftp-netrc.rb,v 1.1 2005/12/19 16:25:52 bshow Exp $
+
+require 'net/ftp'
+require 'net/netrc'
+
+module Net
+
+  class FTP
+
+    alias_method :orig_connect, :connect  # :nodoc:
+    alias_method :orig_login, :login      # :nodoc:
+
+    # cache host name for later use by login
+    def connect(host, port = FTP_PORT) # :nodoc:
+      @host = host
+      orig_connect(host, port)
+    end
+
+    #
+    # Logs in to the remote host. The session must have been previously
+    # connected. 
+    #
+    # If +user+ is nil, Net::Netrc#locate is used to lookup login information
+    # based on the host name supplied to Net::Netrc#connect.
+    #
+    # If +user+ is the string "anonymous" and the +password+ is nil, a password
+    # of user@host is synthesized. If the +acct+ parameter is not nil, an FTP
+    # ACCT command is sent following the successful login. Raises an exception
+    # on error (typically Net::FTPPermError).
+    #
+    # Example:
+    #
+    #   require 'net/ftp-netrc'     # (brings in net/ftp and net/netrc)
+    #
+    #   ftp = Net::FTP.new('myhost')
+    #   ftp.login(nil)
+    #   ftp.last_response
+    #   => 230 User myuser logged in.
+    #
+    def login(user = "anonymous", passwd = nil, acct = nil)
+      if user.nil?
+        rc = Net::Netrc.locate(@host)
+        if rc
+          user = rc.login
+          passwd = rc.password
+          acct = rc.account
+        else
+          user = ''
+          passwd = ''
+        end
+      end
+      orig_login(user, passwd, acct)
+    end
+
+  end
+
+end

data/lib/net/netrc.rb

@@ -7,16 +7,79 @@
 #
 # See Net::Netrc for usage.
 #
-# $Id: netrc.rb,v 1.1 2005/12/15 15:09:01 bshow Exp $
+# $Id: netrc.rb,v 1.3 2005/12/19 16:42:01 bshow Exp $
 
 require 'etc'
 
 module Net
 
+  # Net::Netrc provides an interface to the ftp(1) .netrc file containing login
+  # information for FTP (or other) servers.
+  #
+  # == Example Usage
+  #
+  #   require 'net/netrc'
+  #
+  #   rc = Net::Netrc.locate('ftp.example.com') or
+  #     raise ".netrc missing or no entry found"
+  #   puts rc.login
+  #   puts rc.password
+  #   puts rc.name
+  #
+  # == The .netrc File
+  #
+  # The .netrc file is a plain text file containing login information.  It is
+  # typically located in the user's home directory. (See #rcname for specific
+  # details on how the .netrc file is located.)
+  #
+  # On Unix platforms, the .netrc must be owned by the process' effective
+  # user id and must not be group- or world-writable, or a SecurityError
+  # will be raised.
+  #
+  # The .netrc file contains whitespace-separated tokens. Tokens containing
+  # whitespace must be enclosed in double quotes. The following tokens are
+  # recognized:
+  #
+  # [machine _name_]
+  #   Identifies a remote machine name. #locate searches sequentially for
+  #   a matching +machine+ token. Once a match is found, subsequent tokens
+  #   are processed until either EOF is reached or another +machine+
+  #   (or +default+) token is parsed.
+  #
+  # [login _name_]
+  #   Identifies remote user name.
+  #
+  # [password _string_]
+  #   Supplies remote password.
+  #   
+  # [account _string_]
+  #   Supplies an additional account password.
+  #
+  # [macdef _name_]
+  #   Begins a macro definition, which ends with the next blank line
+  #   encountered. Ignored by Net::Netrc.
+  #
+  # [default]
+  #   Defines default account information. The login information here
+  #   will be returned if a matching +machine+ token is not found
+  #   during parsing. If supplied, +default+ must appear after any
+  #   +machine+ entries.
+  #
+  # == Sample .netrc file
+  #
+  # The following is an example of a .netrc file:
+  #
+  #   machine host1.austin.century.com 
+  #     login fred 
+  #     password bluebonnet
+  #
+  #   default login john password ranger
+  #
+
   class Netrc
 
     VERSION_MAJOR = 0
-    VERSION_MINOR = 1
+    VERSION_MINOR = 2
     VERSION_PATCH = 0
     VERSION = "#{VERSION_MAJOR}.#{VERSION_MINOR}.#{VERSION_PATCH}"
 
@@ -113,6 +176,12 @@ module Net
     # the matching entry for that name, or the default entry. If
     # no match is found and no default entry exists, nil is returned.
     #
+    # The returned object's #machine, #login, #password, and #account
+    # attributes will be set to the corresponding values from the .netrc file
+    # entry.  #machine will be nil if the +default+ .netrc entry was used. The
+    # other attributes will be nil if the corresponding token in the .netrc
+    # file was not present.
+    #
     # +io+ is a previously-opened IO object. If not supplied,
     # #rcopen is called to locate and open the .netrc file. +io+
     # will be closed when this method returns.

metadata

@@ -3,8 +3,8 @@ rubygems_version: 0.8.11
 specification_version: 1
 name: net-netrc
 version: !ruby/object:Gem::Version 
-  version: 0.1.0
-date: 2005-12-15 00:00:00 -05:00
+  version: 0.2.0
+date: 2005-12-19 00:00:00 -05:00
 summary: Net::Netrc provides ftp(1)-style .netrc parsing
 require_paths: 
   - lib
@@ -31,6 +31,7 @@ authors:
 files: 
   - lib/net
   - lib/net/netrc.rb
+  - lib/net/ftp-netrc.rb
   - test/test_netrc.rb
 test_files: 
   - test/test_netrc.rb