[elpa] externals/plz 9156de9c59 81/81: Release: 0.1

[ELPA Syncer]

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

    Release: 0.1
    
    Adding Info manual, etc.
---
 .elpaignore |   3 +
 README.org  |  46 +++++++--
 plz.el      |  39 +++++++-
 plz.info    | 310 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 389 insertions(+), 9 deletions(-)

diff --git a/.elpaignore b/.elpaignore
new file mode 100644
index 0000000000..616bc3e6e7
--- /dev/null
+++ b/.elpaignore
@@ -0,0 +1,3 @@
+Makefile
+makem.sh
+NOTES.org
diff --git a/README.org b/README.org
index 2ef7ba2702..632735b61c 100644
--- a/README.org
+++ b/README.org
@@ -22,6 +22,7 @@
 - [[#changelog][Changelog]]
 - [[#credits][Credits]]
 - [[#development][Development]]
+  - [[#copyright-assignment][Copyright assignment]]
 :END:
 
 * Installation
@@ -50,7 +51,7 @@ The only public function is ~plz~, which sends an HTTP 
request and returns eithe
 
 Synchronously =GET= a URL and return the response body as a decoded string 
(here, raw JSON):
 
-#+BEGIN_SRC elisp :exports both :results value code
+#+BEGIN_SRC elisp :exports both :results value code :cache yes
   (plz 'get "https://httpbin.org/user-agent";)
 #+END_SRC
 
@@ -61,7 +62,7 @@ Synchronously =GET= a URL and return the response body as a 
decoded string (here
 
 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
+#+BEGIN_SRC elisp :exports both :results value code :cache yes
   (plz 'get "https://httpbin.org/get"; :as #'json-read)
 #+END_SRC
 
@@ -78,7 +79,7 @@ Synchronously =GET= a URL that returns a JSON object, and 
parse and return it as
 
 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
+#+BEGIN_SRC elisp :exports both :cache yes
   (plz 'post "https://httpbin.org/post";
     :headers '(("Content-Type" . "application/json"))
     :body (json-encode '(("key" . "value")))
@@ -92,7 +93,7 @@ Asynchronously =POST= a JSON object in the request body, then 
parse a JSON objec
 
 Synchronously download a JPEG file, then create an Emacs image object from the 
data:
 
-#+BEGIN_SRC elisp :exports both
+#+BEGIN_SRC elisp :exports both :cache yes
   (let ((jpeg-data (plz 'get "https://httpbin.org/image/jpeg"; :as 'binary)))
     (create-image jpeg-data nil 'data))
 #+END_SRC
@@ -144,9 +145,9 @@ Synchronously download a JPEG file, then create an Emacs 
image object from the d
 :TOC:      :depth 0
 :END:
 
-** 0.1-pre
+** 0.1
 
-Not tagged yet.
+Initial release.
 
 * Credits
 
@@ -156,7 +157,11 @@ Not tagged yet.
 
 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.
+Note that ~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 been 
needed by the author.  Patches are welcome, as long as they include passing 
tests.
+
+** Copyright assignment
+
+This package is part of [[https://www.gnu.org/software/emacs/][GNU Emacs]], 
being distributed in [[https://elpa.gnu.org/][GNU ELPA]].  Contributions to 
this project must follow GNU guidelines, which means that, as with other parts 
of Emacs, patches of more than a few lines must be accompanied by having 
assigned copyright for the contribution to the FSF.  Contributors who wish to 
do so may contact [[mailto:emacs-devel@gnu.org][emacs-devel@gnu.org]] to 
request the assignment form.
 
 * License
 :PROPERTIES:
@@ -165,10 +170,35 @@ Bug reports, feature requests, suggestions — /oh my/!
 
 GPLv3
 
+* COMMENT Export setup                                             :noexport:
+:PROPERTIES:
+:TOC:      :ignore (this descendants)
+:END:
+
+# Copied from org-super-agenda's readme, in which much was borrowed from Org's 
=org-manual.org=.
+
+#+OPTIONS: broken-links:t *:t
+
+** Info export options
+
+#+TEXINFO_DIR_CATEGORY: Emacs
+#+TEXINFO_DIR_TITLE: Plz: (plz)
+#+TEXINFO_DIR_DESC: HTTP library using Curl as a backend
+
+# NOTE: We could use these, but that causes a pointless error, 
"org-compile-file: File "..README.info" wasn't produced...", so we just rename 
the files in the after-save-hook instead.
+# #+TEXINFO_FILENAME: plz.info
+# #+EXPORT_FILE_NAME: plz.texi
+
+** File-local variables
+
+# NOTE: Setting org-comment-string buffer-locally is a nasty hack to work 
around GitHub's org-ruby's HTML rendering, which does not respect noexport 
tags.  The only way to hide this tree from its output is to use the COMMENT 
keyword, but that prevents Org from processing the export options declared in 
it.  So since these file-local variables don't affect org-ruby, wet set 
org-comment-string to an unused keyword, which prevents Org from deleting this 
tree from the export buffer, which all [...]
+
 # Local Variables:
 # eval: (require 'org-make-toc)
+# after-save-hook: (lambda nil (when (and (require 'ox-texinfo nil t) 
(org-texinfo-export-to-info)) (delete-file "README.texi") (rename-file 
"README.info" "plz.info" t)))
 # before-save-hook: org-make-toc
 # org-export-with-properties: ()
 # org-export-with-title: t
+# org-export-initial-scope: buffer
+# org-comment-string: "NOTCOMMENT"
 # End:
-
diff --git a/plz.el b/plz.el
index b016a954e1..e082c9f298 100644
--- a/plz.el
+++ b/plz.el
@@ -5,7 +5,7 @@
 ;; Author: Adam Porter <adam@alphapapa.net>
 ;; Maintainer: Adam Porter <adam@alphapapa.net>
 ;; URL: https://github.com/alphapapa/plz.el
-;; Version: 0.1-pre
+;; Version: 0.1
 ;; Package-Requires: ((emacs "26.3"))
 ;; Keywords: comm, network, http
 
@@ -44,6 +44,43 @@
 ;; 2.  There's already a package called `request'.
 ;; 3.  Naming things is hard.
 
+;;;; Usage:
+
+;; Call function `plz' to make an HTTP request.  Its docstring
+;; explains its arguments.  `plz' also supports other HTTP methods,
+;; uploading and downloading binary files, sending URL parameters and
+;; HTTP headers, configurable timeouts, error-handling "else" and
+;; always-called "finally" functions, and more.
+
+;; Basic usage is simple.  For example, to make a synchronous request
+;; and return the HTTP response body as a string:
+;;
+;;   (plz 'get "https://httpbin.org/get";)
+;;
+;; Which returns the JSON object as a string:
+;;
+;;   "{
+;;     \"args\": {},
+;;     \"headers\": {
+;;       \"Accept\": \"*/*\",
+;;       \"Accept-Encoding\": \"deflate, gzip\",
+;;       \"Host\": \"httpbin.org\",
+;;       \"User-Agent\": \"curl/7.35.0\"
+;;     },
+;;     \"origin\": \"xxx.xxx.xxx.xxx\",
+;;     \"url\": \"https://httpbin.org/get\";
+;;   }"
+;;
+;; To make the same request asynchronously, decoding the JSON and
+;; printing a message with a value from it:
+;;
+;;   (plz 'get "https://httpbin.org/get"; :as #'json-read
+;;     :then (lambda (alist) (message "URL: %s" (alist-get 'url alist))))
+;;
+;; Which, after the request returns, prints:
+;;
+;;   URL: https://httpbin.org/get
+
 ;;;; Credits:
 
 ;; Thanks to Chris Wellons for inspiration, encouragement, and advice.
diff --git a/plz.info b/plz.info
new file mode 100644
index 0000000000..8b7812b9fe
--- /dev/null
+++ b/plz.info
@@ -0,0 +1,310 @@
+This is README.info, produced by makeinfo version 5.2 from README.texi.
+
+INFO-DIR-SECTION Emacs
+START-INFO-DIR-ENTRY
+* Plz: (plz).           HTTP library using Curl as a backend.
+END-INFO-DIR-ENTRY
+
+
+File: README.info,  Node: Top,  Next: Installation,  Up: (dir)
+
+plz.el
+******
+
+‘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
+(https://httpbin.org/).
+
+* Menu:
+
+* Installation::
+* Usage::
+* Changelog::
+* Credits::
+* Development::
+* License::
+
+— The Detailed Node Listing —
+
+Installation
+
+* MELPA::
+* Manual::
+
+Usage
+
+* Examples::
+* Functions::
+* Tips::
+
+Changelog
+
+* 0.1: 01. 
+
+Development
+
+* Copyright assignment::
+
+
+
+File: README.info,  Node: Installation,  Next: Usage,  Prev: Top,  Up: Top
+
+1 Installation
+**************
+
+* Menu:
+
+* MELPA::
+* Manual::
+
+
+File: README.info,  Node: MELPA,  Next: Manual,  Up: Installation
+
+1.1 MELPA
+=========
+
+This library isn’t on MELPA yet.
+
+
+File: README.info,  Node: Manual,  Prev: MELPA,  Up: Installation
+
+1.2 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)’.
+
+
+File: README.info,  Node: Usage,  Next: Changelog,  Prev: Installation,  Up: 
Top
+
+2 Usage
+*******
+
+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.
+
+* Menu:
+
+* Examples::
+* Functions::
+* Tips::
+
+
+File: README.info,  Node: Examples,  Next: Functions,  Up: Usage
+
+2.1 Examples
+============
+
+Synchronously ‘GET’ a URL and return the response body as a decoded
+string (here, raw JSON):
+
+     (plz 'get "https://httpbin.org/user-agent";)
+
+     "{\n \"user-agent\": \"curl/7.35.0\"\n}\n"
+
+   Synchronously ‘GET’ a URL that returns a JSON object, and parse and
+return it as an alist:
+
+     (plz 'get "https://httpbin.org/get"; :as #'json-read)
+
+     ((args)
+      (headers
+       (Accept . "*/*")
+       (Accept-Encoding . "deflate, gzip")
+       (Host . "httpbin.org")
+       (User-Agent . "curl/7.35.0"))
+      (url . "https://httpbin.org/get";))
+
+   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:
+
+     (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))))
+
+     Result: {"key":"value"}
+
+   Synchronously download a JPEG file, then create an Emacs image object
+from the data:
+
+     (let ((jpeg-data (plz 'get "https://httpbin.org/image/jpeg"; :as 'binary)))
+       (create-image jpeg-data nil 'data))
+
+     (image :type jpeg :data ""ÿØÿà^@^PJFIF...")
+
+
+File: README.info,  Node: Functions,  Next: Tips,  Prev: Examples,  Up: Usage
+
+2.2 Functions
+=============
+
+‘plz’
+     _(method url &key headers body else finally noquery (as ’string)
+     (then ’sync) (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, to pass its return value; it is called in the
+          response buffer, which is narrowed to the response body
+          (suitable for, e.g.  ‘json-read’).
+        • ‘file’ to pass a temporary filename to which the response body
+          has been saved without decoding.
+        • ‘(file FILENAME)’ to pass ‘FILENAME’ after having saved the
+          response body to it without decoding.  ‘FILENAME’ must be a
+          non-existent file; if it exists, it will not be overwritten,
+          and an error will be signaled.
+
+     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.
+
+
+File: README.info,  Node: Tips,  Prev: Functions,  Up: Usage
+
+2.3 Tips
+========
+
+   • 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.
+
+
+File: README.info,  Node: Changelog,  Next: Credits,  Prev: Usage,  Up: Top
+
+3 Changelog
+***********
+
+* Menu:
+
+* 0.1: 01. 
+
+
+File: README.info,  Node: 01,  Up: Changelog
+
+3.1 0.1
+=======
+
+Initial release.
+
+
+File: README.info,  Node: Credits,  Next: Development,  Prev: Changelog,  Up: 
Top
+
+4 Credits
+*********
+
+   • Thanks to Chris Wellons (https://github.com/skeeto), author of the
+     Elfeed (https://github.com/skeeto/elfeed) feed reader and the
+     popular blog null program (https://nullprogram.com/), for his
+     invaluable advice, review, and encouragement.
+
+
+File: README.info,  Node: Development,  Next: License,  Prev: Credits,  Up: Top
+
+5 Development
+*************
+
+Bug reports, feature requests, suggestions — _oh my_!
+
+   Note that ‘plz’ is a young library, and its only client so far is
+Ement.el (https://github.com/alphapapa/ement.el).  There are a variety
+of HTTP and ‘curl’ features it does not yet support, since they have not
+been needed by the author.  Patches are welcome, as long as they include
+passing tests.
+
+* Menu:
+
+* Copyright assignment::
+
+
+File: README.info,  Node: Copyright assignment,  Up: Development
+
+5.1 Copyright assignment
+========================
+
+This package is part of GNU Emacs (https://www.gnu.org/software/emacs/),
+being distributed in GNU ELPA (https://elpa.gnu.org/).  Contributions to
+this project must follow GNU guidelines, which means that, as with other
+parts of Emacs, patches of more than a few lines must be accompanied by
+having assigned copyright for the contribution to the FSF.  Contributors
+who wish to do so may contact emacs-devel@gnu.org <emacs-devel@gnu.org>
+to request the assignment form.
+
+
+File: README.info,  Node: License,  Prev: Development,  Up: Top
+
+6 License
+*********
+
+GPLv3
+
+
+
+Tag Table:
+Node: Top199
+Node: Installation943
+Node: MELPA1083
+Node: Manual1209
+Node: Usage1488
+Node: Examples1976
+Node: Functions3343
+Node: Tips6234
+Node: Changelog6536
+Node: 016662
+Node: Credits6745
+Node: Development7111
+Node: Copyright assignment7625
+Node: License8213
+
+End Tag Table
+
+
+Local Variables:
+coding: utf-8
+End: