aamine

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


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

3 files changed, 154 insertions, 97 deletions

diff --git a/doc/net/http.rd.ja b/doc/net/http.rd.ja
index 98e5b3dc63..0041e4155d 100644
--- a/doc/net/http.rd.ja
+++ b/doc/net/http.rd.ja
@@ -27,8 +27,8 @@
 
     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' )
     }
 
 === プロクシ経由のアクセス
@@ -78,9 +78,9 @@ Net::HTTP を継承しているので Net::HTTP と全く同じように使えます。
     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
     }
 
 バージョン 1.2 (Ruby 1.7 以降に添付) では次のように書けます。
@@ -90,8 +90,8 @@ Net::HTTP を継承しているので Net::HTTP と全く同じように使えます。
     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
     }
 
 == 新しい仕様への変更と移行措置について
@@ -148,11 +148,11 @@ Ruby 1.6 に入っているのが http.rb 1.1 で 1.7 以降が 1.2 ですが、
 
         # 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?
     自身が (Proxy メソッドによって作成された) プロクシ用のクラスならば真。
@@ -233,13 +233,13 @@ Ruby 1.6 に入っているのが http.rb 1.1 で 1.7 以降が 1.2 ですが、
         
         # 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 )
@@ -256,7 +256,7 @@ Ruby 1.6 に入っているのが http.rb 1.1 で 1.7 以降が 1.2 ですが、
 
         response = nil
         Net::HTTP.start( 'some.www.server', 80 ) {|http|
-          response = http.head( '/index.html' )
+            response = http.head( '/index.html' )
         }
         p response['content-type']
 
@@ -283,13 +283,13 @@ Ruby 1.6 に入っているのが http.rb 1.1 で 1.7 以降が 1.2 ですが、
 
         # 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 )
@@ -309,10 +309,10 @@ Ruby 1.6 に入っているのが http.rb 1.1 で 1.7 以降が 1.2 ですが、
 
         # 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 )
@@ -332,11 +332,11 @@ Ruby 1.6 に入っているのが http.rb 1.1 で 1.7 以降が 1.2 ですが、
 
         # 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
         }
 
 
diff --git a/doc/net/pop.rd.ja b/doc/net/pop.rd.ja
index b21cf72603..67510183b1 100644
--- a/doc/net/pop.rd.ja
+++ b/doc/net/pop.rd.ja
@@ -12,57 +12,93 @@
 
 === メールの受信
 
-メールを受信してファイル 'inbox/1' 'inbox/2'... に書きこみ、
-サーバ上からメールを消します。
-pop3.server.address は適宜読みかえてください。
+以下のコードは、メールを受信してファイル 'inbox/1' 'inbox/2'... に
+書きこみ、サーバ上からメールを消します。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                                           ###
+
+POP サーバはネットワークのむこうに存在するので、なにか仕事をさせる
+にはその前に開始手続きを、終わったら終了手続きを、行わなければいけ
+ません。それを行うのが Net::POP3#start と #finish で、POP3 オブジェクト
+はその二つのメソッドの間でだけ有効になります。
+
+サーバ上のメールは POPMail オブジェクトとして表現されており、この
+オブジェクトのメソッドを呼ぶことでメールを取ってきたり消したりする
+ことができます。POP3#mails はこの POPMail オブジェクトの配列であり、
+POP3#each_mail はさらに mails.each のショートカットです。
 
 === 短くする
 
-以下は動作は同じでコードを短くしたバージョンです。
+上の例はあえて省略や短縮用メソッドを避けたためにかなり冗長です。
+まず、ブロック付きの Net::POP3.start を使うことで POP3.new #start
+#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
+    }
+
+POP3#delete_all を使うとさらに #each_mail と 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
     }
 
 クラスメソッドの POP3.delete_all を使うとさらに短くなります。
 
     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
@@ -78,7 +114,7 @@ pop3.server.address は適宜読みかえてください。
     Net::POP3.delete_all( 'pop3.server.address', 110,
                           'YourAccount', 'YourPassword' ) do |m|
       File.open( 'inbox', 'w' ) {|f|
-        m.pop f   ####
+          m.pop f   ####
       }
     end
 
@@ -93,7 +129,7 @@ APOP 認証を使うには
     require 'net/pop'
     Net::APOP.start( 'apop.server.address', 110,
                      'YourAccount', 'YourPassword' ) {|pop|
-      # Rest code is same.
+        # Rest code is same.
     }
 
     # (2)
@@ -102,7 +138,7 @@ APOP 認証を使うには
                      'YourAccount', 'YourPassword',
                      true   ####
     ) {|pop|
-      # Rest code is same.
+        # Rest code is same.
     }
 
 == Net::POP3 class
@@ -119,21 +155,21 @@ APOP 認証を使うには
     password で POP ログインします。第二引数 port に nil を渡すと
     POP3 のデフォルトポート(110)を使います。
 
-        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| .... }
     POP セッションを開き、サーバ上のすべてのメールに対して繰り返します。
     以下と同じです。
 
         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
@@ -159,10 +195,10 @@ APOP 認証を使うには
     POP before SMTP 専用です。
 
         # 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' )
 
 === メソッド
 
@@ -249,20 +285,20 @@ POP サーバー上のメール一通を抽象的に表現するクラス。
         # 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| .... }
     メールの文字列を少しづつ読みこみ、順次ブロックに与えます。
 
         # 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/doc/net/smtp.rd.ja b/doc/net/smtp.rd.ja
index 9b0c6a29af..7b4073ca62 100644
--- a/doc/net/smtp.rd.ja
+++ b/doc/net/smtp.rd.ja
@@ -20,7 +20,7 @@ SMTP を使ってメールを送るにはまず SMTP.start でセッションを開きます。
 
     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
     }
 
 your.smtp.server は適切な SMTP サーバのアドレスに読みかえてください。
@@ -31,7 +31,7 @@ your.smtp.server は適切な SMTP サーバのアドレスに読みかえてください。
     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
@@ -42,6 +42,27 @@ your.smtp.server は適切な SMTP サーバのアドレスに読みかえてください。
     EndOfMail
     }
 
+=== セッションを終了する
+
+メールを送ったら SMTP#finish を呼んでセッションを終了しなければいけ
+ません。File のように GC 時に勝手に close されることもありません。
+いろいろなところで finish がないソースコードの例を見掛けますが、
+すべて誤りです。finish は必ず呼んでください。
+
+またブロック付きの SMTP.start/SMTP#start を使うと勝手に finish を
+呼んでくれるので便利です。可能な限りブロック付きの start を使うのが
+よいでしょう。
+
+    # 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'
+    }
+
 === 文字列以外からの送信
 
 ひとつ上の例では文字列リテラル(ヒアドキュメント)を使って送信しましたが、
@@ -50,9 +71,9 @@ each メソッドを持ったオブジェクトからならなんでも送ることができます。
 
     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'
+        }
     }
 
 === Hello ドメイン
@@ -82,7 +103,7 @@ SMTP ではメールを送る側のホストの名前を要求されるのですが、
 
         # 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'
         }
 
 === メソッド
@@ -128,9 +149,9 @@ SMTP ではメールを送る側のホストの名前を要求されるのですが、
 
         # 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| .... }
@@ -140,11 +161,11 @@ SMTP ではメールを送る側のホストの名前を要求されるのですが、
 
         # 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
         }
 
 == 発生する例外