标题: plz.el

属性: LOGGING nil

注意：最好将这些内容放在文件底部的导出选项标题下，但似乎"TEXINFO_DIR_CATEGORY"只在文件顶部有效。

EXPORT_FILE_NAME: plz.texi

TEXINFO_DIR_CATEGORY: Emacs

TEXINFO_DIR_TITLE: Plz: (plz)

TEXINFO_DIR_DESC: 使用Curl作为后端的HTTP库

注意：本README与org-make-toc https://github.com/alphapapa/org-make-toc包配合使用，该包会自动更新目录。

[[http://elpa.gnu.org/packages/plz.html][file:http://elpa.gnu.org/packages/plz.svg]]

#+HTML: <img src="https://yellow-cdn.veclightyear.com/835a84d5/3ac9e63d-7987-4135-9361-211a4caa0d16.png" align="right">

~~plz~~是一个Emacs的HTTP库。它使用~~curl~~作为后端，避免了使用Emacs内置~~url~~库的一些问题。它支持同步和异步请求。其API旨在简单、自然且富有表现力。其代码旨在简洁且组织良好。每个功能都经过[[https://httpbin.org/][httpbin]]的测试。

目录 :noexport: :PROPERTIES: :TOC: :include siblings :END: :CONTENTS:

[[#installation][安装]]
[[#usage][使用]]
- [[#examples][示例]]
- [[#functions][函数]]
- [[#queueing][队列]]
[[#changelog][更新日志]]
[[#credits][致谢]]
[[#development][开发]]
- [[#copyright-assignment][版权声明]] :END:

安装 :PROPERTIES: :TOC: :depth 0 :END:

** GNU ELPA

~~plz~~可在[[http://elpa.gnu.org/packages/plz.html][GNU ELPA]]中获取。可以在Emacs中使用~~package-install~~命令安装。

** 手动安装

~~plz~~除了Emacs和~~curl~~外没有其他依赖。它已知可在Emacs 26.3或更高版本上运行。要手动安装，只需将=plz.el=放入您的~~load-path~~中，然后执行~(require 'plz)~。

使用 :PROPERTIES: :TOC: :depth 1 :END:

主要的公共函数是~~plz~~，它发送HTTP请求并返回指定类型的结果（对于同步请求），或~~curl~~进程对象（对于异步请求）。对于异步请求，可以指定回调函数、错误处理函数和终结器函数，以及各种其他选项。

** 示例

同步GET一个URL并将响应体作为解码后的字符串返回（这里是原始JSON）：

#+BEGIN_SRC elisp :exports both :results value code :cache yes (plz 'get "https://httpbin.org/user-agent") #+END_SRC

#+RESULTS[47fef7e4780e9fac6c99d7661c29de580bf0fa14]: #+begin_src elisp "{\n "user-agent": "curl/7.35.0"\n}\n" #+end_src

同步GET一个返回JSON对象的URL，并将其解析并作为关联列表返回：

#+BEGIN_SRC elisp :exports both :results value code :cache yes (plz 'get "https://httpbin.org/get" :as #'json-read) #+END_SRC

#+RESULTS[a117174ba62b2be3ea3f23e5c43662047b81bccf]: #+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

异步POST一个JSON对象在请求体中，然后从响应体中解析JSON对象，并用结果调用一个函数：

#+BEGIN_SRC elisp :exports both :cache yes (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[3f4fdd16c4980bf36c3930e91f69cc379cca4a35]: : Result: {"key":"value"}

同步下载一个JPEG文件，然后从数据创建一个Emacs图像对象：

#+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

#+RESULTS[fbe8a6c8cb097ac08e992ea90bdbd50e7337a385]: : (image :type jpeg :data ""ÿØÿà^@^PJFIF...")

** 函数

~~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))/

使用curl请求~~URL~~的~~METHOD~~。返回curl进程对象，或对于同步请求，返回选定的结果。

~~HEADERS~~可以是一个与请求一起发送的额外头部的关联列表。

~~BODY~~可以是一个字符串、一个缓冲区，或者像~(file FILENAME)~这样的列表，用于从磁盘上传文件。

~~BODY-TYPE~~可以是~~text~~以文本形式发送~~BODY~~，或~~binary~~以二进制形式发送。

AS选择要传递给回调函数~~THEN~~的结果类型，或同步请求要返回的结果类型。它可以是：
- ~~buffer~~传递响应缓冲区，该缓冲区将被缩小到响应体并根据~~DECODE~~进行解码。
- ~~binary~~将响应体作为未解码的字符串传递。
- ~~string~~将响应体作为解码后的字符串传递。
- ~~response~~传递一个~~plz-response~~结构。
- ~~file~~传递一个临时文件名，响应体已被保存到该文件中而未解码。
- (file ~~FILENAME)~~在将响应体保存到~~FILENAME~~后传递它，而不解码。~~FILENAME~~必须是不存在的文件；如果它存在，将不会被覆盖，并会发出错误信号。~~FILENAME~~通过expand-file-name~处理，请参见该函数。
- 一个函数，在响应缓冲区中调用，并将其缩小到响应体（适用于例如~~json-read~~）。
如果~~DECODE~~为非nil，响应体会自动解码。对于二进制内容，它应该为nil。当AS为~~binary~~时，~~DECODE~~自动设置为nil。

~~THEN~~是一个回调函数，其唯一参数由上面的AS选择；如果请求失败且未给出~~ELSE~~函数（见下文），参数将是描述错误的~~plz-error~~结构。或者~~THEN~~可以是~~sync~~以进行同步请求，在这种情况下，结果直接从这个函数返回。

~~ELSE~~是一个可选的回调函数，在请求失败时调用（即如果curl失败，或者如果~~HTTP~~响应有非2xx状态码）。它以一个~~plz-error~~结构作为参数调用。如果~~ELSE~~为nil，当请求失败时会发出~~plz-curl-error~~或~~plz-http-error~~信号，并带有~~plz-error~~结构作为错误数据。对于同步请求，此参数被忽略。

注意：在~~plz~~的v0.8版本中，只会发出一个错误信号：~~plz-error~~。现有的错误，~~plz-curl-error~~和~~plz-http-error~~，继承自~~plz-error~~，以允许应用程序在使用v0.7时更新其代码（即任何~~condition-case~~形式现在应该只处理~~plz-error~~，而不是其他两个）。

~~FINALLY~~是一个可选函数，在~~THEN~~或~~ELSE~~之后适当调用，不带参数。对于同步请求，此参数被忽略。

~~CONNECT-TIMEOUT~~和~~TIMEOUT~~是限制连接到主机和从主机接收响应所需时间的秒数。

~~NOQUERY~~传递给~~make-process~~，请参见该函数。 ~~FILTER~~ 是一个可选函数，用作 curl 进程的过滤器。它可以用于以流式方式处理 HTTP 响应。该函数必须接受两个参数:运行 curl 的进程对象，以及从进程接收到的输出字符串。默认的进程过滤器将进程的输出插入到进程缓冲区中。提供的 ~~FILTER~~ 函数至少应将输出插入到进程缓冲区中直到 HTTP 正文部分。

** 队列

~~plz~~ 提供了一个简单的系统来队列 HTTP 请求。首先，通过调用 ~~make-plz-queue~~ 创建一个 ~~plz-queue~~ 结构体。然后用该结构体作为第一个参数调用 ~~plz-queue~~，其余参数与传递给 ~~plz~~ 的参数相同。最后调用 ~~plz-run~~ 来运行队列中的请求。

所有与队列相关的函数都返回队列作为它们的值，使其易于使用。例如:

#+begin_src elisp :exports code (defvar my-queue (make-plz-queue :limit 2))

(plz-run (plz-queue my-queue 'get "https://httpbin.org/get?foo=0" :then (lambda (body) (message "%s" body)))) #+end_src

或者:

#+begin_src elisp :exports code (let ((queue (make-plz-queue :limit 2 :finally (lambda () (message "队列为空。")))) (urls '("https://httpbin.org/get?foo=0" "https://httpbin.org/get?foo=1"))) (plz-run (dolist (url urls queue) (plz-queue queue 'get url :then (lambda (body) (message "%s" body)))))) #+end_src

你也可以用 ~~plz-clear~~ 清空队列，它会取消任何活动或排队的请求并调用它们的 ~~:else~~ 函数。~~plz-length~~ 返回队列中活动和排队请求的数量。

** 提示

你可以在 =plz= 组中自定义设置，但这只能用于调整一些默认值。正常操作不需要更改或绑定全局变量。

更新日志

** 0.10-pre

暂无新内容。

** 0.9.1

修复

下载到文件时展开文件名(这已经应用于上传时传递的文件名)。(感谢 [[https://github.com/josephmturner][Joseph Turner]])

** 0.9

兼容性

现在支持的最低 Emacs 版本为 27.1。(不再实际测试 ~~plz~~ 与早于 27.1 的 Emacs 版本。对于 Emacs 26.3，可以使用早期版本的 ~~plz~~，或者此版本可能兼容，无需或仅需少量修改，但维护者不提供支持。)

新增

下载到文件时，会向 Curl 传递 ~~--create-dirs~~ 选项，以便自动创建任何必要的子目录。([[https://github.com/alphapapa/plz.el/pull/64][#64]]。感谢 [[https://github.com/josephmturner][Joseph Turner]] 和 [[https://ushin.org/][USHIN]])

更改

移除 ~~plz-timeout~~ 选项。(它是 ~~plz~~ 的 ~~:timeout~~ 参数的默认值，该参数传递给 Curl 作为其 ~~--max-time~~ 参数，限制请求操作的总持续时间。此参数默认应未设置，因为较大或较慢的下载可能无法在特定时间内完成，默认设置此选项对用户来说是出乎意料的，可能导致请求不必要地超时。)
使用参数 ~~:as 'file~~ 或 ~~:as '(file FILENAME)~~ 现在将文件名传递给 Curl，允许它直接将数据写入文件(而不是将数据接收到 Emacs 缓冲区然后写入文件。这在下载大文件时提高了性能，显著减少了 Emacs 的 CPU 和内存使用)。

修复

改进了对 Emacs 进程哨兵相关问题的解决方案。(如果 Emacs 在 ~~plz~~ 为同步请求返回后调用哨兵，则不尝试第二次处理响应。参见 [[https://github.com/alphapapa/plz.el/issues/53][#53]]。感谢 [[https://github.com/josephmturner][Joseph Turner]] 的大量调试帮助，以及 [[https://ushin.org/][USHIN]] 赞助的部分工作。)
调用 ~~generate-new-buffer~~ 时禁用缓冲区钩子(作为额外保护，防止在出错时出现"kill buffer?"提示)。(参见 [[https://github.com/alphapapa/plz.el/pull/52][#52]]。感谢 [[https://github.com/mkcms][Michał Krzywkowski]]。)
- 在 Emacs 28 之前的版本中，避免在出错时出现"kill buffer?"提示。(参见 [[https://github.com/alphapapa/plz.el/pull/52][#52]] 和 [[https://github.com/alphapapa/plz.el/issues/57][#57]]。感谢 [[https://github.com/mkcms][Michał Krzywkowski]]。)

开发

~~plz~~ 现在自动测试 Emacs 版本 27.1、27.2、28.1、28.2、29.1、29.2、29.3 和 ~~master~~ 分支的最新快照(新增 29.2 和 29.3)。

** 0.8

新增

函数 ~~plz~~ 现在接受 ~~:filter~~ 参数，可用于覆盖默认的进程过滤器(例如用于流式响应)。([[https://github.com/alphapapa/plz.el/pull/43][#43]], [[https://github.com/alphapapa/plz.el/pull/50][#50]]。感谢 [[https://github.com/r0man][Roman Scherer]]。)

** 0.7.3

修复

修复在 GNU ELPA 上生成 Info 手册的问题。(同时，Info 手册不再提交到 Git。)

** 0.7.2

修复

下载到文件时不删除预先存在的文件。([[https://github.com/alphapapa/plz.el/pull/41][#41]]。感谢 [[https://github.com/josephmturner][Joseph Turner]]。)

** 0.7.1

修复

处理 HTTP 303 重定向。(感谢 [[https://github.com/hubisan][Daniel Hubmann]] 的报告。)

** 0.7

更改

定义了一个新的错误信号 ~~plz-error~~。现有的信号 ~~plz-curl-error~~ 和 ~~plz-http-error~~ 继承自它，因此处理 ~~plz-error~~ 可以捕获这两种错误。

注意: 现有的信号 ~~plz-curl-error~~ 和 ~~plz-http-error~~ 在此被废弃，它们将在 v0.8 中移除。应用程序应在使用 v0.7 时更新，只期望 ~~plz-error~~。

修复

通过实施故障保护和解决 Emacs 进程处理代码的问题，显著提高了可靠性。(参见 [[https://github.com/alphapapa/plz.el/issues/3][#3]]。)
curl 进程的 STDERR 输出不再包含在响应正文中(这种情况有时会发生，取决于 Emacs 的内部竞争条件)。(修复 [[https://github.com/alphapapa/plz.el/issues/23][#23]]。)
对同步请求使用 ~~with-local-quit~~(防止 Emacs 有时抱怨)。(修复 [[https://github.com/alphapapa/plz.el/issues/26][#26]]。)
对 ~~:as 'buffer~~ 结果类型进行了各种修复:在适当时解码正文；对二进制设置非多字节；缩小到正文；不过早杀死缓冲区。
清空队列时，不尝试杀死已完成的进程。

内部

响应处理现在在进程哨兵之外进行，因此任何错误(例如在用户回调中)不会从哨兵内部发出信号。(这避免了 Emacs 在这种情况下强加的 2 秒暂停。)
测试运行在 [[https://github.com/postmanlabs/httpbin][httpbin]] 的本地实例上(因为 ~~httpbin.org~~ 服务器经常过载)。
不再定义缓冲区局部变量；改用进程属性。

** 0.6

新增

函数 ~~plz~~ 的 ~~:body~~ 参数现在接受一个类似 ~~(file FILENAME)~~ 的列表，用于从磁盘上传文件(通过将文件名传递给 curl，而不是将其内容读入 Emacs 并通过管道发送给 curl)。

修复

函数 ~~plz~~ 的文档字符串现在提到 ~~:body~~ 参数也可以是一个缓冲区(这是一个有意的功能，但意外地未记录)。
使用 ~~:as 'response~~ 时处理 HTTP 3xx 重定向。

** 0.5.4 修复

仅在队列为空后运行队列的 ~~finally~~ 函数。（新功能不应在周五设计和发布。）

** 0.5.3

修复

将 ~~plz-queue~~ 结构中的新槽移至末尾，以防止已编译应用程序的无效字节编译器扩展（这需要在升级 ~~plz~~ 后重新编译它们）。

** 0.5.2

修复

清除队列时，仅在指定时调用 ~~plz-queue~~ 的 ~~finally~~ 函数。

** 0.5.1

修复

仅在指定时调用 ~~plz-queue~~ 的 ~~finally~~ 函数。（感谢 [[https://github.com/redchops][Dan Oriani]] 报告。）

** 0.5

新增

~~plz-queue~~ 结构的 ~~finally~~ 槽，一个在队列完成时调用的函数。

** 0.4

新增

支持 HTTP ~~HEAD~~ 请求。（感谢 [[https://ushin.org/][USHIN]] 赞助。）

变更

允许发送无主体的 ~~POST~~ 和 ~~PUT~~ 请求。（[[https://github.com/alphapapa/plz.el/issues/16][#16]]。感谢 [[https://github.com/josephmturner][Joseph Turner]] 报告。感谢 [[https://ushin.org/][USHIN]] 赞助。）

修复

所有 2xx HTTP 状态码都被视为成功。（[[https://github.com/alphapapa/plz.el/issues/17][#17]]。感谢 [[https://github.com/josephmturner][Joseph Turner]] 报告。感谢 [[https://ushin.org/][USHIN]] 赞助。）
错误信号包含正确的错误数据。

内部

测试套件明确测试 HTTP/1.1 和 HTTP/2。
测试套件还测试 Emacs 版本 27.2、28.1 和 28.2。

** 0.3

新增

处理来自 Curl 的 HTTP 代理头。（[[https://github.com/alphapapa/plz.el/issues/2][#2]]。感谢 [[https://github.com/alanthird][Alan Third]] 和 [[https://github.com/sawyerzheng][Sawyer Zheng]] 报告。）

修复

替换了 Ispell 默认词典中没有的单词（以使 ~~checkdoc~~ 检查通过）。

** 0.2.1

修复

处理 Curl 进程被中断的情况。

** 0.2

新增

简单的请求队列。

** 0.1

初始发布。

致谢

感谢 [[https://github.com/skeeto][Chris Wellons]]，[[https://github.com/skeeto/elfeed][Elfeed]] 订阅阅读器的作者和热门博客 [[https://nullprogram.com/][null program]] 的作者，感谢他宝贵的建议、审查和鼓励。

开发

错误报告、功能请求、建议 — 真是太好了！

请注意，~~plz~~ 是一个年轻的库，目前它唯一的客户端是 [[https://github.com/alphapapa/ement.el][Ement.el]]。有许多 HTTP 和 ~~curl~~ 功能它还不支持，因为作者还没有需要它们。欢迎提交补丁，只要它们包含通过的测试。

** 版权转让

这个包是 [[https://www.gnu.org/software/emacs/][GNU Emacs]] 的一部分，在 [[https://elpa.gnu.org/][GNU ELPA]] 中分发。对这个项目的贡献必须遵循 GNU 的指导原则，这意味着，与 Emacs 的其他部分一样，超过几行的补丁必须附带将贡献的版权转让给 FSF。希望这样做的贡献者可以联系 [[mailto:emacs-devel@gnu.org][emacs-devel@gnu.org]] 请求转让表格。