From 170c2949eacd9a168f760bdd53837b9b857ca128 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Sun, 11 Dec 2022 22:54:04 +0000 Subject: [PATCH 1/3] Enhanced RDoc for HTTPHeader --- lib/net/http/header.rb | 147 ++++++++++++++++++++++++++++++++--------- 1 file changed, 117 insertions(+), 30 deletions(-) diff --git a/lib/net/http/header.rb b/lib/net/http/header.rb index 3c95ee33..0e80d927 100644 --- a/lib/net/http/header.rb +++ b/lib/net/http/header.rb @@ -381,11 +381,11 @@ def each_header #:yield: +key+, +value+ # # Output: # - # "content-type" - # "connection" - # "cache-control" - # "cf-cache-status" - # "cf-ray" + # "content-type" + # "connection" + # "cache-control" + # "cf-cache-status" + # "cf-ray" # # Returns an enumerator if no block is given. # @@ -610,8 +610,19 @@ def set_range(r, e = nil) alias range= set_range - # Returns an Integer object which represents the HTTP Content-Length: - # header field, or +nil+ if that field was not provided. + # Returns the value of field 'Content-Length' as an integer, + # or +nil+ if there is no such field; + # see {Content-Length request header}[https://en.wikipedia.org/wiki/List_of_HTTP_header_fields#content-length-request-header]: + # + # res = Net::HTTP.start(hostname) do |http| + # http.get('/nosuch/1') + # end # => # + # res.content_length # => 2 + # res = Net::HTTP.start(hostname) do |http| + # http.get('/todos/1') + # end # => # + # res.content_length # => nil + # def content_length return nil unless key?('Content-Length') len = self['Content-Length'].slice(/\d+/) or @@ -619,6 +630,20 @@ def content_length len.to_i end + # Sets the value of field 'Content-Length' to the given numeric; + # see {Content-Length response header}[https://en.wikipedia.org/wiki/List_of_HTTP_header_fields#content-length-response-header]: + # + # _uri = uri.dup + # hostname = _uri.hostname # => "jsonplaceholder.typicode.com" + # _uri.path = '/posts' # => "/posts" + # req = Net::HTTP::Post.new(_uri) # => # + # req.body = '{"title": "foo","body": "bar","userId": 1}' + # req.content_length = req.body.size # => 42 + # req.content_type = 'application/json' + # res = Net::HTTP.start(hostname) do |http| + # http.request(req) + # end # => # + # def content_length=(len) unless len @header.delete 'content-length' @@ -627,20 +652,35 @@ def content_length=(len) @header['content-length'] = [len.to_i.to_s] end - # Returns "true" if the "transfer-encoding" header is present and - # set to "chunked". This is an HTTP/1.1 feature, allowing - # the content to be sent in "chunks" without at the outset - # stating the entire content length. + # Returns +true+ if field 'Transfer-Encoding' + # exists and has value 'chunked', + # +false+ otherwise; + # see {Transfer-Encoding response header}[https://en.wikipedia.org/wiki/List_of_HTTP_header_fields#transfer-encoding-response-header]: + # + # res = Net::HTTP.start(hostname) do |http| + # http.get('/todos/1') + # end # => # + # res['Transfer-Encoding'] # => "chunked" + # res.chunked? # => true + # def chunked? return false unless @header['transfer-encoding'] field = self['Transfer-Encoding'] (/(?:\A|[^\-\w])chunked(?![\-\w])/i =~ field) ? true : false end - # 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. + # Returns a Range object representing the value of field + # 'Content-Range', or +nil+ if no such field exists; + # see {Content-Range response header}[https://en.wikipedia.org/wiki/List_of_HTTP_header_fields#content-range-response-header]: + # + # res = Net::HTTP.start(hostname) do |http| + # http.get('/todos/1') + # end # => # + # res['Content-Range'] # => nil + # res['Content-Range'] = 'bytes 0-499/1000' + # res['Content-Range'] # => "bytes 0-499/1000" + # res.content_range # => 0..499 + # def content_range return nil unless @header['content-range'] m = %r<\A\s*(\w+)\s+(\d+)-(\d+)/(\d+|\*)>.match(self['Content-Range']) or @@ -649,14 +689,33 @@ def content_range m[2].to_i .. m[3].to_i end - # The length of the range represented in Content-Range: header. + # Returns the integer representing length of the value of field + # 'Content-Range', or +nil+ if no such field exists; + # see {Content-Range response header}[https://en.wikipedia.org/wiki/List_of_HTTP_header_fields#content-range-response-header]: + # + # res = Net::HTTP.start(hostname) do |http| + # http.get('/todos/1') + # end # => # + # res['Content-Range'] # => nil + # res['Content-Range'] = 'bytes 0-499/1000' + # res.range_length # => 500 + # def range_length r = content_range() or return nil r.end - r.begin + 1 end - # Returns a content type string such as "text/html". - # This method returns nil if Content-Type: header field does not exist. + # Returns the {media type}[https://en.wikipedia.org/wiki/Media_type] + # from the value of field 'Content-Type', + # or +nil+ if no such field exists; + # see {Content-Type response header}[https://en.wikipedia.org/wiki/List_of_HTTP_header_fields#content-type-response-header]: + # + # res = Net::HTTP.start(hostname) do |http| + # http.get('/todos/1') + # end # => # + # res['content-type'] # => "application/json; charset=utf-8" + # res.content_type # => "application/json" + # def content_type return nil unless main_type() if sub_type() @@ -665,16 +724,35 @@ def content_type end end - # Returns a content type string such as "text". - # This method returns nil if Content-Type: header field does not exist. + # Returns the leading ('type') part of the + # {media type}[https://en.wikipedia.org/wiki/Media_type] + # from the value of field 'Content-Type', + # or +nil+ if no such field exists; + # see {Content-Type response header}[https://en.wikipedia.org/wiki/List_of_HTTP_header_fields#content-type-response-header]: + # + # res = Net::HTTP.start(hostname) do |http| + # http.get('/todos/1') + # end # => # + # res['content-type'] # => "application/json; charset=utf-8" + # res.main_type # => "application" + # def main_type return nil unless @header['content-type'] self['Content-Type'].split(';').first.to_s.split('/')[0].to_s.strip end - # Returns a content type string such as "html". - # This method returns nil if Content-Type: header field does not exist - # or sub-type is not given (e.g. "Content-Type: text"). + # Returns the trailing ('subtype') part of the + # {media type}[https://en.wikipedia.org/wiki/Media_type] + # from the value of field 'Content-Type', + # or +nil+ if no such field exists; + # see {Content-Type response header}[https://en.wikipedia.org/wiki/List_of_HTTP_header_fields#content-type-response-header]: + # + # res = Net::HTTP.start(hostname) do |http| + # http.get('/todos/1') + # end # => # + # res['content-type'] # => "application/json; charset=utf-8" + # res.sub_type # => "json" + # def sub_type return nil unless @header['content-type'] _, sub = *self['Content-Type'].split(';').first.to_s.split('/') @@ -682,9 +760,16 @@ def sub_type sub.strip end - # 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'} + # Returns the trailing ('parameters') part of the value of field 'Content-Type', + # or +nil+ if no such field exists; + # see {Content-Type response header}[https://en.wikipedia.org/wiki/List_of_HTTP_header_fields#content-type-response-header]: + # + # res = Net::HTTP.start(hostname) do |http| + # http.get('/todos/1') + # end # => # + # res['content-type'] # => "application/json; charset=utf-8" + # res.type_params # => {"charset"=>"utf-8"} + # def type_params result = {} list = self['Content-Type'].to_s.split(';') @@ -696,10 +781,12 @@ def type_params result end - # 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'}. + # Sets the value of field 'Content-Type'; + # returns the new value; + # see {Content-Type request header}[https://en.wikipedia.org/wiki/List_of_HTTP_header_fields#content-type-request-header]: + # + # req = Net::HTTP::Get.new(uri) + # req.set_content_type('application/json') # => ["application/json"] # # Net::HTTPHeader#content_type= is an alias for Net::HTTPHeader#set_content_type. def set_content_type(type, params = {}) From 921b6907abae8f484c147f1f00f26d4481a3d996 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Mon, 12 Dec 2022 18:58:07 +0000 Subject: [PATCH 2/3] Enhanced RDoc for HTTPHeader --- lib/net/http/header.rb | 66 +++++++++++------------------------------- 1 file changed, 17 insertions(+), 49 deletions(-) diff --git a/lib/net/http/header.rb b/lib/net/http/header.rb index 0e80d927..c354f8fc 100644 --- a/lib/net/http/header.rb +++ b/lib/net/http/header.rb @@ -207,9 +207,7 @@ def size #:nodoc: obsolete # or +nil+ if there is no such key; # see {Fields}[rdoc-ref:Net::HTTPHeader@Fields]: # - # res = Net::HTTP.start(hostname) do |http| - # http.get('/todos/1') - # end + # res = Net::HTTP.get(hostname, '/todos/1') # res['Connection'] # => "keep-alive" # res['Nosuch'] # => nil # @@ -293,9 +291,7 @@ def add_field(key, val) # or +nil+ if there is no such field; # see {Fields}[rdoc-ref:Net::HTTPHeader@Fields]: # - # res = Net::HTTP.start(hostname) do |http| - # http.get('/todos/1') - # end + # res = Net::HTTP.get(hostname, '/todos/1') # res.get_fields('Connection') # => ["keep-alive"] # res.get_fields('Nosuch') # => nil # @@ -314,9 +310,7 @@ def get_fields(key) # ignores the +default_val+; # see {Fields}[rdoc-ref:Net::HTTPHeader@Fields]: # - # res = Net::HTTP.start(hostname) do |http| - # http.get('/todos/1') - # end + # res = Net::HTTP.get(hostname, '/todos/1') # # # Field exists; block not called. # res.fetch('Connection') do |value| @@ -343,9 +337,7 @@ def fetch(key, *args, &block) #:yield: +key+ # Calls the block with each key/value pair: # - # res = Net::HTTP.start(hostname) do |http| - # http.get('/todos/1') - # end + # res = Net::HTTP.get(hostname, '/todos/1') # res.each_header do |key, value| # p [key, value] if key.start_with?('c') # end @@ -372,9 +364,7 @@ def each_header #:yield: +key+, +value+ # Calls the block with each field key: # - # res = Net::HTTP.start(hostname) do |http| - # http.get('/todos/1') - # end + # res = Net::HTTP.get(hostname, '/todos/1') # res.each_key do |key| # p key if key.start_with?('c') # end @@ -399,9 +389,7 @@ def each_name(&block) #:yield: +key+ # Calls the block with each capitalized field name: # - # res = Net::HTTP.start(hostname) do |http| - # http.get('/todos/1') - # end + # res = Net::HTTP.get(hostname, '/todos/1') # res.each_capitalized_name do |key| # p key if key.start_with?('C') # end @@ -427,9 +415,7 @@ def each_capitalized_name #:yield: +key+ # Calls the block with each string field value: # - # res = Net::HTTP.start(hostname) do |http| - # http.get('/todos/1') - # end + # res = Net::HTTP.get(hostname, '/todos/1') # res.each_value do |value| # p value if value.start_with?('c') # end @@ -614,13 +600,9 @@ def set_range(r, e = nil) # or +nil+ if there is no such field; # see {Content-Length request header}[https://en.wikipedia.org/wiki/List_of_HTTP_header_fields#content-length-request-header]: # - # res = Net::HTTP.start(hostname) do |http| - # http.get('/nosuch/1') - # end # => # + # res = Net::HTTP.get(hostname, '/nosuch/1') # res.content_length # => 2 - # res = Net::HTTP.start(hostname) do |http| - # http.get('/todos/1') - # end # => # + # res = Net::HTTP.get(hostname, '/todos/1') # res.content_length # => nil # def content_length @@ -652,14 +634,12 @@ def content_length=(len) @header['content-length'] = [len.to_i.to_s] end - # Returns +true+ if field 'Transfer-Encoding' + # Returns +true+ if field 'Transfer-Encoding' # exists and has value 'chunked', # +false+ otherwise; # see {Transfer-Encoding response header}[https://en.wikipedia.org/wiki/List_of_HTTP_header_fields#transfer-encoding-response-header]: # - # res = Net::HTTP.start(hostname) do |http| - # http.get('/todos/1') - # end # => # + # res = Net::HTTP.get(hostname, '/todos/1') # res['Transfer-Encoding'] # => "chunked" # res.chunked? # => true # @@ -673,9 +653,7 @@ def chunked? # 'Content-Range', or +nil+ if no such field exists; # see {Content-Range response header}[https://en.wikipedia.org/wiki/List_of_HTTP_header_fields#content-range-response-header]: # - # res = Net::HTTP.start(hostname) do |http| - # http.get('/todos/1') - # end # => # + # res = Net::HTTP.get(hostname, '/todos/1') # res['Content-Range'] # => nil # res['Content-Range'] = 'bytes 0-499/1000' # res['Content-Range'] # => "bytes 0-499/1000" @@ -693,9 +671,7 @@ def content_range # 'Content-Range', or +nil+ if no such field exists; # see {Content-Range response header}[https://en.wikipedia.org/wiki/List_of_HTTP_header_fields#content-range-response-header]: # - # res = Net::HTTP.start(hostname) do |http| - # http.get('/todos/1') - # end # => # + # res = Net::HTTP.get(hostname, '/todos/1') # res['Content-Range'] # => nil # res['Content-Range'] = 'bytes 0-499/1000' # res.range_length # => 500 @@ -710,9 +686,7 @@ def range_length # or +nil+ if no such field exists; # see {Content-Type response header}[https://en.wikipedia.org/wiki/List_of_HTTP_header_fields#content-type-response-header]: # - # res = Net::HTTP.start(hostname) do |http| - # http.get('/todos/1') - # end # => # + # res = Net::HTTP.get(hostname, '/todos/1') # res['content-type'] # => "application/json; charset=utf-8" # res.content_type # => "application/json" # @@ -730,9 +704,7 @@ def content_type # or +nil+ if no such field exists; # see {Content-Type response header}[https://en.wikipedia.org/wiki/List_of_HTTP_header_fields#content-type-response-header]: # - # res = Net::HTTP.start(hostname) do |http| - # http.get('/todos/1') - # end # => # + # res = Net::HTTP.get(hostname, '/todos/1') # res['content-type'] # => "application/json; charset=utf-8" # res.main_type # => "application" # @@ -747,9 +719,7 @@ def main_type # or +nil+ if no such field exists; # see {Content-Type response header}[https://en.wikipedia.org/wiki/List_of_HTTP_header_fields#content-type-response-header]: # - # res = Net::HTTP.start(hostname) do |http| - # http.get('/todos/1') - # end # => # + # res = Net::HTTP.get(hostname, '/todos/1') # res['content-type'] # => "application/json; charset=utf-8" # res.sub_type # => "json" # @@ -764,9 +734,7 @@ def sub_type # or +nil+ if no such field exists; # see {Content-Type response header}[https://en.wikipedia.org/wiki/List_of_HTTP_header_fields#content-type-response-header]: # - # res = Net::HTTP.start(hostname) do |http| - # http.get('/todos/1') - # end # => # + # res = Net::HTTP.get(hostname, '/todos/1') # res['content-type'] # => "application/json; charset=utf-8" # res.type_params # => {"charset"=>"utf-8"} # From e59ba2fb7e7061e9baa3a0ccbb395f0a7f002fd3 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Mon, 12 Dec 2022 19:14:07 +0000 Subject: [PATCH 3/3] Enhanced RDoc for HTTPHeader --- lib/net/http/header.rb | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/lib/net/http/header.rb b/lib/net/http/header.rb index c354f8fc..17977e1c 100644 --- a/lib/net/http/header.rb +++ b/lib/net/http/header.rb @@ -207,7 +207,7 @@ def size #:nodoc: obsolete # or +nil+ if there is no such key; # see {Fields}[rdoc-ref:Net::HTTPHeader@Fields]: # - # res = Net::HTTP.get(hostname, '/todos/1') + # res = Net::HTTP.get_response(hostname, '/todos/1') # res['Connection'] # => "keep-alive" # res['Nosuch'] # => nil # @@ -291,7 +291,7 @@ def add_field(key, val) # or +nil+ if there is no such field; # see {Fields}[rdoc-ref:Net::HTTPHeader@Fields]: # - # res = Net::HTTP.get(hostname, '/todos/1') + # res = Net::HTTP.get_response(hostname, '/todos/1') # res.get_fields('Connection') # => ["keep-alive"] # res.get_fields('Nosuch') # => nil # @@ -310,7 +310,7 @@ def get_fields(key) # ignores the +default_val+; # see {Fields}[rdoc-ref:Net::HTTPHeader@Fields]: # - # res = Net::HTTP.get(hostname, '/todos/1') + # res = Net::HTTP.get_response(hostname, '/todos/1') # # # Field exists; block not called. # res.fetch('Connection') do |value| @@ -337,7 +337,7 @@ def fetch(key, *args, &block) #:yield: +key+ # Calls the block with each key/value pair: # - # res = Net::HTTP.get(hostname, '/todos/1') + # res = Net::HTTP.get_response(hostname, '/todos/1') # res.each_header do |key, value| # p [key, value] if key.start_with?('c') # end @@ -364,7 +364,7 @@ def each_header #:yield: +key+, +value+ # Calls the block with each field key: # - # res = Net::HTTP.get(hostname, '/todos/1') + # res = Net::HTTP.get_response(hostname, '/todos/1') # res.each_key do |key| # p key if key.start_with?('c') # end @@ -389,7 +389,7 @@ def each_name(&block) #:yield: +key+ # Calls the block with each capitalized field name: # - # res = Net::HTTP.get(hostname, '/todos/1') + # res = Net::HTTP.get_response(hostname, '/todos/1') # res.each_capitalized_name do |key| # p key if key.start_with?('C') # end @@ -415,7 +415,7 @@ def each_capitalized_name #:yield: +key+ # Calls the block with each string field value: # - # res = Net::HTTP.get(hostname, '/todos/1') + # res = Net::HTTP.get_response(hostname, '/todos/1') # res.each_value do |value| # p value if value.start_with?('c') # end @@ -600,9 +600,9 @@ def set_range(r, e = nil) # or +nil+ if there is no such field; # see {Content-Length request header}[https://en.wikipedia.org/wiki/List_of_HTTP_header_fields#content-length-request-header]: # - # res = Net::HTTP.get(hostname, '/nosuch/1') + # res = Net::HTTP.get_response(hostname, '/nosuch/1') # res.content_length # => 2 - # res = Net::HTTP.get(hostname, '/todos/1') + # res = Net::HTTP.get_response(hostname, '/todos/1') # res.content_length # => nil # def content_length @@ -639,7 +639,7 @@ def content_length=(len) # +false+ otherwise; # see {Transfer-Encoding response header}[https://en.wikipedia.org/wiki/List_of_HTTP_header_fields#transfer-encoding-response-header]: # - # res = Net::HTTP.get(hostname, '/todos/1') + # res = Net::HTTP.get_response(hostname, '/todos/1') # res['Transfer-Encoding'] # => "chunked" # res.chunked? # => true # @@ -653,7 +653,7 @@ def chunked? # 'Content-Range', or +nil+ if no such field exists; # see {Content-Range response header}[https://en.wikipedia.org/wiki/List_of_HTTP_header_fields#content-range-response-header]: # - # res = Net::HTTP.get(hostname, '/todos/1') + # res = Net::HTTP.get_response(hostname, '/todos/1') # res['Content-Range'] # => nil # res['Content-Range'] = 'bytes 0-499/1000' # res['Content-Range'] # => "bytes 0-499/1000" @@ -671,7 +671,7 @@ def content_range # 'Content-Range', or +nil+ if no such field exists; # see {Content-Range response header}[https://en.wikipedia.org/wiki/List_of_HTTP_header_fields#content-range-response-header]: # - # res = Net::HTTP.get(hostname, '/todos/1') + # res = Net::HTTP.get_response(hostname, '/todos/1') # res['Content-Range'] # => nil # res['Content-Range'] = 'bytes 0-499/1000' # res.range_length # => 500 @@ -686,7 +686,7 @@ def range_length # or +nil+ if no such field exists; # see {Content-Type response header}[https://en.wikipedia.org/wiki/List_of_HTTP_header_fields#content-type-response-header]: # - # res = Net::HTTP.get(hostname, '/todos/1') + # res = Net::HTTP.get_response(hostname, '/todos/1') # res['content-type'] # => "application/json; charset=utf-8" # res.content_type # => "application/json" # @@ -704,7 +704,7 @@ def content_type # or +nil+ if no such field exists; # see {Content-Type response header}[https://en.wikipedia.org/wiki/List_of_HTTP_header_fields#content-type-response-header]: # - # res = Net::HTTP.get(hostname, '/todos/1') + # res = Net::HTTP.get_response(hostname, '/todos/1') # res['content-type'] # => "application/json; charset=utf-8" # res.main_type # => "application" # @@ -719,7 +719,7 @@ def main_type # or +nil+ if no such field exists; # see {Content-Type response header}[https://en.wikipedia.org/wiki/List_of_HTTP_header_fields#content-type-response-header]: # - # res = Net::HTTP.get(hostname, '/todos/1') + # res = Net::HTTP.get_response(hostname, '/todos/1') # res['content-type'] # => "application/json; charset=utf-8" # res.sub_type # => "json" # @@ -734,7 +734,7 @@ def sub_type # or +nil+ if no such field exists; # see {Content-Type response header}[https://en.wikipedia.org/wiki/List_of_HTTP_header_fields#content-type-response-header]: # - # res = Net::HTTP.get(hostname, '/todos/1') + # res = Net::HTTP.get_response(hostname, '/todos/1') # res['content-type'] # => "application/json; charset=utf-8" # res.type_params # => {"charset"=>"utf-8"} #