http.client-docs: Added documentation for HEAD, TRACE, OPTIONS and DELETE methods

diff --git a/basis/http/client/client-docs.factor b/basis/http/client/client-docs.factor
index d5f50de109c408d35a0ba381c7942d4df866c6f9..5a5460a17928e315d6ae72e4584f2fb798725921 100644 (file)
--- a/basis/http/client/client-docs.factor
+++ b/basis/http/client/client-docs.factor
@@ -20,6 +20,26 @@ HELP: <post-request>
 { $description "Constructs an HTTP POST request for submitting post data to the URL." }
 { $notes "The request can be passed on to " { $link http-request } ", possibly after cookies and headers are set." } ;
 
+HELP: <head-request>
+{ $values { "url" "a " { $link url } " or " { $link string } } { "request" request } }
+{ $description "Constructs an HTTP HEAD request for retrieving the URL." }
+{ $notes "The request can be passed on to " { $link http-request } ", possibly after cookies and headers are set." } ;
+
+HELP: <delete-request>
+{ $values { "url" "a " { $link url } " or " { $link string } } { "request" request } }
+{ $description "Constructs an HTTP DELETE request for the requested URL." }
+{ $notes "The request can be passed on to " { $link http-request } ", possibly after cookies and headers are set." } ;
+
+HELP: <options-request>
+{ $values { "url" "a " { $link url } " or " { $link string } } { "request" request } }
+{ $description "Constructs an HTTP OPTIONS request for the requested URL." }
+{ $notes "The request can be passed on to " { $link http-request } ", possibly after cookies and headers are set." } ;
+
+HELP: <trace-request>
+{ $values { "url" "a " { $link url } " or " { $link string } } { "request" request } }
+{ $description "Constructs an HTTP TRACE request for the requested URL." }
+{ $notes "The request can be passed on to " { $link http-request } ", possibly after cookies and headers are set." } ;
+
 HELP: download
 { $values { "url" "a " { $link url } " or " { $link string } } }
 { $description "Downloads the contents of the URL to a file in the " { $link current-directory } " having the same file name." }
@@ -45,6 +65,26 @@ HELP: http-put
 { $description "Submits an HTTP PUT request." }
 { $errors "Throws an error if the HTTP request fails." } ;
 
+HELP: http-head
+{ $values { "url" "a " { $link url } " or " { $link string } } { "response" response } { "data" sequence } }
+{ $description "Same as " { $link http-get } " except that the server is not supposed to return a message-body in the response, as per RFC2616. However in practise, most web servers respond to GET and HEAD method calls with identical responses." }
+{ $errors "Throws an error if the HTTP request fails." } ;
+ 
+HELP: http-delete
+{ $values { "url" "a " { $link url } " or " { $link string } } { "response" response } { "data" sequence } }
+{ $description "Requests that the origin server delete the resource identified by the URL." }
+{ $errors "Throws an error if the HTTP request fails." } ;
+
+HELP: http-options
+{ $values { "url" "a " { $link url } " or " { $link string } } { "response" response } { "data" sequence } }
+{ $description "Submits an HTTP OPTIONS request." }
+{ $errors "Throws an error if the HTTP request fails." } ;
+
+HELP: http-trace
+{ $values { "url" "a " { $link url } " or " { $link string } } { "response" response } { "data" sequence } }
+{ $description "Submits an HTTP TRACE request." }
+{ $errors "Throws an error if the HTTP request fails." } ;
+
 HELP: with-http-get
 { $values { "url" "a " { $link url } " or " { $link string } } { "quot" { $quotation "( chunk -- )" } } { "response" response } }
 { $description "Downloads the contents of a URL. Chunks of data are passed to the quotation as they are read." }
@@ -110,6 +150,39 @@ ARTICLE: "http.client.put" "PUT requests with the HTTP client"
 { $subsections <post-request> }
 "Both words take a post data parameter; see " { $link "http.client.post-data" } "." ;
 
+ARTICLE: "http.client.head" "HEAD requests with the HTTP client"
+"Basic usage involves passing a " { $link url } " and getting a " { $link response } " and data back:"
+{ $subsections http-head }
+"Advanced usage involves constructing a " { $link request } ", which allows " { $link "http.cookies" } " and " { $link "http.headers" } " to be set:"
+{ $subsections
+    <head-request>
+} ;
+
+ARTICLE: "http.client.delete" "DELETE requests with the HTTP client"
+"Basic usage involves passing a " { $link url } " and getting a " { $link response } " and data back:"
+{ $subsections http-delete }
+"Advanced usage involves constructing a " { $link request } ", which allows " { $link "http.cookies" } " and " { $link "http.headers" } " to be set:"
+{ $subsections
+    <delete-request>
+} ;
+
+ARTICLE: "http.client.options" "OPTIONS requests with the HTTP client"
+"Basic usage involves passing a " { $link url } " and getting a " { $link response } " and data back:"
+{ $subsections http-options }
+"Advanced usage involves constructing a " { $link request } ", which allows " { $link "http.cookies" } " and " { $link "http.headers" } " to be set:"
+{ $subsections
+    <options-request>
+}
+"RFC2616 does not define any use for an entity body, yet allows for the inclusion of one as part of the OPTIONS method. This is not supported with this version of the http.client. The current implementation of http-options only supports a " { $link url } " request with no corresponding post-data, as per the stack effect." ;
+
+ARTICLE: "http.client.trace" "TRACE requests with the HTTP client"
+"Basic usage involves passing a " { $link url } " and getting a " { $link response } " and data back:"
+{ $subsections http-trace }
+"Advanced usage involves constructing a " { $link request } ", which allows " { $link "http.cookies" } " and " { $link "http.headers" } " to be set:"
+{ $subsections
+    <trace-request>
+} ;
+
 ARTICLE: "http.client.encoding" "Character encodings and the HTTP client"
 "The " { $link http-request } ", " { $link http-get } " and " { $link http-post } " words output a sequence containing data that was sent by the server."
 $nl
@@ -139,6 +212,13 @@ $nl
 }
 "Submission data for POST and PUT requests:"
 { $subsections "http.client.post-data" }
+"Other HTTP methods are also supported:"
+{ $subsections
+    "http.client.head"
+    "http.client.delete"
+    "http.client.options"
+    "http.client.trace"
+}
 "More esoteric use-cases, for example HTTP methods other than the above, are accommodated by constructing an empty request object with " { $link <request> } " and filling everything in by hand."
 { $subsections
     "http.client.encoding"