[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[elpa] externals/plz 9156de9c59 81/81: Release: 0.1
From: |
ELPA Syncer |
Subject: |
[elpa] externals/plz 9156de9c59 81/81: Release: 0.1 |
Date: |
Wed, 11 May 2022 17:58:04 -0400 (EDT) |
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:
- [elpa] externals/plz f2176dc56c 60/81: Change/Fix: Avoid command-line arguments, (continued)
- [elpa] externals/plz f2176dc56c 60/81: Change/Fix: Avoid command-line arguments, ELPA Syncer, 2022/05/11
- [elpa] externals/plz ac5bc006f3 62/81: Docs: Add readme, ELPA Syncer, 2022/05/11
- [elpa] externals/plz 278391562a 69/81: Docs: Tidy, ELPA Syncer, 2022/05/11
- [elpa] externals/plz a5ccf48d80 70/81: Tests: Add check/error to a test, ELPA Syncer, 2022/05/11
- [elpa] externals/plz 2f48423834 72/81: Docs: Add mascot, ELPA Syncer, 2022/05/11
- [elpa] externals/plz 0b32c64f77 74/81: Notes: Rename file, ELPA Syncer, 2022/05/11
- [elpa] externals/plz 7e456638a6 75/81: Meta: Move notes to orphan branch, ELPA Syncer, 2022/05/11
- [elpa] externals/plz 69d5bf74f6 77/81: Fix: (plz--coding-system) Alist key, ELPA Syncer, 2022/05/11
- [elpa] externals/plz 1d3efc036c 78/81: Add: (plz) DELETE method, ELPA Syncer, 2022/05/11
- [elpa] externals/plz 9e308f1833 80/81: Meta: Tidy headers, etc. for ELPA, ELPA Syncer, 2022/05/11
- [elpa] externals/plz 9156de9c59 81/81: Release: 0.1,
ELPA Syncer <=
- [elpa] externals/plz bca0b3112b 20/81: Tidy, ELPA Syncer, 2022/05/11
- [elpa] externals/plz 2b51ecd6be 27/81: Meta: Add test.yml for GitHub Actions, ELPA Syncer, 2022/05/11
- [elpa] externals/plz 4f74be6565 30/81: Notes: Add idea, ELPA Syncer, 2022/05/11
- [elpa] externals/plz fbdcd69950 09/81: Changes, ELPA Syncer, 2022/05/11
- [elpa] externals/plz 4588884c11 10/81: Changes, ELPA Syncer, 2022/05/11
- [elpa] externals/plz 2c19b7f11d 11/81: Changes, ELPA Syncer, 2022/05/11
- [elpa] externals/plz 6a21c7e809 12/81: Significant changes, ELPA Syncer, 2022/05/11
- [elpa] externals/plz 5b00a61ce3 15/81: Rename functions, ELPA Syncer, 2022/05/11
- [elpa] externals/plz 370d0bbc1a 21/81: Tidy, ELPA Syncer, 2022/05/11
- [elpa] externals/plz 971077e1d3 23/81: Tests, ELPA Syncer, 2022/05/11