From baf7a09d3509f7d858fc7a705e14feaaf5ad56b6 Mon Sep 17 00:00:00 2001 From: naruse Date: Sat, 27 Nov 2010 19:22:53 +0000 Subject: [PATCH] * lib/net/http.rb: improve rdoc. patched by Mike Perham [ruby-core:33433] git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@29953 b2dd03c8-39d4-4d8f-98ff-823fe69b080e --- ChangeLog | 5 ++ lib/net/http.rb | 126 +++++++++++++++++++++++------------------------- 2 files changed, 65 insertions(+), 66 deletions(-) diff --git a/ChangeLog b/ChangeLog index 0a15d9691d1686..774595f28a18da 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,8 @@ +Sun Nov 28 03:58:47 2010 NARUSE, Yui + + * lib/net/http.rb: improve rdoc. + patched by Mike Perham [ruby-core:33433] + Sat Nov 27 19:12:10 2010 Tanaka Akira * time.c: parenthesize macro arguments. diff --git a/lib/net/http.rb b/lib/net/http.rb index 33c88c8ce579e0..092a27b07256a8 100644 --- a/lib/net/http.rb +++ b/lib/net/http.rb @@ -18,12 +18,6 @@ # # See Net::HTTP for an overview and examples. # -# NOTE: You can find Japanese version of this document here: -# http://www.ruby-lang.org/ja/man/html/net_http.html -# -#-- -# $Id$ -#++ require 'net/protocol' autoload :OpenSSL, 'openssl' @@ -36,48 +30,61 @@ class HTTPBadResponse < StandardError; end class HTTPHeaderSyntaxError < StandardError; end # :startdoc: - # == What Is This Library? + # == An HTTP client API for Ruby. # - # This library provides your program functions to access WWW - # documents via HTTP, Hyper Text Transfer Protocol version 1.1. - # For details of HTTP, refer to [RFC2616] - # (http://www.ietf.org/rfc/rfc2616.txt). + # For more details about HTTP, see [RFC2616](http://www.ietf.org/rfc/rfc2616.txt). # # == Examples # - # === Getting Document From WWW Server + # === Fetching Documents # - # Example #1: Simple GET+print + # Simple GET # # require 'net/http' - # Net::HTTP.get_print 'www.example.com', '/index.html' - # - # Example #2: Simple GET+print by URL - # - # require 'net/http' - # require 'uri' - # Net::HTTP.get_print URI.parse('http://www.example.com/index.html') + # Net::HTTP.get('www.example.com', '/index.html') => String # - # Example #3: More generic GET+print + # Simple GET by URI object # # require 'net/http' # require 'uri' - # - # url = URI.parse('http://www.example.com/index.html') - # res = Net::HTTP.start(url.hostname, url.port) {|http| - # http.get('/index.html') - # } - # puts res.body - # - # Example #4: More generic GET+print - # - # require 'net/http' - # - # url = URI.parse('http://www.example.com/index.html') - # req = Net::HTTP::Get.new(url.path) - # res = Net::HTTP.start(url.hostname, url.port) {|http| - # http.request(req) - # } + # 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 @@ -97,11 +104,11 @@ class HTTPHeaderSyntaxError < StandardError; end # puts res.body # # #3: Detailed control - # url = URI.parse('http://www.example.com/todo.cgi') - # req = Net::HTTP::Post.new(url.path) + # 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(url.hostname, url.port).start {|http| http.request(req) } + # res = Net::HTTP.new(uri.hostname, uri.port).start {|http| http.request(req) } # case res # when Net::HTTPSuccess, Net::HTTPRedirection # # OK @@ -116,9 +123,8 @@ class HTTPHeaderSyntaxError < StandardError; end # # === Accessing via Proxy # - # Net::HTTP.Proxy creates http proxy class. It has same - # methods of Net::HTTP but its instances always connect to - # proxy, instead of given host. + # Net::HTTP::Proxy has the same methods as Net::HTTP but its instances always + # connect via the proxy, instead of given host. # # require 'net/http' # @@ -130,11 +136,11 @@ class HTTPHeaderSyntaxError < StandardError; end # : # } # - # Since Net::HTTP.Proxy returns Net::HTTP itself when proxy_addr is nil, - # there's no need to change code if there's proxy or not. + # Since Net::HTTP::Proxy returns Net::HTTP itself when proxy_addr is nil, + # there's no need to change code if there's a proxy or not. # - # There are two additional parameters in Net::HTTP.Proxy which allow to - # specify proxy user name and password: + # There are two additional parameters in Net::HTTP::Proxy which you can use to + # specify a proxy username and password: # # Net::HTTP::Proxy(proxy_addr, proxy_port, proxy_user = nil, proxy_pass = nil) # @@ -153,8 +159,8 @@ class HTTPHeaderSyntaxError < StandardError; end # : # } # - # Note that net/http never rely on HTTP_PROXY environment variable. - # If you want to use proxy, set it explicitly. + # Note that net/http does not use the HTTP_PROXY environment variable. + # If you want to use a proxy, you must set it explicitly. # # === Following Redirection # @@ -176,21 +182,9 @@ class HTTPHeaderSyntaxError < StandardError; end # # print fetch('http://www.ruby-lang.org') # - # Net::HTTPSuccess and Net::HTTPRedirection is a HTTPResponse class. - # All HTTPResponse objects belong to its own response class which - # indicate HTTP result status. For details of response classes, - # see section "HTTP Response Classes". - # - # === Basic Authentication - # - # require 'net/http' - # - # Net::HTTP.start('www.example.com') {|http| - # req = Net::HTTP::Get.new('/secret-page.html') - # req.basic_auth 'account', 'password' - # response = http.request(req) - # print response.body - # } + # Net::HTTPSuccess and Net::HTTPRedirection are HTTPResponse subclasses. + # All HTTPResponse objects belong to their own response class which + # indicates the HTTP result status. # # === HTTP Request Classes # @@ -280,7 +274,7 @@ class HTTPHeaderSyntaxError < StandardError; end # Net::HTTP.version_1_2 # Net::HTTP.start {|http3| ...(http3 has 1.2 features)... } # - # This function is NOT thread-safe. + # Switching versions is NOT thread-safe. # class HTTP < Protocol @@ -1798,7 +1792,7 @@ def initialize(path, initheader = nil) class HTTP # reopen # - # HTTP 1.1 methods --- RFC2616 + # HTTP/1.1 methods --- RFC2616 # class Get < HTTPRequest