o protocol.rb, smtp.rb, pop.rb, http.rb: define all#inspect()

o  protocol.rb, smtp.rb, pop.rb, http.rb:  modify/add documents


git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@746 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

4 files changed, 151 insertions, 109 deletions

diff --git a/lib/net/http.rb b/lib/net/http.rb
index d364237956..40f6238d50 100644
--- a/lib/net/http.rb
+++ b/lib/net/http.rb
@@ -8,16 +8,6 @@ This file is derived from "http-access.rb".
 This library is distributed under the terms of the Ruby license.
 You can freely distribute/modify this library.
 
-=end
-
-require 'net/protocol'
-
-
-module Net
-
-  class HTTPBadResponse < StandardError; end
-
-=begin
 
 = class HTTP
 
@@ -50,7 +40,10 @@ module Net
   get data from "path" on connecting host.
   "header" must be a Hash like { 'Accept' => '*/*', ... }.
   Data is written to "dest" by using "<<" method.
-  This method returns Net::HTTPResponse object and "dest".
+  This method returns Net::HTTPResponse object, and "dest".
+
+    # example
+    response, body = http.get( '/index.html' )
 
   If called as iterator, give a part String of entity body.
 
@@ -59,15 +52,15 @@ module Net
   raised. At that time, you can get Response object from 
   execption object. (same in head/post)
 
-    ex.
-
+    # example
     begin
-      head, body = http.get(...)
-    rescue ProtoRetriableError
+      response, body = http.get(...)
+    rescue Net::ProtoRetriableError
       response = $!.data
       ...
     end
 
+
 : head( path, header = nil )
   get only header from "path" on connecting host.
   "header" is a Hash like { 'Accept' => '*/*', ... }.
@@ -94,25 +87,46 @@ module Net
   "header" must be a Hash like { 'Accept' => '*/*', ... }.
   This method gives HTTPReadAdapter object to block.
 
+    ex.
+    
+    http.get2( '/index.html' ) do |f|
+      # f is a HTTPReadAdapter object
+      f.header
+      f.body
+    end
+
 : head2( path, header = nil )
   send HEAD request for "path".
   "header" must be a Hash like { 'Accept' => '*/*', ... }.
   The difference between "head" method is that
   "head2" does not raise exceptions.
 
+    ex.
+    
+    http.head2( '/index.html' ) do |f|
+      f.header
+    end
+
 : post2( path, data, header = nil ) {|adapter| .... }
   post "data"(must be String now) to "path".
   "header" must be a Hash like { 'Accept' => '*/*', ... }.
   This method gives HTTPReadAdapter object to block.
 
+    ex.
+    
+    http.post2( '/index.html', 'data data data...' ) do |f|
+      f.header
+      f.body
+    end
+
 
 = class HTTPResponse
 
-== Methods
-
 HTTP response object.
 All "key" is case-insensitive.
 
+== Methods
+
 : code
   HTTP result code. For example, '302'
 
@@ -134,6 +148,9 @@ All "key" is case-insensitive.
 : each {|name,value| .... }
   iterate for each field name and value pair
 
+: body
+  "dest" argument for HTTP#get, post, put
+
 
 = class HTTPReadAdapter
 
@@ -154,6 +171,14 @@ All "key" is case-insensitive.
 
 =end
 
+require 'net/protocol'
+
+
+module Net
+
+  class HTTPBadResponse < StandardError; end
+
+
   class HTTP < Protocol
 
     protocol_param :port,         '80'
@@ -320,6 +345,10 @@ All "key" is case-insensitive.
       @header = @body = nil
     end
 
+    def inspect
+      "#<#{type}>"
+    end
+
     def header
       unless @header then
         @header = @command.get_response
@@ -358,6 +387,10 @@ All "key" is case-insensitive.
     attr_reader :http_body_exist
     attr_accessor :body
 
+    def inspect
+      "#<Net::HTTPResponse #{code}>"
+    end
+
     def []( key )
       @data[ key.downcase ]
     end
@@ -463,10 +496,12 @@ All "key" is case-insensitive.
       super sock
     end
 
-
     attr_reader :http_version
 
-      
+    def inspect
+      "#<Net::HTTPCommand>"
+    end
+
     def get( path, u_header )
       return unless begin_critical
       request sprintf('GET %s HTTP/%s', path, HTTPVersion), u_header
diff --git a/lib/net/pop.rb b/lib/net/pop.rb
index 1d3e41a54b..df95bc0c34 100644
--- a/lib/net/pop.rb
+++ b/lib/net/pop.rb
@@ -7,17 +7,6 @@ written by Minero Aoki <aamine@dp.u-netsurf.ne.jp>
 This library is distributed under the terms of the Ruby license.
 You can freely distribute/modify this library.
 
-=end
-
-
-require 'net/protocol'
-require 'md5'
-
-
-module Net
-
-
-=begin
 
 == Net::POP3
 
@@ -51,52 +40,16 @@ Net::Protocol
   an array of ((URL:#POPMail)).
   This array is renewed when session started.
 
-=end
-
-  class POP3 < Protocol
-
-    protocol_param :port,         '110'
-    protocol_param :command_type, '::Net::POP3Command'
-
-    protocol_param :mail_type,    '::Net::POPMail'
-
-    def initialize( addr = nil, port = nil )
-      super
-      @mails = [].freeze
-    end
-
-        
-    attr :mails
-
-    def each
-      @mails.each {|m| yield m }
-    end
-
-
-    private
-
 
-    def do_start( acnt, pwd )
-      @command.auth( acnt, pwd )
-
-      @mails = []
-      t = type.mail_type
-      @command.list.each_with_index do |size,idx|
-        if size then
-          @mails.push t.new( idx, size, @command )
-        end
-      end
-      @mails.freeze
-    end
+== Net::APOP
 
-  end
+This class defines no new methods.
+Only difference from POP3 is using APOP authentification.
 
-  POP         = POP3
-  POPSession  = POP3
-  POP3Session = POP3
+=== Super Class
 
+Net::POP3
 
-=begin
 
 == Net::POPMail
 
@@ -107,7 +60,7 @@ A class of mail which exists on POP server.
 Object
 
 
-=== Method
+=== Methods
 
 : all( dest = '' )
 : pop
@@ -155,6 +108,54 @@ Object
 
 =end
 
+require 'net/protocol'
+require 'md5'
+
+
+module Net
+
+  class POP3 < Protocol
+
+    protocol_param :port,         '110'
+    protocol_param :command_type, '::Net::POP3Command'
+
+    protocol_param :mail_type,    '::Net::POPMail'
+
+    def initialize( addr = nil, port = nil )
+      super
+      @mails = [].freeze
+    end
+
+    attr :mails
+
+    def each
+      @mails.each {|m| yield m }
+    end
+
+
+    private
+
+    def do_start( acnt, pwd )
+      @command.auth( acnt, pwd )
+
+      @mails = []
+      t = type.mail_type
+      @command.list.each_with_index do |size,idx|
+        if size then
+          @mails.push t.new( idx, size, @command )
+        end
+      end
+      @mails.freeze
+    end
+
+  end
+
+  POP         = POP3
+  POPSession  = POP3
+  POP3Session = POP3
+
+
+
   class POPMail
 
     def initialize( n, s, cmd )
@@ -165,9 +166,12 @@ Object
       @deleted = false
     end
 
-
     attr :size
 
+    def inspect
+      "#<#{type} #{@num}#{@deleted ? ' deleted' : ''}>"
+    end
+
     def all( dest = '' )
       if iterator? then
         dest = ReadAdapter.new( Proc.new )
@@ -202,23 +206,9 @@ Object
   end
 
 
-=begin
-
-== Net::APOP
-
-This class defines no new methods.
-Only difference from POP3 is using APOP authentification.
-
-=== Super Class
-
-Net::POP3
-
-=end
 
   class APOP < POP3
-
     protocol_param :command_type, 'Net::APOPCommand'
-
   end
 
   APOPSession = APOP
@@ -234,7 +224,6 @@ Net::POP3
       }
     end
 
-
     def auth( acnt, pass )
       critical {
         @socket.writeline 'USER ' + acnt
@@ -245,7 +234,6 @@ Net::POP3
       }
     end
 
-
     def list
       arr = []
       critical {
@@ -258,7 +246,6 @@ Net::POP3
       arr
     end
 
-
     def rset
       critical {
         getok 'RSET'
@@ -273,14 +260,12 @@ Net::POP3
       }
     end
 
-
     def retr( num, dest = '', &block )
       critical {
         getok sprintf( 'RETR %d', num )
         @socket.read_pendstr( dest, &block )
       }
     end
-
     
     def dele( num )
       critical {
@@ -288,14 +273,12 @@ Net::POP3
       }
     end
 
-
     def uidl( num )
       critical {
         getok( sprintf 'UIDL %d', num ).msg.split(' ')[1]
       }
     end
 
-
     def quit
       critical {
         getok 'QUIT'
@@ -305,7 +288,6 @@ Net::POP3
 
     private
 
-
     def check_reply_auth
       begin
         cod = check_reply( SuccessCode )
@@ -316,7 +298,6 @@ Net::POP3
       return cod
     end
 
-
     def get_reply
       str = @socket.readline
 
@@ -343,7 +324,6 @@ Net::POP3
       @stamp = m[0]
     end
 
-
     def auth( account, pass )
       critical {
         @socket.writeline sprintf( 'APOP %s %s',
diff --git a/lib/net/protocol.rb b/lib/net/protocol.rb
index 18d82ddca0..1b6c35420c 100644
--- a/lib/net/protocol.rb
+++ b/lib/net/protocol.rb
@@ -153,10 +153,13 @@ Object
       @socket  = nil
     end
 
-
     attr_reader :address, :port,
                 :command, :socket
 
+    def inspect
+      "#<#{type} #{address}:#{port} open=#{active?}>"
+    end
+
 
     def start( *args )
       return false if active?
@@ -231,6 +234,10 @@ Object
     attr_accessor :socket
     attr_reader :last_reply
 
+    def inspect
+      "#<#{type}>"
+    end
+
     # abstract quit
 
 
@@ -295,6 +302,10 @@ Object
     attr_reader :code_type, :code, :message
     alias msg message
 
+    def inspect
+      "#<#{type} #{code}>"
+    end
+
     def error!( data = nil )
       raise code_type.error_type.new( code + ' ' + Net.quote(msg), data )
     end
@@ -320,6 +331,10 @@ Object
     end
 
     attr :data
+
+    def inspect
+      "#<#{type}>"
+    end
   
   end
 
@@ -335,6 +350,10 @@ Object
 
     attr_reader :parents
 
+    def inspect
+      "#<#{type}>"
+    end
+
     def error_type
       @err
     end
@@ -370,6 +389,10 @@ Object
       @mid = mid
     end
 
+    def inspect
+      "#<#{type}>"
+    end
+
     def write( str )
       @sock.__send__ @mid, str
     end
@@ -383,6 +406,10 @@ Object
       @block = block
     end
 
+    def inspect
+      "#<#{type}>"
+    end
+
     def <<( str )
       @block.call str
     end
@@ -414,6 +441,10 @@ Object
       alias open new
     end
 
+    def inspect
+      "#<#{type} open=#{!@closed}>"
+    end
+
     def reopen
       unless closed? then
         @socket.close
diff --git a/lib/net/smtp.rb b/lib/net/smtp.rb
index d11cff6235..bc346d3138 100644
--- a/lib/net/smtp.rb
+++ b/lib/net/smtp.rb
@@ -7,17 +7,6 @@ written by Minero Aoki <aamine@dp.u-netsurf.ne.jp>
 This library is distributed under the terms of the Ruby license.
 You can freely distribute/modify this library.
 
-=end
-
-
-require 'net/protocol'
-require 'md5'
-
-
-module Net
-
-
-=begin
 
 == Net::SMTP
 
@@ -81,6 +70,13 @@ Net::Protocol
 
 =end
 
+require 'net/protocol'
+require 'md5'
+
+
+module Net
+
+
   class SMTP < Protocol
 
     protocol_param :port,         '25'