aamine

* lib/net/protocol.rb: Protocol#start returns the return value of block.
* lib/net/protocol.rb: set timeout limit by default.
* lib/net/protocol.rb: new methods WriteAdapter#write, puts, print, printf.
* lib/net/protocol.rb: change template method scheme.
* lib/net/http.rb: rename HTTP#get2 to request_get, post2 to request_post ...
* lib/net/pop.rb: POP#auth_only did not work.
* lib/net/smtp.rb: should not resolve HELO domain automatically.


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

3 files changed, 72 insertions, 60 deletions

diff --git a/doc/net/http.rd.ja b/doc/net/http.rd.ja
index 0041e4155d..6b1555a8dd 100644
--- a/doc/net/http.rd.ja
+++ b/doc/net/http.rd.ja
@@ -1,6 +1,6 @@
 =begin
 
-= net/http.rb version 1.1.37
+= net/http.rb
 
 == このライブラリについて
 
@@ -204,15 +204,16 @@ Ruby 1.6 に入っているのが http.rb 1.1 で 1.7 以降が 1.2 ですが、
     プロクシ経由で接続する HTTP オブジェクトならプロクシのポート。
     そうでないなら nil。
 
-: get( path, header = nil, dest = '' )
+: get( path, header = nil )
 : get( path, header = nil ) {|str| .... }
-    サーバ上の path にあるエンティティを取得し、dest に << メソッドを
-    使って書きこみます。また header が nil でなければリクエストを送る
-    ときにその内容を HTTP ヘッダとして書きこみます。header はハッシュで、
-    「ヘッダ名 => 内容」のような形式でなければいけません。
+    サーバ上の path にあるエンティティを取得します。また header が nil
+    でなければ、リクエストを送るときにその内容を HTTP ヘッダとして書き
+    こみます。header はハッシュで、「ヘッダ名 => 内容」のような形式で
+    なければいけません。
 
-    返り値は、バージョン 1.1 では HTTPResponse と dest 二要素の配列です。
-    1.2 では HTTPResponse ただひとつのみです。
+    返り値は、バージョン 1.1 では HTTPResponse とエンティティボディ文字列の
+    二要素の配列です。1.2 では HTTPResponse ただひとつのみです。この場合、
+    エンティティボディは response.body で得られます。
 
     ブロックとともに呼ばれた時はエンティティボディを少しづつブロックに
     与えます。
@@ -237,10 +238,6 @@ Ruby 1.6 に入っているのが http.rb 1.1 で 1.7 以降が 1.2 ですが、
               f.write str
             end
         }
-        # same effect
-        File.open( 'save.txt', 'w' ) {|f|
-            http.get '/~foo/', nil, f
-        }
 
 : head( path, header = nil )
     サーバ上の path にあるエンティティのヘッダのみを取得します。
@@ -260,7 +257,7 @@ Ruby 1.6 に入っているのが http.rb 1.1 で 1.7 以降が 1.2 ですが、
         }
         p response['content-type']
 
-: post( path, data, header = nil, dest = '' )
+: post( path, data, header = nil )
 : post( path, data, header = nil ) {|str| .... }
     サーバ上の path にあるエンティティに対し文字列 data を
     送ります。レスポンスは << メソッドを使って dest に書き
@@ -275,55 +272,54 @@ Ruby 1.6 に入っているのが http.rb 1.1 で 1.7 以降が 1.2 ですが、
     一方 1.2 では全く例外を発生しません。
 
         # version 1.1
-        response, body = http.post( '/cgi-bin/search.rb', 'querytype=subject&target=ruby' )
+        response, body = http.post( '/cgi-bin/search.rb', 'query=subject&target=ruby' )
+
         # version 1.2
-        response = http.post( '/cgi-bin/search.rb', 'querytype=subject&target=ruby' )
-        # compatible for both version
-        response , = http.post( '/cgi-bin/search.rb', 'querytype=subject&target=ruby' )
+        response = http.post( '/cgi-bin/search.rb', 'query=subject&target=ruby' )
+
+        # compatible in both version
+        response , = http.post( '/cgi-bin/search.rb', 'query=subject&target=ruby' )
 
         # using block
         File.open( 'save.html', 'w' ) {|f|
-            http.post( '/cgi-bin/search.rb', 'querytype=subject&target=ruby' ) do |str|
+            http.post( '/cgi-bin/search.rb',
+                       'query=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
-        }
 
-: get2( path, header = nil )
-: get2( path, header = nil ) {|response| .... }
+: request_get( path, header = nil )
+: request_get( path, header = nil ) {|response| .... }
     path にあるエンティティを取得します。HTTPResponse
     オブジェクトを返します。
 
     ブロックとともに呼び出されたときは、ブロック実行中は接続を
     維持したまま HTTPResponse オブジェクトをブロックに渡します。
 
-    このメソッドはステータスに関らず例外を発生させません。
+    このメソッドは HTTP プロトコルに関連した例外は発生させません。
 
         # example
-        response = http.get2( '/index.html' )
+        response = http.request_get( '/index.html' )
         p response['content-type']
         puts response.body          # body is already read
 
         # using block
-        http.get2( '/index.html' ) {|response|
+        http.request_get( '/index.html' ) {|response|
             p response['content-type']
             response.read_body do |str|   # read body now
               print str
             end
         }
 
-: post2( path, header = nil )
-: post2( path, header = nil ) {|response| .... }
+: request_post( path, data, header = nil )
+: request_post( path, data, header = nil ) {|response| .... }
     path にあるエンティティを取得します。HTTPResponse
     オブジェクトを返します。
 
     ブロックとともに呼び出されたときは、ボディを読みこむ前に
     HTTPResponse オブジェクトをブロックに渡します。
 
-    このメソッドはステータスに関らず例外を発生させません。
+    このメソッドは HTTP プロトコルに関連した例外は発生させません。
 
         # example
         response = http.post2( '/cgi-bin/nice.rb', 'datadatadata...' )
diff --git a/doc/net/pop.rd.ja b/doc/net/pop.rd.ja
index 67510183b1..2c7e22f29f 100644
--- a/doc/net/pop.rd.ja
+++ b/doc/net/pop.rd.ja
@@ -1,6 +1,6 @@
 =begin
 
-= net/pop.rb version 1.1.37
+= net/pop.rb
 
 == このライブラリについて
 
@@ -120,27 +120,21 @@ POP3#delete_all を使うとさらに #each_mail と m.delete を
 
 === APOP
 
-APOP 認証を使うには
-(1) POP3 クラスのかわりに APOP クラスを使う
-(2) POP3.start の第五引数に true を渡す
-の二通りの方法があります。
+Net::POP3 クラスのかわりに Net::APOP クラスを使うと、認証時に APOP を
+使うようになります。また動的にノーマル POP と APOP を選択するには、
+以下のように Net::POP3.APOP() メソッドを使うのが便利です。
 
-    # (1)
     require 'net/pop'
-    Net::APOP.start( 'apop.server.address', 110,
-                     'YourAccount', 'YourPassword' ) {|pop|
-        # Rest code is same.
-    }
 
-    # (2)
-    require 'net/pop'
-    Net::POP3.start( 'apop.server.address', 110,
-                     'YourAccount', 'YourPassword',
-                     true   ####
-    ) {|pop|
+    # use APOP authentication if $isapop == true
+    pop = Net::POP3.APOP($isapop).new( 'apop.server.address', 110 )
+    pop.start( YourAccount', 'YourPassword' ) {|pop|
         # Rest code is same.
     }
 
+この方法はクラス自体を変えるので、クラスメソッドの start や foreach、
+delete_all、auth_only なども APOP とともに使えます。
+
 == Net::POP3 class
 
 === クラスメソッド
@@ -162,6 +156,18 @@ APOP 認証を使うには
 	    end
         }
 
+: APOP( is_apop )
+    bool が真なら Net::APOP クラス、偽なら Net::POP3 クラスを返します。
+    以下の例のように使ってください。
+
+        # example 1
+        pop = Net::POP3::APOP($isapop).new( addr, port )
+
+        # example 2
+        Net::POP3::APOP($isapop).start( addr, port ) {|pop|
+            ....
+        }
+
 : foreach( address, port = 110, account, password ) {|mail| .... }
     POP セッションを開き、サーバ上のすべてのメールに対して繰り返します。
     以下と同じです。
diff --git a/doc/net/smtp.rd.ja b/doc/net/smtp.rd.ja
index 7b4073ca62..cc87865dc7 100644
--- a/doc/net/smtp.rd.ja
+++ b/doc/net/smtp.rd.ja
@@ -1,6 +1,6 @@
 =begin
 
-= net/smtp.rb version 1.1.37
+= net/smtp.rb
 
 == このライブラリについて
 
@@ -76,17 +76,25 @@ each メソッドを持ったオブジェクトからならなんでも送ることができます。
         }
     }
 
-=== Hello ドメイン
+=== HELO ドメイン
 
-SMTP ではメールを送る側のホストの名前を要求されるのですが、
-ダイヤルアップなどの場合には自分のマシンに正式な名前がない場合が
-あります。そのような場合は適宜 SMTP サーバの名前などを与えてやら
-ないと配送を拒否されることがあります。SMTP.start あるいは SMTP#start
-の引数 helo_domain がそれです。
+SMTP ではメールを送る側のホストの名前 (HELO ドメインと呼ぶ) を要求
+されるのですが、Net::SMTP ではとりあえず localhost.localdomain と
+いう名前を送信しています。たいていの SMTP サーバはこの HELO ドメイン
+による認証はあまり真面目に行わないので (簡単に偽造できるからです)
+問題にならないことが多いのですが、まれにメールセッションを切られる
+こともあります。そういうときはとりあえず HELO ドメインを与えてみて
+ください。もちろんそれ以外の時も HELO ドメインはちゃんと渡すのが
+ベストです。
+
+HELO ドメインは SMTP.start/SMTP#start の第三引数 helo_domain に指定
+します。
 
     Net::SMTP.start( 'your.smtp.server', 25,
                      'mail.from.domain' ) {|smtp|
 
+よくあるダイヤルアップホストの場合、HELO ドメインには ISP のメール
+サーバのドメインを使っておけばたいてい通ります。
 
 == class Net::SMTP
 
@@ -96,8 +104,8 @@ SMTP ではメールを送る側のホストの名前を要求されるのですが、
     新しい SMTP オブジェクトを生成します。address はSMTPサーバーのFQDNで、
     port は接続するポート番号です。ただし、このメソッドではまだ接続はしません。
 
-: start( address, port = 25, helo_domain = Socket.gethostname, account = nil, password = nil, authtype = nil )
-: start( address, port = 25, helo_domain = Socket.gethostname, account = nil, password = nil, authtype = nil ) {|smtp| .... }
+: start( address, port = 25, helo_domain = 'localhost.localdomain', account = nil, password = nil, authtype = nil )
+: start( address, port = 25, helo_domain = 'localhost.localdomain', account = nil, password = nil, authtype = nil ) {|smtp| .... }
     以下と同じです。
         Net::SMTP.new(address,port).start(helo_domain,account,password,authtype)
 
@@ -161,11 +169,13 @@ 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' ) {|f|
+                f.puts 'From: aamine@loveruby.net'
+                f.puts 'To: someone@somedomain.org'
+                f.puts 'Subject: test mail'
+                f.puts
+                f.puts 'This is test mail.'
+	    }
         }
 
 == 発生する例外