aamine

* lib/net/protocol.rb: calls on_connect before conn_command


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

4 files changed, 143 insertions, 94 deletions

diff --git a/lib/net/http.rb b/lib/net/http.rb
index 730ea8eafc..5fb2e299a0 100644
--- a/lib/net/http.rb
+++ b/lib/net/http.rb
@@ -43,8 +43,8 @@ This is required for compatibility.
 
     require 'net/http'
     Net::HTTP.start( 'some.www.server', 80 ) {|http|
-      response , = http.post( '/cgi-bin/any.rhtml',
-                              'querytype=subject&target=ruby' )
+        response , = http.post( '/cgi-bin/any.rhtml',
+                                'querytype=subject&target=ruby' )
     }
 
 === Accessing via Proxy
@@ -94,9 +94,9 @@ URI class will be included in ruby standard library.
     require 'net/http'
 
     Net::HTTP.start( 'auth.some.domain' ) {|http|
-      response , = http.get( '/need-auth.cgi',
-              'Authentication' => ["#{account}:#{password}"].pack('m').strip )
-      print response.body
+        response , = http.get( '/need-auth.cgi',
+                'Authentication' => ["#{account}:#{password}"].pack('m').strip )
+        print response.body
     }
 
 In version 1.2 (Ruby 1.7 or later), you can write like this:
@@ -106,8 +106,8 @@ In version 1.2 (Ruby 1.7 or later), you can write like this:
     req = Net::HTTP::Get.new('/need-auth.cgi')
     req.basic_auth 'account', 'password'
     Net::HTTP.start( 'auth.some.domain' ) {|http|
-      response = http.request( req )
-      print response.body
+        response = http.request(req)
+        print response.body
     }
 
 == Switching Net::HTTP versions
@@ -157,11 +157,11 @@ Yes, this is not thread-safe.
 
         # example
         proxy_class = Net::HTTP::Proxy( 'proxy.foo.org', 8080 )
-          :
-        proxy_class.start( 'www.ruby-lang.org' ) do |http|
-          # connecting proxy.foo.org:8080
-          :
-        end
+                        :
+        proxy_class.start( 'www.ruby-lang.org' ) {|http|
+            # connecting proxy.foo.org:8080
+                        :
+        }
 
 : proxy_class?
     If self is HTTP, false.
@@ -242,13 +242,13 @@ Yes, this is not thread-safe.
         
         # using block
         File.open( 'save.txt', 'w' ) {|f|
-          http.get( '/~foo/', nil ) do |str|
-            f.write str
-          end
+            http.get( '/~foo/', nil ) do |str|
+              f.write str
+            end
         }
         # same effect
         File.open( 'save.txt', 'w' ) {|f|
-          http.get '/~foo/', nil, f
+            http.get '/~foo/', nil, f
         }
 
 : head( path, header = nil )
@@ -263,7 +263,7 @@ Yes, this is not thread-safe.
 
         response = nil
         Net::HTTP.start( 'some.www.server', 80 ) {|http|
-          response = http.head( '/index.html' )
+            response = http.head( '/index.html' )
         }
         p response['content-type']
 
@@ -290,13 +290,13 @@ Yes, this is not thread-safe.
 
         # using block
         File.open( 'save.html', 'w' ) {|f|
-          http.post( '/cgi-bin/search.rb', 'querytype=subject&target=ruby' ) do |str|
-            f.write str
-          end
+            http.post( '/cgi-bin/search.rb', 'querytype=subject&target=ruby' ) do |str|
+              f.write str
+            end
         }
         # same effect
         File.open( 'save.html', 'w' ) {|f|
-          http.post '/cgi-bin/search.rb', 'querytype=subject&target=ruby', nil, f
+            http.post '/cgi-bin/search.rb', 'querytype=subject&target=ruby', nil, f
         }
 
 : get2( path, header = nil )
@@ -315,10 +315,10 @@ Yes, this is not thread-safe.
 
         # using block
         http.get2( '/index.html' ) {|response|
-          p response['content-type']
-          response.read_body do |str|   # read body now
-            print str
-          end
+            p response['content-type']
+            response.read_body do |str|   # read body now
+              print str
+            end
         }
 
 : post2( path, header = nil )
@@ -335,11 +335,11 @@ Yes, this is not thread-safe.
 
         # using block
         http.post2( '/cgi-bin/nice.rb', 'datadatadata...' ) {|response|
-          p response.status
-          p response['content-type']
-          response.read_body do |str|   # read body now
-            print str
-          end
+            p response.status
+            p response['content-type']
+            response.read_body do |str|   # read body now
+              print str
+	    end
         }
 
 : request( request [, data] )
diff --git a/lib/net/pop.rb b/lib/net/pop.rb
index 925dfce147..eca7c60949 100644
--- a/lib/net/pop.rb
+++ b/lib/net/pop.rb
@@ -29,49 +29,81 @@ Replace 'pop3.server.address' your POP3 server address.
 
     require 'net/pop'
 
-    Net::POP3.start( 'pop3.server.address', 110,
-                     'YourAccount', 'YourPassword' ) {|pop|
-      if pop.mails.empty? then
-        puts 'no mail.'
-      else
-        i = 0
-        pop.each_mail do |m|   # or "pop.mails.each ..."
-          File.open( 'inbox/' + i.to_s, 'w' ) {|f|
+    pop = Net::POP3.new( 'pop3.server.address', 110 )
+    pop.start( 'YourAccount', 'YourPassword' )          ###
+    if pop.mails.empty? then
+      puts 'no mail.'
+    else
+      i = 0
+      pop.each_mail do |m|   # or "pop.mails.each ..."
+	File.open( 'inbox/' + i.to_s, 'w' ) {|f|
             f.write m.pop
-          }
-          m.delete
-          i += 1
-        end
+        }
+        m.delete
+        i += 1
       end
       puts "#{pop.mails.size} mails popped."
+    end
+    pop.finish                                           ###
+
+(1) call Net::POP3#start and start POP session
+(2) access mails by using POP3#each_mail and/or POP3#mails
+(3) close POP session by calling POP3#finish or use block form #start.
+
+This example is using block form #start to close the session.
+=== Enshort Code
+
+The example above is very verbose. You can enshort code by using
+some utility methods. At first, block form of Net::POP3.start can
+alternates POP3.new, POP3#start and POP3#finish.
+
+    require 'net/pop'
+
+    Net::POP3.start( 'pop3.server.address', 110 )
+                     'YourAccount', 'YourPassword' )
+	if pop.mails.empty? then
+	  puts 'no mail.'
+	else
+	  i = 0
+	  pop.each_mail do |m|   # or "pop.mails.each ..."
+	    File.open( 'inbox/' + i.to_s, 'w' ) {|f|
+                f.write m.pop
+	    }
+	    m.delete
+	    i += 1
+	  end
+          puts "#{pop.mails.size} mails popped."
+	end
     }
 
-=== Shorter Version
+POP3#delete_all alternates #each_mail and m.delete.
 
     require 'net/pop'
+
     Net::POP3.start( 'pop3.server.address', 110,
                      'YourAccount', 'YourPassword' ) {|pop|
-      if pop.mails.empty? then
-        puts 'no mail.'
-      else
-        i = 0
-        pop.delete_all do |m|
-          File.open( 'inbox/' + i.to_s, 'w' ) {|f|
-            f.write m.pop
-          }
-          i += 1
-        end
-      end
+	if pop.mails.empty? then
+	  puts 'no mail.'
+	else
+	  i = 0
+	  pop.delete_all do |m|
+	    File.open( 'inbox/' + i.to_s, 'w' ) {|f|
+		f.write m.pop
+	    }
+	    i += 1
+	  end
+	end
     }
 
 And here is more shorter example.
 
     require 'net/pop'
+
     i = 0
     Net::POP3.delete_all( 'pop3.server.address', 110,
                           'YourAccount', 'YourPassword' ) do |m|
       File.open( 'inbox/' + i.to_s, 'w' ) {|f|
-        f.write m.pop
+          f.write m.pop
       }
       i += 1
     end
@@ -85,7 +117,7 @@ This example does not create such one.
     Net::POP3.delete_all( 'pop3.server.address', 110,
                           'YourAccount', 'YourPassword' ) do |m|
       File.open( 'inbox', 'w' ) {|f|
-        m.pop f   ####
+          m.pop f   ####
       }
     end
 
@@ -99,7 +131,7 @@ net/pop also supports APOP authentication. There's two way to use APOP:
     require 'net/pop'
     Net::APOP.start( 'apop.server.address', 110,
                      'YourAccount', 'YourPassword' ) {|pop|
-      # Rest code is same.
+        # Rest code is same.
     }
 
     # (2)
@@ -108,7 +140,7 @@ net/pop also supports APOP authentication. There's two way to use APOP:
                      'YourAccount', 'YourPassword',
                      true   ####
     ) {|pop|
-      # Rest code is same.
+        # Rest code is same.
     }
 
 == Net::POP3 class
@@ -123,21 +155,21 @@ net/pop also supports APOP authentication. There's two way to use APOP:
 : start( address, port = 110, account, password ) {|pop| .... }
     equals to Net::POP3.new( address, port ).start( account, password )
 
-        Net::POP3.start( addr, port, account, password ) do |pop|
-          pop.each_mail do |m|
-            file.write m.pop
-            m.delete
-          end
-        end
+        Net::POP3.start( addr, port, account, password ) {|pop|
+	    pop.each_mail do |m|
+	      file.write m.pop
+	      m.delete
+	    end
+        }
 
 : foreach( address, port = 110, account, password ) {|mail| .... }
     starts POP3 protocol and iterates for each POPMail object.
     This method equals to
 
         Net::POP3.start( address, port, account, password ) {|pop|
-          pop.each_mail do |m|
-            yield m
-          end
+            pop.each_mail do |m|
+	      yield m
+	    end
         }
 
         # example
@@ -163,10 +195,10 @@ net/pop also supports APOP authentication. There's two way to use APOP:
     This method must not be called while POP3 session is opened.
 
         # example
-        pop = Net::POP3.auth_only( 'your.pop3.server',
-                                    nil,     # using default (110)
-                                   'YourAccount',
-                                   'YourPassword' )
+        Net::POP3.auth_only( 'your.pop3.server',
+                             nil,     # using default (110)
+                             'YourAccount',
+                             'YourPassword' )
 
 === Instance Methods
 
@@ -253,20 +285,20 @@ A class of mail which exists on POP server.
         # example
         allmails = nil
         POP3.start( 'your.pop3.server', 110,
-                    'YourAccount, 'YourPassword' ) do |pop|
-          allmails = pop.mails.collect {|popmail| popmail.pop }
-        end
+                    'YourAccount, 'YourPassword' ) {|pop|
+            allmails = pop.mails.collect {|popmail| popmail.pop }
+        }
 
 : pop {|str| .... }
     gives the block part strings of a mail.
 
         # example
         POP3.start( 'localhost', 110 ) {|pop3|
-          pop3.each_mail do |m|
-            m.pop do |str|
-              # do anything
-            end
-          end
+	    pop3.each_mail do |m|
+	      m.pop do |str|
+		# do anything
+	      end
+	    end
         }
 
 : header
diff --git a/lib/net/protocol.rb b/lib/net/protocol.rb
index 600dc04b58..c67be1863f 100644
--- a/lib/net/protocol.rb
+++ b/lib/net/protocol.rb
@@ -146,8 +146,8 @@ module Net
 
     def connect
       conn_socket @address, @port
-      conn_command @socket
       on_connect
+      conn_command @socket
     end
 
     def re_connect
diff --git a/lib/net/smtp.rb b/lib/net/smtp.rb
index 5331ee17e7..dfb27660fd 100644
--- a/lib/net/smtp.rb
+++ b/lib/net/smtp.rb
@@ -37,7 +37,7 @@ executed.
 
     require 'net/smtp'
     Net::SMTP.start( 'your.smtp.server', 25 ) {|smtp|
-      # use smtp object only in this block
+        # use smtp object only in this block
     }
 
 Replace 'your.smtp.server' by your SMTP server. Normally
@@ -49,7 +49,7 @@ Then you can send mail.
     require 'net/smtp'
 
     Net::SMTP.start( 'your.smtp.server', 25 ) {|smtp|
-      smtp.send_mail <<EndOfMail, 'your@mail.address', 'to@some.domain'
+        smtp.send_mail <<EndOfMail, 'your@mail.address', 'to@some.domain'
     From: Your Name <your@mail.address>
     To: Dest Address <to@some.domain>
     Subject: test mail
@@ -60,6 +60,23 @@ Then you can send mail.
     EndOfMail
     }
 
+=== Closing Session
+
+You MUST close SMTP session after sending mails, by calling #finish
+method. You can also use block form of SMTP.start/SMTP#start, which
+closes session automatically. I strongly recommend later one. It is
+more beautiful and simple.
+
+    # using SMTP#finish
+    smtp = Net::SMTP.start( 'your.smtp.server', 25 )
+    smtp.send_mail mail_string, 'from@address', 'to@address'
+    smtp.finish
+
+    # using block form of SMTP.start
+    Net::SMTP.start( 'your.smtp.server', 25 ) {|smtp|
+        smtp.send_mail mail_string, 'from@address', 'to@address'
+    }
+
 === Sending Mails from Any Sources
 
 In an example above I sent mail from String (here document literal).
@@ -68,9 +85,9 @@ like File and Array.
 
     require 'net/smtp'
     Net::SMTP.start( 'your.smtp.server', 25 ) {|smtp|
-      File.open( 'Mail/draft/1' ) {|f|
-        smtp.send_mail f, 'your@mail.address', 'to@some.domain'
-      }
+        File.open( 'Mail/draft/1' ) {|f|
+            smtp.send_mail f, 'your@mail.address', 'to@some.domain'
+        }
     }
 
 === Giving "Hello" Domain
@@ -99,7 +116,7 @@ send or reject SMTP session by this data.
 
         # example
         Net::SMTP.start( 'your.smtp.server' ) {
-          smtp.send_mail mail_string, 'from@mail.address', 'dest@mail.address'
+            smtp.send_mail mail_string, 'from@mail.address', 'dest@mail.address'
         }
 
 === Instance Methods
@@ -153,9 +170,9 @@ send or reject SMTP session by this data.
 
         # example
         Net::SMTP.start( 'your.smtp.server' ) {|smtp|
-          smtp.send_mail mail_string,
-                         'from@mail.address',
-                         'dest@mail.address' 'dest2@mail.address'
+            smtp.send_mail mail_string,
+                           'from@mail.address',
+                           'dest@mail.address' 'dest2@mail.address'
         }
 
 : ready( from_addr, *to_addrs ) {|adapter| .... }
@@ -169,11 +186,11 @@ send or reject SMTP session by this data.
 
         # example
         Net::SMTP.start( 'your.smtp.server', 25 ) {|smtp|
-          smtp.ready( 'from@mail.addr', 'dest@mail.addr' ) do |adapter|
-            adapter.write str1
-            adapter.write str2
-            adapter.write str3
-          end
+	    smtp.ready( 'from@mail.addr', 'dest@mail.addr' ) do |adapter|
+	      adapter.write str1
+	      adapter.write str2
+	      adapter.write str3
+	    end
         }
 
 == Exceptions