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

ChangeLog

@@ -1,3 +1,7 @@
+Sun Dec  9 18:06:05 2001  Minero Aoki  <aamine@loveruby.net>
+
+	* lib/net/protocol.rb: calls on_connect before conn_command
+
 Fri Dec  7 19:20:44 2001  Minero Aoki  <aamine@loveruby.net>
 
 	* lib/net/smtp.rb: uses Digest::MD5 instead of MD5 (again).

doc/net/http.rd.ja

@@ -90,7 +90,7 @@ 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 )
+        response = http.request(req)
         print response.body
     }
 
@@ -149,10 +149,10 @@ Ruby 1.6
         # example
         proxy_class = Net::HTTP::Proxy( 'proxy.foo.org', 8080 )
                         :
-        proxy_class.start( 'www.ruby-lang.org' ) do |http|
+        proxy_class.start( 'www.ruby-lang.org' ) {|http|
             # connecting proxy.foo.org:8080
                         :
-        end
+        }
 
 : proxy_class?
     自身が (Proxy メソッドによって作成された) プロクシ用のクラスならば真。

doc/net/pop.rd.ja

@@ -12,14 +12,14 @@
 
 === メールの受信
 
-メールを受信してファイル 'inbox/1' 'inbox/2'... に書きこみ、
+以下のコードは、メールを受信してファイル 'inbox/1' 'inbox/2'... に
-サーバ上からメールを消します。
+書きこみ、サーバ上からメールを消します。pop3.server.address は適宜
-pop3.server.address は適宜読みかえてください。
+読みかえてください。
 
     require 'net/pop'
 
-    Net::POP3.start( 'pop3.server.address', 110,
+    pop = Net::POP3.new( 'pop3.server.address', 110 )
-                     'YourAccount', 'YourPassword' ) {|pop|
+    pop.start( 'YourAccount', 'YourPassword' )          ###
     if pop.mails.empty? then
       puts 'no mail.'
     else
@@ -31,15 +31,50 @@ pop3.server.address
         m.delete
         i += 1
       end
-      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
@@ -58,6 +93,7 @@ pop3.server.address
 クラスメソッドの POP3.delete_all を使うとさらに短くなります。
 
     require 'net/pop'
+
     i = 0
     Net::POP3.delete_all( 'pop3.server.address', 110,
                           'YourAccount', 'YourPassword' ) do |m|
@@ -119,12 +155,12 @@ APOP ǧ
     password で POP ログインします。第二引数 port に nil を渡すと
     POP3 のデフォルトポート(110)を使います。
 
-        Net::POP3.start( addr, port, account, password ) do |pop|
+        Net::POP3.start( addr, port, account, password ) {|pop|
 	    pop.each_mail do |m|
 	      file.write m.pop
 	      m.delete
 	    end
-        end
+        }
 
 : foreach( address, port = 110, account, password ) {|mail| .... }
     POP セッションを開き、サーバ上のすべてのメールに対して繰り返します。
@@ -159,7 +195,7 @@ APOP ǧ
     POP before SMTP 専用です。
 
         # example
-        pop = Net::POP3.auth_only( 'your.pop3.server',
+        Net::POP3.auth_only( 'your.pop3.server',
                              nil,     # using default (110)
                              'YourAccount',
                              'YourPassword' )
@@ -249,9 +285,9 @@ POP
         # example
         allmails = nil
         POP3.start( 'your.pop3.server', 110,
-                    'YourAccount, 'YourPassword' ) do |pop|
+                    'YourAccount, 'YourPassword' ) {|pop|
             allmails = pop.mails.collect {|popmail| popmail.pop }
-        end
+        }
 
 : pop {|str| .... }
     メールの文字列を少しづつ読みこみ、順次ブロックに与えます。

doc/net/smtp.rd.ja

@@ -42,6 +42,27 @@ your.smtp.server
     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'
+    }
+
 === 文字列以外からの送信
 
 ひとつ上の例では文字列リテラル(ヒアドキュメント)を使って送信しましたが、

lib/net/http.rb

@@ -106,7 +106,7 @@ 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 )
+        response = http.request(req)
         print response.body
     }
 
@@ -158,10 +158,10 @@ 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|
+        proxy_class.start( 'www.ruby-lang.org' ) {|http|
             # connecting proxy.foo.org:8080
                         :
-        end
+        }
 
 : proxy_class?
     If self is HTTP, false.

lib/net/pop.rb

@@ -29,8 +29,8 @@ Replace 'pop3.server.address' your POP3 server address.
 
     require 'net/pop'
 
-    Net::POP3.start( 'pop3.server.address', 110,
+    pop = Net::POP3.new( 'pop3.server.address', 110 )
-                     'YourAccount', 'YourPassword' ) {|pop|
+    pop.start( 'YourAccount', 'YourPassword' )          ###
     if pop.mails.empty? then
       puts 'no mail.'
     else
@@ -42,13 +42,44 @@ Replace 'pop3.server.address' your POP3 server address.
         m.delete
         i += 1
       end
-      end
       puts "#{pop.mails.size} mails popped."
-    }
+    end
+    pop.finish                                           ###
 
-=== Shorter Version
+(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
+    }
+
+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
@@ -67,6 +98,7 @@ Replace 'pop3.server.address' your POP3 server address.
 And here is more shorter example.
 
     require 'net/pop'
+
     i = 0
     Net::POP3.delete_all( 'pop3.server.address', 110,
                           'YourAccount', 'YourPassword' ) do |m|
@@ -123,12 +155,12 @@ 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|
+        Net::POP3.start( addr, port, account, password ) {|pop|
 	    pop.each_mail do |m|
 	      file.write m.pop
 	      m.delete
 	    end
-        end
+        }
 
 : foreach( address, port = 110, account, password ) {|mail| .... }
     starts POP3 protocol and iterates for each POPMail object.
@@ -163,7 +195,7 @@ 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',
+        Net::POP3.auth_only( 'your.pop3.server',
                              nil,     # using default (110)
                              'YourAccount',
                              'YourPassword' )
@@ -253,9 +285,9 @@ A class of mail which exists on POP server.
         # example
         allmails = nil
         POP3.start( 'your.pop3.server', 110,
-                    'YourAccount, 'YourPassword' ) do |pop|
+                    'YourAccount, 'YourPassword' ) {|pop|
             allmails = pop.mails.collect {|popmail| popmail.pop }
-        end
+        }
 
 : pop {|str| .... }
     gives the block part strings of a mail.

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

lib/net/smtp.rb

@@ -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).