* lib/net/http.rb: improve rdoc.

This change the order of chapter because such overview should begin with simple examples. ed by Eric Hodel [ruby-core:33469] git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@30001 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
author: naruse <naruse@b2dd03c8-39d4-4d8f-98ff-823fe69b080e> 2010-12-01 15:07:35 +0000
committer: naruse <naruse@b2dd03c8-39d4-4d8f-98ff-823fe69b080e> 2010-12-01 15:07:35 +0000
commit: 594633fbea10405b76101970d0ba54db18de49fd ()
tree: 052522500cc90f81db59b05113e6364570b71eb0
parent: 91d2ee737d599139a629d58d52e52cb4105d4772 (diff)
3 files changed, 296 insertions, 323 deletions
@@ -1,3 +1,10 @@
 Wed Dec 1 22:01:49 2010 NAKAMURA Usaku <[email protected]>
 * numeric.c (Init_Numeric): fixed a potential bug when using bccwin32
@@ -32,314 +32,350 @@ module Net #:nodoc:
 # == An HTTP client API for Ruby.
 #
- # For more details about HTTP, see [RFC2616](http://www.ietf.org/rfc/rfc2616.txt).
 #
- # == Examples
 #
- # === Fetching Documents
 #
- # Simple GET
 #
- # require 'net/http'
- # Net::HTTP.get('www.example.com', '/index.html') => String
 #
- # Simple GET by URI object
 #
- # require 'net/http'
- # require 'uri'
- # Net::HTTP.get(URI.parse('http://www.example.com/index.html?count=10')) => String
 #
- # More generic GET with dynamic parameters
 #
- # require 'net/http'
- # require 'uri'
 #
- # uri = URI.parse('http://www.example.com/index.html')
- # params = { :limit => 10, :page => 3 }
- # uri.query = URI.encode_www_form(params)
- # res = Net::HTTP.get_response(uri)
- # puts res.body if res.is_a?(Net::HTTPSuccess)
 #
- # Even more generic GET with Basic Auth and custom header
 #
- # require 'net/http'
 #
- # uri = URI.parse('http://www.example.com/index.html?key=value')
- # req = Net::HTTP::Get.new(uri.request_uri)
- # req.basic_auth 'user', 'pass'
- # req['X-Custom-Header'] = Time.now.to_i
- # res = Net::HTTP.start(uri.hostname, uri.port) {|http|
- # http.request(req)
- # }
- # puts res.body
 #
- # Accessing Response data:
 #
- # res = Net::HTTP.get_response(URI.parse('http://www.example.com/index.html'))
- # # Headers
- # res['Set-Cookie'] => String
- # res.get_fields('set-cookie') => Array
- # res.to_hash['set-cookie'] => Array
- # puts "Headers: #{res.to_hash.inspect}"
- # # Status
- # puts res.code => '200'
- # puts res.message => 'OK'
- # puts res.class.name => 'HTTPOK'
- # puts res.body
 #
- # === Posting Form Data
 #
- # require 'net/http'
- # require 'uri'
 #
- # #1: Simple POST
- # res = Net::HTTP.post_form(URI.parse('http://www.example.com/search.cgi'),
- # {'q' => 'ruby', 'max' => '50'})
- # puts res.body
 #
- # #2: Detailed control of POST with authentication
 #
- # uri = URI.parse('http://www.example.com/todo.cgi')
- # req = Net::HTTP::Post.new(uri.path)
- # req.basic_auth 'jack', 'pass'
- # req.set_form_data({'from' => '2005-01-01', 'to' => '2005-03-31'}, ';')
- # res = Net::HTTP.new(uri.hostname, uri.port).start {|http| http.request(req) }
- # case res
- # when Net::HTTPSuccess, Net::HTTPRedirection
- # # OK
- # else
- # res.error!
- # end
 #
- # #3: Multiple values
- # res = Net::HTTP.post_form(URI.parse('http://www.example.com/search.cgi'),
- # {'q' => ['ruby', 'perl'], 'max' => '50'})
- # puts res.body
 #
- # === Accessing via Proxy
 #
- # Net::HTTP.Proxy is an http proxy class. It has the same
- # methods as Net::HTTP, but its instances always connect via a proxy,
- # instead of directly to the given host.
 #
- # require 'net/http'
 #
- # proxy_addr = 'your.proxy.host'
- # proxy_port = 8080
- # :
- # Net::HTTP::Proxy(proxy_addr, proxy_port).start('www.example.com') {|http|
- # # always connect to your.proxy.addr:8080
- # :
- # }
 #
- # The top-level Net::HTTP class creates objects which represent
- # HTTP sessions.
 #
- # Since Net::HTTP.Proxy returns Net::HTTP itself when +proxy_addr+ is nil,
- # there's no need to change your code depending on whether there's a proxy
- # or not.
 #
- # There are two additional parameters in Net::HTTP.Proxy which allow you to
- # specify a user name and password for the proxy:
 #
- # Net::HTTP::Proxy(proxy_addr, proxy_port, proxy_user = nil, proxy_pass = nil)
 #
- # You can use them to work with authorization-enabled proxies:
 #
- # require 'net/http'
- # require 'uri'
 #
- # proxy_host = 'your.proxy.host'
- # proxy_port = 8080
- # uri = URI.parse(ENV['http_proxy'])
- # proxy_user, proxy_pass = uri.userinfo.split(/:/) if uri.userinfo
- # Net::HTTP::Proxy(proxy_host, proxy_port,
- # proxy_user, proxy_pass).start('www.example.com') {|http|
- # # always connect to your.proxy.addr:8080 using specified username and password
- # :
- # }
 #
- # Note that net/http does not use the HTTP_PROXY environment variable.
- # If you want to use a proxy, you must do so explicitly.
 #
 # === Following Redirection
 #
- # require 'net/http'
- # require 'uri'
 #
- # def fetch(uri_str, limit = 10)
- # # You should choose better exception.
- # raise ArgumentError, 'HTTP redirect too deep' if limit == 0
 #
- # response = Net::HTTP.get_response(URI.parse(uri_str))
- # case response
- # when Net::HTTPSuccess then response
- # when Net::HTTPRedirection then fetch(response['location'], limit - 1)
- # else
- # response.error!
- # end
 # end
 #
- # print fetch('http://www.ruby-lang.org')
 #
- # Net::HTTPSuccess and Net::HTTPRedirection are HTTPResponse subclasses.
- # All HTTPResponse objects belong to their own response class, which
- # indicates the HTTP result status. For details of the response classes,
- # see the section "HTTP Response Classes".
 #
- # === Full example with retrying and error reporting
 #
- # require 'uri'
- # require 'net/http'
 #
- # url = "http://www.example.com/"
 #
- # # Break apart the URL
- # uri = URI.parse(url)
- # # Reassemble the path for the HTTP request
- # if uri.query
- # path = uri.path + '?' + uri.query
- # else
- # path = uri.path
- # end
 #
- # # Create a request object
- # request = Net::HTTP::Get.new(path)
- #
- # # Prepare an HTTP connection object
- # http = Net::HTTP.new(uri.host, uri.port)
- #
- # # Open the connection and issue the request, retrying up to 3 times if there
- # # is a timeout
- # attempts = 1
- # begin
- # response = http.request(request)
- # rescue Exception => e
- # puts e
- # puts "[Retrying]"
- # attempts += 1
- # retry if attempts <= 3
- # end
 #
- # # Report the result
- # if response.kind_of? Net::HTTPSuccess
- # puts response.body
- # else
- # raise "Error fetching #{url}: #{response.code} #{response.message}"
- # end
 #
- # === HTTP Request Classes
 #
- # Here is HTTP request class hierarchy.
 #
- # Net::HTTPRequest
- # Net::HTTP::Get
- # Net::HTTP::Head
- # Net::HTTP::Post
- # Net::HTTP::Put
- # Net::HTTP::Prop
- # Net::HTTP::Lock
- # Net::HTTP::Unlock
- # Net::HTTP::Options
- # Net::HTTP::Propfind
- # Net::HTTP::Delete
- # Net::HTTP::Move
- # Net::HTTP::Copy
- # Net::HTTP::Mkcol
- # Net::HTTP::Trace
 #
- # === HTTP Response Classes
 #
- # The request() method returns a response of a specific class, depending
- # on the result of the HTTP request.
 #
- # To handle the result, you can use case/when statements. Example:
 #
- # response = http.request(req)
- # case response
- # when Net::HTTPSuccess
- # # Succeeded
- # when Net::HTTPInformation
- # # Continuing process
- # when Net::HTTPRedirection
- # # Page has moved, handle redirect
- # when Net::HTTPClientError
- # # Client is wrong
- # when Net::HTTPServerError
- # # Site is broken
- # else
- # # Unknown
- # end
 #
- # The HTTPResponse classes all provide +code+ and +message+ accessors to
- # obtain the 3-digit HTTP result code and the HTTP result message sent by
- # the server.
- #
- # Here is HTTP response class hierarchy.
- # All classes are defined in Net module.
- #
- # HTTPResponse
- # HTTPUnknownResponse
- # HTTPInformation # 1xx
- # HTTPContinue # 100
- # HTTPSwitchProtocol # 101
- # HTTPSuccess # 2xx
- # HTTPOK # 200
- # HTTPCreated # 201
- # HTTPAccepted # 202
- # HTTPNonAuthoritativeInformation # 203
- # HTTPNoContent # 204
- # HTTPResetContent # 205
- # HTTPPartialContent # 206
- # HTTPRedirection # 3xx
- # HTTPMultipleChoice # 300
- # HTTPMovedPermanently # 301
- # HTTPFound # 302
- # HTTPSeeOther # 303
- # HTTPNotModified # 304
- # HTTPUseProxy # 305
- # HTTPTemporaryRedirect # 307
- # HTTPClientError # 4xx
- # HTTPBadRequest # 400
- # HTTPUnauthorized # 401
- # HTTPPaymentRequired # 402
- # HTTPForbidden # 403
- # HTTPNotFound # 404
- # HTTPMethodNotAllowed # 405
- # HTTPNotAcceptable # 406
- # HTTPProxyAuthenticationRequired # 407
- # HTTPRequestTimeOut # 408
- # HTTPConflict # 409
- # HTTPGone # 410
- # HTTPLengthRequired # 411
- # HTTPPreconditionFailed # 412
- # HTTPRequestEntityTooLarge # 413
- # HTTPRequestURITooLong # 414
- # HTTPUnsupportedMediaType # 415
- # HTTPRequestedRangeNotSatisfiable # 416
- # HTTPExpectationFailed # 417
- # HTTPServerError # 5xx
- # HTTPInternalServerError # 500
- # HTTPNotImplemented # 501
- # HTTPBadGateway # 502
- # HTTPServiceUnavailable # 503
- # HTTPGatewayTimeOut # 504
- # HTTPVersionNotSupported # 505
 #
 # == Switching Net::HTTP versions
 #
- # You can use net/http.rb 1.1 features (bundled with Ruby 1.6)
- # by calling HTTP.version_1_1. Calling Net::HTTP.version_1_2
- # allows you to use 1.2 features again.
 #
- # # 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)... }
 #
 # Switching versions is NOT thread-safe.
 #
@@ -2,6 +2,11 @@
 = net/https -- SSL/TLS enhancement for Net::HTTP.
 == Info
 'OpenSSL for Ruby 2' project
 Copyright (C) 2001 GOTOU Yuuzou <[email protected]>
@@ -11,81 +16,6 @@
 This program is licenced under the same licence as Ruby.
 (See the file 'LICENCE'.)
-== Example
-
-Here is a simple HTTP client:
-
- require 'net/http'
- require 'uri'
-
- uri = URI.parse(ARGV[0] || 'http://localhost/')
- http = Net::HTTP.new(uri.host, uri.port)
- http.start {
- http.request_get(uri.path) {|res|
- print res.body
- }
- }
-
-It can be replaced by the following code:
-
- require 'net/https'
- require 'uri'
-
- uri = URI.parse(ARGV[0] || 'https://localhost/')
- http = Net::HTTP.new(uri.host, uri.port)
- http.use_ssl = true if uri.scheme == "https" # enable SSL/TLS
- http.start {
- http.request_get(uri.path) {|res|
- print res.body
- }
- }
-
-== class Net::HTTP
-
-=== Instance Methods
-
-: use_ssl?
- returns true if use SSL/TLS with HTTP.
-
-: use_ssl=((|true_or_false|))
- sets use_ssl.
-
-: peer_cert
- return the X.509 certificates the server presented.
-
-: key, key=((|key|))
- Sets an OpenSSL::PKey::RSA or OpenSSL::PKey::DSA object.
- (This method is appeared in Michal Rokos's OpenSSL extension.)
-
-: cert, cert=((|cert|))
- Sets an OpenSSL::X509::Certificate object as client certificate
- (This method is appeared in Michal Rokos's OpenSSL extension).
-
-: ca_file, ca_file=((|path|))
- Sets path of a CA certification file in PEM format.
- The file can contrain several CA certificates.
-
-: ca_path, ca_path=((|path|))
- Sets path of a CA certification directory containing certifications
- in PEM format.
-
-: verify_mode, verify_mode=((|mode|))
- Sets the flags for server the certification verification at
- beginning of SSL/TLS session.
- OpenSSL::SSL::VERIFY_NONE or OpenSSL::SSL::VERIFY_PEER is acceptable.
-
-: verify_callback, verify_callback=((|proc|))
- Sets the verify callback for the server certification verification.
-
-: verify_depth, verify_depth=((|num|))
- Sets the maximum depth for the certificate chain verification.
-
-: cert_store, cert_store=((|store|))
- Sets the X509::Store to verify peer certificate.
-
-: ssl_timeout, ssl_timeout=((|sec|))
- Sets the SSL timeout seconds.
-
 =end
 require 'net/http'
author	naruse <naruse@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>	2010-12-01 15:07:35 +0000
committer	naruse <naruse@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>	2010-12-01 15:07:35 +0000
commit	594633fbea10405b76101970d0ba54db18de49fd ()
tree	052522500cc90f81db59b05113e6364570b71eb0
parent	91d2ee737d599139a629d58d52e52cb4105d4772 (diff)