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/http.rb: rename HTTP#get2 to request_get, post2 to request_post ...
* lib/net/smtp.rb: should not resolve HELO domain automatically.


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

2 files changed, 52 insertions, 44 deletions

diff --git a/doc/net/http.rd.ja b/doc/net/http.rd.ja
index 3de2c3611a..7569f98f72 100644
--- a/doc/net/http.rd.ja
+++ b/doc/net/http.rd.ja
@@ -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...' )
@@ -341,12 +337,14 @@ Ruby 1.6 に入っているのが http.rb 1.1 で 1.7 以降が 1.2 ですが、
 
 : request( request [, data] )
 : request( request [, data] ) {|response| .... }
-    リクエストオブジェクト request を送信します。POST の時は data も
-    与えられます。(POST 以外で data を与えると ArgumentError を発生します)
+    HTTPResquest オブジェクト request を送信します。POST/PUT の時は data も
+    与えられます (POST/PUT 以外で data を与えると ArgumentError を発生します)。
 
     ブロックとともに呼びだされたときはボディを読みこまずに HTTPResponse
     オブジェクトをブロックに与えます。
 
+    このメソッドは HTTP プロトコルに関連した例外は発生させません。
+
 == class Net::HTTP::Get, Head, Post
 
 HTTP リクエストを抽象化するクラス。key はすべて大文字小文字を
diff --git a/doc/net/smtp.rd.ja b/doc/net/smtp.rd.ja
index fee0acbd36..cc87865dc7 100644
--- a/doc/net/smtp.rd.ja
+++ b/doc/net/smtp.rd.ja
@@ -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.'
+	    }
         }
 
 == 発生する例外