[ruby/net-http] [DOC] Enhanced RDoc for Net::HTTPHeader
(https://github.com/ruby/net-http/pull/83) https://github.com/ruby/net-http/commit/1ea5004098
This commit is contained in:
Burdette Lamar
git
parent
3d272b0fc8
commit
171e94bd95
@ -126,38 +126,49 @@
|
||||
# Various convenience methods retrieve values, set values, query values,
|
||||
# set form values, or iterate over fields.
|
||||
#
|
||||
# === Getters
|
||||
#
|
||||
# - #[]: Returns the string value for the given field.
|
||||
# - #content_length: Returns the integer value of field <tt>'Content-Length'</tt>.
|
||||
# - #content_range: Returns the Range value of field <tt>'Content-Range'</tt>.
|
||||
# - #content_type: Returns the string value of field <tt>'Content-Type'</tt>.
|
||||
# - #main_type: Returns first part of the string value of field <tt>'Content-Type'</tt>.
|
||||
# - #sub_type: Returns second part of the string value of field <tt>'Content-Type'</tt>.
|
||||
# - #range: Returns an array of Range objects of field <tt>'Range'</tt>, or +nil+.
|
||||
# - #range_length: Returns the integer length of the range given in field <tt>'Content-Range'</tt>.
|
||||
# - #type_params: Returns the string parameters for <tt>'Content-Type'</tt>.
|
||||
#
|
||||
# === Setters
|
||||
#
|
||||
# - #[]=: Sets the string or array value for the given field.
|
||||
# \Method #[]= can set any field, but does little to validate the new value;
|
||||
# some of the other setter methods provide some validation:
|
||||
#
|
||||
# - #[]=: Sets the string or array value for the given key.
|
||||
# - #add_field: Creates or adds to the array value for the given key.
|
||||
# - #basic_auth: Sets the string authorization header for <tt>'Authorization'</tt>.
|
||||
# - #content_length=: Sets the integer length for field <tt>'Content-Length</tt>.
|
||||
# - #content_type=: Sets the string value for field <tt>'Content-Type'</tt>.
|
||||
# - #proxy_basic_auth: Sets the string authorization header for <tt>'Proxy-Authorization'</tt>.
|
||||
# - #set_range: Sets the value for field <tt>'Range'</tt>.
|
||||
#
|
||||
# === Form Setters
|
||||
#
|
||||
# - #set_form: Sets an HTML form data set.
|
||||
# - #set_form_data: Sets header fields and a body from HTML form data.
|
||||
#
|
||||
# === Getters
|
||||
#
|
||||
# \Method #[] can retrieve the value of any field that exists,
|
||||
# but always as a string;
|
||||
# some of the other getter methods return something different
|
||||
# from the simple string value:
|
||||
#
|
||||
# - #[]: Returns the string field value for the given key.
|
||||
# - #content_length: Returns the integer value of field <tt>'Content-Length'</tt>.
|
||||
# - #content_range: Returns the Range value of field <tt>'Content-Range'</tt>.
|
||||
# - #content_type: Returns the string value of field <tt>'Content-Type'</tt>.
|
||||
# - #fetch: Returns the string field value for the given key.
|
||||
# - #get_fields: Returns the array field value for the given +key+.
|
||||
# - #main_type: Returns first part of the string value of field <tt>'Content-Type'</tt>.
|
||||
# - #sub_type: Returns second part of the string value of field <tt>'Content-Type'</tt>.
|
||||
# - #range: Returns an array of Range objects of field <tt>'Range'</tt>, or +nil+.
|
||||
# - #range_length: Returns the integer length of the range given in field <tt>'Content-Range'</tt>.
|
||||
# - #type_params: Returns the string parameters for <tt>'Content-Type'</tt>.
|
||||
#
|
||||
# === Queries
|
||||
#
|
||||
# - #chunked?: Returns whether field <tt>'Transfer-Encoding'</tt> is set to <tt>'chunked'</tt>.
|
||||
# - #connection_close?: Returns whether field <tt>'Connection'</tt> is set to <tt>'close'</tt>.
|
||||
# - #connection_keep_alive?: Returns whether field <tt>'Connection'</tt> is set to <tt>'keep-alive'</tt>.
|
||||
# - #key?: Returns whether a given field exists.
|
||||
#
|
||||
# === Form Setters
|
||||
#
|
||||
# - #set_form: Sets an HTML form data set.
|
||||
# - #set_form_data: Sets header fields and a body from HTML form data.
|
||||
# - #key?: Returns whether a given key exists.
|
||||
#
|
||||
# === Iterators
|
||||
#
|
||||
@ -165,7 +176,7 @@
|
||||
# - #each_capitalized_name: Passes each capitalized field name to the block.
|
||||
# - #each_header: Passes each field name/value pair to the block.
|
||||
# - #each_name: Passes each field name to the block.
|
||||
# - #each_value: Passes each field value to the block.
|
||||
# - #each_value: Passes each string field value to the block.
|
||||
#
|
||||
module Net::HTTPHeader
|
||||
|
||||
@ -196,12 +207,14 @@ module Net::HTTPHeader
|
||||
# or +nil+ if there is no such key;
|
||||
# see {Fields}[rdoc-ref:Net::HTTPHeader@Fields]:
|
||||
#
|
||||
# req = Net::HTTP::Get.new(uri)
|
||||
# req['Accept'] # => "*/*"
|
||||
# req['Foo'] = %w[bar baz bat]
|
||||
# req['Foo'] # => "bar, baz, bat"
|
||||
# res['Nosuch'] # => nil
|
||||
# res = Net::HTTP.start(hostname) do |http|
|
||||
# http.get('/todos/1')
|
||||
# end
|
||||
# res['Connection'] # => "keep-alive"
|
||||
# res['Nosuch'] # => nil
|
||||
#
|
||||
# Note that some field values may be retrieved via convenience methods;
|
||||
# see {Getters}[rdoc-ref:Net::HTTPHeader@Getters].
|
||||
def [](key)
|
||||
a = @header[key.downcase.to_s] or return nil
|
||||
a.join(', ')
|
||||
@ -216,6 +229,8 @@ module Net::HTTPHeader
|
||||
# req['Accept'] = 'text/html'
|
||||
# req['Accept'] # => "text/html"
|
||||
#
|
||||
# Note that some field values may be set via convenience methods;
|
||||
# see {Setters}[rdoc-ref:Net::HTTPHeader@Setters].
|
||||
def []=(key, val)
|
||||
unless val
|
||||
@header.delete key.downcase.to_s
|
||||
@ -278,12 +293,11 @@ module Net::HTTPHeader
|
||||
# or +nil+ if there is no such field;
|
||||
# see {Fields}[rdoc-ref:Net::HTTPHeader@Fields]:
|
||||
#
|
||||
# req = Net::HTTP::Get.new(uri)
|
||||
# req['Foo'] = 'bar'
|
||||
# req.get_fields('Foo') # => ["bar"]
|
||||
# req.add_field('Foo', 'baz')
|
||||
# req.get_fields('Foo') # => ["bar", "baz"]
|
||||
# req.get_fields('Nosuch') # => nil
|
||||
# res = Net::HTTP.start(hostname) do |http|
|
||||
# http.get('/todos/1')
|
||||
# end
|
||||
# res.get_fields('Connection') # => ["keep-alive"]
|
||||
# res.get_fields('Nosuch') # => nil
|
||||
#
|
||||
def get_fields(key)
|
||||
stringified_downcased_key = key.downcase.to_s
|
||||
@ -300,18 +314,27 @@ module Net::HTTPHeader
|
||||
# ignores the +default_val+;
|
||||
# see {Fields}[rdoc-ref:Net::HTTPHeader@Fields]:
|
||||
#
|
||||
# req = Net::HTTP::Get.new(uri)
|
||||
# req['Foo'] = 'bar'
|
||||
# req.fetch('Foo') {|key| key.capitalize } # => "bar"
|
||||
# req.fetch('Nosuch') {|key| key.capitalize } # => "Nosuch"
|
||||
# res = Net::HTTP.start(hostname) do |http|
|
||||
# http.get('/todos/1')
|
||||
# end
|
||||
#
|
||||
# # Field exists; block not called.
|
||||
# res.fetch('Connection') do |value|
|
||||
# fail 'Cannot happen'
|
||||
# end # => "keep-alive"
|
||||
#
|
||||
# # Field does not exist; block called.
|
||||
# res.fetch('Nosuch') do |value|
|
||||
# value.downcase
|
||||
# end # => "nosuch"
|
||||
#
|
||||
# With no block, returns the string value for +key+ if it exists;
|
||||
# otherwise, returns +default_val+ if it was given;
|
||||
# otherwise raises an exception:
|
||||
#
|
||||
# req.fetch('Foo') # => "bar"
|
||||
# req.fetch('Nosuch', :baz) # => :baz
|
||||
# req.fetch('Nosuch') # Raises KeyError.
|
||||
# res.fetch('Connection', 'Foo') # => "keep-alive"
|
||||
# res.fetch('Nosuch', 'Foo') # => "Foo"
|
||||
# res.fetch('Nosuch') # Raises KeyError.
|
||||
#
|
||||
def fetch(key, *args, &block) #:yield: +key+
|
||||
a = @header.fetch(key.downcase.to_s, *args, &block)
|
||||
@ -320,15 +343,20 @@ module Net::HTTPHeader
|
||||
|
||||
# Calls the block with each key/value pair:
|
||||
#
|
||||
# req = Net::HTTP::Get.new(uri)
|
||||
# req.each_header {|key, value| p [key, value] }
|
||||
# res = Net::HTTP.start(hostname) do |http|
|
||||
# http.get('/todos/1')
|
||||
# end
|
||||
# res.each_header do |key, value|
|
||||
# p [key, value] if key.start_with?('c')
|
||||
# end
|
||||
#
|
||||
# Output:
|
||||
#
|
||||
# ["accept-encoding", "gzip;q=1.0,deflate;q=0.6,identity;q=0.3"]
|
||||
# ["accept", "*/*"]
|
||||
# ["user-agent", "Ruby"]
|
||||
# ["host", "jsonplaceholder.typicode.com"]
|
||||
# ["content-type", "application/json; charset=utf-8"]
|
||||
# ["connection", "keep-alive"]
|
||||
# ["cache-control", "max-age=43200"]
|
||||
# ["cf-cache-status", "HIT"]
|
||||
# ["cf-ray", "771d17e9bc542cf5-ORD"]
|
||||
#
|
||||
# Returns an enumerator if no block is given.
|
||||
#
|
||||
@ -344,15 +372,20 @@ module Net::HTTPHeader
|
||||
|
||||
# Calls the block with each field key:
|
||||
#
|
||||
# req = Net::HTTP::Get.new(uri)
|
||||
# req.each_key {|key| p key }
|
||||
# res = Net::HTTP.start(hostname) do |http|
|
||||
# http.get('/todos/1')
|
||||
# end
|
||||
# res.each_key do |key|
|
||||
# p key if key.start_with?('c')
|
||||
# end
|
||||
#
|
||||
# Output:
|
||||
#
|
||||
# "accept-encoding"
|
||||
# "accept"
|
||||
# "user-agent"
|
||||
# "host"
|
||||
# "content-type"
|
||||
# "connection"
|
||||
# "cache-control"
|
||||
# "cf-cache-status"
|
||||
# "cf-ray"
|
||||
#
|
||||
# Returns an enumerator if no block is given.
|
||||
#
|
||||
@ -366,15 +399,20 @@ module Net::HTTPHeader
|
||||
|
||||
# Calls the block with each capitalized field name:
|
||||
#
|
||||
# req = Net::HTTP::Get.new(uri)
|
||||
# req.each_capitalized_name {|key| p key }
|
||||
# res = Net::HTTP.start(hostname) do |http|
|
||||
# http.get('/todos/1')
|
||||
# end
|
||||
# res.each_capitalized_name do |key|
|
||||
# p key if key.start_with?('C')
|
||||
# end
|
||||
#
|
||||
# Output:
|
||||
#
|
||||
# "Accept-Encoding"
|
||||
# "Accept"
|
||||
# "User-Agent"
|
||||
# "Host"
|
||||
# "Content-Type"
|
||||
# "Connection"
|
||||
# "Cache-Control"
|
||||
# "Cf-Cache-Status"
|
||||
# "Cf-Ray"
|
||||
#
|
||||
# The capitalization is system-dependent;
|
||||
# see {Case Mapping}[rdoc-ref:case_mapping.rdoc].
|
||||
@ -387,17 +425,20 @@ module Net::HTTPHeader
|
||||
end
|
||||
end
|
||||
|
||||
# Calls the block with each field value:
|
||||
# Calls the block with each string field value:
|
||||
#
|
||||
# req = Net::HTTP::Get.new(uri)
|
||||
# req.each_value {|value| p value }
|
||||
# res = Net::HTTP.start(hostname) do |http|
|
||||
# http.get('/todos/1')
|
||||
# end
|
||||
# res.each_value do |value|
|
||||
# p value if value.start_with?('c')
|
||||
# end
|
||||
#
|
||||
# Output:
|
||||
#
|
||||
# "gzip;q=1.0,deflate;q=0.6,identity;q=0.3"
|
||||
# "*/*"
|
||||
# "Ruby"
|
||||
# "jsonplaceholder.typicode.com"
|
||||
# "chunked"
|
||||
# "cf-q-config;dur=6.0000002122251e-06"
|
||||
# "cloudflare"
|
||||
#
|
||||
# Returns an enumerator if no block is given.
|
||||
def each_value #:yield: +value+
|
||||
@ -465,6 +506,7 @@ module Net::HTTPHeader
|
||||
# or +nil+ if there is no such field;
|
||||
# see {Range request header}[https://en.wikipedia.org/wiki/List_of_HTTP_header_fields#range-request-header]:
|
||||
#
|
||||
# req = Net::HTTP::Get.new(uri)
|
||||
# req['Range'] = 'bytes=0-99,200-299,400-499'
|
||||
# req.range # => [0..99, 200..299, 400..499]
|
||||
# req.delete('Range')
|
||||
@ -522,6 +564,7 @@ module Net::HTTPHeader
|
||||
#
|
||||
# With argument +length+:
|
||||
#
|
||||
# req = Net::HTTP::Get.new(uri)
|
||||
# req.set_range(100) # => 100
|
||||
# req['Range'] # => "bytes=0-99"
|
||||
#
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user