add doc/net/http.rd.ja pop.rd.ja smtp.rd.ja

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

3 files changed, 882 insertions, 0 deletions

diff --git a/doc/net/http.rd.ja b/doc/net/http.rd.ja
new file mode 100644
index 0000000000..08447b10d6
--- /dev/null
+++ b/doc/net/http.rd.ja
@@ -0,0 +1,435 @@
+=begin
+
+= net/http.rb version 1.2.3
+
+== このライブラリについて
+
+汎用データ転送プロトコル HTTP を扱うライブラリです。
+実装は [RFC2616] ((<URL:http://www.ietf.org/rfc/rfc2616.txt>)) に
+基いています。
+
+== 使用例
+
+=== ウェブサーバからドキュメントを得る (GET)
+
+    require 'net/http'
+    Net::HTTP.start( 'some.www.server', 80 ) {|http|
+      response , = http.get('/index.html')
+      puts response.body
+    }
+
+また以下は同じ意味で短く書いたものです。
+
+    require 'net/http'
+    Net::HTTP.get_print 'some.www.server', '/index.html'
+
+=== フォームの情報を送信する (POST)
+
+    require 'net/http'
+    Net::HTTP.start( 'some.www.server', 80 ) {|http|
+      response , = http.post( '/cgi-bin/any.rhtml',
+                              'querytype=subject&target=ruby' )
+    }
+
+=== プロクシ経由のアクセス
+
+Net::HTTP のクラスメソッド Net::HTTP.Proxy は、常にプロクシ経由で
+接続するような動作をする、新しいクラスを作成して返します。このクラスは
+Net::HTTP を継承しているので Net::HTTP と全く同じように使えます。
+
+    require 'net/http'
+
+    $proxy_addr = 'your.proxy.addr'
+    $proxy_port = 8080
+          :
+    Net::HTTP::Proxy($proxy_addr, $proxy_port).start( 'some.www.server' ) {|http|
+      # always connect to your.proxy.addr:8080
+          :
+    }
+
+また Net::HTTP.Proxy は第一引数が nil だと Net::HTTP 自身を返すので
+上のコードのように書いておけばプロクシなしの場合にも対応できます。
+
+=== リダイレクトに対応する
+
+    require 'net/http'
+    Net::HTTP.version_1_1
+
+    host = 'www.ruby-lang.org'
+    path = '/'
+    begin
+      Net::HTTP.start( host, 80 ) {|http|
+	response , = http.get(path)
+        print response.body
+      }
+    rescue Net::ProtoRetriableError => err
+      if m = %r<http://([^/]+)>.match( err.response['location'] ) then
+	host = m[1].strip
+	path = m.post_match
+	retry
+      end
+    end
+
+この例では URL からホスト名を得るのにいいかげんな方法を使っていますが、
+将来 URI クラスが標準添付になればもっと簡単になるはずです。
+
+=== Basic 認証
+
+    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
+    }
+
+バージョン 1.2 (Ruby 1.7 以降に添付) では次のように書けます。
+
+    require '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
+    }
+
+== 新しい仕様への変更と移行措置について
+
+Ruby 1.6 に入っているのが http.rb 1.1 で 1.7 以降が 1.2 ですが、
+この間ではかなり大きく仕様が変わります。そこで突然に仕様を変更
+するのでなく、両方の実装を並存させる時期を設けることにしました。
+
+メソッド HTTP.version_1_2、HTTP.version_1_1 を呼ぶと
+そのあとに生成される Net::HTTP オブジェクトはそれぞれの
+バージョンの仕様で動作するようになります。以下は使用例です。
+
+    # example
+    Net::HTTP.start {|http1| ...(http1 has 1.2 features)... }
+
+    Net::HTTP.version_1_1
+    Net::HTTP.start {|http2| ...(http2 has 1.1 features)... }
+
+    Net::HTTP.version_1_2
+    Net::HTTP.start {|http3| ...(http3 has 1.2 features)... }
+
+この機能はスレッドセーフではありません。
+
+== class Net::HTTP
+
+=== クラスメソッド
+
+: new( address = 'localhost', port = 80, proxy_addr = nil, proxy_port = nil )
+    新しい HTTP オブジェクトを生成します。address は HTTP サーバーの FQDN で、
+    port は接続するポート番号です。このメソッドではまだ接続はしません。
+
+    proxy_addr を与えるとプロクシを介して接続するオブジェクトを生成します。
+
+: start( address = 'localhost', port = 80, proxy_addr = nil, proxy_port = nil )
+: start( address = 'localhost', port = 80, proxy_addr = nil, proxy_port = nil ) {|http| .... }
+    以下と同じです。
+
+        Net::HTTP.new(address, port, proxy_addr, proxy_port).start(&block)
+
+: get( address, path, port = 80 )
+    ホスト address の port 番ポートに接続して path の表現する
+    エンティティを取得、文字列で返します。
+
+: get_print( address, path, port = 80 )
+    ホスト address の port 番ポートに接続して path の表現する
+    エンティティを取得したうえ、$stdout に << で出力します。
+
+: Proxy( address, port = 80 )
+    常に指定されたプロクシに接続するクラスを作成し返します。
+    このクラスは Net::HTTP を継承しているので Net::HTTP と全く
+    同じように使えます。
+
+    address が nil のときは Net::HTTP クラスをそのまま返します。
+
+        # 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?
+    自身が (Proxy メソッドによって作成された) プロクシ用のクラスならば真。
+
+: port
+    HTTP のデフォルトポート (80)。
+
+=== メソッド
+
+: start
+: start {|http| .... }
+    TCP コネクションを張り、HTTP セッションを開始します。
+    すでにセッションが開始していたら例外 IOError を発生します。
+
+    イテレータとして呼ばれた時はブロックの間だけセッションを接続し、
+    ブロック終了とともに自動的にセッションを閉じます。
+
+: active?
+    HTTP セッションが開始されていたら真。
+
+: address
+    接続するアドレス
+
+: port
+    接続するポート番号
+
+: open_timeout
+: open_timeout=(n)
+    接続時に待つ最大秒数。この秒数たってもコネクションが
+    開かなければ例外 TimeoutError を発生します。
+
+: read_timeout
+: read_timeout=(n)
+    読みこみ (read(1) 一回) でブロックしてよい最大秒数。
+    この秒数たっても読みこめなければ例外 TimeoutError を発生します。
+
+: finish
+    HTTP セッションを終了します。セッション開始前にこのメソッドが
+    呼ばれた場合は例外 IOError を発生します。
+
+: proxy?
+    プロクシを介して接続するなら真。
+
+: proxy_address
+    プロクシ経由で接続する HTTP オブジェクトならプロクシのアドレス。
+    そうでないなら nil。
+
+: proxy_port
+    プロクシ経由で接続する HTTP オブジェクトならプロクシのポート。
+    そうでないなら nil。
+
+: get( path, header = nil, dest = '' )
+: get( path, header = nil ) {|str| .... }
+    サーバ上の path にあるエンティティを取得し、dest に << メソッドを
+    使って書きこみます。また header が nil でなければリクエストを送る
+    ときにその内容を HTTP ヘッダとして書きこみます。header はハッシュで、
+    「ヘッダ名 => 内容」のような形式でなければいけません。
+
+    返り値は、バージョン 1.1 では HTTPResponse と dest 二要素の配列です。
+    1.2 では HTTPResponse ただひとつのみです。
+
+    ブロックとともに呼ばれた時はエンティティボディを少しづつブロックに
+    与えます。
+
+    1.1 では 3xx (再試行可能なエラー)に対しても例外を発生します。この場合
+    HTTPResponse は例外オブジェクトから err.response で得ることができます。
+    一方 1.2 では全く例外を発生しません。
+
+        # version 1.1 (bundled with Ruby 1.6)
+        response, body = http.get( '/index.html' )
+
+        # version 1.2 (bundled with Ruby 1.7 or later)
+        response = http.get( '/index.html' )
+
+        # compatible in both version
+        response , = http.get( '/index.html' )
+        response.body
+        
+        # using block
+        File.open( 'save.txt', 'w' ) {|f|
+          http.get( '/~foo/', nil ) do |str|
+            f.write str
+          end
+        }
+        # same effect
+        File.open( 'save.txt', 'w' ) {|f|
+          http.get '/~foo/', nil, f
+        }
+
+: head( path, header = nil )
+    サーバ上の path にあるエンティティのヘッダのみを取得します。
+    また header が nil でなければリクエストを送るときにその内容を
+    HTTP ヘッダとして書きこみます。header はハッシュで、
+    「ヘッダ名 => 内容」のような形式でなければいけません。
+
+    HTTPResponse オブジェクトを返します。
+
+    1.1 では 3xx (再試行可能なエラー)に対しても例外を発生します。この場合
+    HTTPResponse は例外オブジェクトから err.response で得ることができます。
+    一方 1.2 では全く例外を発生しません。
+
+        response = nil
+        Net::HTTP.start( 'some.www.server', 80 ) {|http|
+          response = http.head( '/index.html' )
+        }
+        p response['content-type']
+
+: post( path, data, header = nil, dest = '' )
+: post( path, data, header = nil ) {|str| .... }
+    サーバ上の path にあるエンティティに対し文字列 data を
+    送ります。レスポンスは << メソッドを使って dest に書き
+    こまれます。header は get メソッドと同じです。
+    HTTPResponse オブジェクトと dest の配列を返します。
+
+    イテレータとして呼びだされたときはエンティティボディを少しづつ
+    ブロックに与えます。
+
+    1.1 では 3xx (再試行可能なエラー)に対しても例外を発生します。この場合
+    HTTPResponse は例外オブジェクトから err.response で得ることができます。
+    一方 1.2 では全く例外を発生しません。
+
+        # version 1.1
+        response, body = http.post( '/cgi-bin/search.rb', 'querytype=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' )
+
+        # using block
+        File.open( 'save.html', 'w' ) {|f|
+          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
+        }
+
+: get2( path, header = nil )
+: get2( path, header = nil ) {|response| .... }
+    path にあるエンティティを取得します。HTTPResponse
+    オブジェクトを返します。
+
+    ブロックとともに呼び出されたときは、ブロック実行中は接続を
+    維持したまま HTTPResponse オブジェクトをブロックに渡します。
+
+    このメソッドはステータスに関らず例外を発生させません。
+
+        # example
+        response = http.get2( '/index.html' )
+        p response['content-type']
+        puts response.body          # body is already read
+
+        # using block
+        http.get2( '/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| .... }
+    path にあるエンティティを取得します。HTTPResponse
+    オブジェクトを返します。
+
+    ブロックとともに呼び出されたときは、ボディを読みこむ前に
+    HTTPResponse オブジェクトをブロックに渡します。
+
+    このメソッドはステータスに関らず例外を発生させません。
+
+        # example
+        response = http.post2( '/cgi-bin/nice.rb', 'datadatadata...' )
+        p response.status
+        puts response.body          # body is already read
+
+        # 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
+        }
+
+: request( request [, data] )
+: request( request [, data] ) {|response| .... }
+    リクエストオブジェクト request を送信します。POST の時は data も
+    与えられます。(POST 以外で data を与えると ArgumentError を発生します)
+
+    ブロックとともに呼びだされたときはボディを読みこまずに HTTPResponse
+    オブジェクトをブロックに与えます。
+
+== class Net::HTTP::Get, Head, Post
+
+HTTP リクエストを抽象化するクラス。key はすべて大文字小文字を
+区別しません。
+
+=== クラスメソッド
+
+: new
+    HTTP リクエストオブジェクトを生成します。
+
+=== メソッド
+
+: self[ key ]
+    key ヘッダフィールドの文字列。
+    key は大文字小文字を区別しません。
+
+: self[ key ] = val
+    key ヘッダフィールドに val をセットします。
+    key は大文字小文字を区別しません。
+
+: each {|name, val| .... }
+    ヘッダ名とその値に対するくりかえし。ヘッダ名は小文字で統一されます。
+
+: basic_auth( account, password )
+    Authrization: ヘッダを basic auth 用にセットします。
+
+: range
+    Range: ヘッダの示す範囲を Range オブジェクトで返します。
+
+: range = r
+: set_range( i, len )
+    範囲を指定してエンティティを取得するためのヘッダ Range: をセットします。
+    r は Range オブジェクト、i, len は始点と長さです。
+
+: content_length
+    Content-Length: ヘッダの値 (整数)。
+
+: content_range
+    Content-Range: ヘッダの値 (Range)。
+
+== class Net::HTTPResponse
+
+HTTP レスポンスのクラスです。
+引数がヘッダフィールド名である場合、大文字小文字を区別しません。
+
+=== メソッド
+
+: self[ key ]
+    key ヘッダフィールド(文字列)です。たとえばキー 'content-length'
+    に対しては '2048' のような文字列が得られます。
+    key は大文字小文字を区別しません。
+
+: self[ key ] = val
+    key ヘッダフィールドを value に設定します。
+    key は大文字小文字を区別しません。
+
+: key?( key )
+    key というヘッダフィールドがあれば真。
+    key は大文字小文字を区別しません。
+
+: each {|name,value| .... }
+    すべてのヘッダフィールド名とその値のペアに対するくりかえし。
+
+: canonical_each {|name,value| .... }
+    ヘッダフィールドの正式名とその値のペアに対して繰り返します。
+
+: code
+    HTTP のリザルトコードです。例えば '302' などです。
+
+: message
+    HTTP サーバがリザルトコードに付加して返すメッセージです。
+    例えば 'Not Found' などです。
+
+: read_body( dest = '' )
+    エンティティボディを取得し dest に << メソッドを使って書きこみます。
+    同じ HTTPResponse オブジェクトに対して二回以上呼ばれた場合、
+    二回目からはなにもせずに一回目の返り値をそのまま返します。
+
+: read_body {|str| .... }
+    エンティティボディを少しづつ取得して順次ブロックに与えます。
+
+: body
+    エンティティボディです。read_body を呼んでいればその引数 dest、
+    呼んでいなければエンティティボディを文字列として読みこんで返します。
+
+=end
diff --git a/doc/net/pop.rd.ja b/doc/net/pop.rd.ja
new file mode 100644
index 0000000000..a810e1e92a
--- /dev/null
+++ b/doc/net/pop.rd.ja
@@ -0,0 +1,284 @@
+=begin
+
+= net/pop.rb version 1.2.3
+
+== このライブラリについて
+
+メールを受信するためのプロトコル POP3 (Post Office Protocol version 3) を
+を扱うライブラリです。POP3 の実装は [RFC1939]
+((<URL:http://www.ietf.org/rfc/rfc1939.txt>)) に基いています。
+
+== 使用例
+
+=== メールの受信
+
+メールを受信してファイル '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|
+            f.write m.pop
+          }
+          m.delete
+          i += 1
+        end
+      end
+      puts "#{pop.mails.size} mails popped."
+    }
+
+=== 短くする
+
+以下は動作は同じでコードを短くしたバージョンです。
+
+    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
+    }
+
+クラスメソッドの 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
+      }
+      i += 1
+    end
+
+=== ファイルに直接書く
+
+これまでの例では m.pop の部分でメールをひとつの文字列として
+うけとっていましたが、たとえば 3MB くらいある巨大なメールの場合は
+これではまずい場合があります。そのような場合は以下のように m.pop
+に File オブジェクトを与える手が使えます。
+
+    require 'net/pop'
+    Net::POP3.delete_all( 'pop3.server.address', 110,
+                          'YourAccount', 'YourPassword' ) do |m|
+      File.open( 'inbox', 'w' ) {|f|
+        m.pop f   ####
+      }
+    end
+
+=== APOP
+
+APOP 認証を使うには
+(1) POP3 クラスのかわりに APOP クラスを使う
+(2) POP3.start の第五引数に true を渡す
+の二通りの方法があります。
+
+    # (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|
+      # Rest code is same.
+    }
+
+== Net::POP3 class
+
+=== クラスメソッド
+
+: new( address = 'localhost', port = 110, apop = false )
+    Net::POP3 オブジェクトを生成します。まだ接続はしません。
+    apop が真のときは APOP 認証を行うオブジェクトを生成します。
+
+: start( address = 'localhost', port = 110, account, password )
+: start( address = 'localhost', port = 110, account, password ) {|pop| .... }
+    address の port 番ポートに接続し、アカウント account パスワード
+    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
+
+: foreach( address = 'localhost', port = 110, account, password ) {|mail| .... }
+    POP セッションを開き、サーバ上のすべてのメールに対して繰り返します。
+    以下と同じです。
+
+        Net::POP3.start( address, port, account, password ) {|pop|
+          pop.each_mail do |m|
+            yield m
+          end
+        }
+
+        # example
+        Net::POP3.foreach( 'your.pop.server', 110,
+                           'YourAccount', 'YourPassword' ) do |m|
+          file.write m.pop
+          m.delete if $DELETE
+        end
+
+: delete_all( address = 'localhost', port = 110, account, password )
+: delete_all( address = 'localhost', port = 110, account, password ) {|mail| .... }
+    POP セッションを開き、サーバ上のメールをすべて削除します。
+    ブロックが与えられた時は削除する前にブロックにそのメールを
+    渡します。以下と同じです。
+
+        # example
+        Net::POP3.delete_all( addr, nil, 'YourAccount', 'YourPassword' ) do |m|
+          m.pop file
+        end
+
+: auth_only( address = 'localhost', port = 110, account, password )
+    POP セッションを開き認証だけを行って接続を切ります。
+    POP before SMTP 専用です。
+
+        # example
+        pop = Net::POP3.auth_only( 'your.pop3.server',
+                                    nil,     # using default (110)
+                                   'YourAccount',
+                                   'YourPassword' )
+
+=== メソッド
+
+: start( account, password )
+: start( account, password ) {|pop| .... }
+    リモートホストとの接続を開始し、アカウントに account、
+    パスワードに password を使って POP ログインします。
+
+: active?
+    POP3 セッションが開始されていたら真。
+
+: address
+    接続するアドレス
+
+: port
+    接続するポート番号
+
+: open_timeout
+: open_timeout=(n)
+    接続時に待つ最大秒数。この秒数たってもコネクションが
+    開かなければ例外 TimeoutError を発生します。
+
+: read_timeout
+: read_timeout=(n)
+    読みこみ (read(1) 一回) でブロックしてよい最大秒数。
+    この秒数たっても読みこめなければ例外 TimeoutError を発生します。
+
+: finish
+    POP3 セッションを終了します。セッション開始前にこのメソッドが
+    呼ばれた場合は例外 IOError を発生します。
+
+: mails
+    Net::POPMail オブジェクトの配列をかえします。
+    この配列はセッションを開始したときに自動的に更新されます。
+
+: each_mail {|popmail| .... }
+: each {|popmail| .... }
+    pop3.mails.each と同じです。
+
+: delete_all
+: delete_all {|popmail| .... }
+    サーバ上のメールを全て消去します。
+    ブロックを与えられたときは消去する前にその POPMail オブジェクトを
+    ブロックに渡します。
+
+        # example
+        n = 1
+        pop.delete_all do |m|
+          File.open("inbox/#{n}") {|f| f.write m.pop }
+          n += 1
+        end
+
+: auth_only( account, password )
+    POP セッションを開き認証だけを行って接続を切ります。
+    POP before SMTP 専用です。
+        # example
+        pop = Net::POP3.new( 'your.pop3.server' )
+        pop.auth_only 'YourAccount', 'YourPassword'
+
+: reset
+    セッションをリセットします。
+    具体的には POPMail#delete で消したメールが全て復活します。
+    (POP3 ではメール一個だけを復活する方法はありません)
+
+== Net::APOP
+
+このクラスでは新しいメソッドは導入していません。
+認証方式が APOP に変わるだけです。
+
+=== スーパークラス
+Net::POP3
+
+== Net::POPMail
+
+POP サーバー上のメール一通を抽象的に表現するクラス。
+メールの取得や消去といった操作をカプセル化します。
+
+=== メソッド
+
+: pop( dest = '' )
+    メールを受信して dest に << メソッドを使って書きこみます。
+    dest を返します。
+
+        # example
+        allmails = nil
+        POP3.start( 'your.pop3.server', 110,
+                    'YourAccount, 'YourPassword' ) do |pop|
+          allmails = pop.mails.collect {|popmail| popmail.pop }
+        end
+
+: pop {|str| .... }
+    メールの文字列を少しづつ読みこみ、順次ブロックに与えます。
+
+        # example
+        POP3.start( 'localhost', 110 ) {|pop3|
+          pop3.each_mail do |m|
+            m.pop do |str|
+              # do anything
+            end
+          end
+        }
+
+: header
+    ヘッダだけを受信して文字列で返します。
+
+: top( lines )
+    メールヘッダと lines 行ぶんの本文を取得し文字列で返します。
+
+: delete
+    サーバ上からメールを削除します。
+
+: size
+    メールのサイズ (単位はバイト) をかえします。
+
+: deleted?
+    メールがサーバ上で消去されているとき真。消去してしまったら
+    POP3#reset を使う以外に復活する方法はありません。
+
+=end
diff --git a/doc/net/smtp.rd.ja b/doc/net/smtp.rd.ja
new file mode 100644
index 0000000000..16fa5d598d
--- /dev/null
+++ b/doc/net/smtp.rd.ja
@@ -0,0 +1,163 @@
+=begin
+
+= net/smtp.rb version 1.2.3
+
+== このライブラリについて
+
+メールを送信するためのプロトコル SMTP (Simple Mail Transfer Protocol)
+を扱うライブラリです。ヘッダなどメールのデータを扱うことはできません。
+SMTP の実装は [RFC2821] ((<URL:http://www.ietf.org/rfc/rfc2821.txt>))
+に基いています。
+
+== 使用例
+
+=== とにかくメールを送る
+
+SMTP を使ってメールを送るにはまず SMTP.start でセッションを開きます。
+第一引数がサーバのアドレスで第二引数がポート番号です。
+ブロックを使うと File.open と同じように終端処理を自動的にやってくれる
+のでおすすめです。
+
+    require 'net/smtp'
+    Net::SMTP.start( 'your.smtp.server', 25 ) {|smtp|
+      # use smtp object only in this block
+    }
+
+your.smtp.server は適切な SMTP サーバのアドレスに読みかえてください。
+通常は LAN の管理者やプロバイダが SMTP サーバを用意してくれているはずです。
+
+セッションが開いたらあとは send_mail でメールを流しこむだけです。
+
+    require 'net/smtp'
+
+    Net::SMTP.start( 'your.smtp.server', 25 ) {|smtp|
+      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
+    Date: Sat, 23 Jun 2001 16:26:43 +0900
+    Message-Id: <unique.message.id.string@some.domain>
+
+    This is test mail.
+    EndOfMail
+    }
+
+=== 文字列以外からの送信
+
+ひとつ上の例では文字列リテラル(ヒアドキュメント)を使って送信しましたが、
+each メソッドを持ったオブジェクトからならなんでも送ることができます。
+以下は File オブジェクトから直接送信する例です。
+
+    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'
+      }
+    }
+
+=== Hello ドメイン
+
+SMTP ではメールを送る側のホストの名前を要求されるのですが、
+ダイヤルアップなどの場合には自分のマシンに正式な名前がない場合が
+あります。そのような場合は適宜 SMTP サーバの名前などを与えてやら
+ないと配送を拒否されることがあります。SMTP.start あるいは SMTP#start
+の引数 helo_domain がそれです。
+
+    Net::SMTP.start( 'your.smtp.server', 25,
+                     'mail.from.domain' ) {|smtp|
+
+
+== class Net::SMTP
+
+=== クラスメソッド
+
+: new( address = 'localhost', port = 25 )
+    新しい SMTP オブジェクトを生成します。address はSMTPサーバーのFQDNで、
+    port は接続するポート番号です。ただし、このメソッドではまだ接続はしません。
+
+: start( address = 'localhost', port = 25, helo_domain = Socket.gethostname, account = nil, password = nil, authtype = nil )
+: start( address = 'localhost', port = 25, helo_domain = Socket.gethostname, account = nil, password = nil, authtype = nil ) {|smtp| .... }
+    以下と同じです。
+        Net::SMTP.new(address,port).start(helo_domain,account,password,authtype)
+
+        # example
+        Net::SMTP.start( 'your.smtp.server' ) {
+          smtp.send_mail mail_string, 'from@mail.address', 'dest@mail.address'
+        }
+
+=== メソッド
+
+: start( helo_domain = <local host name>, account = nil, password = nil, authtype = nil )
+: start( helo_domain = <local host name>, account = nil, password = nil, authtype = nil ) {|smtp| .... }
+    TCP コネクションを張り、同時に SMTP セッションを開始します。そのとき、
+    こちらのホストの FQDN を helo_domain に指定します。
+    もしすでにセッションが開始していたら IOError を発生します。
+
+    account と password の両方が与えられた場合、AUTH コマンドによって
+    認証を行います。authtype は使用する認証のタイプで、シンボル
+    で :plain か :cram_md5 を指定します。
+
+: active?
+    SMTP セッションが開始されていたら真。
+
+: address
+    接続するアドレス
+
+: port
+    接続するポート番号
+
+: open_timeout
+: open_timeout=(n)
+    接続時に待つ最大秒数。この秒数たってもコネクションが
+    開かなければ例外 TimeoutError を発生します。
+
+: read_timeout
+: read_timeout=(n)
+    読みこみ (read(1) 一回) でブロックしてよい最大秒数。
+    この秒数たっても読みこめなければ例外 TimeoutError を発生します。
+
+: finish
+    SMTP セッションを終了します。セッション開始前にこのメソッドが
+    呼ばれた場合は例外 IOError を発生します。
+
+: send_mail( mailsrc, from_addr, *to_addrs )
+    mailsrc をメールとして送信します。mailsrc は each イテレータを持つ
+    オブジェクトならなんでも構いません (たとえば String や File)。
+    from_domain は送り主のメールアドレス ('...@...'のかたちのもの) で、
+    to_addrs には送信先メールアドレスを並べます。
+
+        # example
+        Net::SMTP.start( 'your.smtp.server' ) {|smtp|
+          smtp.send_mail mail_string,
+                         'from@mail.address',
+                         'dest@mail.address' 'dest2@mail.address'
+        }
+
+: ready( from_addr, *to_addrs ) {|adapter| .... }
+    メール書きこみの準備をしたうえで、write メソッドを持つオブジェクトを
+    ブロックにあたえます。from_addr は送信元メールアドレスで to_addrs は
+    宛先のメールボックスです。
+
+        # 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 レベルの) エラーがおこった場合、
+以下の例外が発生します。
+: Net::ProtoSyntaxError
+    SMTP コマンドの構文ミス(500番台)
+: Net::ProtoFatalError
+    恒久的なエラー(550番台)
+: Net::ProtoUnknownError
+    予期しないエラー。おそらくバグ
+: Net::ProtoServerBusy
+    一時的なエラー(420/450番台)
+
+=end