ruby-changes:17962
From: naruse <ko1@a...>
Date: Tue, 30 Nov 2010 11:57:11 +0900 (JST)
Subject: [ruby-changes:17962] Ruby:r29979 (trunk): * lib/net/http.rb: improve rdoc.
naruse 2010-11-30 11:56:14 +0900 (Tue, 30 Nov 2010) New Revision: 29979 http://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=rev&revision=29979 Log: * lib/net/http.rb: improve rdoc. patched by mathew murphy [ruby-core:33472] ref #4100 Modified files: trunk/ChangeLog trunk/lib/net/http.rb Index: ChangeLog =================================================================== --- ChangeLog (revision 29978) +++ ChangeLog (revision 29979) @@ -1,3 +1,8 @@ +Tue Nov 30 11:39:13 2010 NARUSE, Yui <naruse@r...> + + * lib/net/http.rb: improve rdoc. + patched by mathew murphy [ruby-core:33472] ref #4100 + Tue Nov 30 05:03:44 2010 Eric Hodel <drbrain@s...> * lib/uri/common.rb (encode_www_form, encode_www_form_component): @@ -2,3 +7,3 @@ Improve english in documentation. - + * ext/openssl/ossl_ssl.c (ssl_version=, ciphers=): Document @@ -433,7 +438,7 @@ Thu Nov 18 00:02:17 2010 James Edward Gray II <jeg2@r...> - * lib/csv.rb: Upgrading output encoding with ASCII content + * lib/csv.rb: Upgrading output encoding with ASCII content as needed. [ruby-core:33229] Wed Nov 17 23:19:21 2010 Nobuyoshi Nakada <nobu@r...> @@ -925,14 +930,14 @@ Mon Nov 1 21:25:57 2010 URABE Shyouhei <shyouhei@r...> * main.c: <stdlib.h> is needed, to introduce the getenv(3) - prototype declaration. Without it a C compiler shall infer - the getenv type as "int getenv(...);", but this is totally - wrong, especially when your machine's sizeof(int) and - sizeof(char*) differs. On such environment a return value - of getenv(3), which is in fact a char*, might first casted - into a int (loses data here), and then casted back to char* - by automatic integral promotion to fit to the prototype of - ruby_set_debug_option(). + prototype declaration. Without it a C compiler shall infer + the getenv type as "int getenv(...);", but this is totally + wrong, especially when your machine's sizeof(int) and + sizeof(char*) differs. On such environment a return value + of getenv(3), which is in fact a char*, might first casted + into a int (loses data here), and then casted back to char* + by automatic integral promotion to fit to the prototype of + ruby_set_debug_option(). Sun Oct 31 23:27:09 2010 Koichi Sasada <ko1@a...> Index: lib/net/http.rb =================================================================== --- lib/net/http.rb (revision 29978) +++ lib/net/http.rb (revision 29979) @@ -97,13 +97,8 @@ # {'q' => 'ruby', 'max' => '50'}) # puts res.body # - # #2: POST with basic authentication - # res = Net::HTTP.post_form(URI.parse('http://jack:pass@w.../todo.cgi'), - # {'from' => '2005-01-01', - # 'to' => '2005-03-31'}) - # puts res.body + # #2: Detailed control of POST with authentication # - # #3: Detailed control # uri = URI.parse('http://www.example.com/todo.cgi') # req = Net::HTTP::Post.new(uri.path) # req.basic_auth 'jack', 'pass' @@ -116,15 +111,16 @@ # res.error! # end # - # #4: Multiple values + # #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 has the same methods as Net::HTTP but its instances always - # connect via the proxy, instead of given host. + # 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' # @@ -136,15 +132,19 @@ # : # } # - # 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. + # The top-level Net::HTTP class creates objects which represent + # HTTP sessions. # - # There are two additional parameters in Net::HTTP::Proxy which you can use to - # specify a proxy username and password: + # 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 may use them to work with authorization-enabled proxies: + # You can use them to work with authorization-enabled proxies: # # require 'net/http' # require 'uri' @@ -160,7 +160,7 @@ # } # # Note that net/http does not use the HTTP_PROXY environment variable. - # If you want to use a proxy, you must set it explicitly. + # If you want to use a proxy, you must do so explicitly. # # === Following Redirection # @@ -183,9 +183,51 @@ # 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. + # 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. @@ -208,6 +250,31 @@ # # === 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. # @@ -292,13 +359,7 @@ # :startdoc: # Turns on net/http 1.2 (ruby 1.8) features. - # Defaults to ON in ruby 1.8. - # - # I strongly recommend to call this method always. - # - # require 'net/http' - # Net::HTTP.version_1_2 - # + # Defaults to ON in ruby 1.8 or later. def HTTP.version_1_2 @newimpl = true end @@ -309,13 +370,13 @@ @newimpl = false end - # true if net/http is in version 1.2 mode. + # Returns true if net/http is in version 1.2 mode. # Defaults to true. def HTTP.version_1_2? @newimpl end - # true if net/http is in version 1.1 compatible mode. +! # Returns true if net/http is in version 1.1 compatible mode. # Defaults to true. def HTTP.version_1_1? not @newimpl @@ -331,9 +392,9 @@ # # - # Get body from target and output it to +$stdout+. The - # target can either be specified as (+uri+), or as - # (+host+, +path+, +port+ = 80); so: + # Gets the body text from the target and outputs it to $stdout. The + # target can either be specified as + # (+uri+), or as (+host+, +path+, +port+ = 80); so: # # Net::HTTP.get_print URI.parse('http://www.example.com/index.html') # @@ -350,7 +411,7 @@ nil end - # Send a GET request to the target and return the response + # Sends a GET request to the target and returns the HTTP response # as a string. The target can either be specified as # (+uri+), or as (+host+, +path+, +port+ = 80); so: # @@ -364,7 +425,7 @@ get_response(uri_or_host, path, port).body end - # Send a GET request to the target and return the response + # Sends a GET request to the target and returns the HTTP response # as a Net::HTTPResponse object. The target can either be specified as # (+uri+), or as (+host+, +path+, +port+ = 80); so: # @@ -390,12 +451,13 @@ end end - # Posts HTML form data to the +URL+. - # Form data must be represented as a Hash of String to String, e.g: + # Posts HTML form data to the specified URI object. + # The form data must be provided as a Hash mapping from String to String. + # Example: # # { "cmd" => "search", "q" => "ruby", "max" => "50" } # - # This method also does Basic Authentication iff +URL+.user exists. + # This method also does Basic Authentication iff +url+.user exists. # # Example: # @@ -441,8 +503,8 @@ # HTTP.start(address, port, p_addr, p_port, p_user, p_pass, &block) # HTTP.start(address, port=nil, p_addr=nil, p_port=nil, p_user=nil, p_pass=nil, opt, &block) # - # creates a new Net::HTTP object and opens its TCP connection and - # HTTP session. + # Creates a new Net::HTTP object, then additionally opens the TCP + # connection and HTTP session. # # Argments are following: # _address_ :: hostname or IP address of the server @@ -465,7 +527,8 @@ # block finishes. In this case, the return value of this method # is the return value of the block. If no block is given, the # return value of this method is the newly created Net::HTTP object - # itself, and the caller is responsible for closing it upon completion. + # itself, and the caller is responsible for closing it upon completion + # using the finish() method. def HTTP.start(address, *arg, &block) # :yield: +http+ arg.pop if opt = Hash.try_convert(arg[-1]) port, p_addr, p_port, p_user, p_pass = *arg @@ -488,9 +551,10 @@ alias newobj new end - # Creates a new Net::HTTP object. - # If +proxy_addr+ is given, creates an Net::HTTP object with proxy support. - # This method does not open the TCP connection. + # Creates a new Net::HTTP object without opening a TCP connection or + # HTTP session. + # The +address+ should be a DNS hostname or IP address. + # If +p_addr+ is given, creates a Net::HTTP object with proxy support. def HTTP.new(address, port = nil, p_addr = nil, p_port = nil, p_user = nil, p_pass = nil) h = Proxy(p_addr, p_port, p_user, p_pass).newobj(address, port) h.instance_eval { @@ -499,8 +563,9 @@ h end - # Creates a new Net::HTTP object for the specified +address+. - # This method does not open the TCP connection. + # Creates a new Net::HTTP object for the specified server address, + # without opening the TCP connection or initializing the HTTP session. + # The +address+ should be a DNS hostname or IP address. def initialize(address, port = nil) @address = address @port = (port || HTTP.default_port) @@ -528,10 +593,10 @@ "#<#{self.class} #{@address}:#{@port} open=#{started?}>" end - # *WARNING* This method causes serious security hole. + # *WARNING* This method opens a serious security hole. # Never use this method in production code. # - # Set an output stream for debugging. + # Sets an output stream for debugging. # # http = Net::HTTP.new # http.set_debug_output $stderr @@ -542,19 +607,19 @@ @debug_output = output end - # The host name to connect to. + # The DNS host name or IP address to connect to. attr_reader :address # The port number to connect to. attr_reader :port - # Seconds to wait until connection is opened. + # Number of seconds to wait for the connection to open. # If the HTTP object cannot open a connection in this many seconds, # it raises a TimeoutError exception. attr_accessor :open_timeout - # Seconds to wait until reading one block (by one read(2) call). - # If the HTTP object cannot open a connection in this many seconds, + # Number of seconds to wait for one block to be read (via one read(2) + # call). If the HTTP object cannot read data in this many seconds, # it raises a TimeoutError exception. attr_reader :read_timeout @@ -564,7 +629,7 @@ @read_timeout = sec end - # returns true if the HTTP session is started. + # Returns true if the HTTP session has been started. def started? @started end @@ -573,7 +638,7 @@ attr_accessor :close_on_empty_response - # returns true if use SSL/TLS with HTTP. + # Returns true if SSL/TLS is being used with HTTP. def use_ssl? @use_ssl end @@ -604,14 +669,14 @@ @socket.io.peer_cert end - # Opens TCP connection and HTTP session. + # Opens a TCP connection and HTTP session. # - # When this method is called with block, gives a HTTP object - # to the block and closes the TCP connection / HTTP session - # after the block executed. + # When this method is called with a block, it passes the Net::HTTP + # object to the block, and closes the TCP connection and HTTP session + # after the block has been executed. # - # When called with a block, returns the return value of the - # block; otherwise, returns self. + # When called with a block, it returns the return value of the + # block; otherwise, it returns self. # def start # :yield: http raise IOError, 'HTTP session already opened' if @started @@ -681,8 +746,8 @@ end private :on_connect - # Finishes HTTP session and closes TCP connection. - # Raises IOError if not started. + # Finishes the HTTP session and closes the TCP connection. + # Raises IOError if the session has not been started. def finish raise IOError, 'HTTP session not yet started' unless started? do_finish @@ -708,13 +773,18 @@ @proxy_user = nil @proxy_pass = nil - # Creates an HTTP proxy class. - # Arguments are address/port of proxy host and username/password - # if authorization on proxy server is required. - # You can replace the HTTP class with created proxy class. + # Creates an HTTP proxy class which behaves like Net::HTTP, but + # performs all access via the specified proxy. # - # If ADDRESS is nil, this method returns self (Net::HTTP). + # The arguments are the DNS name or IP address of the proxy host, + # the port to use to access the proxy, and a username and password + # if authorization is required to use the proxy. # + # You can replace any use of the Net::HTTP class with use of the + # proxy class created. + # + # If +p_addr+ is nil, this method returns self (a Net::HTTP object). + # # # Example # proxy_class = Net::HTTP::Proxy('proxy.example.com', 8080) # : @@ -846,9 +916,9 @@ # # In version 1.1, this method might raise an exception for # 3xx (redirect). In this case you can get a HTTPResponse object - # by "anException.response". + # from "anException.response". # - # In version 1.2, this method never raises exception. + # In version 1.2, this method never raises an exception. # # # version 1.1 (bundled with Ruby 1.6) # response, body = http.get('/index.html') @@ -907,7 +977,8 @@ # # In version 1.1, this method might raise an exception for # 3xx (redirect). On the case you can get a HTTPResponse object - # by "anException.response". + # as "anException.response". + # # In version 1.2, this method never raises an exception. # # response = nil @@ -930,7 +1001,7 @@ # In version 1.2 (ruby 1.8), this method returns a Net::HTTPResponse object. # # If called with a block, yields each fragment of the - # entity body in turn as a string as it are read from + # entity body in turn as a string as it is read from # the socket. Note that in this case, the returned response # object will *not* contain a (meaningful) body. # @@ -1035,12 +1106,12 @@ request(Trace.new(path, initheader)) end - # Sends a GET request to the +path+ and gets a response, - # as an HTTPResponse object. + # Sends a GET request to the +path+. + # Returns the response as a Net::HTTPResponse object. # - # When called with a block, yields an HTTPResponse object. - # The body of this response will not have been read yet; - # the caller can process it using HTTPResponse#read_body, + # When called with a block, passes an HTTPResponse object to the block. + # The body of the response will not have been read yet; + # the block can process it using HTTPResponse#read_body, # if desired. # # Returns the response. @@ -1048,11 +1119,11 @@ # This method never raises Net::* exceptions. # # response = http.request_get('/index.html') - # # The entity body is already read here. + # # The entity body is already read in this case. # p response['content-type'] # puts response.body # - # # using block + # # Using a block # http.request_get('/index.html') {|response| # p response['content-type'] # response.read_body do |str| # read body now @@ -1064,8 +1135,8 @@ request(Get.new(path, initheader), &block) end - # Sends a HEAD request to the +path+ and gets a response, - # as an HTTPResponse object. + # Sends a HEAD request to the +path+ and returns the response + # as a Net::HTTPResponse object. # # Returns the response. # @@ -1078,14 +1149,14 @@ request(Head.new(path, initheader), &block) end - # Sends a POST request to the +path+ and gets a response, - # as an HTTPResponse object. + # Sends a POST request to the +path+. # - # When called with a block, yields an HTTPResponse object. - # The body of this response will not have been read yet; - # the caller can process it using HTTPResponse#read_body, - # if desired. + # Returns the response as a Net::HTTPResponse object. # + # When called with a block, the block is passed an HTTPResponse + # object. The body of that response will not have been read yet; + # the block can process it using HTTPResponse#read_body, if desired. + # # Returns the response. # # This method never raises Net::* exceptions. @@ -1093,7 +1164,7 @@ # # example # response = http.request_post('/cgi-bin/nice.rb', 'datadatadata...') # p response.status - # puts response.body # body is already read + # puts response.body # body is already read in this case # # # using block # http.request_post('/cgi-bin/nice.rb', 'datadatadata...') {|response| @@ -1119,9 +1190,9 @@ # Sends an HTTP request to the HTTP server. - # This method also sends DATA string if DATA is given. + # Also sends a DATA string if +data+ is given. # - # Returns a HTTPResponse object. + # Returns a Net::HTTPResponse object. # # This method never raises Net::* exceptions. # @@ -1133,17 +1204,19 @@ request r, data end - # Sends an HTTPRequest object REQUEST to the HTTP server. - # This method also sends DATA string if REQUEST is a post/put request. - # Giving DATA for get/head request causes ArgumentError. + # Sends an HTTPRequest object +req+ to the HTTP server. # - # When called with a block, yields an HTTPResponse object. - # The body of this response will not have been read yet; - # the caller can process it using HTTPResponse#read_body, + # If +req+ is a Net::HTTP::Post or Net::HTTP::Put request containing + # data, the data is also sent. Providing data for a Net::HTTP::Head or + # Net::HTTP::Get request results in an ArgumentError. + # + # Returns an HTTPResponse object. + # + # When called with a block, passes an HTTPResponse object to the block. + # The body of the response will not have been read yet; + # the block can process it using HTTPResponse#read_body, # if desired. # - # Returns a HTTPResponse object. - # # This method never raises Net::* exceptions. # def request(req, body = nil, &block) # :yield: +response+ @@ -1284,14 +1357,15 @@ HTTPSession = HTTP + # The HTTPHeader module defines methods for reading and writing + # HTTP headers. # - # Header module. + # It is used as a mixin by other classes, to provide hash-like + # access to HTTP header values. Unlike raw hash access, HTTPHeader + # provides access via case-insensitive keys. It also provides + # methods for accessing commonly-used HTTP header values in more + # convenient formats. # - # Provides access to @header in the mixed-into class as a hash-like - # object, except with case-insensitive keys. Also provides - # methods for accessing commonly-used header values in a more - # convenient format. - # module HTTPHeader def initialize_http_header(initheader) @@ -1326,7 +1400,7 @@ end # [Ruby 1.8.3] - # Adds header field instead of replace. + # Adds a value to a named header field, instead of replacing its value. # Second argument +val+ must be a String. # See also #[]=, #[] and #get_fields. # @@ -1366,14 +1440,20 @@ # Returns the header field corresponding to the case-insensitive key. # Returns the default value +args+, or the result of the block, or - # raises an IndexErrror if there's no header field named +key+ + # raises an IndexError if there's no header field named +key+ # See Hash#fetch def fetch(key, *args, &block) #:yield: +key+ a = @header.fetch(key.downcase, *args, &block) a.kind_of?(Array) ? a.join(', ') : a end - # Iterates for each header names and values. + # Iterates through the header names and values, passing in the name + # and value to the code block supplied. + # + # Example: + # + # response.header.each_header {|key,value| puts "#{key} = #{value}" } + # def each_header #:yield: +key+, +value+ block_given? or return enum_for(__method__) @header.each do |k,va| @@ -1383,7 +1463,8 @@ alias each each_header - # Iterates for each header names. + # Iterates through the header names in the header, passing + # each header name to the code block. def each_name(&block) #:yield: +key+ block_given? or return enum_for(__method__) @header.each_key(&block) @@ -1391,7 +1472,12 @@ alias each_key each_name - # Iterates for each capitalized header names. + # Iterates through the header names in the header, passing + # capitalized header names to the code block. + # + # Note that header names are capitalized systematically; + # capitalization may not match that used by the remote HTTP + # server in its response. def each_capitalized_name #:yield: +key+ block_given? or return enum_for(__method__) @header.each_key do |k| @@ -1399,7 +1485,8 @@ end end - # Iterates for each header values. + # Iterates through header values, passing each value to the + # code block. def each_value #:yield: +value+ block_given? or return enum_for(__method__) @header.each_value do |va| @@ -1407,7 +1494,7 @@ end end - # Removes a header field. + # Removes a header field, specified by case-insensitive key. def delete(key) @header.delete(key.downcase) end @@ -1417,12 +1504,20 @@ @header.key?(key.downcase) end - # Returns a Hash consist of header names and values. + # Returns a Hash consisting of header names and values. + # e.g. + # {"cache-control" => "private", + # "content-type" => "text/html", + # "date" => "Wed, 22 Jun 2005 22:11:50 GMT"} def to_hash @header.dup end # As for #each_header, except the keys are provided in capitalized form. + # + # Note that header names are capitalized systematically; + # capitalization may not match that used by the remote HTTP + # server in its response. def each_capitalized block_given? or return enum_for(__method__) @header.each do |k,v| @@ -1437,8 +1532,8 @@ end private :capitalize - # Returns an Array of Range objects which represents Range: header field, - # or +nil+ if there is no such header. + # Returns an Array of Range objects which represent the Range: + # HTTP header field, or +nil+ if there is no such header. def range return nil unless @header['range'] self['Range'].split(/,/).map {|spec| @@ -1455,8 +1550,10 @@ } end - # Set Range: header from Range (arg r) or beginning index and - # length from it (arg idx&len). + # Sets the HTTP Range: header. + # Accepts either a Range object as a single argument, + # or a beginning index and a length from that index. + # Example: # # req.range = (0..1023) # req.set_range 0, 1023 @@ -1492,8 +1589,8 @@ alias range= set_range - # Returns an Integer object which represents the Content-Length: header field - # or +nil+ if that field is not provided. + # Returns an Integer object which represents the HTTP Content-Length: + # header field, or +nil+ if that field was not provided. def content_length return nil unless key?('Content-Length') len = self['Content-Length'].slice(/\d+/) or @@ -1519,8 +1616,9 @@ (/(?:\A|[^\-\w])chunked(?![\-\w])/i =~ field) ? true : false end - # Returns a Range object which represents Content-Range: header field. - # This indicates, for a partial entity body, where this fragment + # Returns a Range object which represents the value of the Content-Range: + # header field. + # For a partial entity body, this indicates where this fragment # fits inside the full entity body, as range of byte offsets. def content_range return nil unless @header['content-range'] @@ -1562,8 +1660,9 @@ sub.strip end - # Returns content type parameters as a Hash as like - # {"charset" => "iso-2022-jp"}. + # Any parameters specified for the content type, returned as a Hash. + # For example, a header of Content-Type: text/html; charset=EUC-JP + # would result in type_params returning {'charset' => 'EUC-JP'} def type_params result = {} list = self['Content-Type'].to_s.split(';') @@ -1575,8 +1674,10 @@ result end - # Set Content-Type: header field by +type+ and +params+. - # +type+ must be a String, +params+ must be a Hash. + # Sets the content type in an HTTP header. + # The +type+ should be a full HTTP content type, e.g. "text/html". + # The +params+ are an optional Hash of parameters to add after the + # content type, e.g. {'charset' => 'iso-8859-1'} def set_content_type(type, params = {}) @header['content-type'] = [type + params.map{|k,v|"; #{k}=#{v}"}.join('')] end @@ -1587,8 +1688,8 @@ # +params+ should be a Hash containing HTML form data. # Optional argument +sep+ means data record separator. # - # This method also set Content-Type: header field to - # application/x-www-form-urlencoded. + # Values are URL encoded as necessary and the content-type is set to + # application/x-www-form-urlencoded # # Example: # http.form_data = {"q" => "ruby", "lang" => "en"} @@ -1648,12 +1749,11 @@ end + # HTTPGenericRequest is the parent of the HTTPRequest class. + # Do not use this directly; use a subclass of HTTPRequest. # - # Parent of HTTPRequest class. Do not use this directly; use - # a subclass of HTTPRequest. + # Mixes in the HTTPHeader module to provide easier access to HTTP headers. # - # Mixes in the HTTPHeader module. - # class HTTPGenericRequest include HTTPHeader @@ -1775,8 +1875,10 @@ # - # HTTP request class. This class wraps request header and entity path. - # You *must* use its subclass, Net::HTTP::Get, Post, Head. + # HTTP request class. + # This class wraps together the request header and the request path. + # You cannot use this class directly. Instead, you should use one of its + # subclasses: Net::HTTP::Get, Net::HTTP::Post, Net::HTTP::Head. # class HTTPRequest < HTTPGenericRequest @@ -1795,42 +1897,54 @@ # HTTP/1.1 methods --- RFC2616 # + # See Net::HTTPGenericRequest for attributes and methods. + # See Net::HTTP for usage examples. class Get < HTTPRequest METHOD = 'GET' REQUEST_HAS_BODY = false RESPONSE_HAS_BODY = true end + # See Net::HTTPGenericRequest for attributes and methods. + # See Net::HTTP for usage examples. class Head < HTTPRequest METHOD = 'HEAD' REQUEST_HAS_BODY = false RESPONSE_HAS_BODY = false end + # See Net::HTTPGenericRequest for attributes and methods. + # See Net::HTTP for usage examples. class Post < HTTPRequest METHOD = 'POST' REQUEST_HAS_BODY = true RESPONSE_HAS_BODY = true end + # See Net::HTTPGenericRequest for attributes and methods. + # See Net::HTTP for usage examples. class Put < HTTPRequest METHOD = 'PUT' REQUEST_HAS_BODY = true RESPONSE_HAS_BODY = true end + # See Net::HTTPGenericRequest for attributes and methods. + # See Net::HTTP for usage examples. class Delete < HTTPRequest METHOD = 'DELETE' REQUEST_HAS_BODY = false RESPONSE_HAS_BODY = true end + # See Net::HTTPGenericRequest for attributes and methods. class Options < HTTPRequest METHOD = 'OPTIONS' REQUEST_HAS_BODY = false RESPONSE_HAS_BODY = false end + # See Net::HTTPGenericRequest for attributes and methods. class Trace < HTTPRequest METHOD = 'TRACE' REQUEST_HAS_BODY = false @@ -1841,6 +1955,7 @@ # PATCH method --- RFC5789 # + # See Net::HTTPGenericRequest for attributes and methods. class Patch < HTTPRequest METHOD = 'PATCH' REQUEST_HAS_BODY = true @@ -1851,42 +1966,49 @@ # WebDAV methods --- RFC2518 # + # See Net::HTTPGenericRequest for attributes and methods. class Propfind < HTTPRequest METHOD = 'PROPFIND' REQUEST_HAS_BODY = true RESPONSE_HAS_BODY = true end + # See Net::HTTPGenericRequest for attributes and methods. class Proppatch < HTTPRequest METHOD = 'PROPPATCH' REQUEST_HAS_BODY = true RESPONSE_HAS_BODY = true end + # See Net::HTTPGenericRequest for attributes and methods. class Mkcol < HTTPRequest METHOD = 'MKCOL' REQUEST_HAS_BODY = true RESPONSE_HAS_BODY = true end + # See Net::HTTPGenericRequest for attributes and methods. class Copy < HTTPRequest METHOD = 'COPY' REQUEST_HAS_BODY = false RESPONSE_HAS_BODY = true end + # See Net::HTTPGenericRequest for attributes and methods. class Move < HTTPRequest METHOD = 'MOVE' REQUEST_HAS_BODY = false RESPONSE_HAS_BODY = true end + # See Net::HTTPGenericRequest for attributes and methods. class Lock < HTTPRequest METHOD = 'LOCK' REQUEST_HAS_BODY = true RESPONSE_HAS_BODY = true end + # See Net::HTTPGenericRequest for attributes and methods. class Unlock < HTTPRequest METHOD = 'UNLOCK' REQUEST_HAS_BODY = true @@ -1900,7 +2022,8 @@ ### # HTTP exception class. - # You must use its subclasses. + # You cannot use HTTPExceptions directly; instead, you must use + # its subclasses. module HTTPExceptions def initialize(msg, res) #:nodoc: super msg @@ -1924,11 +2047,17 @@ end - # HTTP response class. This class wraps response header and entity. - # Mixes in the HTTPHeader module, which provides access to response - # header values both via hash-like methods and individual readers. + # HTTP response class. + # + # This class wraps together the response header and the response body (the + # entity requested). + # + # It mixes in the HTTPHeader module, which provides access to response + # header values both via hash-like methods and via individual readers. + # # Note that each possible HTTP response code defines its own # HTTPResponse subclass. These are listed below. + # # All classes are # defined under the Net module. Indentation indicates inheritance. # @@ -2272,12 +2401,12 @@ # The HTTP version supported by the server. attr_reader :http_version - # HTTP result code string. For example, '302'. You can also - # determine the response type by which response subclass the - # response object is an instance of. + # The HTTP result code string. For example, '302'. You can also + # determine the response type by examining which response subclass + # the response object is an instance of. attr_reader :code - # HTTP result message. For example, 'Not Found'. + # The HTTP result message sent by the server. For example, 'Not Found'. attr_reader :message alias msg message # :nodoc: obsolete @@ -2315,7 +2444,7 @@ self.class::EXCEPTION_TYPE end - # Raises HTTP error if the response is not 2xx. + # Raises an HTTP error if the response is not 2xx (success). def value error! unless self.kind_of?(HTTPSuccess) end @@ -2354,12 +2483,14 @@ end end - # Gets entity body. If the block given, yields it to +block+. - # The body is provided in fragments, as it is read in from the socket. + # Gets the entity body returned by the remote HTTP server. # - # Calling this method a second or subsequent time will return the - # already read string. + # If a block is given, the body is passed to the block, and + # the body is provided in fragments, as it is read in from the socket. # + # Calling this method a second or subsequent time for the same + # HTTPResponse object will return the value already read. + # # http.request_get('/index.html') {|res| # puts res.read_body # } @@ -2394,10 +2525,10 @@ @body end - # Returns the entity body. + # Returns the full entity body. # # Calling this method a second or subsequent time will return the - # already read string. + # string already read. # # http.request_get('/index.html') {|res| # puts res.body -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/