[elpa] externals/plz-see 0dc77f9f69 04/10: Add readme and docstrings

[ELPA Syncer]

branch: externals/plz-see
commit 0dc77f9f6908e1c235523ea7f29a765ce946f812
Author: Augusto Stoffel <arstoffel@gmail.com>
Commit: Augusto Stoffel <arstoffel@gmail.com>

    Add readme and docstrings
---
 README.org | 79 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 plz-see.el | 49 ++++++++++++++++++++++++++++++++++----
 2 files changed, 124 insertions(+), 4 deletions(-)

diff --git a/README.org b/README.org
new file mode 100644
index 0000000000..1c01980d22
--- /dev/null
+++ b/README.org
@@ -0,0 +1,79 @@
+#+title: plz-see.el
+
+=plz-see= is an interactive HTTP client for Emacs based on the 
[[https://github.com/alphapapa/plz.el][plz]]
+library.  It is interactive in the sense that request responses are
+pretty-printed in a pop-up buffer.  It can be used to explore and test
+web APIs or to debug packages that use =plz=.
+
+The main function provided by the package is unsurprisingly named
+=plz-see=, which has the essentially the same API as =plz=.  See the
+docstring for details on the differences.
+
+Additionally, the following variables (which become buffer-local when
+set) are provided for convenience:
+
+- =plz-see-base-url=: Prefix added to the all “relative” URLs passed
+  to =plz-see=.  Paradoxically, a URL in considered relative if it
+  starts with =/=
+- =plz-see-base-headers=: Alist of headers added to all requests.
+  Entries of this list can be overridden using the =HEADERS= argument
+  of =plz-see=.
+
+For further customization options, see =M-x customize-group plz-see RET=.
+
+** Examples
+
+Make a GET request:
+
+#+begin_src emacs-lisp
+(plz-see 'get "https://httpbin.org/get?hello=world";)
+#+end_src
+
+Send some data through a POST request:
+
+#+begin_src emacs-lisp
+(plz-see 'post "https://httpbin.org/post"; :body "Hello World!")
+(plz-see 'post "https://httpbin.org/post"; :body (current-buffer))
+(plz-see 'post "https://httpbin.org/post"; :body '(file "./README.org"))
+#+end_src
+
+Set a base URL to shorten =plz-see= calls in a given buffer:
+
+#+begin_src emacs-lisp
+(setq-local plz-see-base-url "https://httpbin.org";)
+(plz-see 'get "/image/jpeg")
+(plz-see 'get "/status/404")
+#+end_src
+
+Authenticate with username and password, read a bearer token from the
+server response, and store it in the default headers for future use.
+
+#+begin_src emacs-lisp
+(progn
+  (setq-local plz-see-base-url "http://localhost:8080";)
+  (setq-local user "user@example.com" pass "1234"))
+
+(plz-see 'post "/login"
+         :headers '(("Content-Type" . "application/x-www-form-urlencoded"))
+         :body (format "username=%s&password=%s"
+                       (url-hexify-string user)
+                       (url-hexify-string pass))
+         :as 'json-read
+         :then (let ((buffer (current-buffer)))
+                 (lambda (r)
+                   (with-current-buffer buffer
+                     (let ((token (alist-get 'access_token r)))
+                       (setq plz-see-base-headers
+                             `(("Authorization" . ,(concat "Bearer " 
token)))))))))
+
+(plz-see 'get "/authenticated")  ; Yay!
+#+end_src
+
+** Alternatives
+
+There are several alternatives to this package, such as 
[[https://github.com/pashky/restclient.el][restclient]] and
+[[https://github.com/federicotdn/verb][verb]].  They are certainly more fully 
featured than =plz-see= and
+arguably have a more user-friendly notation.
+
+=plz-see= is geared towards those who prefer writing Elisp.  It can
+also be called from Eshell or IELM.
diff --git a/plz-see.el b/plz-see.el
index 96f8429818..2e5451f6d1 100644
--- a/plz-see.el
+++ b/plz-see.el
@@ -67,7 +67,7 @@ If nil, never delete old response buffers."
     (dolist (sym headers)
       (put sym 'risky-local-variable t))
     (cons "" headers))
-  "Header line format for plz-see result buffers."
+  "Header line format for `plz-see' result buffers."
   :type 'sexp)
 
 (defcustom plz-see-headers-buffer nil
@@ -96,7 +96,7 @@ or a buffer name to use a separate buffer."
                 :value-type function))
 
 (defvar-local plz-see-response nil
-  "Store the `plz-response' object in a plz-see buffer.")
+  "Store the `plz-response' object in a `plz-see' buffer.")
 
 (defvar plz-see--buffers '(0 . nil)
   "List of buffers generated by `plz-see'.
@@ -140,6 +140,7 @@ The car is the number of buffers created so far.")
 ;;; Response buffer construction
 
 (defun plz-see--prepare-buffer (response)
+  "Create a prettified buffer from the RESPONSE contents."
   (let* ((buffer (generate-new-buffer
                   (format "*plz-see-%s*" (cl-incf (car plz-see--buffers)))))
          (error (and (plz-error-p response) response))
@@ -165,6 +166,9 @@ The car is the number of buffers created so far.")
       buffer)))
 
 (defun plz-see--continue (as continue)
+  "Continuation function for `plz' call made by `plz-see'.
+CONTINUE is either the THEN or ELSE function of the `plz-see'
+call and AS specifies the argument type they expect."
   (lambda (response)
     (if-let ((curl-error (and (plz-error-p response)
                               (plz-error-curl-error response))))
@@ -187,7 +191,7 @@ The car is the number of buffers created so far.")
 ;;; User commands
 
 (defun plz-see-kill-old-buffers (n)
-  "Kill all but the N most recent plz-see buffers.
+  "Kill all but the N most recent `plz-see' buffers.
 Interactively, N is the prefix argument."
   (interactive "p")
   (let ((buffers (seq-drop plz-see--buffers n)))
@@ -222,6 +226,43 @@ Interactively, N is the prefix argument."
                    &rest rest
                    &key headers then else as
                    &allow-other-keys)
+  "Request METHOD from URL with curl and display the result in a buffer.
+
+HEADERS may be an alist of extra headers to send with the
+request.
+
+BODY may be a string, a buffer, or a list like `(file FILENAME)'
+to upload a file from disk.
+
+AS selects the kind of result to pass to the callback function
+THEN, or the kind of result to return for synchronous requests.
+It may be (note that not all choices provided by the original
+`plz' function are supported):
+
+- `buffer' to pass the response buffer (after prettifying it with
+  one of the `'plz-see-content-type-alist' entries).
+
+- `response' to pass a `plz-response' structure.
+
+- A function, which is called in the response buffer with it
+  narrowed to the response body (suitable for, e.g. `json-read').
+
+THEN is a callback function, whose sole argument is selected
+above with AS; if the request fails and no ELSE function is
+given (see below), the argument will be a `plz-error' structure
+describing the error.  (Note that unlike the original `plz',
+synchronous requests are not supported.)
+
+ELSE is an optional callback function called when the request
+fails (i.e. if curl fails, or if the HTTP response has a non-2xx
+status code).  It is called with one argument, a `plz-error'
+structure.
+
+Other possible keyword arguments are BODY-TYPE, DECODE, FINALLY,
+CONNECT-TIMEOUT, TIMEOUT and NOQUERY.  They are passed directly
+to `plz', which see.
+
+\(To silence checkdoc, we mention the internal argument REST.)"
   (interactive `(get ,(read-from-minibuffer "Make GET request: ")))
   (when (and plz-see-base-url
              (string-prefix-p "/" url))
@@ -233,7 +274,7 @@ Interactively, N is the prefix argument."
          :headers headers
          :as 'response
          :then (plz-see--continue as then)
-         :else (plz-see--continue as else)
+         :else (plz-see--continue as (or else then))
          rest))
 
 (provide 'plz-see)