From c6dc1266418a5cb84a91718946f9be00d073c2f7 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Sun, 20 Nov 2022 19:43:07 +0000 Subject: [PATCH] [ruby/net-http] Enhanced RDoc for Net::HTTPHeader https://github.com/ruby/net-http/commit/995ff356b4 --- lib/net/http/header.rb | 143 ++++++++++++++++++++++------------------- 1 file changed, 77 insertions(+), 66 deletions(-) diff --git a/lib/net/http/header.rb b/lib/net/http/header.rb index 618fb7767b..be635ecadc 100644 --- a/lib/net/http/header.rb +++ b/lib/net/http/header.rb @@ -20,26 +20,21 @@ # # A field key may be: # -# - A string: Key 'Foo' is treated as if it were -# 'Foo'.downcase; i.e., 'foo'. -# - A symbol: Key :Foo is treated as if it were -# :Foo.to_s.downcase; i.e., 'foo'. +# - A string: Key 'Accept' is treated as if it were +# 'Accept'.downcase; i.e., 'accept'. +# - A symbol: Key :Accept is treated as if it were +# :Accept.to_s.downcase; i.e., 'accept'. # # Examples: # -# req = Net::HTTP.get(uri) -# req[:Accept] # => "*/*" +# req = Net::HTTP::Get.new(uri) +# req[:accept] # => "*/*" # req['Accept'] # => "*/*" # req['ACCEPT'] # => "*/*" # # req['accept'] = 'text/html' -# req['accept'] # => "text/html" -# req[:Accept] = 'text/html' -# req['accept'] # => "text/html" -# req['Accept'] = 'application/json' -# req['accept'] # => "application/json" -# req['ACCEPT'] = 'text/plain' -# req['accept'] # => "text/plain" +# req[:accept] = 'text/html' +# req['ACCEPT'] = 'text/html' # # === Field Values # @@ -73,15 +68,15 @@ # # - \String: # -# req[:foo] = 'bar' -# req[:foo] # => "bar" -# req.get_fields(:foo) # => ["bar"] +# req['Accept'] = 'text/html' # => "text/html" +# req['Accept'] # => "text/html" +# req.get_fields('Accept') # => ["text/html"] # # - \Symbol: # -# req[:foo] = :bar -# req[:foo] # => "bar" -# req.get_fields(:foo) # => ["bar"] +# req['Accept'] = :text # => :text +# req['Accept'] # => "text" +# req.get_fields('Accept') # => ["text"] # # - Simple array: # @@ -113,35 +108,35 @@ # === Getters # # - #[]: Returns the string value for the given field. -# - #content_length: Returns the integer value of field +:content-length+. -# - #content_range: Returns the Range value of field +:content-range+. -# - #content_type: Returns the string value of field +:content-type+. -# - #main_type: Returns first part of the string value of field +:content-type+. -# - #sub_type: Returns second part of the string value of field +:content-type+. -# - #range: Returns an array of Range objects, or +nil+. -# - #range_length: Returns the integer length of the range given in field +:range+. -# - #type_params: Returns the string parameters for +:content-type+. +# - #content_length: Returns the integer value of field 'Content-Length'. +# - #content_range: Returns the Range value of field 'Content-Range'. +# - #content_type: Returns the string value of field 'Content-Type'. +# - #main_type: Returns first part of the string value of field 'Content-Type'. +# - #sub_type: Returns second part of the string value of field 'Content-Type'. +# - #range: Returns an array of Range objects of field 'Range', or +nil+. +# - #range_length: Returns the integer length of the range given in field 'Content-Range'. +# - #type_params: Returns the string parameters for 'Content-Type'. # # === Setters # # - #[]=: Sets the string or array value for the given field. -# - #basic_auth: Sets the string authorization header for +:Basic+ authorization. -# - #content_length=: Sets the integer length for field +:content-length+. -# - #content_type=: Sets the string value for field +:content-type+. -# - #proxy_basic_auth: Set Proxy-Authorization: header for “Basic” authorization. -# - #range=: 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: +# - #basic_auth: Sets the string authorization header for 'Authorization'. +# - #content_length=: Sets the integer length for field 'Content-Length. +# - #content_type=: Sets the string value for field 'Content-Type'. +# - #proxy_basic_auth: Sets the string authorization header for 'Proxy-Authorization'. +# - #range=: Sets the value for field +'Range'+. # # === Queries # -# - #chunked?: Returns whether field +:transfer-encoding+ is set to 'chunked'. -# - #connection_close?: Returns whether field +:connection+ is set to 'close'. -# - #connection_keep_alive?: Returns whether field +:connection+ is set to 'keep-alive'. +# - #chunked?: Returns whether field 'Transfer-Encoding' is set to 'chunked'. +# - #connection_close?: Returns whether field 'Connection' is set to 'close'. +# - #connection_keep_alive?: Returns whether field 'Connection' is set to 'keep-alive'. # - #key?: Returns whether a given field exists. # # === Form Setters # # - #set_form: Sets an HTML form data set. -# - #set_form_data: Set header fields and a body from HTML form data. +# - #set_form_data: Sets header fields and a body from HTML form data. # # === Iterators # @@ -151,6 +146,15 @@ # - #each_name: Passes each field name to the block. # - #each_value: Passes each field value to the block. # +# == Hash of Headers +# +# Each of the iterator methods above returns a hash of the headers of +self+. +# Note that modifying that returned hash actually modifies the headers: +# +# h = req.each_header {|k, v| } +# h.clear +# req.to_hash # => {} +# module Net::HTTPHeader def initialize_http_header(initheader) #:nodoc: @@ -181,10 +185,10 @@ module Net::HTTPHeader # 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 + # req['Accept'] # => "*/*" + # req['Foo'] = %w[bar baz bat] + # req['Foo'] # => "bar, baz, bat" + # res['Nosuch'] # => nil # def [](key) a = @header[key.downcase.to_s] or return nil @@ -196,9 +200,9 @@ module Net::HTTPHeader # see {Fields}[rdoc-ref:Net::HTTPHeader@Fields]: # # req = Net::HTTP::Get.new(uri) - # req[:accept] # => "*/*" - # req[:accept] = 'text/html' - # req[:accept] # => "text/html" + # req['Accept'] # => "*/*" + # req['Accept'] = 'text/html' + # req['Accept'] # => "text/html" # def []=(key, val) unless val @@ -213,13 +217,13 @@ module Net::HTTPHeader # see {Fields}[rdoc-ref:Net::HTTPHeader@Fields]: # # req = Net::HTTP::Get.new(uri) - # req.add_field(:foo, 'bar') - # req[:foo] # => "bar" - # req.add_field(:foo, 'baz') - # req[:foo] # => "bar, baz" - # req.add_field(:foo, %w[baz bam]) - # req[:foo] # => "bar, baz, baz, bam" - # req.get_fields(:foo) # => ["bar", "baz", "baz", "bam"] + # req.add_field('Foo', 'bar') + # req['Foo'] # => "bar" + # req.add_field('Foo', 'baz') + # req['Foo'] # => "bar, baz" + # req.add_field('Foo', %w[baz bam]) + # req['Foo'] # => "bar, baz, baz, bam" + # req.get_fields('Foo') # => ["bar", "baz", "baz", "bam"] # def add_field(key, val) stringified_downcased_key = key.downcase.to_s @@ -263,11 +267,11 @@ module Net::HTTPHeader # 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 + # req['Foo'] = 'bar' + # req.get_fields('Foo') # => ["bar"] + # req.add_field('Foo', 'baz') + # req.get_fields('Foo') # => ["bar", "baz"] + # req.get_fields('Nosuch') # => nil # def get_fields(key) stringified_downcased_key = key.downcase.to_s @@ -283,17 +287,17 @@ module Net::HTTPHeader # 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" + # req['Foo'] = 'bar' + # req.fetch('Foo') {|key| key.capitalize } # => "bar" + # req.fetch('Nosuch') {|key| key.capitalize } # => "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 IndexError. + # req.fetch('Foo') # => "bar" + # req.fetch('Nosuch', :baz) # => :baz + # req.fetch('Nosuch') # Raises KeyError. # def fetch(key, *args, &block) #:yield: +key+ a = @header.fetch(key.downcase.to_s, *args, &block) @@ -301,7 +305,7 @@ module Net::HTTPHeader end # Calls the block with each key/value pair; - # returns the value of #to_hash; + # returns the {hash of headers}[rdoc-ref:Net::HTTPHeader@Hash+of+Headers]; # see {Fields}[rdoc-ref:Net::HTTPHeader@Fields]: # # req = Net::HTTP::Get.new(uri) @@ -315,6 +319,8 @@ module Net::HTTPHeader # ["host", "jsonplaceholder.typicode.com"] # # Returns an enumerator if no block is given. + # + # Net::HTTPHeader#each is an alias for Net::HTTPHeader#each_header. def each_header #:yield: +key+, +value+ block_given? or return enum_for(__method__) { @header.size } @header.each do |k,va| @@ -325,7 +331,7 @@ module Net::HTTPHeader alias each each_header # Calls the block with each field key; - # returns the value of #to_hash; + # returns the {hash of headers}[rdoc-ref:Net::HTTPHeader@Hash+of+Headers]; # see {Fields}[rdoc-ref:Net::HTTPHeader@Fields]: # # req = Net::HTTP::Get.new(uri) @@ -349,7 +355,7 @@ module Net::HTTPHeader alias each_key each_name # Calls the block with each capitalized field name; - # returns the value of #to_hash; + # returns the {hash of headers}[rdoc-ref:Net::HTTPHeader@Hash+of+Headers]; # see {Fields}[rdoc-ref:Net::HTTPHeader@Fields]: # # req = Net::HTTP::Get.new(uri) @@ -410,6 +416,8 @@ module Net::HTTPHeader # server in its response. # # Returns an enumerator if no block is given. + # + # Net::HTTPHeader#canonical_each is an alias for Net::HTTPHeader#each_capitalized. def each_capitalized block_given? or return enum_for(__method__) { @header.size } @header.each do |k,v| @@ -505,7 +513,7 @@ module Net::HTTPHeader r end - alias range= set_range + n range= set_range # Returns an Integer object which represents the HTTP Content-Length: # header field, or +nil+ if that field was not provided. @@ -596,7 +604,9 @@ module Net::HTTPHeader # 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'} + # content type, e.g. {'charset' => 'iso-8859-1'}. + # + # Net::HTTPHeader#content_type= is an alias for Net::HTTPHeader#set_content_type. def set_content_type(type, params = {}) @header['content-type'] = [type + params.map{|k,v|"; #{k}=#{v}"}.join('')] end @@ -616,6 +626,7 @@ module Net::HTTPHeader # http.form_data = {"q" => ["ruby", "perl"], "lang" => "en"} # http.set_form_data({"q" => "ruby", "lang" => "en"}, ';') # + # Net::HTTPHeader#form_data= is an alias for Net::HTTPHeader#set_form_data. def set_form_data(params, sep = '&') query = URI.encode_www_form(params) query.gsub!(/&/, sep) if sep != '&'