From 21538fc0240bba207f2900be9a6cc5d79065b8e0 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Wed, 18 May 2022 09:56:32 -0500 Subject: [PATCH] Enhanced RDoc for Net::HTTP --- lib/net/http.rb | 133 ++++++++++++++++++++++++++++++++++++------------ 1 file changed, 101 insertions(+), 32 deletions(-) diff --git a/lib/net/http.rb b/lib/net/http.rb index acfdbec4..56292495 100644 --- a/lib/net/http.rb +++ b/lib/net/http.rb @@ -36,7 +36,7 @@ class HTTPHeaderSyntaxError < StandardError; end # # Net::HTTP provides a rich library which can be used to build HTTP # user-agents. For more details about HTTP see - # [RFC2616](http://www.ietf.org/rfc/rfc2616.txt). + # {RFC2616}[https://datatracker.ietf.org/doc/html/rfc2616]. # # Net::HTTP is designed to work closely with URI. URI::HTTP#host, # URI::HTTP#port and URI::HTTP#request_uri are designed to work with @@ -44,17 +44,21 @@ class HTTPHeaderSyntaxError < StandardError; end # # If you are only performing a few GET requests you should try OpenURI. # - # == Simple Examples + # == About the Examples + # + # Many examples on this page refer to one of these two websites: + # + # - {Example Domain}[http://www.example.com]. + # - {JSONPlaceholder}[https://jsonplaceholder.typicode.com]. # # All examples assume you have loaded Net::HTTP with: # # require 'net/http' # - # This will also require 'uri' so you don't need to require it separately. + # == Simple Examples # - # The Net::HTTP methods in the following section do not persist - # connections. They are not recommended if you are performing many HTTP - # requests. + # The Net::HTTP methods in this section do not persist connections. + # They are not recommended if you are performing many HTTP requests. # # === GET # @@ -433,20 +437,41 @@ class << HTTP # short cut methods # + # Prints the body text from the target to $stdout; + # returns +nil+. + # + # The target may be specified either as: + # + # - A URI: # - # Gets the body text from the target and outputs it to $stdout. The - # target can either be specified as - # (+uri+, +headers+), or as (+host+, +path+, +port+ = 80); so: + # uri = URI('https://jsonplaceholder.typicode.com/todos/1') + # Net::HTTP.get_print(uri) # - # Net::HTTP.get_print URI('http://www.example.com/index.html') + # With this form, you may specify a hash of headers: # - # or: + # headers = {Accept: 'text/json'} + # Net::HTTP.get_print(uri, headers) # - # Net::HTTP.get_print 'www.example.com', '/index.html' + # - Host and path: # - # you can also specify request headers: + # host = 'jsonplaceholder.typicode.com' + # path = '/todos/1' + # Net::HTTP.get_print(host, path) # - # Net::HTTP.get_print URI('http://www.example.com/index.html'), { 'Accept' => 'text/html' } + # With this form, you may specify an integer port: + # + # Net::HTTP.get_print(host, path, 80) + # + # Any of the above prints: + # + # { + # "userId": 1, + # "id": 1, + # "title": "delectus aut autem", + # "completed": false + # } + # + # Related: HTTP.get, HTTP.get_response. # def HTTP.get_print(uri_or_host, path_or_headers = nil, port = nil) get_response(uri_or_host, path_or_headers, port) {|res| @@ -457,39 +482,83 @@ def HTTP.get_print(uri_or_host, path_or_headers = nil, port = nil) nil end - # Sends a GET request to the target and returns the HTTP response - # as a string. The target can either be specified as - # (+uri+, +headers+), or as (+host+, +path+, +port+ = 80); so: + # Returns the body text (string) from the target to $stdout. + # + # The target may be specified either as: + # + # - A URI: # - # print Net::HTTP.get(URI('http://www.example.com/index.html')) + # uri = URI('https://jsonplaceholder.typicode.com/todos/1') + # puts Net::HTTP.get(uri) # - # or: + # With this form, you may specify a hash of headers: # - # print Net::HTTP.get('www.example.com', '/index.html') + # headers = {Accept: 'text/json'} + # puts Net::HTTP.get(uri, headers) # - # you can also specify request headers: + # - Host and path: # - # Net::HTTP.get(URI('http://www.example.com/index.html'), { 'Accept' => 'text/html' }) + # host = 'jsonplaceholder.typicode.com' + # path = '/todos/1' + # puts Net::HTTP.get(host, path) + # + # With this form, you may specify an integer port: + # + # puts Net::HTTP.get(host, path, 80) + # + # Any of the above prints (via +puts+): + # + # { + # "userId": 1, + # "id": 1, + # "title": "delectus aut autem", + # "completed": false + # } + # + # Related: HTTP.get_print, HTTP.get_response. # def HTTP.get(uri_or_host, path_or_headers = nil, port = nil) get_response(uri_or_host, path_or_headers, port).body end - # 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+, +headers+), or as (+host+, +path+, +port+ = 80); so: + # Gets the response from the target as an instance + # of a subclass of HTTPResponse (such as HTTPOK). + # + # With no block given, returns the response; + # with a block given, calls the block with the response + # and returns the block's value. + # + # The target may be specified either as: + # + # - A URI: + # + # uri = URI('https://jsonplaceholder.typicode.com/todos/1') + # Net::HTTP.get_response(uri) + # # => # + # Net::HTTP.get_response(uri) {|response| p response.class } + # # Prints Net::HTTPOK + # + # With this form, you may specify a hash of headers: + # + # headers = {Accept: 'text/json'} + # Net::HTTP.get_response(uri, headers) + # # => # # - # res = Net::HTTP.get_response(URI('http://www.example.com/index.html')) - # print res.body + # - Host and path: # - # or: + # host = 'jsonplaceholder.typicode.com' + # path = '/todos/1' + # Net::HTTP.get_response(host, path) + # # => # + # Net::HTTP.get_response(host, path) {|response| p response.class } + # # Prints Net::HTTPOK # - # res = Net::HTTP.get_response('www.example.com', '/index.html') - # print res.body + # With this form, you may specify an integer port: # - # you can also specify request headers: + # Net::HTTP.get_response(host, path, 80) + # # => # # - # Net::HTTP.get_response(URI('http://www.example.com/index.html'), { 'Accept' => 'text/html' }) + # Related: HTTP.get_print, HTTP.get. # def HTTP.get_response(uri_or_host, path_or_headers = nil, port = nil, &block) if path_or_headers && !path_or_headers.is_a?(Hash)