[elpa] externals/plz ac5bc006f3 62/81: Docs: Add readme

[ELPA Syncer]

branch: externals/plz
commit ac5bc006f3e212db0c4bb7496146c1dbe2fa8c5a
Author: Adam Porter <adam@alphapapa.net>
Commit: Adam Porter <adam@alphapapa.net>

    Docs: Add readme
---
 README.org | 161 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 161 insertions(+)

diff --git a/README.org b/README.org
new file mode 100644
index 0000000000..beb08a1d90
--- /dev/null
+++ b/README.org
@@ -0,0 +1,161 @@
+#+TITLE: plz.el
+
+#+PROPERTY: LOGGING nil
+
+# Note: This readme works with the org-make-toc 
<https://github.com/alphapapa/org-make-toc> package, which automatically 
updates the table of contents.
+
+# 
[[https://melpa.org/#/package-name][file:https://melpa.org/packages/plz-badge.svg]]
 
[[https://stable.melpa.org/#/package-name][file:https://stable.melpa.org/packages/plz-badge.svg]]
+
+~plz~ is an HTTP library for Emacs.  It uses ~curl~ as a backend, which avoids 
some of the issues with using Emacs's built-in ~url~ library.  It supports both 
synchronous and asynchronous requests.  Its API is intended to be simple, 
natural, and expressive.  Its code is intended to be simple and well-organized. 
 Every feature is tested against [[httpbin.org/][httpbin]].
+
+* Contents                                                         :noexport:
+:PROPERTIES:
+:TOC:      :include siblings
+:END:
+:CONTENTS:
+- [[#installation][Installation]]
+- [[#usage][Usage]]
+  - [[#examples][Examples]]
+  - [[#functions][Functions]]
+- [[#changelog][Changelog]]
+- [[#credits][Credits]]
+- [[#development][Development]]
+:END:
+
+* Installation
+:PROPERTIES:
+:TOC:      :depth 0
+:END:
+
+** MELPA
+
+# If you installed from MELPA, you're done.
+
+This library isn't on MELPA yet.
+
+** Manual
+
+ ~plz~ has no dependencies other than Emacs and ~curl~.  It's known to work on 
Emacs 26.3 or later.  Simply place =plz.el= in your ~load-path~ and ~(require 
'plz)~.
+
+* Usage
+:PROPERTIES:
+:TOC:      :depth 1
+:END:
+
+The only public function is ~plz~, which sends an HTTP request and returns 
either the result of the specified type (for a synchronous request), or the 
~curl~ process object (for asynchronous requests).  For asynchronous requests, 
callback, error-handling, and finalizer functions may be specified, as well as 
various other options.
+
+** Examples
+
+Synchronously =GET= a URL that returns a JSON object, and parse and return it 
as an alist:
+
+#+BEGIN_SRC elisp :exports both :results value code
+  (plz 'get "https://httpbin.org/get";
+    :as #'json-read :then 'sync)
+#+END_SRC
+
+#+RESULTS:
+#+BEGIN_SRC elisp
+  ((args)
+   (headers
+    (Accept . "*/*")
+    (Accept-Encoding . "deflate, gzip")
+    (Host . "httpbin.org")
+    (User-Agent . "curl/7.35.0"))
+   (url . "https://httpbin.org/get";))
+#+END_SRC
+
+Asynchronously =POST= a JSON object in the request body, then parse a JSON 
object from the response body, and call a function with the result:
+
+#+BEGIN_SRC elisp :exports both
+  (plz 'post "https://httpbin.org/post";
+    :headers '(("Content-Type" . "application/json"))
+    :body (json-encode '(("key" . "value")))
+    :as #'json-read
+    :then (lambda (alist)
+            (message "Result: %s" (alist-get 'data alist))))
+#+END_SRC
+
+#+RESULTS:
+: Result: {"key":"value"}
+
+Synchronously download a JPEG file, then create an Emacs image object from the 
data:
+
+#+BEGIN_SRC elisp :exports both
+  (let ((jpeg-data (plz 'get "https://httpbin.org/image/jpeg";
+                     :as 'binary :then 'sync)))
+    (create-image jpeg-data nil 'data))
+#+END_SRC
+
+#+RESULTS:
+: (image :type jpeg :data ""ÿØÿà^@^PJFIF...")
+
+** Functions
+
++ ~plz~ :: /(method url &key headers body as then else finally noquery 
(body-type 'text) (decode t decode-s) (connect-timeout plz-connect-timeout) 
(timeout plz-timeout))/
+
+  Request ~METHOD~ from ~URL~ with curl.  Return the curl process object or, 
for a synchronous request, the selected result.
+
+  ~HEADERS~ may be an alist of extra headers to send with the request.
+
+  ~BODY-TYPE~ may be ~text~ to send ~BODY~ as text, or ~binary~ to send it as 
binary.
+
+  ~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:
+
+    - ~buffer~ to pass the response buffer.
+    - ~binary~ to pass the response body as an undecoded string.
+    - ~string~ to pass the response body as a decoded string.
+    - ~response~ to pass a ~plz-response~ struct.
+    - A function, which is called in the response buffer with it narrowed to 
the response body (suitable for, e.g. ~json-read~).
+
+  If ~DECODE~ is non-nil, the response body is decoded automatically.  For 
binary content, it should be nil.  When ~AS~ is ~binary~, ~DECODE~ is 
automatically set to nil.
+
+  ~THEN~ is a callback function, whose sole argument is selected above with 
~AS~.  Or ~THEN~ may be ~sync~ to make a synchronous request, in which case the 
result is returned directly.
+
+  ~ELSE~ is an optional callback function called when the request fails with 
one argument, a ~plz-error~ struct.  If ~ELSE~ is nil, an error is signaled 
when the request fails, either ~plz-curl-error~ or ~plz-http-error~ as 
appropriate, with a ~plz-error~ struct as the error data.  For synchronous 
requests, this argument is ignored.
+
+  ~FINALLY~ is an optional function called without argument after ~THEN~ or 
~ELSE~, as appropriate.  For synchronous requests, this argument is ignored.
+
+  ~CONNECT-TIMEOUT~ and ~TIMEOUT~ are a number of seconds that limit how long 
it takes to connect to a host and to receive a response from a host, 
respectively.
+
+  ~NOQUERY~ is passed to ~make-process~, which see.
+
+** Tips
+:PROPERTIES:
+:TOC:      :ignore (this)
+:END:
+
++ You can customize settings in the =plz= group, but this can only be used to 
adjust a few defaults.  It's not intended that changing or binding global 
variables be necessary for normal operation.
+
+* Changelog
+:PROPERTIES:
+:TOC:      :depth 0
+:END:
+
+** 0.1-pre
+
+Not tagged yet.
+
+* Credits
+
++  Thanks to [[https://github.com/skeeto][Chris Wellons]], author of the 
[[https://github.com/skeeto/elfeed][Elfeed]] feed reader and the popular blog 
[[https://nullprogram.com/][null program]], for his invaluable advice, review, 
and encouragement.
+
+* Development
+
+Bug reports, feature requests, suggestions — /oh my/!
+
+~plz~ is a young library, and its only client so far is 
[[https://github.com/alphapapa/ement.el][Ement.el]].  There are a variety of 
HTTP and ~curl~ features it does not yet support, since they have not yet been 
needed by the author.  Patches are welcome, as long as they include passing 
tests.
+
+* License
+:PROPERTIES:
+:TOC:      :ignore (this)
+:END:
+
+GPLv3
+
+# Local Variables:
+# eval: (require 'org-make-toc)
+# before-save-hook: org-make-toc
+# org-export-with-properties: ()
+# org-export-with-title: t
+# End:
+