kotovalexarian-likes-github/ruby--ruby
1
0
Fork 0
mirror of https://github.com/ruby/ruby.git synced 2022-11-09 12:17:21 -05:00
Code Releases Activity

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

Browse source 
patched by mathew murphy [ruby-core:33472] ref #4100

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@29979 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
This commit is contained in:
naruse 2010-11-30 02:56:14 +00:00
parent fbf5f32416
commit 80c21e35cb
2 changed files with 288 additions and 152 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

5
ChangeLog
View file

@ -1,3 +1,8 @@
Tue Nov 30 11:39:13 2010 NARUSE, Yui <naruse@ruby-lang.org>
* 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@segment7.net> Tue Nov 30 05:03:44 2010 Eric Hodel <drbrain@segment7.net>
* lib/uri/common.rb (encode_www_form, encode_www_form_component): * lib/uri/common.rb (encode_www_form, encode_www_form_component):

415
lib/net/http.rb
View file

@ -97,13 +97,8 @@ module Net #:nodoc:
# {'q' => 'ruby', 'max' => '50'}) # {'q' => 'ruby', 'max' => '50'})
# puts res.body # puts res.body
# #
# #2: POST with basic authentication # #2: Detailed control of POST with authentication
# res = Net::HTTP.post_form(URI.parse('http://jack:pass@www.example.com/todo.cgi'),
# {'from' => '2005-01-01',
# 'to' => '2005-03-31'})
# puts res.body
# #
# #3: Detailed control
# uri = URI.parse('http://www.example.com/todo.cgi') # uri = URI.parse('http://www.example.com/todo.cgi')
# req = Net::HTTP::Post.new(uri.path) # req = Net::HTTP::Post.new(uri.path)
# req.basic_auth 'jack', 'pass' # req.basic_auth 'jack', 'pass'
@ -116,15 +111,16 @@ module Net #:nodoc:
# res.error! # res.error!
# end # end
# #
# #4: Multiple values # #3: Multiple values
# res = Net::HTTP.post_form(URI.parse('http://www.example.com/search.cgi'), # res = Net::HTTP.post_form(URI.parse('http://www.example.com/search.cgi'),
# {'q' => ['ruby', 'perl'], 'max' => '50'}) # {'q' => ['ruby', 'perl'], 'max' => '50'})
# puts res.body # puts res.body
# #
# === Accessing via Proxy # === Accessing via Proxy
# #
# Net::HTTP::Proxy has the same methods as Net::HTTP but its instances always # Net::HTTP.Proxy is an http proxy class. It has the same
# connect via the proxy, instead of given host. # methods as Net::HTTP, but its instances always connect via a proxy,
# instead of directly to the given host.
# #
# require 'net/http' # require 'net/http'
# #
@ -136,15 +132,19 @@ module Net #:nodoc:
# : # :
# } # }
# #
# Since Net::HTTP::Proxy returns Net::HTTP itself when proxy_addr is nil, # The top-level Net::HTTP class creates objects which represent
# there's no need to change code if there's a proxy or not. # HTTP sessions.
# #
# There are two additional parameters in Net::HTTP::Proxy which you can use to # Since Net::HTTP.Proxy returns Net::HTTP itself when +proxy_addr+ is nil,
# specify a proxy username and password: # 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) # 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 'net/http'
# require 'uri' # require 'uri'
@ -160,7 +160,7 @@ module Net #:nodoc:
# } # }
# #
# Note that net/http does not use the HTTP_PROXY environment variable. # 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 # === Following Redirection
# #
@ -183,8 +183,50 @@ module Net #:nodoc:
# print fetch('http://www.ruby-lang.org') # print fetch('http://www.ruby-lang.org')
# #
# Net::HTTPSuccess and Net::HTTPRedirection are HTTPResponse subclasses. # Net::HTTPSuccess and Net::HTTPRedirection are HTTPResponse subclasses.
# All HTTPResponse objects belong to their own response class which # All HTTPResponse objects belong to their own response class, which
# indicates the HTTP result status. # 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 # === HTTP Request Classes
# #
@ -208,6 +250,31 @@ module Net #:nodoc:
# #
# === HTTP Response Classes # === 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. # Here is HTTP response class hierarchy.
# All classes are defined in Net module. # All classes are defined in Net module.
# #
@ -292,13 +359,7 @@ module Net #:nodoc:
# :startdoc: # :startdoc:
# Turns on net/http 1.2 (ruby 1.8) features. # Turns on net/http 1.2 (ruby 1.8) features.
# Defaults to ON in ruby 1.8. # Defaults to ON in ruby 1.8 or later.
#
# I strongly recommend to call this method always.
#
# require 'net/http'
# Net::HTTP.version_1_2
#
def HTTP.version_1_2 def HTTP.version_1_2
@newimpl = true @newimpl = true
end end
@ -309,13 +370,13 @@ module Net #:nodoc:
@newimpl = false @newimpl = false
end 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. # Defaults to true.
def HTTP.version_1_2? def HTTP.version_1_2?
@newimpl @newimpl
end 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. # Defaults to true.
def HTTP.version_1_1? def HTTP.version_1_1?
not @newimpl not @newimpl
@ -331,9 +392,9 @@ module Net #:nodoc:
# #
# #
# Get body from target and output it to +$stdout+. The # Gets the body text from the target and outputs it to $stdout. The
# target can either be specified as (+uri+), or as # target can either be specified as
# (+host+, +path+, +port+ = 80); so: # (+uri+), or as (+host+, +path+, +port+ = 80); so:
# #
# Net::HTTP.get_print URI.parse('http://www.example.com/index.html') # Net::HTTP.get_print URI.parse('http://www.example.com/index.html')
# #
@ -350,7 +411,7 @@ module Net #:nodoc:
nil nil
end 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 # as a string. The target can either be specified as
# (+uri+), or as (+host+, +path+, +port+ = 80); so: # (+uri+), or as (+host+, +path+, +port+ = 80); so:
# #
@ -364,7 +425,7 @@ module Net #:nodoc:
get_response(uri_or_host, path, port).body get_response(uri_or_host, path, port).body
end 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 # as a Net::HTTPResponse object. The target can either be specified as
# (+uri+), or as (+host+, +path+, +port+ = 80); so: # (+uri+), or as (+host+, +path+, +port+ = 80); so:
# #
@ -390,12 +451,13 @@ module Net #:nodoc:
end end
end end
# Posts HTML form data to the +URL+. # Posts HTML form data to the specified URI object.
# Form data must be represented as a Hash of String to String, e.g: # The form data must be provided as a Hash mapping from String to String.
# Example:
# #
# { "cmd" => "search", "q" => "ruby", "max" => "50" } # { "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: # Example:
# #
@ -441,8 +503,8 @@ module Net #:nodoc:
# HTTP.start(address, port, p_addr, p_port, p_user, p_pass, &block) # 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) # 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 # Creates a new Net::HTTP object, then additionally opens the TCP
# HTTP session. # connection and HTTP session.
# #
# Argments are following: # Argments are following:
# _address_ :: hostname or IP address of the server # _address_ :: hostname or IP address of the server
@ -465,7 +527,8 @@ module Net #:nodoc:
# block finishes. In this case, the return value of this method # block finishes. In this case, the return value of this method
# is the return value of the block. If no block is given, the # 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 # 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+ def HTTP.start(address, *arg, &block) # :yield: +http+
arg.pop if opt = Hash.try_convert(arg[-1]) arg.pop if opt = Hash.try_convert(arg[-1])
port, p_addr, p_port, p_user, p_pass = *arg port, p_addr, p_port, p_user, p_pass = *arg
@ -488,9 +551,10 @@ module Net #:nodoc:
alias newobj new alias newobj new
end end
# Creates a new Net::HTTP object. # Creates a new Net::HTTP object without opening a TCP connection or
# If +proxy_addr+ is given, creates an Net::HTTP object with proxy support. # HTTP session.
# This method does not open the TCP connection. # 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) 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 = Proxy(p_addr, p_port, p_user, p_pass).newobj(address, port)
h.instance_eval { h.instance_eval {
@ -499,8 +563,9 @@ module Net #:nodoc:
h h
end end
# Creates a new Net::HTTP object for the specified +address+. # Creates a new Net::HTTP object for the specified server address,
# This method does not open the TCP connection. # 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) def initialize(address, port = nil)
@address = address @address = address
@port = (port || HTTP.default_port) @port = (port || HTTP.default_port)
@ -528,10 +593,10 @@ module Net #:nodoc:
"#<#{self.class} #{@address}:#{@port} open=#{started?}>" "#<#{self.class} #{@address}:#{@port} open=#{started?}>"
end end
# *WARNING* This method causes serious security hole. # *WARNING* This method opens a serious security hole.
# Never use this method in production code. # Never use this method in production code.
# #
# Set an output stream for debugging. # Sets an output stream for debugging.
# #
# http = Net::HTTP.new # http = Net::HTTP.new
# http.set_debug_output $stderr # http.set_debug_output $stderr
@ -542,19 +607,19 @@ module Net #:nodoc:
@debug_output = output @debug_output = output
end end
# The host name to connect to. # The DNS host name or IP address to connect to.
attr_reader :address attr_reader :address
# The port number to connect to. # The port number to connect to.
attr_reader :port 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, # If the HTTP object cannot open a connection in this many seconds,
# it raises a TimeoutError exception. # it raises a TimeoutError exception.
attr_accessor :open_timeout attr_accessor :open_timeout
# Seconds to wait until reading one block (by one read(2) call). # Number of seconds to wait for one block to be read (via one read(2)
# If the HTTP object cannot open a connection in this many seconds, # call). If the HTTP object cannot read data in this many seconds,
# it raises a TimeoutError exception. # it raises a TimeoutError exception.
attr_reader :read_timeout attr_reader :read_timeout
@ -564,7 +629,7 @@ module Net #:nodoc:
@read_timeout = sec @read_timeout = sec
end end
# returns true if the HTTP session is started. # Returns true if the HTTP session has been started.
def started? def started?
@started @started
end end
@ -573,7 +638,7 @@ module Net #:nodoc:
attr_accessor :close_on_empty_response 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? def use_ssl?
@use_ssl @use_ssl
end end
@ -604,14 +669,14 @@ module Net #:nodoc:
@socket.io.peer_cert @socket.io.peer_cert
end 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 # When this method is called with a block, it passes the Net::HTTP
# to the block and closes the TCP connection / HTTP session # object to the block, and closes the TCP connection and HTTP session
# after the block executed. # after the block has been executed.
# #
# When called with a block, returns the return value of the # When called with a block, it returns the return value of the
# block; otherwise, returns self. # block; otherwise, it returns self.
# #
def start # :yield: http def start # :yield: http
raise IOError, 'HTTP session already opened' if @started raise IOError, 'HTTP session already opened' if @started
@ -681,8 +746,8 @@ module Net #:nodoc:
end end
private :on_connect private :on_connect
# Finishes HTTP session and closes TCP connection. # Finishes the HTTP session and closes the TCP connection.
# Raises IOError if not started. # Raises IOError if the session has not been started.
def finish def finish
raise IOError, 'HTTP session not yet started' unless started? raise IOError, 'HTTP session not yet started' unless started?
do_finish do_finish
@ -708,12 +773,17 @@ module Net #:nodoc:
@proxy_user = nil @proxy_user = nil
@proxy_pass = nil @proxy_pass = nil
# Creates an HTTP proxy class. # Creates an HTTP proxy class which behaves like Net::HTTP, but
# Arguments are address/port of proxy host and username/password # performs all access via the specified proxy.
# if authorization on proxy server is required.
# You can replace the HTTP class with created proxy class.
# #
# 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 # # Example
# proxy_class = Net::HTTP::Proxy('proxy.example.com', 8080) # proxy_class = Net::HTTP::Proxy('proxy.example.com', 8080)
@ -846,9 +916,9 @@ module Net #:nodoc:
# #
# In version 1.1, this method might raise an exception for # In version 1.1, this method might raise an exception for
# 3xx (redirect). In this case you can get a HTTPResponse object # 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) # # version 1.1 (bundled with Ruby 1.6)
# response, body = http.get('/index.html') # response, body = http.get('/index.html')
@ -907,7 +977,8 @@ module Net #:nodoc:
# #
# In version 1.1, this method might raise an exception for # In version 1.1, this method might raise an exception for
# 3xx (redirect). On the case you can get a HTTPResponse object # 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. # In version 1.2, this method never raises an exception.
# #
# response = nil # response = nil
@ -930,7 +1001,7 @@ module Net #:nodoc:
# In version 1.2 (ruby 1.8), this method returns a Net::HTTPResponse object. # In version 1.2 (ruby 1.8), this method returns a Net::HTTPResponse object.
# #
# If called with a block, yields each fragment of the # 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 # the socket. Note that in this case, the returned response
# object will *not* contain a (meaningful) body. # object will *not* contain a (meaningful) body.
# #
@ -1035,12 +1106,12 @@ module Net #:nodoc:
request(Trace.new(path, initheader)) request(Trace.new(path, initheader))
end end
# Sends a GET request to the +path+ and gets a response, # Sends a GET request to the +path+.
# as an HTTPResponse object. # Returns the response as a Net::HTTPResponse object.
# #
# When called with a block, yields an HTTPResponse object. # When called with a block, passes an HTTPResponse object to the block.
# The body of this response will not have been read yet; # The body of the response will not have been read yet;
# the caller can process it using HTTPResponse#read_body, # the block can process it using HTTPResponse#read_body,
# if desired. # if desired.
# #
# Returns the response. # Returns the response.
@ -1048,11 +1119,11 @@ module Net #:nodoc:
# This method never raises Net::* exceptions. # This method never raises Net::* exceptions.
# #
# response = http.request_get('/index.html') # 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'] # p response['content-type']
# puts response.body # puts response.body
# #
# # using block # # Using a block
# http.request_get('/index.html') {|response| # http.request_get('/index.html') {|response|
# p response['content-type'] # p response['content-type']
# response.read_body do |str| # read body now # response.read_body do |str| # read body now
@ -1064,8 +1135,8 @@ module Net #:nodoc:
request(Get.new(path, initheader), &block) request(Get.new(path, initheader), &block)
end end
# Sends a HEAD request to the +path+ and gets a response, # Sends a HEAD request to the +path+ and returns the response
# as an HTTPResponse object. # as a Net::HTTPResponse object.
# #
# Returns the response. # Returns the response.
# #
@ -1078,13 +1149,13 @@ module Net #:nodoc:
request(Head.new(path, initheader), &block) request(Head.new(path, initheader), &block)
end end
# Sends a POST request to the +path+ and gets a response, # Sends a POST request to the +path+.
# as an HTTPResponse object.
# #
# When called with a block, yields an HTTPResponse object. # Returns the response as a Net::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, the block is passed an HTTPResponse
# if desired. # 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. # Returns the response.
# #
@ -1093,7 +1164,7 @@ module Net #:nodoc:
# # example # # example
# response = http.request_post('/cgi-bin/nice.rb', 'datadatadata...') # response = http.request_post('/cgi-bin/nice.rb', 'datadatadata...')
# p response.status # p response.status
# puts response.body # body is already read # puts response.body # body is already read in this case
# #
# # using block # # using block
# http.request_post('/cgi-bin/nice.rb', 'datadatadata...') {|response| # http.request_post('/cgi-bin/nice.rb', 'datadatadata...') {|response|
@ -1119,9 +1190,9 @@ module Net #:nodoc:
# Sends an HTTP request to the HTTP server. # 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. # This method never raises Net::* exceptions.
# #
@ -1133,17 +1204,19 @@ module Net #:nodoc:
request r, data request r, data
end end
# Sends an HTTPRequest object REQUEST to the HTTP server. # Sends an HTTPRequest object +req+ 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.
# #
# When called with a block, yields an HTTPResponse object. # If +req+ is a Net::HTTP::Post or Net::HTTP::Put request containing
# The body of this response will not have been read yet; # data, the data is also sent. Providing data for a Net::HTTP::Head or
# the caller can process it using HTTPResponse#read_body, # 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. # if desired.
# #
# Returns a HTTPResponse object.
#
# This method never raises Net::* exceptions. # This method never raises Net::* exceptions.
# #
def request(req, body = nil, &block) # :yield: +response+ def request(req, body = nil, &block) # :yield: +response+
@ -1284,13 +1357,14 @@ module Net #:nodoc:
HTTPSession = HTTP 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 to @header in the mixed-into class as a hash-like # provides access via case-insensitive keys. It also provides
# object, except with case-insensitive keys. Also provides # methods for accessing commonly-used HTTP header values in more
# methods for accessing commonly-used header values in a more # convenient formats.
# convenient format.
# #
module HTTPHeader module HTTPHeader
@ -1326,7 +1400,7 @@ module Net #:nodoc:
end end
# [Ruby 1.8.3] # [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. # Second argument +val+ must be a String.
# See also #[]=, #[] and #get_fields. # See also #[]=, #[] and #get_fields.
# #
@ -1366,14 +1440,20 @@ module Net #:nodoc:
# Returns the header field corresponding to the case-insensitive key. # Returns the header field corresponding to the case-insensitive key.
# Returns the default value +args+, or the result of the block, or # 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 # See Hash#fetch
def fetch(key, *args, &block) #:yield: +key+ def fetch(key, *args, &block) #:yield: +key+
a = @header.fetch(key.downcase, *args, &block) a = @header.fetch(key.downcase, *args, &block)
a.kind_of?(Array) ? a.join(', ') : a a.kind_of?(Array) ? a.join(', ') : a
end 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+ def each_header #:yield: +key+, +value+
block_given? or return enum_for(__method__) block_given? or return enum_for(__method__)
@header.each do |k,va| @header.each do |k,va|
@ -1383,7 +1463,8 @@ module Net #:nodoc:
alias each each_header 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+ def each_name(&block) #:yield: +key+
block_given? or return enum_for(__method__) block_given? or return enum_for(__method__)
@header.each_key(&block) @header.each_key(&block)
@ -1391,7 +1472,12 @@ module Net #:nodoc:
alias each_key each_name 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+ def each_capitalized_name #:yield: +key+
block_given? or return enum_for(__method__) block_given? or return enum_for(__method__)
@header.each_key do |k| @header.each_key do |k|
@ -1399,7 +1485,8 @@ module Net #:nodoc:
end end
end end
# Iterates for each header values. # Iterates through header values, passing each value to the
# code block.
def each_value #:yield: +value+ def each_value #:yield: +value+
block_given? or return enum_for(__method__) block_given? or return enum_for(__method__)
@header.each_value do |va| @header.each_value do |va|
@ -1407,7 +1494,7 @@ module Net #:nodoc:
end end
end end
# Removes a header field. # Removes a header field, specified by case-insensitive key.
def delete(key) def delete(key)
@header.delete(key.downcase) @header.delete(key.downcase)
end end
@ -1417,12 +1504,20 @@ module Net #:nodoc:
@header.key?(key.downcase) @header.key?(key.downcase)
end 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 def to_hash
@header.dup @header.dup
end end
# As for #each_header, except the keys are provided in capitalized form. # 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 def each_capitalized
block_given? or return enum_for(__method__) block_given? or return enum_for(__method__)
@header.each do |k,v| @header.each do |k,v|
@ -1437,8 +1532,8 @@ module Net #:nodoc:
end end
private :capitalize private :capitalize
# Returns an Array of Range objects which represents Range: header field, # Returns an Array of Range objects which represent the Range:
# or +nil+ if there is no such header. # HTTP header field, or +nil+ if there is no such header.
def range def range
return nil unless @header['range'] return nil unless @header['range']
self['Range'].split(/,/).map {|spec| self['Range'].split(/,/).map {|spec|
@ -1455,8 +1550,10 @@ module Net #:nodoc:
} }
end end
# Set Range: header from Range (arg r) or beginning index and # Sets the HTTP Range: header.
# length from it (arg idx&len). # 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.range = (0..1023)
# req.set_range 0, 1023 # req.set_range 0, 1023
@ -1492,8 +1589,8 @@ module Net #:nodoc:
alias range= set_range alias range= set_range
# Returns an Integer object which represents the Content-Length: header field # Returns an Integer object which represents the HTTP Content-Length:
# or +nil+ if that field is not provided. # header field, or +nil+ if that field was not provided.
def content_length def content_length
return nil unless key?('Content-Length') return nil unless key?('Content-Length')
len = self['Content-Length'].slice(/\d+/) or len = self['Content-Length'].slice(/\d+/) or
@ -1519,8 +1616,9 @@ module Net #:nodoc:
(/(?:\A|[^\-\w])chunked(?![\-\w])/i =~ field) ? true : false (/(?:\A|[^\-\w])chunked(?![\-\w])/i =~ field) ? true : false
end end
# Returns a Range object which represents Content-Range: header field. # Returns a Range object which represents the value of the Content-Range:
# This indicates, for a partial entity body, where this fragment # header field.
# For a partial entity body, this indicates where this fragment
# fits inside the full entity body, as range of byte offsets. # fits inside the full entity body, as range of byte offsets.
def content_range def content_range
return nil unless @header['content-range'] return nil unless @header['content-range']
@ -1562,8 +1660,9 @@ module Net #:nodoc:
sub.strip sub.strip
end end
# Returns content type parameters as a Hash as like # Any parameters specified for the content type, returned as a Hash.
# {"charset" => "iso-2022-jp"}. # For example, a header of Content-Type: text/html; charset=EUC-JP
# would result in type_params returning {'charset' => 'EUC-JP'}
def type_params def type_params
result = {} result = {}
list = self['Content-Type'].to_s.split(';') list = self['Content-Type'].to_s.split(';')
@ -1575,8 +1674,10 @@ module Net #:nodoc:
result result
end end
# Set Content-Type: header field by +type+ and +params+. # Sets the content type in an HTTP header.
# +type+ must be a String, +params+ must be a Hash. # 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 = {}) def set_content_type(type, params = {})
@header['content-type'] = [type + params.map{|k,v|"; #{k}=#{v}"}.join('')] @header['content-type'] = [type + params.map{|k,v|"; #{k}=#{v}"}.join('')]
end end
@ -1587,8 +1688,8 @@ module Net #:nodoc:
# +params+ should be a Hash containing HTML form data. # +params+ should be a Hash containing HTML form data.
# Optional argument +sep+ means data record separator. # Optional argument +sep+ means data record separator.
# #
# This method also set Content-Type: header field to # Values are URL encoded as necessary and the content-type is set to
# application/x-www-form-urlencoded. # application/x-www-form-urlencoded
# #
# Example: # Example:
# http.form_data = {"q" => "ruby", "lang" => "en"} # http.form_data = {"q" => "ruby", "lang" => "en"}
@ -1648,11 +1749,10 @@ module Net #:nodoc:
end 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 # Mixes in the HTTPHeader module to provide easier access to HTTP headers.
# a subclass of HTTPRequest.
#
# Mixes in the HTTPHeader module.
# #
class HTTPGenericRequest class HTTPGenericRequest
@ -1775,8 +1875,10 @@ module Net #:nodoc:
# #
# HTTP request class. This class wraps request header and entity path. # HTTP request class.
# You *must* use its subclass, Net::HTTP::Get, Post, Head. # 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 class HTTPRequest < HTTPGenericRequest
@ -1795,42 +1897,54 @@ module Net #:nodoc:
# HTTP/1.1 methods --- RFC2616 # HTTP/1.1 methods --- RFC2616
# #
# See Net::HTTPGenericRequest for attributes and methods.
# See Net::HTTP for usage examples.
class Get < HTTPRequest class Get < HTTPRequest
METHOD = 'GET' METHOD = 'GET'
REQUEST_HAS_BODY = false REQUEST_HAS_BODY = false
RESPONSE_HAS_BODY = true RESPONSE_HAS_BODY = true
end end
# See Net::HTTPGenericRequest for attributes and methods.
# See Net::HTTP for usage examples.
class Head < HTTPRequest class Head < HTTPRequest
METHOD = 'HEAD' METHOD = 'HEAD'
REQUEST_HAS_BODY = false REQUEST_HAS_BODY = false
RESPONSE_HAS_BODY = false RESPONSE_HAS_BODY = false
end end
# See Net::HTTPGenericRequest for attributes and methods.
# See Net::HTTP for usage examples.
class Post < HTTPRequest class Post < HTTPRequest
METHOD = 'POST' METHOD = 'POST'
REQUEST_HAS_BODY = true REQUEST_HAS_BODY = true
RESPONSE_HAS_BODY = true RESPONSE_HAS_BODY = true
end end
# See Net::HTTPGenericRequest for attributes and methods.
# See Net::HTTP for usage examples.
class Put < HTTPRequest class Put < HTTPRequest
METHOD = 'PUT' METHOD = 'PUT'
REQUEST_HAS_BODY = true REQUEST_HAS_BODY = true
RESPONSE_HAS_BODY = true RESPONSE_HAS_BODY = true
end end
# See Net::HTTPGenericRequest for attributes and methods.
# See Net::HTTP for usage examples.
class Delete < HTTPRequest class Delete < HTTPRequest
METHOD = 'DELETE' METHOD = 'DELETE'
REQUEST_HAS_BODY = false REQUEST_HAS_BODY = false
RESPONSE_HAS_BODY = true RESPONSE_HAS_BODY = true
end end
# See Net::HTTPGenericRequest for attributes and methods.
class Options < HTTPRequest class Options < HTTPRequest
METHOD = 'OPTIONS' METHOD = 'OPTIONS'
REQUEST_HAS_BODY = false REQUEST_HAS_BODY = false
RESPONSE_HAS_BODY = false RESPONSE_HAS_BODY = false
end end
# See Net::HTTPGenericRequest for attributes and methods.
class Trace < HTTPRequest class Trace < HTTPRequest
METHOD = 'TRACE' METHOD = 'TRACE'
REQUEST_HAS_BODY = false REQUEST_HAS_BODY = false
@ -1841,6 +1955,7 @@ module Net #:nodoc:
# PATCH method --- RFC5789 # PATCH method --- RFC5789
# #
# See Net::HTTPGenericRequest for attributes and methods.
class Patch < HTTPRequest class Patch < HTTPRequest
METHOD = 'PATCH' METHOD = 'PATCH'
REQUEST_HAS_BODY = true REQUEST_HAS_BODY = true
@ -1851,42 +1966,49 @@ module Net #:nodoc:
# WebDAV methods --- RFC2518 # WebDAV methods --- RFC2518
# #
# See Net::HTTPGenericRequest for attributes and methods.
class Propfind < HTTPRequest class Propfind < HTTPRequest
METHOD = 'PROPFIND' METHOD = 'PROPFIND'
REQUEST_HAS_BODY = true REQUEST_HAS_BODY = true
RESPONSE_HAS_BODY = true RESPONSE_HAS_BODY = true
end end
# See Net::HTTPGenericRequest for attributes and methods.
class Proppatch < HTTPRequest class Proppatch < HTTPRequest
METHOD = 'PROPPATCH' METHOD = 'PROPPATCH'
REQUEST_HAS_BODY = true REQUEST_HAS_BODY = true
RESPONSE_HAS_BODY = true RESPONSE_HAS_BODY = true
end end
# See Net::HTTPGenericRequest for attributes and methods.
class Mkcol < HTTPRequest class Mkcol < HTTPRequest
METHOD = 'MKCOL' METHOD = 'MKCOL'
REQUEST_HAS_BODY = true REQUEST_HAS_BODY = true
RESPONSE_HAS_BODY = true RESPONSE_HAS_BODY = true
end end
# See Net::HTTPGenericRequest for attributes and methods.
class Copy < HTTPRequest class Copy < HTTPRequest
METHOD = 'COPY' METHOD = 'COPY'
REQUEST_HAS_BODY = false REQUEST_HAS_BODY = false
RESPONSE_HAS_BODY = true RESPONSE_HAS_BODY = true
end end
# See Net::HTTPGenericRequest for attributes and methods.
class Move < HTTPRequest class Move < HTTPRequest
METHOD = 'MOVE' METHOD = 'MOVE'
REQUEST_HAS_BODY = false REQUEST_HAS_BODY = false
RESPONSE_HAS_BODY = true RESPONSE_HAS_BODY = true
end end
# See Net::HTTPGenericRequest for attributes and methods.
class Lock < HTTPRequest class Lock < HTTPRequest
METHOD = 'LOCK' METHOD = 'LOCK'
REQUEST_HAS_BODY = true REQUEST_HAS_BODY = true
RESPONSE_HAS_BODY = true RESPONSE_HAS_BODY = true
end end
# See Net::HTTPGenericRequest for attributes and methods.
class Unlock < HTTPRequest class Unlock < HTTPRequest
METHOD = 'UNLOCK' METHOD = 'UNLOCK'
REQUEST_HAS_BODY = true REQUEST_HAS_BODY = true
@ -1900,7 +2022,8 @@ module Net #:nodoc:
### ###
# HTTP exception class. # HTTP exception class.
# You must use its subclasses. # You cannot use HTTPExceptions directly; instead, you must use
# its subclasses.
module HTTPExceptions module HTTPExceptions
def initialize(msg, res) #:nodoc: def initialize(msg, res) #:nodoc:
super msg super msg
@ -1924,11 +2047,17 @@ module Net #:nodoc:
end end
# HTTP response class. This class wraps response header and entity. # HTTP response class.
# Mixes in the HTTPHeader module, which provides access to response #
# header values both via hash-like methods and individual readers. # 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 # Note that each possible HTTP response code defines its own
# HTTPResponse subclass. These are listed below. # HTTPResponse subclass. These are listed below.
#
# All classes are # All classes are
# defined under the Net module. Indentation indicates inheritance. # defined under the Net module. Indentation indicates inheritance.
# #
@ -2272,12 +2401,12 @@ module Net #:nodoc:
# The HTTP version supported by the server. # The HTTP version supported by the server.
attr_reader :http_version attr_reader :http_version
# HTTP result code string. For example, '302'. You can also # The HTTP result code string. For example, '302'. You can also
# determine the response type by which response subclass the # determine the response type by examining which response subclass
# response object is an instance of. # the response object is an instance of.
attr_reader :code 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 attr_reader :message
alias msg message # :nodoc: obsolete alias msg message # :nodoc: obsolete
@ -2315,7 +2444,7 @@ module Net #:nodoc:
self.class::EXCEPTION_TYPE self.class::EXCEPTION_TYPE
end end
# Raises HTTP error if the response is not 2xx. # Raises an HTTP error if the response is not 2xx (success).
def value def value
error! unless self.kind_of?(HTTPSuccess) error! unless self.kind_of?(HTTPSuccess)
end end
@ -2354,11 +2483,13 @@ module Net #:nodoc:
end end
end end
# Gets entity body. If the block given, yields it to +block+. # Gets the entity body returned by the remote HTTP server.
# The body is provided in fragments, as it is read in from the socket.
# #
# Calling this method a second or subsequent time will return the # If a block is given, the body is passed to the block, and
# already read string. # 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| # http.request_get('/index.html') {|res|
# puts res.read_body # puts res.read_body
@ -2394,10 +2525,10 @@ module Net #:nodoc:
@body @body
end end
# Returns the entity body. # Returns the full entity body.
# #
# Calling this method a second or subsequent time will return the # Calling this method a second or subsequent time will return the
# already read string. # string already read.
# #
# http.request_get('/index.html') {|res| # http.request_get('/index.html') {|res|
# puts res.body # puts res.body