Good signature from 066DAFCB81E42C40 GNU ELPA Signing Agent (2019) <elpasign@elpa.gnu.org> (trust undefined) created at 2023-07-09T17:05:02-0400 using RSA

;;; test-plz.el --- Tests for plz          -*- lexical-binding: t; -*-
;; Copyright (C) 2019-2022  Free Software Foundation, Inc.
;; Author: Adam Porter <adam@alphapapa.net>
;; Maintainer: Adam Porter <adam@alphapapa.net>
;; This file is part of GNU Emacs.
;;; License:
;; This program is free software; you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation, either version 3 of the License, or
;; (at your option) any later version.
;; This program is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;; GNU General Public License for more details.
;; You should have received a copy of the GNU General Public License
;; along with this program.  If not, see <https://www.gnu.org/licenses/>.
;;; Commentary:
;; NOTE: NOTE: NOTE: NOTE: Yes, four NOTEs, because this is important:
;; As of this moment, all of the tests pass when run with makem.sh.
;; And when running them in an interactive Emacs with ERT, one test at
;; a time, individual tests pass, or almost always do (depending on
;; whether the httpbin.org server is overloaded).  But when running
;; multiple tests in ERT at one time,
;; i.e. (ert-run-tests-interactively "plz-"), multiple, if not most,
;; tests fail, but not the same ones every time.
;; I have now spent hours trying to figure out why, inserting many
;; debug statements in many functions, and come up with nothing.  I
;; tried changing the way `accept-process-output' is called, like
;; using timeouts or JUST-THIS-ONE, but it made no difference.  I
;; tried calling it extra times, nope.  I tried calling the sentinel
;; extra times when it seemed that it hadn't run the THEN function,
;; nope.  Nothing seems to make a difference.
;; I even checked out an earlier commit, before the commit that
;; rewrote/merged the synchronous request code into the `plz'
;; function, thinking that surely I broke something--but, nope, they
;; apparently failed the same way back then: passing with makem.sh,
;; passing individually, but failing when run in close succession by
;; ERT.
;; After inserting enough debug statements, I noticed that the process
;; sentinel sometimes seemed to run for the last time after the ERT
;; test had returned, which suggests that ERT might be doing something
;; weird, or somehow its instrumentation interferes with the
;; process-handling code.  But if that's not the cause, then I'm out
;; of ideas.
;; So then I tried rewriting the synchronous request code to use
;; `call-process-region', instead of calling `accept-process-output'
;; in a loop to block on the curl process (which is how the Elisp
;; manual says to do it), but that still made no difference: even the
;; async requests fail in the same way with ERT.  So that doesn't
;; appear to be the problem, either.
;; So is there some kind of fundamental flaw in the `plz' design?
;; Maybe.  Is there a simple, logical oversight in its code that only
;; manifests under certain conditions?  Maybe.  Is ERT doing something
;; weird that's interfering with process-related code?  Maybe.  Is
;; Emacs's own process-handling code still broken in some mysterious
;; way?  Maybe.
;; But despite all of that, when using `plz' "in anger", in `ement',
;; it seems to work reliably for me.  I did get one report from one
;; user that sounded like the same kind of problem I'm seeing with ERT
;; here, but then he tried `ement-connect' again, and it worked.  And
;; I'm sitting here watching `ement' constantly using `plz' to talk to
;; the matrix.org server, and I haven't had a single error or failure,
;; even after hours of being connected.  It *seems* to *actually*
;; work.
;; So, if you're reading this, and you're wondering whether you should
;; use `plz': Well, please do, and please let me know if you have any
;; problems; I do need to know whether it's working for other users.
;; And if you think you might know what's going wrong when running the
;; tests in ERT, please let me know, because I'm out of ideas: as far
;; as I can tell, when it comes to process-handling in Emacs, "there
;; be dragons."
;;; Code:
;;;; Requirements
(require 'ert)
(require 'json)
(require 'let-alist)
(require 'map)
(require 'plz)
;;;; Variables
(defvar plz-test-uri-prefix
  ;; "https://httpbin.org"
  "http://localhost"
  "URI prefix for HTTP requests, without trailing slash.
If running httpbin locally, set to \"http://localhost\".")
;;;; Customization
;;;; Commands
;;;; Macros
(cl-defun plz-test-wait (process &optional (seconds 0.1) (times 100))
  "Wait for SECONDS seconds TIMES times for PROCESS to finish."
  (when process
    ;; Sometimes it seems that the process is killed, the THEN
    ;; function called by its sentinel, and its buffer killed, all
    ;; before this function gets called with the process argument;
    ;; when that happens, tests that use this can fail.  Testing
    ;; whether PROCESS is non-nil seems to fix it, but it's possible
    ;; that something funny is going on...
    (cl-loop for i upto times ;; 10 seconds
             while (equal 'run (process-status process))
             do (sleep-for seconds))))
(cl-defmacro plz-deftest (name () &body docstring-keys-and-body)
  "Like `ert-deftest', but defines tests for both HTTP/1.1 and HTTP/2."
  (declare (debug (&define [&name "test@" symbolp]
			   sexp [&optional stringp]
			   [&rest keywordp sexp] def-body))
           (doc-string 3)
           (indent 2))
  `(progn
     ,@(cl-loop for http-version in '("1.1" "2")
                collect (let ((name (intern (format "%s-http%s" name http-version))))
                          `(ert-deftest ,name ()
                             (let ((plz-curl-default-args
                                    ',(append plz-curl-default-args (list (format "--http%s" http-version)))))
                               ,@docstring-keys-and-body))))))
;;;; Functions
(defun plz-test-url (url-part)
  "Return URL-PART appended to `plz-test-uri-prefix'.
Also, any instance of \"URI-PREFIX\" in URL-PART is replaced with
`plz-test-uri-prefix' in URL-encoded form."
  (setf url-part (replace-regexp-in-string "URI-PREFIX" (url-hexify-string plz-test-uri-prefix)
                                           url-part t t))
  (concat plz-test-uri-prefix url-part))
(defmacro plz-test-get-response (response)
  "Test parts of RESPONSE with `should'."
  `(progn
     (should (plz-response-p ,response))
     (should (numberp (plz-response-version ,response)))
     (should (eq 200 (plz-response-status ,response)))
     (should (equal "application/json" (alist-get 'content-type (plz-response-headers ,response))))
     (should (string-match "curl"
                           (map-nested-elt (json-read-from-string (plz-response-body ,response))
                                           '(headers User-Agent))))))
;;;; Tests
;;;;; Async
(plz-deftest plz-get-string nil
  (let* ((test-string)
         (process (plz 'get (plz-test-url "/get")
                    :as 'string
                    :then (lambda (string)
                            (setf test-string string)))))
    (plz-test-wait process)
    (should (string-match "curl" test-string))))
(plz-deftest plz-get-buffer nil
  (let* ((result-buffer)
         (process (plz 'get (plz-test-url "/get")
                    :as 'buffer :then (lambda (buffer)
                                        (setf result-buffer buffer)))))
    (unwind-protect
        (progn
          (plz-test-wait process)
          (should (buffer-live-p result-buffer))
          (with-current-buffer result-buffer
            (should-not (looking-at-p plz-http-response-status-line-regexp))
            (should (string-match "curl" (buffer-string)))))
      (kill-buffer result-buffer)
      (should-not (buffer-live-p result-buffer)))))
(plz-deftest plz-get-response nil
  (let* ((test-response)
         (process (plz 'get (plz-test-url "/get")
                    :as 'response
                    :then (lambda (response)
                            (setf test-response response)))))
    (plz-test-wait process)
    (plz-test-get-response test-response)))
(plz-deftest plz-get-json nil
  (let* ((test-json)
         (process (plz 'get (plz-test-url "/get")
                    :as #'json-read
                    :then (lambda (json)
                            (setf test-json json)))))
    (plz-test-wait process)
    (let-alist test-json
      (should (string-match "curl" .headers.User-Agent)))))
(plz-deftest plz-post-json-string nil
  (let* ((json-string (json-encode (list (cons "key" "value"))))
         (response-json)
         (process (plz 'post (plz-test-url "/post")
                    :headers '(("Content-Type" . "application/json"))
                    :body json-string
                    :as #'json-read
                    :then (lambda (json)
                            (setf response-json json)))))
    (plz-test-wait process)
    (let-alist response-json
      (should (string-match "curl" .headers.User-Agent))
      (should (string= "value" (alist-get 'key (json-read-from-string .data)))))))
(plz-deftest plz-post-jpeg-string nil
  (let* ((jpeg-to-upload (plz 'get (plz-test-url "/image/jpeg")
                           :as 'binary :then 'sync))
         (_ (unless jpeg-to-upload
              (error "jpeg-to-upload is nil")))
         (response-json)
         (response-jpeg)
         (process (plz 'post (plz-test-url "/post")
                    :headers '(("Content-Type" . "image/jpeg"))
                    :body jpeg-to-upload :body-type 'binary
                    :as #'json-read
                    :then (lambda (json)
                            (setf response-json json
                                  response-jpeg
                                  (base64-decode-string
                                   (string-remove-prefix "data:application/octet-stream;base64,"
                                                         (alist-get 'data json))))))))
    (should (equal 'jpeg (image-type-from-data jpeg-to-upload)))
    (plz-test-wait process)
    (should response-json)
    (should (equal 'jpeg (image-type-from-data response-jpeg)))
    (should (equal (length jpeg-to-upload) (length response-jpeg)))
    (should (equal jpeg-to-upload response-jpeg))))
;; TODO: POST JSON buffer.
(plz-deftest plz-put-json-string nil
  (let* ((json-string (json-encode (list (cons "key" "value"))))
         (response-json)
         (process (plz 'put (plz-test-url "/put")
                    :headers '(("Content-Type" . "application/json"))
                    :body json-string
                    :as #'json-read
                    :then (lambda (json)
                            (setf response-json json)))))
    (plz-test-wait process)
    (let-alist response-json
      (should (string-match "curl" .headers.User-Agent))
      (should (string= "value" (alist-get 'key (json-read-from-string .data)))))))
;; TODO: Put JSON buffer.
;;;;; Sync
(plz-deftest plz-get-string-sync nil
  (let-alist (json-read-from-string (plz 'get (plz-test-url "/get")
                                      :as 'string :then 'sync))
    (should (equal (plz-test-url "/get") .url))))
(plz-deftest plz-get-response-sync nil
  (plz-test-get-response (plz 'get (plz-test-url "/get")
                           :as 'response :then 'sync)))
(plz-deftest plz-get-json-sync nil
  (let-alist (plz 'get (plz-test-url "/get")
               :as #'json-read :then 'sync)
    (should (string-match "curl" .headers.User-Agent))))
(plz-deftest plz-get-buffer-sync nil
  (let ((buffer (plz 'get (plz-test-url "/get")
                  :as 'buffer :then 'sync)))
    (unwind-protect
        (should (buffer-live-p buffer))
      (kill-buffer buffer))))
;;;;; Headers
;; These tests were added when plz--curl was changed to send headers
;; with "--config" rather than on the command line.
(plz-deftest plz-get-with-headers ()
  (let* ((response-json)
         (process (plz 'get (plz-test-url "/get")
                    :headers '(("X-Plz-Test-Header" . "plz-test-header-value"))
                    :as #'json-read
                    :then (lambda (json)
                            (setf response-json json)))))
    (plz-test-wait process)
    (let-alist response-json
      (should (equal "plz-test-header-value" .headers.X-Plz-Test-Header)))))
(plz-deftest plz-post-with-headers ()
  (let* ((alist (list (cons "key" "value")))
         (response-json)
         (process (plz 'post (plz-test-url "/post")
                    :headers '(("Content-Type" . "application/json")
                               ("X-Plz-Test-Header" . "plz-test-header-value"))
                    :body (json-encode alist)
                    :as #'json-read
                    :then (lambda (json)
                            (setf response-json json)))))
    (plz-test-wait process)
    (let-alist response-json
      (should (equal "plz-test-header-value" .headers.X-Plz-Test-Header))
      (should (equal "value" (alist-get 'key (json-read-from-string .data)))))))
(plz-deftest plz-get-json-with-headers-sync ()
  (let-alist (plz 'get (plz-test-url "/get")
               :headers '(("X-Plz-Test-Header" . "plz-test-header-value"))
               :as #'json-read :then 'sync)
    (should (string-match "curl" .headers.User-Agent))
    (should (equal "plz-test-header-value" .headers.X-Plz-Test-Header))))
;;;;; HEAD requests
;; NOTE: httpbin.org doesn't appear to support a "/head" endpoint,
;; so we'll use "/get".
(plz-deftest plz-head-without-headers ()
  ;; I'm not sure how useful it may be to make a HEAD request without
  ;; caring about the headers, but perhaps it could be useful as a
  ;; lightweight way to test a server's presence, so we should
  ;; probably support it.  This merely tests that no error is
  ;; signaled, which should mean that the HEAD request succeeded.
  (should (plz 'head (plz-test-url "/get"))))
(plz-deftest plz-head-as-response ()
  (let ((response (plz 'head (plz-test-url "/get")
                    :as 'response)))
    (should (equal "application/json"
                   (alist-get 'content-type
                              (plz-response-headers response))))))
;;;;; POST requests
(plz-deftest plz-post-empty-body ()
  (should (equal ""
                 (alist-get 'data
                            (json-read-from-string
                             (plz 'post (plz-test-url "/post"))))))
  (should (equal "application/json"
                 (alist-get 'content-type
                            (plz-response-headers
                             (plz 'post (plz-test-url "/post") :as 'response))))))
;;;;; Status codes
(plz-deftest plz-201-succeeds ()
  ;; This merely tests that a 201 response does not signal an error.
  (should (plz 'get (plz-test-url "/status/201"))))
(plz-deftest plz-400-errors ()
  (should-error (plz 'get (plz-test-url "/status/400"))))
(plz-deftest plz-500-errors ()
  (should-error (plz 'get (plz-test-url "/status/500"))))
;;;;; Redirects
(plz-deftest plz-301-redirects ()
  (plz-test-get-response
   (plz 'get (plz-test-url "/redirect-to?url=URI-PREFIX%2Fget&status_code=301")
     :as 'response :then 'sync)))
(plz-deftest plz-302-redirects ()
  (plz-test-get-response
   (plz 'get (plz-test-url "/redirect-to?url=URI-PREFIX%2Fget&status_code=302")
     :as 'response :then 'sync)))
(plz-deftest plz-307-redirects ()
  (plz-test-get-response
   (plz 'get (plz-test-url "/redirect-to?url=URI-PREFIX%2Fget&status_code=307")
     :as 'response :then 'sync)))
(plz-deftest plz-308-redirects ()
  (plz-test-get-response
   (plz 'get (plz-test-url "/redirect-to?url=URI-PREFIX%2Fget&status_code=308")
     :as 'response :then 'sync)))
;;;;; Errors
;; TODO: Sync requests with ":as 'response" should return response for errors rather than signaling.
(plz-deftest plz-get-curl-error-async nil
  ;; Async.
  (let* ((err)
         (process (plz 'get "https://httpbinnnnnn.org/get/status/404"
                    :as 'string :then #'ignore
                    :else (lambda (e)
                            (setf err e)))))
    (plz-test-wait process)
    (should (plz-error-p err))
    (should (equal '(6 . "Couldn't resolve host. The given remote host was not resolved.")
                   (plz-error-curl-error err)))))
;; FIXME: This test works interactively but not in batch mode: it
;; stalls the Emacs process indefinitely, using either sleep-for or
;; sit-for.
;; (plz-deftest plz-get-killed-error nil
;;   ;; Async.
;;   (let* ((err)
;;          (process (plz 'get "https://httpbinnnnnn.org/get/status/404"
;;                     :as 'string
;;                     :else (lambda (e)
;;                             (setf err e)))))
;;     (sit-for 0.01)
;;     (delete-process process)
;;     (should (not (process-live-p process)))
;;     (should (plz-error-p err))
;;     (should (equal "curl process killed"
;;                    (plz-error-message err)))))
(plz-deftest plz-get-curl-error-sync nil
  ;; Sync.
  (pcase-let ((`(,_signal . (,_message ,data))
	       (should-error (plz 'get "https://httpbinnnnnn.org/get/status/404"
                               :as 'string :then 'sync)
                             :type 'plz-error)))
    (should (plz-error-p data))
    (should (equal '(6 . "Couldn't resolve host. The given remote host was not resolved.")
                   (plz-error-curl-error data)))))
(plz-deftest plz-get-404-error-sync  nil
  (pcase-let ((`(,_signal . (,_message ,data))
	       (should-error (plz 'get (plz-test-url "/get/status/404")
			       :as 'string :then 'sync)
                             :type 'plz-error)))
    (should (plz-error-p data))
    (should (plz-response-p (plz-error-response data)))
    (should (eq 404 (plz-response-status (plz-error-response data))))))
(plz-deftest plz-get-404-error-async nil
  (let* ((err)
         (process (plz 'get (plz-test-url "/get/status/404")
                    :as 'string :then #'ignore
                    :else (lambda (e)
                            (setf err e)))))
    (plz-test-wait process)
    (should (plz-error-p err))
    (should (plz-response-p (plz-error-response err)))
    (should (eq 404 (plz-response-status (plz-error-response err))))))
(plz-deftest plz-get-timeout-error-sync nil
  (pcase-let* ((start-time (current-time))
               (`(,_signal . (,_message ,(cl-struct plz-error (curl-error `(,code . ,message)))))
		(should-error (plz 'get (plz-test-url "/delay/5")
				:as 'string :then 'sync :timeout 1)
			      :type 'plz-error))
               (end-time (current-time)))
    (should (eq 28 code))
    (should (equal "Operation timeout." message))
    (should (< (time-to-seconds (time-subtract end-time start-time)) 1.1))))
(plz-deftest plz-get-timeout-error-async nil
  (let* ((start-time (current-time))
         (end-time)
         (plz-error)
         (process (plz 'get (plz-test-url "/delay/5")
                    :as 'response :timeout 1 :then #'ignore
                    :else (lambda (e)
                            (setf end-time (current-time)
                                  plz-error e)))))
    (plz-test-wait process)
    (should (eq 28 (car (plz-error-curl-error plz-error))))
    (should (equal "Operation timeout." (cdr (plz-error-curl-error plz-error))))
    (should (< (time-to-seconds (time-subtract end-time start-time)) 1.1))))
;;;;; Finally
(plz-deftest plz-get-finally nil
  (let* ((finally-null t)
         (process (plz 'get (plz-test-url "/get")
                    :as 'string
                    :then #'ignore
                    :finally (lambda ()
                               (setf finally-null nil)))))
    (plz-test-wait process)
    (should-not finally-null)))
;;;;; Binary
(plz-deftest plz-get-jpeg ()
  (let* ((test-jpeg)
         (process (plz 'get (plz-test-url "/image/jpeg")
                    :as 'binary
                    :then (lambda (string)
                            (setf test-jpeg string)))))
    (plz-test-wait process)
    (should (equal 'jpeg (image-type-from-data test-jpeg)))))
(plz-deftest plz-get-jpeg-sync ()
  (let ((jpeg (plz 'get (plz-test-url "/image/jpeg")
                :as 'binary :then 'sync)))
    (should (equal 'jpeg (image-type-from-data jpeg)))))
;;;;; Downloading to files
(plz-deftest plz-get-temp-file ()
  (let ((filename (plz 'get (plz-test-url "/image/jpeg")
                    :as 'file :then 'sync)))
    (unwind-protect
        (let ((jpeg-data (with-temp-buffer
                           (insert-file-contents filename)
                           (buffer-string))))
          (should (equal 'jpeg (image-type-from-data jpeg-data))))
      ;; It's a temp file, so it should always be deleted.
      (delete-file filename))))
(plz-deftest plz-get-named-file ()
  (let ((filename (make-temp-file "plz-")))
    ;; HACK: Delete the temp file and reuse its name, because
    ;; `make-temp-name' is less convenient to use.
    (delete-file filename)
    (unwind-protect
        (progn
          (plz 'get (plz-test-url "/image/jpeg")
            :as `(file ,filename) :then 'sync)
          (let ((jpeg-data (with-temp-buffer
                             (insert-file-contents filename)
                             (buffer-string))))
            (should (equal 'jpeg (image-type-from-data jpeg-data)))))
      ;; It's a temp file, so it should always be deleted.
      (when (file-exists-p filename)
        (delete-file filename)))))
(plz-deftest plz-upload-file-by-name ()
  (let ((filename (make-temp-file "plz-"))
        response-json process)
    (unwind-protect
        (progn
          (with-temp-file filename
            (insert "deadbeef"))
          (setf process
                (plz 'put (plz-test-url "/put")
                  :body `(file ,filename)
                  :as #'json-read
                  :then (lambda (json)
                          (setf response-json json))))
          (plz-test-wait process)
          (should (equal "deadbeef" (alist-get 'data response-json)))
          (should-not (alist-get 'files response-json)))
      (delete-file filename))))
;;;;; Queue
;; TODO: Test that limit is enforced (though it seems to work fine).
(plz-deftest plz-queue-with-finally ()
  "Ensure that a queue with a FINALLY function calls it correctly.
That is, that the function is called after the queue is emptied,
and only called once."
  (let* ((finally-called-at nil)
         (finally-called-times 0)
         (queue (make-plz-queue :limit 2
                                :finally (lambda ()
                                           (setf finally-called-at (current-time))
                                           (cl-incf finally-called-times))))
         (urls (list (plz-test-url "/delay/2")))
         completed-urls queue-started-at)
    (dolist (url urls)
      (plz-queue queue
        'get url :then (lambda (_)
                         (push url completed-urls))))
    (setf queue-started-at (current-time))
    (plz-run queue)
    (cl-loop with waits = 0
             while (and (plz-queue-active queue) (< waits 60))
             do (progn
                  (sleep-for 0.1)
                  (cl-incf waits)))
    (should (seq-set-equal-p urls completed-urls))
    (should (zerop (plz-length queue)))
    (should (= 1 finally-called-times))
    (should (>= (float-time (time-subtract finally-called-at queue-started-at))
                2))))
(plz-deftest plz-queue-without-finally ()
  "Ensure that a queue without a FINALLY function doesn't signal an error."
  (let* ((queue (make-plz-queue :limit 2))
         (urls (list (plz-test-url "/get?foo=0")
                     (plz-test-url "/get?foo=1")))
         completed-urls)
    (dolist (url urls)
      (plz-queue queue
        'get url :then (lambda (_)
                         (push url completed-urls))))
    (plz-run queue)
    (cl-loop with waits = 0
             while (and (plz-queue-active queue) (< waits 20))
             do (progn
                  (sleep-for 0.1)
                  (cl-incf waits)))
    (should (seq-set-equal-p urls completed-urls))
    (should (zerop (plz-length queue)))))
;; TODO: Add test for canceling queue.
;;;; Footer
(provide 'test-plz)
;;; test-plz.el ends here

This is README.info, produced by makeinfo version 6.7 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
******
file:http://elpa.gnu.org/packages/plz.svg
(http://elpa.gnu.org/packages/plz.html)
   ‘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
* GNU ELPA::
* Manual::
Usage
* Examples::
* Functions::
* Queueing::
* Tips::
Changelog
* 0.7: 07.
* 0.6: 06.
* 0.5.4: 054.
* 0.5.3: 053.
* 0.5.2: 052.
* 0.5.1: 051.
* 0.5: 05.
* 0.4: 04.
* 0.3: 03.
* 0.2.1: 021.
* 0.2: 02.
* 0.1: 01.
Development
* Copyright assignment::

File: README.info,  Node: Installation,  Next: Usage,  Prev: Top,  Up: Top
1 Installation
**************
* Menu:
* GNU ELPA::
* Manual::

File: README.info,  Node: GNU ELPA,  Next: Manual,  Up: Installation
1.1 GNU ELPA
============
‘plz’ is available in GNU ELPA (http://elpa.gnu.org/packages/plz.html).
It may be installed in Emacs using the ‘package-install’ command.

File: README.info,  Node: Manual,  Prev: GNU ELPA,  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.  To install it manually, 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 main 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::
* Queueing::
* 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: Queueing,  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’ may be a string, a buffer, or a list like ‘(file FILENAME)’
     to upload a file from disk.
     ‘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, which will be narrowed
          to the response body and decoded according to ‘DECODE’.
        • ‘binary’ to pass the response body as an un-decoded string.
        • ‘string’ to pass the response body as a decoded string.
        • ‘response’ to pass a ‘plz-response’ structure.
        • ‘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.
        • 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’; if the request fails and no ‘ELSE’ function is
     given (see below), the argument will be a ‘plz-error’ structure
     describing the error.  Or ‘THEN’ may be ‘sync’ to make a
     synchronous request, in which case the result is returned directly
     from this function.
     ‘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.  If ‘ELSE’ is nil, a ‘plz-curl-error’ or
     ‘plz-http-error’ is signaled when the request fails, with a
     ‘plz-error’ structure as the error data.  For synchronous requests,
     this argument is ignored.
     ‘NOTE’: In v0.8 of ‘plz’, only one error will be signaled:
     ‘plz-error’.  The existing errors, ‘plz-curl-error’ and
     ‘plz-http-error’, inherit from ‘plz-error’ to allow applications to
     update their code while using v0.7 (i.e.  any ‘condition-case’
     forms should now handle only ‘plz-error’, not the other two).
     ‘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: Queueing,  Next: Tips,  Prev: Functions,  Up: Usage
2.3 Queueing
============
‘plz’ provides a simple system for queueing HTTP requests.  First, make
a ‘plz-queue’ struct by calling ‘make-plz-queue’.  Then call ‘plz-queue’
with the struct as the first argument, and the rest of the arguments
being the same as those passed to ‘plz’.  Then call ‘plz-run’ to run the
queued requests.
   All of the queue-related functions return the queue as their value,
making them easy to use.  For example:
     (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))))
   Or:
     (let ((queue (make-plz-queue :limit 2
                                  :finally (lambda ()
                                             (message "Queue empty."))))
           (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))))))
   You may also clear a queue with ‘plz-clear’, which cancels any active
or queued requests and calls their ‘:else’ functions.  And ‘plz-length’
returns the number of a queue’s active and queued requests.

File: README.info,  Node: Tips,  Prev: Queueing,  Up: Usage
2.4 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.7: 07.
* 0.6: 06.
* 0.5.4: 054.
* 0.5.3: 053.
* 0.5.2: 052.
* 0.5.1: 051.
* 0.5: 05.
* 0.4: 04.
* 0.3: 03.
* 0.2.1: 021.
* 0.2: 02.
* 0.1: 01.

File: README.info,  Node: 07,  Next: 06,  Up: Changelog
3.1 0.7
=======
*Changes*
   • A new error signal, ‘plz-error’, is defined.  The existing signals,
     ‘plz-curl-error’ and ‘plz-http-error’, inherit from it, so handling
     ‘plz-error’ catches both.
     *NOTE:* The existing signals, ‘plz-curl-error’ and
     ‘plz-http-error’, are hereby deprecated, and they will be removed
     in v0.8.  Applications should be updated while using v0.7 to only
     expect ‘plz-error’.
   *Fixes*
   • Significant improvement in reliability by implementing failsafes
     and workarounds for Emacs’s process-handling code.  (See #3
     (https://github.com/alphapapa/plz.el/issues/3).)
   • STDERR output from curl processes is not included in response
     bodies (which sometimes happened, depending on Emacs’s internal
     race conditions).  (Fixes #23
     (https://github.com/alphapapa/plz.el/issues/23).)
   • Use ‘with-local-quit’ for synchronous requests (preventing Emacs
     from complaining sometimes).  (Fixes #26
     (https://github.com/alphapapa/plz.el/issues/26).)
   • Various fixes for ‘:as 'buffer’ result type: decode body when
     appropriate; unset multibyte for binary; narrow to body; don’t kill
     buffer prematurely.
   • When clearing a queue, don’t try to kill finished processes.
   *Internal*
   • Response processing now happens outside the process sentinel, so
     any errors (e.g.  in user callbacks) are not signaled from inside
     the sentinel.  (This avoids the 2-second pause Emacs imposes in
     such cases.)
   • Tests run against a local instance of httpbin
     (https://github.com/postmanlabs/httpbin) (since the ‘httpbin.org’
     server is often overloaded).
   • No buffer-local variables are defined anymore; process properties
     are used instead.

File: README.info,  Node: 06,  Next: 054,  Prev: 07,  Up: Changelog
3.2 0.6
=======
*Additions*
   • Function ‘plz’’s ‘:body’ argument now accepts a list like ‘(file
     FILENAME)’ to upload a file from disk (by passing the filename to
     curl, rather than reading its content into Emacs and sending it to
     curl through the pipe).
   *Fixes*
   • Function ‘plz’’s docstring now mentions that the ‘:body’ argument
     may also be a buffer (an intentional feature that was accidentally
     undocumented).
   • Handle HTTP 3xx redirects when using ‘:as 'response’.

File: README.info,  Node: 054,  Next: 053,  Prev: 06,  Up: Changelog
3.3 0.5.4
=========
*Fixes*
   • Only run queue’s ‘finally’ function after queue is empty.  (New
     features should not be designed and released on a Friday.)

File: README.info,  Node: 053,  Next: 052,  Prev: 054,  Up: Changelog
3.4 0.5.3
=========
*Fixes*
   • Move new slot in ‘plz-queue’ struct to end to prevent invalid
     byte-compiler expansions for already-compiled applications (which
     would require them to be recompiled after upgrading ‘plz’).

File: README.info,  Node: 052,  Next: 051,  Prev: 053,  Up: Changelog
3.5 0.5.2
=========
*Fixes*
   • When clearing a queue, only call ‘plz-queue’’s ‘finally’ function
     when specified.

File: README.info,  Node: 051,  Next: 05,  Prev: 052,  Up: Changelog
3.6 0.5.1
=========
*Fixes*
   • Only call ‘plz-queue’’s ‘finally’ function when specified.  (Thanks
     to Dan Oriani (https://github.com/redchops) for reporting.)

File: README.info,  Node: 05,  Next: 04,  Prev: 051,  Up: Changelog
3.7 0.5
=======
*Additions*
   • Struct ‘plz-queue’’s ‘finally’ slot, a function called when the
     queue is finished.

File: README.info,  Node: 04,  Next: 03,  Prev: 05,  Up: Changelog
3.8 0.4
=======
*Additions*
   • Support for HTTP ‘HEAD’ requests.  (Thanks to Inc.  for
     sponsoring.)
   *Changes*
   • Allow sending ‘POST’ and ‘PUT’ requests without bodies.  (#16
     (https://github.com/alphapapa/plz.el/issues/16).  Thanks to Joseph
     Turner (https://github.com/josephmturner) for reporting.  Thanks to
     Inc.  for sponsoring.)
   *Fixes*
   • All 2xx HTTP status codes are considered successful.  (#17
     (https://github.com/alphapapa/plz.el/issues/17).  Thanks to Joseph
     Turner (https://github.com/josephmturner) for reporting.  Thanks to
     Inc.  for sponsoring.)
   • Errors are signaled with error data correctly.
   *Internal*
   • Test suite explicitly tests with both HTTP/1.1 and HTTP/2.
   • Test suite also tests with Emacs versions 27.2, 28.1, and 28.2.

File: README.info,  Node: 03,  Next: 021,  Prev: 04,  Up: Changelog
3.9 0.3
=======
*Additions*
   • Handle HTTP proxy headers from Curl.  (#2
     (https://github.com/alphapapa/plz.el/issues/2).  Thanks to Alan
     Third (https://github.com/alanthird) and Sawyer Zheng
     (https://github.com/sawyerzheng) for reporting.)
   *Fixes*
   • Replaced words not in Ispell’s default dictionaries (so ‘checkdoc’
     linting succeeds).

File: README.info,  Node: 021,  Next: 02,  Prev: 03,  Up: Changelog
3.10 0.2.1
==========
*Fixes*
   • Handle when Curl process is interrupted.

File: README.info,  Node: 02,  Next: 01,  Prev: 021,  Up: Changelog
3.11 0.2
========
*Added*
   • Simple request queueing.

File: README.info,  Node: 01,  Prev: 02,  Up: Changelog
3.12 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: Installation1180
Node: GNU ELPA1323
Node: Manual1569
Node: Usage1875
Node: Examples2376
Node: Functions3743
Node: Queueing7440
Node: Tips8823
Node: Changelog9124
Node: 079385
Node: 0611261
Node: 05411872
Node: 05312115
Node: 05212431
Node: 05112638
Node: 0512890
Node: 0413096
Node: 0314002
Node: 02114450
Node: 0214601
Node: 0114732
Node: Credits14828
Node: Development15194
Node: Copyright assignment15708
Node: License16296

End Tag Table

Local Variables:
coding: utf-8
End:

;;; plz.el --- HTTP library                         -*- lexical-binding: t; -*-
;; Copyright (C) 2019-2023  Free Software Foundation, Inc.
;; Author: Adam Porter <adam@alphapapa.net>
;; Maintainer: Adam Porter <adam@alphapapa.net>
;; URL: https://github.com/alphapapa/plz.el
;; Version: 0.7
;; Package-Requires: ((emacs "26.3"))
;; Keywords: comm, network, http
;; This file is part of GNU Emacs.
;;; License:
;; This program is free software; you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation, either version 3 of the License, or
;; (at your option) any later version.
;; This program is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;; GNU General Public License for more details.
;; You should have received a copy of the GNU General Public License
;; along with this program.  If not, see <https://www.gnu.org/licenses/>.
;;; Commentary:
;;
;; An HTTP library that uses curl as a backend.  Inspired by, and some
;; code copied from, Christopher Wellons's library, elfeed-curl.el.
;;
;; Why this package?
;;
;; 1.  `url' works well for many things, but it has some issues.
;; 2.  `request' works well for many things, but it has some issues.
;; 3.  Chris Wellons doesn't have time to factor his excellent
;;     elfeed-curl.el library out of Elfeed.  This will have to do.
;;
;; Why is it called `plz'?
;;
;; 1.  There's already a package called `http'.
;; 2.  There's already a package called `request'.
;; 3.  Naming things is hard.
;;;; Usage:
;; FIXME(v0.8): Remove the following note.
;; NOTE: In v0.8 of plz, only one error will be signaled: `plz-error'.
;; The existing errors, `plz-curl-error' and `plz-http-error', inherit
;; from `plz-error' to allow applications to update their code while
;; using v0.7 (i.e. any `condition-case' forms should now handle only
;; `plz-error', not the other two).
;; 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.
;;; Code:
;;;; Requirements
(require 'cl-lib)
(require 'rx)
(require 'subr-x)
;;;; Errors
(define-error 'plz-error "plz error")
(define-error 'plz-curl-error "plz: Curl error" 'plz-error)
(define-error 'plz-http-error "plz: HTTP error" 'plz-error)
;;;; Structs
(cl-defstruct plz-response
  version status headers body)
(cl-defstruct plz-error
  curl-error response message)
;;;; Constants
(defconst plz-http-response-status-line-regexp
  (rx "HTTP/" (group (or "1.0" "1.1" "2")) " "
      ;; Status code
      (group (1+ digit)) " "
      ;; Reason phrase
      (optional (group (1+ (not (any "\r\n")))))
      (or
       ;; HTTP 1
       "\r\n"
       ;; HTTP 2
       "\n"))
  "Regular expression matching HTTP response status line.")
(defconst plz-http-end-of-headers-regexp
  (rx (or "\r\n\r\n" "\n\n"))
  "Regular expression matching the end of HTTP headers.
This must work with both HTTP/1 (using CRLF) and HTTP/2 (using
only LF).")
(defconst plz-curl-errors
  ;; Copied from elfeed-curl.el.
  '((1 . "Unsupported protocol.")
    (2 . "Failed to initialize.")
    (3 . "URL malformed. The syntax was not correct.")
    (4 . "A feature or option that was needed to perform the desired request was not enabled or was explicitly disabled at build-time.")
    (5 . "Couldn't resolve proxy. The given proxy host could not be resolved.")
    (6 . "Couldn't resolve host. The given remote host was not resolved.")
    (7 . "Failed to connect to host.")
    (8 . "FTP weird server reply. The server sent data curl couldn't parse.")
    (9 . "FTP access denied.")
    (11 . "FTP weird PASS reply.")
    (13 . "FTP weird PASV reply.")
    (14 . "FTP weird 227 format.")
    (15 . "FTP can't get host.")
    (17 . "FTP couldn't set binary.")
    (18 . "Partial file. Only a part of the file was transferred.")
    (19 . "FTP couldn't download/access the given file, the RETR (or similar) command failed.")
    (21 . "FTP quote error. A quote command returned error from the server.")
    (22 . "HTTP page not retrieved.")
    (23 . "Write error.")
    (25 . "FTP couldn't STOR file.")
    (26 . "Read error. Various reading problems.")
    (27 . "Out of memory. A memory allocation request failed.")
    (28 . "Operation timeout.")
    (30 . "FTP PORT failed.")
    (31 . "FTP couldn't use REST.")
    (33 . "HTTP range error. The range \"command\" didn't work.")
    (34 . "HTTP post error. Internal post-request generation error.")
    (35 . "SSL connect error. The SSL handshaking failed.")
    (36 . "FTP bad download resume.")
    (37 . "FILE couldn't read file.")
    (38 . "LDAP bind operation failed.")
    (39 . "LDAP search failed.")
    (41 . "Function not found. A required LDAP function was not found.")
    (42 . "Aborted by callback.")
    (43 . "Internal error. A function was called with a bad parameter.")
    (45 . "Interface error. A specified outgoing interface could not be used.")
    (47 . "Too many redirects.")
    (48 . "Unknown option specified to libcurl.")
    (49 . "Malformed telnet option.")
    (51 . "The peer's SSL certificate or SSH MD5 fingerprint was not OK.")
    (52 . "The server didn't reply anything, which here is considered an error.")
    (53 . "SSL crypto engine not found.")
    (54 . "Cannot set SSL crypto engine as default.")
    (55 . "Failed sending network data.")
    (56 . "Failure in receiving network data.")
    (58 . "Problem with the local certificate.")
    (59 . "Couldn't use specified SSL cipher.")
    (60 . "Peer certificate cannot be authenticated with known CA certificates.")
    (61 . "Unrecognized transfer encoding.")
    (62 . "Invalid LDAP URL.")
    (63 . "Maximum file size exceeded.")
    (64 . "Requested FTP SSL level failed.")
    (65 . "Sending the data requires a rewind that failed.")
    (66 . "Failed to initialise SSL Engine.")
    (67 . "The user name, password, or similar was not accepted and curl failed to log in.")
    (68 . "File not found on TFTP server.")
    (69 . "Permission problem on TFTP server.")
    (70 . "Out of disk space on TFTP server.")
    (71 . "Illegal TFTP operation.")
    (72 . "Unknown TFTP transfer ID.")
    (73 . "File already exists (TFTP).")
    (74 . "No such user (TFTP).")
    (75 . "Character conversion failed.")
    (76 . "Character conversion functions required.")
    (77 . "Problem with reading the SSL CA cert (path? access rights?).")
    (78 . "The resource referenced in the URL does not exist.")
    (79 . "An unspecified error occurred during the SSH session.")
    (80 . "Failed to shut down the SSL connection.")
    (82 . "Could not load CRL file, missing or wrong format (added in 7.19.0).")
    (83 . "Issuer check failed (added in 7.19.0).")
    (84 . "The FTP PRET command failed")
    (85 . "RTSP: mismatch of CSeq numbers")
    (86 . "RTSP: mismatch of Session Identifiers")
    (87 . "unable to parse FTP file list")
    (88 . "FTP chunk callback reported error")
    (89 . "No connection available, the session will be queued")
    (90 . "SSL public key does not matched pinned public key"))
  "Alist mapping curl error code integers to helpful error messages.")
;;;; Customization
(defgroup plz nil
  "Options for `plz'."
  :group 'network
  :link '(url-link "https://github.com/alphapapa/plz.el"))
(defcustom plz-curl-program "curl"
  "Name of curl program to call."
  :type 'string)
(defcustom plz-curl-default-args
  '("--silent"
    "--compressed"
    "--location")
  "Default arguments to curl.
Note that these arguments are passed on the command line, which
may be visible to other users on the local system."
  :type '(repeat string))
(defcustom plz-connect-timeout 5
  "Default connection timeout in seconds.
This limits how long the connection phase may last (the
\"--connect-timeout\" argument to curl)."
  :type 'number)
(defcustom plz-timeout 60
  "Default request timeout in seconds.
This limits how long an entire request may take, including the
connection phase and waiting to receive the response (the
\"--max-time\" argument to curl)."
  :type 'number)
;;;; Functions
;;;;; Public
(cl-defun plz (method url &rest rest &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 may be a string, a buffer, or a list like `(file FILENAME)'
to upload a file from disk.
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, which will be narrowed to
  the response body and decoded according to DECODE.
- `binary' to pass the response body as an un-decoded string.
- `string' to pass the response body as a decoded string.
- `response' to pass a `plz-response' structure.
- `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.
- 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; if the request fails and no ELSE function is
given (see below), the argument will be a `plz-error' structure
describing the error.  Or THEN may be `sync' to make a
synchronous request, in which case the result is returned
directly from this function.
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.  If ELSE is nil, a `plz-curl-error' or
`plz-http-error' is signaled when the request fails, with a
`plz-error' structure as the error data.  For synchronous
requests, this argument is ignored.
NOTE: In v0.8 of `plz', only one error will be signaled:
`plz-error'.  The existing errors, `plz-curl-error' and
`plz-http-error', inherit from `plz-error' to allow applications
to update their code while using v0.7 (i.e. any `condition-case'
forms should now handle only `plz-error', not the other two).
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.
\(To silence checkdoc, we mention the internal argument REST.)"
  ;; FIXME(v0.8): Remove the note about error changes from the docstring.
  ;; FIXME(v0.8): Update error signals in docstring.
  (declare (indent defun))
  (setf decode (if (and decode-s (not decode))
                   nil decode))
  ;; NOTE: By default, for PUT requests and POST requests >1KB, curl sends an
  ;; "Expect:" header, which causes servers to send a "100 Continue" response, which
  ;; we don't want to have to deal with, so we disable it by setting the header to
  ;; the empty string.  See <https://gms.tf/when-curl-sends-100-continue.html>.
  ;; TODO: Handle "100 Continue" responses and remove this workaround.
  (push (cons "Expect" "") headers)
  (let* ((data-arg (pcase-exhaustive body-type
                     ('binary "--data-binary")
                     ('text "--data")))
         (curl-command-line-args (append plz-curl-default-args
                                         (list "--config" "-")))
         (curl-config-header-args (cl-loop for (key . value) in headers
                                           collect (cons "--header" (format "%s: %s" key value))))
         (curl-config-args (append curl-config-header-args
                                   (list (cons "--url" url))
                                   (when connect-timeout
                                     (list (cons "--connect-timeout"
                                                 (number-to-string connect-timeout))))
                                   (when timeout
                                     (list (cons "--max-time" (number-to-string timeout))))
                                   ;; NOTE: To make a HEAD request
                                   ;; requires using the "--head"
                                   ;; option rather than "--request
                                   ;; HEAD", and doing so with
                                   ;; "--dump-header" duplicates the
                                   ;; headers, so we must instead
                                   ;; specify that for each other
                                   ;; method.
                                   (pcase method
                                     ('get
                                      (list (cons "--dump-header" "-")))
                                     ((or 'put 'post)
                                      (list (cons "--dump-header" "-")
                                            (cons "--request" (upcase (symbol-name method)))
                                            ;; It appears that this must be the last argument
                                            ;; in order to pass data on the rest of STDIN.
                                            (pcase body
                                              (`(file ,filename)
                                               ;; Use `expand-file-name' because curl doesn't
                                               ;; expand, e.g. "~" into "/home/...".
                                               (cons "--upload-file" (expand-file-name filename)))
                                              (_ (cons data-arg "@-")))))
                                     ('delete
                                      (list (cons "--dump-header" "-")
                                            (cons "--request" (upcase (symbol-name method)))))
                                     ('head
                                      (list (cons "--head" "")
                                            (cons "--request" "HEAD"))))))
         (curl-config (cl-loop for (key . value) in curl-config-args
                               concat (format "%s \"%s\"\n" key value)))
         (decode (pcase as
                   ('binary nil)
                   (_ decode)))
         (default-directory
           ;; Avoid making process in a nonexistent directory (in case the current
           ;; default-directory has since been removed).  It's unclear what the best
           ;; directory is, but this seems to make sense, and it should still exist.
           temporary-file-directory)
         (process-buffer (generate-new-buffer " *plz-request-curl*"))
         (stderr-process (make-pipe-process :name "plz-request-curl-stderr"
                                            :buffer (generate-new-buffer " *plz-request-curl-stderr*")
                                            :noquery t
                                            :sentinel #'plz--stderr-sentinel))
         (process (make-process :name "plz-request-curl"
                                :buffer process-buffer
                                :coding 'binary
                                :command (append (list plz-curl-program) curl-command-line-args)
                                :connection-type 'pipe
                                :sentinel #'plz--sentinel
                                :stderr stderr-process
                                :noquery noquery))
         sync-p)
    (when (eq 'sync then)
      (setf sync-p t
            then (lambda (result)
                   (process-put process :plz-result result))
            else nil))
    (setf
     ;; Set the callbacks, etc. as process properties.
     (process-get process :plz-then)
     (pcase-exhaustive as
       ((or 'binary 'string)
        (lambda ()
          (let ((coding-system (or (plz--coding-system) 'utf-8)))
            (pcase as
              ('binary (set-buffer-multibyte nil)))
            (plz--narrow-to-body)
            (when decode
              (decode-coding-region (point) (point-max) coding-system))
            (funcall then (or (buffer-string)
                              (make-plz-error :message (format "buffer-string is nil in buffer:%S" process-buffer)))))))
       ('buffer (progn
                  (setf (process-get process :plz-as) 'buffer)
                  (lambda ()
                    (let ((coding-system (or (plz--coding-system) 'utf-8)))
                      (pcase as
                        ('binary (set-buffer-multibyte nil)))
                      (plz--narrow-to-body)
                      (when decode
                        (decode-coding-region (point) (point-max) coding-system)))
                    (funcall then (current-buffer)))))
       ('response (lambda ()
                    (funcall then (or (plz--response :decode-p decode)
                                      (make-plz-error :message (format "response is nil for buffer:%S  buffer-string:%S"
                                                                       process-buffer (buffer-string)))))))
       ('file (lambda ()
                (set-buffer-multibyte nil)
                (plz--narrow-to-body)
                (let ((filename (make-temp-file "plz-")))
                  (condition-case err
                      (progn
                        (write-region (point-min) (point-max) filename)
                        (funcall then filename))
                    ;; In case of an error writing to the file, delete the temp file
                    ;; and signal the error.  Ignore any errors encountered while
                    ;; deleting the file, which would obscure the original error.
                    (error (ignore-errors
                             (delete-file filename))
                           (funcall then (make-plz-error :message (format "error while writing to file %S: %S" filename err))))))))
       (`(file ,(and (pred stringp) filename))
        (lambda ()
          (set-buffer-multibyte nil)
          (plz--narrow-to-body)
          (condition-case err
              (progn
                (write-region (point-min) (point-max) filename nil nil nil 'excl)
                (funcall then filename))
            ;; Since we are creating the file, it seems sensible to delete it in case of an
            ;; error while writing to it (e.g. a disk-full error).  And we ignore any errors
            ;; encountered while deleting the file, which would obscure the original error.
            (error (ignore-errors
                     (when (file-exists-p filename)
                       (delete-file filename)))
                   (funcall then (make-plz-error :message (format "error while writing to file %S: %S" filename err)))))))
       ((pred functionp) (lambda ()
                           (let ((coding-system (or (plz--coding-system) 'utf-8)))
                             (plz--narrow-to-body)
                             (when decode
                               (decode-coding-region (point) (point-max) coding-system))
                             (funcall then (funcall as))))))
     (process-get process :plz-else) else
     (process-get process :plz-finally) finally
     (process-get process :plz-sync) sync-p
     ;; Record list of arguments for debugging purposes (e.g. when
     ;; using Edebug in a process buffer, this allows determining
     ;; which request the buffer is for).
     (process-get process :plz-args) (apply #'list method url rest)
     ;; HACK: We set the result to a sentinel value so that any other
     ;; value, even nil, means that the response was processed, and
     ;; the sentinel does not need to be called again (see below).
     (process-get process :plz-result) :plz-result)
    ;; Send --config arguments.
    (process-send-string process curl-config)
    (when body
      (cl-typecase body
        (string (process-send-string process body))
        (buffer (with-current-buffer body
                  (process-send-region process (point-min) (point-max))))))
    (process-send-eof process)
    (if sync-p
        (unwind-protect
            (with-local-quit
              ;; See Info node `(elisp)Accepting Output'.
              (unless (and process stderr-process)
                (error "Process unexpectedly nil"))
              (while (accept-process-output process))
              (while (accept-process-output stderr-process))
              (when (eq :plz-result (process-get process :plz-result))
                ;; HACK: Sentinel seems to not have been called: call it again.  (Although
                ;; this is a hack, it seems to be a necessary one due to Emacs's process
                ;; handling.)  See <https://github.com/alphapapa/plz.el/issues/3> and
                ;; <https://debbugs.gnu.org/cgi/bugreport.cgi?bug=50166>.
                (plz--sentinel process "finished\n")
                (when (eq :plz-result (process-get process :plz-result))
                  (error "Plz: NO RESULT FROM PROCESS:%S  ARGS:%S"
                         process rest)))
              ;; Sentinel seems to have been called: check the result.
              (pcase (process-get process :plz-result)
                ((and (pred plz-error-p) data)
                 ;; The AS function signaled an error, which was collected
                 ;; into a `plz-error' struct: re-signal the error here,
                 ;; outside of the sentinel.
                 (if (plz-error-response data)
                     ;; FIXME(v0.8): Signal only plz-error.
                     (signal 'plz-http-error (list "HTTP error" data))
                   (signal 'plz-curl-error (list "Curl error" data))))
                (else
                 ;; The AS function returned a value: return it.
                 else)))
          (unless (eq as 'buffer)
            (kill-buffer process-buffer))
          (kill-buffer (process-buffer stderr-process)))
      ;; Async request: return the process object.
      process)))
;;;;; Queue
;; A simple queue system.
(cl-defstruct plz-queued-request
  "Structure representing a queued `plz' HTTP request.
For more details on these slots, see arguments to the function
`plz'."
  method url headers body else finally noquery
  as then body-type decode
  connect-timeout timeout
  next previous process)
(cl-defstruct plz-queue
  "Structure forming a queue for `plz' requests.
The queue may be appended to (the default) and pre-pended to, and
items may be removed from the front of the queue (i.e. by
default, it's FIFO).  Use functions `plz-queue', `plz-run', and
`plz-clear' to queue, run, and clear requests, respectively."
  (limit 1
         :documentation "Number of simultaneous requests.")
  (active nil
          :documentation "Active requests.")
  (requests nil
            :documentation "Queued requests.")
  (canceled-p nil
              :documentation "Non-nil when queue has been canceled.")
  first-active last-active
  first-request last-request
  (finally nil
           :documentation "Function called with no arguments after queue has been emptied or canceled."))
(defun plz-queue (queue &rest args)
  "Queue request for ARGS on QUEUE and return QUEUE.
To pre-pend to QUEUE rather than append, it may be a list of the
form (`prepend' QUEUE).  QUEUE is a `plz-request' queue.  ARGS
are those passed to `plz', which see.  Use `plz-run' to start
making QUEUE's requests."
  (declare (indent defun))
  (cl-assert (not (equal 'sync (plist-get (cddr args) :then))) nil
             "Only async requests may be queued")
  (pcase-let* ((`(,method ,url . ,rest) args)
               (args `(:method ,method :url ,url ,@rest))
               (request (apply #'make-plz-queued-request args)))
    (pcase queue
      (`(prepend ,queue) (plz--queue-prepend request queue))
      (_ (plz--queue-append request queue))))
  queue)
(defun plz--queue-append (request queue)
  "Add REQUEST to end of QUEUE and return QUEUE."
  (cl-check-type request plz-queued-request
                 "REQUEST must be a `plz-queued-request' structure.")
  (cl-check-type queue plz-queue
                 "QUEUE must be a `plz-queue' structure.")
  (when (plz-queue-last-request queue)
    (setf (plz-queued-request-next (plz-queue-last-request queue)) request))
  (setf (plz-queued-request-previous request) (plz-queue-last-request queue)
        (plz-queue-last-request queue) request)
  (unless (plz-queue-first-request queue)
    (setf (plz-queue-first-request queue) request))
  (unless (plz-queue-last-request queue)
    (setf (plz-queue-last-request queue) request))
  (push request (plz-queue-requests queue))
  queue)
(defun plz--queue-prepend (request queue)
  "Add REQUEST to front of QUEUE and return QUEUE."
  (cl-check-type request plz-queued-request
                 "REQUEST must be a `plz-queued-request' structure.")
  (cl-check-type queue plz-queue
                 "QUEUE must be a `plz-queue' structure.")
  (when (plz-queue-requests queue)
    (setf (plz-queued-request-next request) (car (plz-queue-requests queue))
          (plz-queued-request-previous (plz-queued-request-next request)) request))
  (setf (plz-queue-first-request queue) request)
  (unless (plz-queue-first-request queue)
    (setf (plz-queue-first-request queue) request))
  (unless (plz-queue-last-request queue)
    (setf (plz-queue-last-request queue) request))
  (push request (plz-queue-requests queue))
  queue)
(defun plz--queue-pop (queue)
  "Return the first queued request on QUEUE and remove it from QUEUE."
  (let* ((request (plz-queue-first-request queue))
         (next (plz-queued-request-next request)))
    (when next
      (setf (plz-queued-request-previous next) nil))
    (setf (plz-queue-first-request queue) next
          (plz-queue-requests queue) (delq request (plz-queue-requests queue)))
    (when (eq request (plz-queue-last-request queue))
      (setf (plz-queue-last-request queue) nil))
    request))
(defun plz-run (queue)
  "Process requests in QUEUE and return QUEUE.
Return when QUEUE is at limit or has no more queued requests.
QUEUE should be a `plz-queue' structure."
  (cl-labels ((readyp
               (queue) (and (not (plz-queue-canceled-p queue))
                            (plz-queue-requests queue)
                            ;; With apologies to skeeto...
                            (< (length (plz-queue-active queue)) (plz-queue-limit queue)))))
    (while (readyp queue)
      (pcase-let* ((request (plz--queue-pop queue))
                   ((cl-struct plz-queued-request method url
                               headers body finally noquery as body-type decode connect-timeout timeout
                               (else orig-else) (then orig-then))
                    request)
                   (then (lambda (response)
                           (unwind-protect
                               ;; Ensure any errors in the THEN function don't abort the queue.
                               (funcall orig-then response)
                             (setf (plz-queue-active queue) (delq request (plz-queue-active queue)))
                             (plz-run queue))))
                   (else (lambda (arg)
                           ;; FIXME(v0.8): This should be done in `plz-queue' because
                           ;; `plz-clear' will call the second queued-request's ELSE
                           ;; before it can be set by `plz-run'.
                           (unwind-protect
                               ;; Ensure any errors in the THEN function don't abort the queue.
                               (when orig-else
                                 (funcall orig-else arg))
                             (setf (plz-queue-active queue) (delq request (plz-queue-active queue)))
                             (plz-run queue))))
                   (args (list method url
                               ;; Omit arguments for which `plz' has defaults so as not to nil them.
                               :headers headers :body body :finally finally :noquery noquery
                               :connect-timeout connect-timeout :timeout timeout)))
        ;; Add arguments which override defaults.
        (when as
          (setf args (plist-put args :as as)))
        (when else
          (setf args (plist-put args :else else)))
        (when then
          (setf args (plist-put args :then then)))
        (when decode
          (setf args (plist-put args :decode decode)))
        (when body-type
          (setf args (plist-put args :body-type body-type)))
        (when connect-timeout
          (setf args (plist-put args :connect-timeout connect-timeout)))
        (when timeout
          (setf args (plist-put args :timeout timeout)))
        (setf (plz-queued-request-process request) (apply #'plz args))
        (push request (plz-queue-active queue))))
    (when (and (plz-queue-finally queue)
               (zerop (length (plz-queue-active queue)))
               (zerop (length (plz-queue-requests queue))))
      (funcall (plz-queue-finally queue)))
    queue))
(defun plz-clear (queue)
  "Clear QUEUE and return it.
Cancels any active or pending requests and calls the queue's
FINALLY function.  For pending requests, their ELSE functions
will be called with a `plz-error' structure with the message,
\"`plz' queue cleared; request canceled.\"; active requests will
have their curl processes killed and their ELSE functions called
with the corresponding data."
  (setf (plz-queue-canceled-p queue) t)
  (dolist (request (plz-queue-active queue))
    (when (process-live-p (plz-queued-request-process request))
      (kill-process (plz-queued-request-process request)))
    (setf (plz-queue-active queue) (delq request (plz-queue-active queue))))
  (dolist (request (plz-queue-requests queue))
    (funcall (plz-queued-request-else request)
             (make-plz-error :message "`plz' queue cleared; request canceled."))
    (setf (plz-queue-requests queue) (delq request (plz-queue-requests queue))))
  (when (plz-queue-finally queue)
    (funcall (plz-queue-finally queue)))
  (setf (plz-queue-first-active queue) nil
        (plz-queue-last-active queue) nil
        (plz-queue-first-request queue) nil
        (plz-queue-last-request queue) nil
        (plz-queue-canceled-p queue) nil)
  queue)
(defun plz-length (queue)
  "Return number of of QUEUE's outstanding requests.
Includes active and queued requests."
  (+ (length (plz-queue-active queue))
     (length (plz-queue-requests queue))))
;;;;; Private
(defun plz--sentinel (process status)
  "Sentinel for curl PROCESS.
STATUS should be the process's event string (see info
node `(elisp) Sentinels').  Calls `plz--respond' to process the
HTTP response (directly for synchronous requests, or from a timer
for asynchronous ones)."
  (pcase status
    ((or "finished\n" "killed\n" "interrupt\n"
         (pred numberp)
         (rx "exited abnormally with code " (group (1+ digit))))
     (let ((buffer (process-buffer process)))
       (if (process-get process :plz-sync)
           (plz--respond process buffer status)
         (run-at-time 0 nil #'plz--respond process buffer status))))))
(defun plz--respond (process buffer status)
  "Respond to HTTP response from PROCESS in BUFFER.
Parses the response and calls the THEN/ELSE callbacks
accordingly.  To be called from `plz--sentinel'.  STATUS is the
argument passed to `plz--sentinel', which see."
  ;; Is it silly to call this function "please respond"?  Perhaps, but
  ;; naming things is hard.  The term "process" has another meaning in
  ;; this context, and the old standby, "handle," is much overused.
  ;; "Respond" also means "to react to something," which is what this
  ;; does--react to receiving the HTTP response--and it's an internal
  ;; name, so why not.
  (unwind-protect
      (with-current-buffer buffer
        (pcase-exhaustive status
          ((or 0 "finished\n")
           ;; Curl exited normally: check HTTP status code.
           (goto-char (point-min))
           (plz--skip-proxy-headers)
           (while (plz--skip-redirect-headers))
           (pcase (plz--http-status)
             ((and status (guard (<= 200 status 299)))
              ;; Any 2xx response is considered successful.
              (ignore status) ; Byte-compiling in Emacs <28 complains without this.
              (funcall (process-get process :plz-then)))
             (_
              ;; TODO: If using ":as 'response", the HTTP response
              ;; should be passed to the THEN function, regardless
              ;; of the status code.  Only for curl errors should
              ;; the ELSE function be called.  (Maybe in v0.8.)
              ;; Any other status code is considered unsuccessful
              ;; (for now, anyway).
              (let ((err (make-plz-error :response (plz--response))))
                (pcase-exhaustive (process-get process :plz-else)
                  (`nil (process-put process :plz-result err))
                  ((and (pred functionp) fn) (funcall fn err)))))))
          ((or (and (pred numberp) code)
               (rx "exited abnormally with code " (let code (group (1+ digit)))))
           ;; Curl error.
           (let* ((curl-exit-code (cl-typecase code
                                    (string (string-to-number code))
                                    (number code)))
                  (curl-error-message (alist-get curl-exit-code plz-curl-errors))
                  (err (make-plz-error :curl-error (cons curl-exit-code curl-error-message))))
             (pcase-exhaustive (process-get process :plz-else)
               (`nil (process-put process :plz-result err))
               ((and (pred functionp) fn) (funcall fn err)))))
          ((and (or "killed\n" "interrupt\n") status)
           ;; Curl process killed or interrupted.
           (let* ((message (pcase status
                             ("killed\n" "curl process killed")
                             ("interrupt\n" "curl process interrupted")))
                  (err (make-plz-error :message message)))
             (pcase-exhaustive (process-get process :plz-else)
               (`nil (process-put process :plz-result err))
               ((and (pred functionp) fn) (funcall fn err)))))))
    (when-let ((finally (process-get process :plz-finally)))
      (funcall finally))
    (unless (or (process-get process :plz-sync)
                (eq 'buffer (process-get process :plz-as)))
      (kill-buffer buffer))))
(defun plz--stderr-sentinel (process status)
  "Sentinel for STDERR buffer.
Arguments are PROCESS and STATUS (ok, checkdoc?)."
  (pcase status
    ((or "finished\n" "killed\n" "interrupt\n"
         (pred numberp)
         (rx "exited abnormally with code " (1+ digit)))
     (kill-buffer (process-buffer process)))))
;;;;;; HTTP Responses
;; Functions for parsing HTTP responses.
(defun plz--skip-proxy-headers ()
  "Skip proxy headers in current buffer."
  (when (looking-at plz-http-response-status-line-regexp)
    (let* ((status-code (string-to-number (match-string 2)))
           (reason-phrase (match-string 3)))
      (when (and (equal 200 status-code)
                 (equal "Connection established" reason-phrase))
        ;; Skip proxy headers (curl apparently offers no way to omit
        ;; them).
        (unless (re-search-forward "\r\n\r\n" nil t)
          (signal 'plz-http-error '("plz--response: End of proxy headers not found")))))))
(defun plz--skip-redirect-headers ()
  "Skip HTTP redirect headers in current buffer."
  (when (and (looking-at plz-http-response-status-line-regexp)
             (member (string-to-number (match-string 2)) '(301 302 307 308)))
    ;; Skip redirect headers ("--dump-header" forces redirect headers to be included
    ;; even when used with "--location").
    (or (re-search-forward "\r\n\r\n" nil t)
        (signal 'plz-http-error '("plz--response: End of redirect headers not found")))))
(cl-defun plz--response (&key (decode-p t))
  "Return response structure for HTTP response in current buffer.
When DECODE-P is non-nil, decode the response body automatically
according to the apparent coding system.
Assumes that point is at beginning of HTTP response."
  (save-excursion
    ;; Parse HTTP version and status code.
    (unless (looking-at plz-http-response-status-line-regexp)
      (signal 'plz-http-error
              (list "plz--response: Unable to parse HTTP response status line"
                    (buffer-substring (point) (line-end-position)))))
    (let* ((http-version (string-to-number (match-string 1)))
           (status-code (string-to-number (match-string 2)))
           (headers (plz--headers))
           (coding-system (or (plz--coding-system headers) 'utf-8)))
      (plz--narrow-to-body)
      (when decode-p
        (decode-coding-region (point) (point-max) coding-system))
      (make-plz-response
       :version http-version
       :status status-code
       :headers headers
       :body (buffer-string)))))
(defun plz--coding-system (&optional headers)
  "Return coding system for HTTP response in current buffer.
HEADERS may optionally be an alist of parsed HTTP headers to
refer to rather than the current buffer's un-parsed headers."
  (let* ((headers (or headers (plz--headers)))
         (content-type (alist-get 'content-type headers)))
    (when content-type
      (coding-system-from-name content-type))))
(defun plz--http-status ()
  "Return HTTP status code for HTTP response in current buffer.
Assumes point is at start of HTTP response."
  (when (looking-at plz-http-response-status-line-regexp)
    (string-to-number (match-string 2))))
(defun plz--headers ()
  "Return headers alist for HTTP response in current buffer.
Assumes point is at start of HTTP response."
  (save-excursion
    (forward-line 1)
    (let ((limit (save-excursion
                   (re-search-forward plz-http-end-of-headers-regexp nil)
                   (point))))
      (cl-loop while (re-search-forward (rx bol (group (1+ (not (in ":")))) ":" (1+ blank)
                                            (group (1+ (not (in "\r\n")))))
                                        limit t)
               ;; NOTE: Some HTTP servers send all-lowercase header keys, which means an alist
               ;; lookup with `equal' or `string=' fails when the case differs.  We don't want
               ;; users to have to worry about this, so for consistency, we downcase the
               ;; header name.  And while we're at it, we might as well intern it so we can
               ;; use `alist-get' without having to add "nil nil #'equal" every time.
               collect (cons (intern (downcase (match-string 1))) (match-string 2))))))
(defun plz--narrow-to-body ()
  "Narrow to body of HTTP response in current buffer.
Assumes point is at start of HTTP response."
  (unless (re-search-forward plz-http-end-of-headers-regexp nil t)
    (signal 'plz-http-error '("plz--narrow-to-body: Unable to find end of headers")))
  (narrow-to-region (point) (point-max)))
;;;; Footer
(provide 'plz)
;;; plz.el ends here

;; Generated package description from plz.el  -*- no-byte-compile: t -*-
(define-package "plz" "0.7" "HTTP library" '((emacs "26.3")) :commit "70ebd6edea2b5c376776cd747bc378b07f0e6646" :authors '(("Adam Porter" . "adam@alphapapa.net")) :maintainer '("Adam Porter" . "adam@alphapapa.net") :keywords '("comm" "network" "http") :url "https://github.com/alphapapa/plz.el")

;;; plz-autoloads.el --- automatically extracted autoloads (do not edit)   -*- lexical-binding: t -*-
;; Generated by the `loaddefs-generate' function.
;; This file is part of GNU Emacs.
;;; Code:
(add-to-list 'load-path (or (and load-file-name (directory-file-name (file-name-directory load-file-name))) (car load-path)))

;;; Generated autoloads from plz.el
(register-definition-prefixes "plz" '("plz-"))

;;; End of scraped data
(provide 'plz-autoloads)
;; Local Variables:
;; version-control: never
;; no-byte-compile: t
;; no-update-autoloads: t
;; no-native-compile: t
;; coding: utf-8-emacs-unix
;; End:
;;; plz-autoloads.el ends here

This is the file .../info/dir, which contains the
topmost node of the Info hierarchy, called (dir)Top.
The first time you invoke Info you start off looking at this node.

File: dir,	Node: Top	This is the top of the INFO tree
  This (the Directory node) gives a menu of major topics.
  Typing "q" exits, "H" lists all Info commands, "d" returns here,
  "h" gives a primer for first-timers,
  "mEmacs<Return>" visits the Emacs manual, etc.
  In Emacs, you can click mouse button 2 on a menu item or cross reference
  to select it.
* Menu:

#+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.
[[http://elpa.gnu.org/packages/plz.html][file:http://elpa.gnu.org/packages/plz.svg]]
#+HTML: <img src="images/mascot.png" align="right">
~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 [[https://httpbin.org/][httpbin]].
* Contents                                                         :noexport:
:PROPERTIES:
:TOC:      :include siblings
:END:
:CONTENTS:
- [[#installation][Installation]]
- [[#usage][Usage]]
  - [[#examples][Examples]]
  - [[#functions][Functions]]
  - [[#queueing][Queueing]]
- [[#changelog][Changelog]]
- [[#credits][Credits]]
- [[#development][Development]]
  - [[#copyright-assignment][Copyright assignment]]
:END:
* Installation
:PROPERTIES:
:TOC:      :depth 0
:END:
** GNU ELPA
~plz~ is available in [[http://elpa.gnu.org/packages/plz.html][GNU ELPA]].  It may be installed in Emacs using the ~package-install~ command.
** Manual
 ~plz~ has no dependencies other than Emacs and ~curl~.  It's known to work on Emacs 26.3 or later.  To install it manually, simply place =plz.el= in your ~load-path~ and ~(require 'plz)~.
* Usage
:PROPERTIES:
:TOC:      :depth 1
:END:
The main 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 and return the response body as a decoded string (here, raw 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
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 :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
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 :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"}
Synchronously download a JPEG file, then create an Emacs image object from the data:
#+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...")
** 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~ may be a string, a buffer, or a list like ~(file FILENAME)~ to upload a file from disk.
   ~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, which will be narrowed to the response body and decoded according to ~DECODE~.
   - ~binary~ to pass the response body as an un-decoded string.
   - ~string~ to pass the response body as a decoded string.
   - ~response~ to pass a ~plz-response~ structure.
   - ~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.
   - 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~; if the request fails and no ~ELSE~ function is given (see below), the argument will be a ~plz-error~ structure describing the error.  Or ~THEN~ may be ~sync~ to make a synchronous request, in which case the result is returned directly from this function.
   ~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.  If ~ELSE~ is nil, a ~plz-curl-error~ or ~plz-http-error~ is signaled when the request fails, with a ~plz-error~ structure as the error data.  For synchronous requests, this argument is ignored.
   ~NOTE~: In v0.8 of ~plz~, only one error will be signaled: ~plz-error~.  The existing errors, ~plz-curl-error~ and ~plz-http-error~, inherit from ~plz-error~ to allow applications to update their code while using v0.7 (i.e. any ~condition-case~ forms should now handle only ~plz-error~, not the other two).
   ~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.
** Queueing
~plz~ provides a simple system for queueing HTTP requests.  First, make a ~plz-queue~ struct by calling ~make-plz-queue~.  Then call ~plz-queue~ with the struct as the first argument, and the rest of the arguments being the same as those passed to ~plz~.  Then call ~plz-run~ to run the queued requests.
All of the queue-related functions return the queue as their value, making them easy to use.  For example:
#+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
Or:
#+begin_src elisp :exports code
  (let ((queue (make-plz-queue :limit 2
                               :finally (lambda ()
                                          (message "Queue empty."))))
        (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
You may also clear a queue with ~plz-clear~, which cancels any active or queued requests and calls their ~:else~ functions.  And ~plz-length~ returns the number of a queue's active and queued requests.
** 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.7
*Changes*
+ A new error signal, ~plz-error~, is defined.  The existing signals, ~plz-curl-error~ and ~plz-http-error~, inherit from it, so handling ~plz-error~ catches both.
  *NOTE:* The existing signals, ~plz-curl-error~ and ~plz-http-error~, are hereby deprecated, and they will be removed in v0.8.  Applications should be updated while using v0.7 to only expect ~plz-error~.
*Fixes*
+ Significant improvement in reliability by implementing failsafes and workarounds for Emacs's process-handling code.  (See [[https://github.com/alphapapa/plz.el/issues/3][#3]].)
+ STDERR output from curl processes is not included in response bodies (which sometimes happened, depending on Emacs's internal race conditions).  (Fixes [[https://github.com/alphapapa/plz.el/issues/23][#23]].)
+ Use ~with-local-quit~ for synchronous requests (preventing Emacs from complaining sometimes).  (Fixes [[https://github.com/alphapapa/plz.el/issues/26][#26]].)
+ Various fixes for ~:as 'buffer~ result type: decode body when appropriate; unset multibyte for binary; narrow to body; don't kill buffer prematurely.
+ When clearing a queue, don't try to kill finished processes.
*Internal*
+ Response processing now happens outside the process sentinel, so any errors (e.g. in user callbacks) are not signaled from inside the sentinel.  (This avoids the 2-second pause Emacs imposes in such cases.)
+ Tests run against a local instance of [[https://github.com/postmanlabs/httpbin][httpbin]] (since the ~httpbin.org~ server is often overloaded).
+ No buffer-local variables are defined anymore; process properties are used instead.
** 0.6
*Additions*
+ Function ~plz~'s ~:body~ argument now accepts a list like ~(file FILENAME)~ to upload a file from disk (by passing the filename to curl, rather than reading its content into Emacs and sending it to curl through the pipe).
*Fixes*
+ Function ~plz~'s docstring now mentions that the ~:body~ argument may also be a buffer (an intentional feature that was accidentally undocumented).
+ Handle HTTP 3xx redirects when using ~:as 'response~.
** 0.5.4
*Fixes*
+ Only run queue's ~finally~ function after queue is empty.  (New features should not be designed and released on a Friday.)
** 0.5.3
*Fixes*
+ Move new slot in ~plz-queue~ struct to end to prevent invalid byte-compiler expansions for already-compiled applications (which would require them to be recompiled after upgrading ~plz~).
** 0.5.2
*Fixes*
+ When clearing a queue, only call ~plz-queue~'s ~finally~ function when specified.
** 0.5.1
*Fixes*
+ Only call ~plz-queue~'s ~finally~ function when specified.  (Thanks to [[https://github.com/redchops][Dan Oriani]] for reporting.)
** 0.5
*Additions*
+ Struct ~plz-queue~'s ~finally~ slot, a function called when the queue is finished.
** 0.4
*Additions*
+ Support for HTTP ~HEAD~ requests.  (Thanks to [[https://ushin.org/][USHIN, Inc.]] for sponsoring.)
*Changes*
+ Allow sending ~POST~ and ~PUT~ requests without bodies.  ([[https://github.com/alphapapa/plz.el/issues/16][#16]].  Thanks to [[https://github.com/josephmturner][Joseph Turner]] for reporting.  Thanks to [[https://ushin.org/][USHIN, Inc.]] for sponsoring.)
*Fixes*
+ All 2xx HTTP status codes are considered successful.  ([[https://github.com/alphapapa/plz.el/issues/17][#17]].  Thanks to [[https://github.com/josephmturner][Joseph Turner]] for reporting.  Thanks to [[https://ushin.org/][USHIN, Inc.]] for sponsoring.)
+ Errors are signaled with error data correctly.
*Internal*
+ Test suite explicitly tests with both HTTP/1.1 and HTTP/2.
+ Test suite also tests with Emacs versions 27.2, 28.1, and 28.2.
** 0.3
*Additions*
+ Handle HTTP proxy headers from Curl. ([[https://github.com/alphapapa/plz.el/issues/2][#2]].  Thanks to [[https://github.com/alanthird][Alan Third]] and [[https://github.com/sawyerzheng][Sawyer Zheng]] for reporting.)
*Fixes*
+ Replaced words not in Ispell's default dictionaries (so ~checkdoc~ linting succeeds).
** 0.2.1
*Fixes*
+ Handle when Curl process is interrupted.
** 0.2
*Added*
+ Simple request queueing.
** 0.1
Initial release.
* 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/!
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:
:TOC:      :ignore (this)
:END:
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 allows it to find the export options in it.  And since org-export does respect the noexport tag, the tree is excluded from the info page.
# 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:

				━━━━━━━━
				 PLZ.EL
				━━━━━━━━
[file:http://elpa.gnu.org/packages/plz.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].
[file:http://elpa.gnu.org/packages/plz.svg]
<http://elpa.gnu.org/packages/plz.html>
[httpbin] <https://httpbin.org/>
1 Installation
══════════════
1.1 GNU ELPA
────────────
  `plz' is available in [GNU ELPA].  It may be installed in Emacs using
  the `package-install' command.
[GNU ELPA] <http://elpa.gnu.org/packages/plz.html>
1.2 Manual
──────────
  `plz' has no dependencies other than Emacs and `curl'.  It's known to
  work on Emacs 26.3 or later.  To install it manually, simply place
  `plz.el' in your `load-path' and `(require 'plz)'.
2 Usage
═══════
  The main 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.
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...")
  └────
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' may be a string, a buffer, or a list like `(file
        FILENAME)' to upload a file from disk.
        `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, which will be narrowed
          to the response body and decoded according to `DECODE'.
        • `binary' to pass the response body as an un-decoded string.
        • `string' to pass the response body as a decoded string.
        • `response' to pass a `plz-response' structure.
        • `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.
        • 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'; if the request fails and no `ELSE' function is
        given (see below), the argument will be a `plz-error' structure
        describing the error.  Or `THEN' may be `sync' to make a
        synchronous request, in which case the result is returned
        directly from this function.
        `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.  If `ELSE' is nil, a `plz-curl-error' or
        `plz-http-error' is signaled when the request fails, with a
        `plz-error' structure as the error data.  For synchronous
        requests, this argument is ignored.
        `NOTE': In v0.8 of `plz', only one error will be signaled:
        `plz-error'.  The existing errors, `plz-curl-error' and
        `plz-http-error', inherit from `plz-error' to allow applications
        to update their code while using v0.7 (i.e. any `condition-case'
        forms should now handle only `plz-error', not the other two).
        `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.
2.3 Queueing
────────────
  `plz' provides a simple system for queueing HTTP requests.  First,
  make a `plz-queue' struct by calling `make-plz-queue'.  Then call
  `plz-queue' with the struct as the first argument, and the rest of the
  arguments being the same as those passed to `plz'.  Then call
  `plz-run' to run the queued requests.
  All of the queue-related functions return the queue as their value,
  making them easy to use.  For example:
  ┌────
  │ (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))))
  └────
  Or:
  ┌────
  │ (let ((queue (make-plz-queue :limit 2
  │ 			     :finally (lambda ()
  │ 					(message "Queue empty."))))
  │       (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))))))
  └────
  You may also clear a queue with `plz-clear', which cancels any active
  or queued requests and calls their `:else' functions.  And
  `plz-length' returns the number of a queue's active and queued
  requests.
2.4 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.
3 Changelog
═══════════
3.1 0.7
───────
  *Changes*
  ⁃ A new error signal, `plz-error', is defined.  The existing signals,
    `plz-curl-error' and `plz-http-error', inherit from it, so handling
    `plz-error' catches both.
    *NOTE:* The existing signals, `plz-curl-error' and `plz-http-error',
     are hereby deprecated, and they will be removed in v0.8.
     Applications should be updated while using v0.7 to only expect
     `plz-error'.
  *Fixes*
  ⁃ Significant improvement in reliability by implementing failsafes and
    workarounds for Emacs's process-handling code.  (See [#3].)
  ⁃ STDERR output from curl processes is not included in response bodies
    (which sometimes happened, depending on Emacs's internal race
    conditions).  (Fixes [#23].)
  ⁃ Use `with-local-quit' for synchronous requests (preventing Emacs
    from complaining sometimes).  (Fixes [#26].)
  ⁃ Various fixes for `:as 'buffer' result type: decode body when
    appropriate; unset multibyte for binary; narrow to body; don't kill
    buffer prematurely.
  ⁃ When clearing a queue, don't try to kill finished processes.
  *Internal*
  ⁃ Response processing now happens outside the process sentinel, so any
    errors (e.g. in user callbacks) are not signaled from inside the
    sentinel.  (This avoids the 2-second pause Emacs imposes in such
    cases.)
  ⁃ Tests run against a local instance of [httpbin] (since the
    `httpbin.org' server is often overloaded).
  ⁃ No buffer-local variables are defined anymore; process properties
    are used instead.
[#3] <https://github.com/alphapapa/plz.el/issues/3>
[#23] <https://github.com/alphapapa/plz.el/issues/23>
[#26] <https://github.com/alphapapa/plz.el/issues/26>
[httpbin] <https://github.com/postmanlabs/httpbin>
3.2 0.6
───────
  *Additions*
  ⁃ Function `plz''s `:body' argument now accepts a list like `(file
    FILENAME)' to upload a file from disk (by passing the filename to
    curl, rather than reading its content into Emacs and sending it to
    curl through the pipe).
  *Fixes*
  ⁃ Function `plz''s docstring now mentions that the `:body' argument
    may also be a buffer (an intentional feature that was accidentally
    undocumented).
  ⁃ Handle HTTP 3xx redirects when using `:as 'response'.
3.3 0.5.4
─────────
  *Fixes*
  ⁃ Only run queue's `finally' function after queue is empty.  (New
    features should not be designed and released on a Friday.)
3.4 0.5.3
─────────
  *Fixes*
  ⁃ Move new slot in `plz-queue' struct to end to prevent invalid
    byte-compiler expansions for already-compiled applications (which
    would require them to be recompiled after upgrading `plz').
3.5 0.5.2
─────────
  *Fixes*
  ⁃ When clearing a queue, only call `plz-queue''s `finally' function
    when specified.
3.6 0.5.1
─────────
  *Fixes*
  ⁃ Only call `plz-queue''s `finally' function when specified.  (Thanks
    to [Dan Oriani] for reporting.)
[Dan Oriani] <https://github.com/redchops>
3.7 0.5
───────
  *Additions*
  ⁃ Struct `plz-queue''s `finally' slot, a function called when the
    queue is finished.
3.8 0.4
───────
  *Additions*
  ⁃ Support for HTTP `HEAD' requests.  (Thanks to [USHIN, Inc.] for
    sponsoring.)
  *Changes*
  ⁃ Allow sending `POST' and `PUT' requests without bodies.  ([#16].
    Thanks to [Joseph Turner] for reporting.  Thanks to [USHIN, Inc.]
    for sponsoring.)
  *Fixes*
  ⁃ All 2xx HTTP status codes are considered successful.  ([#17].
    Thanks to [Joseph Turner] for reporting.  Thanks to [USHIN, Inc.]
    for sponsoring.)
  ⁃ Errors are signaled with error data correctly.
  *Internal*
  ⁃ Test suite explicitly tests with both HTTP/1.1 and HTTP/2.
  ⁃ Test suite also tests with Emacs versions 27.2, 28.1, and 28.2.
[USHIN, Inc.] <https://ushin.org/>
[#16] <https://github.com/alphapapa/plz.el/issues/16>
[Joseph Turner] <https://github.com/josephmturner>
[#17] <https://github.com/alphapapa/plz.el/issues/17>
3.9 0.3
───────
  *Additions*
  ⁃ Handle HTTP proxy headers from Curl. ([#2].  Thanks to [Alan Third]
    and [Sawyer Zheng] for reporting.)
  *Fixes*
  ⁃ Replaced words not in Ispell's default dictionaries (so `checkdoc'
    linting succeeds).
[#2] <https://github.com/alphapapa/plz.el/issues/2>
[Alan Third] <https://github.com/alanthird>
[Sawyer Zheng] <https://github.com/sawyerzheng>
3.10 0.2.1
──────────
  *Fixes*
  ⁃ Handle when Curl process is interrupted.
3.11 0.2
────────
  *Added*
  ⁃ Simple request queueing.
3.12 0.1
────────
  Initial release.
4 Credits
═════════
  ⁃ Thanks to [Chris Wellons], author of the [Elfeed] feed reader and
    the popular blog [null program], for his invaluable advice, review,
    and encouragement.
[Chris Wellons] <https://github.com/skeeto>
[Elfeed] <https://github.com/skeeto/elfeed>
[null program] <https://nullprogram.com/>
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].  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.
[Ement.el] <https://github.com/alphapapa/ement.el>
5.1 Copyright assignment
────────────────────────
  This package is part of [GNU Emacs], being distributed in [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
  [emacs-devel@gnu.org] to request the assignment form.
[GNU Emacs] <https://www.gnu.org/software/emacs/>
[GNU ELPA] <https://elpa.gnu.org/>
[emacs-devel@gnu.org] <mailto:emacs-devel@gnu.org>
6 License
═════════
  GPLv3

# * test.yml --- Test Emacs packages using makem.sh on GitHub Actions
# URL: https://github.com/alphapapa/makem.sh
# Version: 0.6-pre
# * Commentary:
# Based on Steve Purcell's examples at
# <https://github.com/purcell/setup-emacs/blob/master/.github/workflows/test.yml>,
# <https://github.com/purcell/package-lint/blob/master/.github/workflows/test.yml>.
# * License:
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
# You should have received a copy of the GNU General Public License
# along with this program.  If not, see <https://www.gnu.org/licenses/>.
# * Code:
name: "CI"
on:
  pull_request:
  push:
    # Comment out this section to enable testing of all branches.
    # branches:
    #   - master
jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        emacs_version:
          - 26.3
          - 27.1
          - 27.2
          - 28.1
          - 28.2
          - snapshot
    steps:
    - uses: purcell/setup-emacs@master
      with:
        version: ${{ matrix.emacs_version }}
    - uses: actions/checkout@v2
    - name: Install Ispell
      run: |
        sudo apt-get install ispell
    - name: Initialize sandbox
      run: |
        SANDBOX_DIR=$(mktemp -d) || exit 1
        echo "SANDBOX_DIR=$SANDBOX_DIR" >> $GITHUB_ENV
        ./makem.sh -vv --sandbox=$SANDBOX_DIR --install-deps --install-linters
    - name: Run httpbin with Docker
      run: docker run -d -p 80:80 -P kennethreitz/httpbin
    # The "all" rule is not used, because it treats compilation warnings
    # as failures, so linting and testing are run as separate steps.
    - name: Lint
      # NOTE: Uncomment this line to treat lint failures as passing so
      #       the job doesn't show failure.  (Enabled for now because
      #       Emacs 29 indents some cl- forms differently, which
      #       causes lint-indent to fail, and what matters most is
      #       that the tests pass.)
      continue-on-error: true
      run: ./makem.sh -vv --sandbox=$SANDBOX_DIR lint
    - name: Test
      if: always()  # Run test even if linting fails.
      run: ./makem.sh -vv --sandbox=$SANDBOX_DIR test
# Local Variables:
# eval: (outline-minor-mode)
# End:

This is mastodon.info, produced by makeinfo version 6.8 from
mastodon.texi.
INFO-DIR-SECTION Emacs
START-INFO-DIR-ENTRY
* Mastodon: (mastodon). Client for Mastodon on ActivityPub networks.
END-INFO-DIR-ENTRY

File: mastodon.info,  Node: Top,  Next: README,  Up: (dir)
* Menu:
* README::
— The Detailed Node Listing —
README
* Installation::
* Usage::
* Dependencies::
* Network compatibility::
* Contributing::
* Supporting ‘mastodon.el’: Supporting mastodonel.
* Contributors::
Installation
* ELPA::
* MELPA::
* Repo::
* Emoji::
* Discover::
Usage
* Logging in to your instance::
* Timelines::
* Composing toots::
* Other commands and account settings::
* Customization::
* Commands and variables index::
* Alternative timeline layout::
* Live-updating timelines mastodon-async-mode::
* Translating toots::
* Bookmarks and ‘mastodon.el’: Bookmarks and mastodonel.
Contributing
* Bug reports::
* Fixes and features::
* Coding style::

File: mastodon.info,  Node: README,  Prev: Top,  Up: Top
1 README
********
‘mastodon.el’ is an Emacs client for the AcitivityPub social networks
that implement the Mastodon API.  For info see joinmastodon.org
(https://joinmastodon.org/).
* Menu:
* Installation::
* Usage::
* Dependencies::
* Network compatibility::
* Contributing::
* Supporting ‘mastodon.el’: Supporting mastodonel.
* Contributors::

File: mastodon.info,  Node: Installation,  Next: Usage,  Up: README
1.1 Installation
================
You can install ‘mastodon.el’ from ELPA, MELPA, or directly from this
repo.  It is also available as a GUIX package.
* Menu:
* ELPA::
* MELPA::
* Repo::
* Emoji::
* Discover::

File: mastodon.info,  Node: ELPA,  Next: MELPA,  Up: Installation
1.1.1 ELPA
----------
You should be able to directly install with:
   ‘M-x package-refresh-contents RET’
   ‘M-x package-install RET mastodon RET’

File: mastodon.info,  Node: MELPA,  Next: Repo,  Prev: ELPA,  Up: Installation
1.1.2 MELPA
-----------
Add ‘MELPA’ to your archives:
     (require 'package)
     (add-to-list 'package-archives
                  '("melpa" . "http://melpa.org/packages/") t)
   Update and install:
   ‘M-x package-refresh-contents RET’
   ‘M-x package-install RET mastodon RET’

File: mastodon.info,  Node: Repo,  Next: Emoji,  Prev: MELPA,  Up: Installation
1.1.3 Repo
----------
Clone this repository and add the lisp directory to your load path.
Then, require it and go.
     (add-to-list 'load-path "/path/to/mastodon.el/lisp")
     (require 'mastodon)
   Or, with ‘use-package’:
     (use-package mastodon
       :ensure t)
   The minimum Emacs version is now 27.1.  But if you are running an
older version it shouldn’t be very hard to get it working.

File: mastodon.info,  Node: Emoji,  Next: Discover,  Prev: Repo,  Up: Installation
1.1.4 Emoji
-----------
‘mastodon-mode’ will enable Emojify
(https://github.com/iqbalansari/emacs-emojify) if it is loaded in your
Emacs environment, so there’s no need to write your own hook anymore.
‘emojify-mode’ is not required.

File: mastodon.info,  Node: Discover,  Prev: Emoji,  Up: Installation
1.1.5 Discover
--------------
‘mastodon-mode’ can provide a context menu for its keybindings if
Discover (https://github.com/mickeynp/discover.el) is installed.  It is
not required.
   if you have Discover, add the following to your Emacs init
configuration:
     (require 'mastodon-discover)
     (with-eval-after-load 'mastodon (mastodon-discover))
   Or, with ‘use-package’:
     (use-package mastodon
       :ensure t
       :config
       (mastodon-discover))

File: mastodon.info,  Node: Usage,  Next: Dependencies,  Prev: Installation,  Up: README
1.2 Usage
=========
* Menu:
* Logging in to your instance::
* Timelines::
* Composing toots::
* Other commands and account settings::
* Customization::
* Commands and variables index::
* Alternative timeline layout::
* Live-updating timelines mastodon-async-mode::
* Translating toots::
* Bookmarks and ‘mastodon.el’: Bookmarks and mastodonel.

File: mastodon.info,  Node: Logging in to your instance,  Next: Timelines,  Up: Usage
1.2.1 Logging in to your instance
---------------------------------
You need to set 2 variables in your init file to get started:
  1. ‘mastodon-instance-url’
  2. ‘mastodon-active-user’
   (see their doc strings for details).  For example If you want to post
toots as "example_user@social.instance.org", then put this in your init
file:
     (setq mastodon-instance-url "https://social.instance.org"
           mastodon-active-user "example_user")
   Then *restart* Emacs and run ‘M-x mastodon’.  Make sure you are
connected to internet before you do this.  If you have multiple mastodon
accounts you can activate one at a time by changing those two variables
and restarting Emacs.
   If you were using mastodon.el before 2FA was implemented and the
above steps do not work, delete the old file specified by
‘mastodon-client--token-file’ and restart Emacs and follow the steps
again.

File: mastodon.info,  Node: Timelines,  Next: Composing toots,  Prev: Logging in to your instance,  Up: Usage
1.2.2 Timelines
---------------
‘M-x mastodon’
   Opens a ‘*mastodon-home*’ buffer in the major mode and displays
toots.  If your credentials are not yet saved, you will be prompted for
email and password.  The app registration process will take place if
your ‘mastodon-token-file’ does not contain ‘:client_id’ and
‘:client_secret’.
  1. Keybindings
     Key                      Action
     -----------------------------------------------------------------------------------------------------------
                              *Help*
     ‘?’                      Show discover menu of all bindings, if ‘discover’ is available
                              *Timeline actions*
     ‘n’                      Go to next item (toot, notification, user)
     ‘p’                      Go to previous item (toot, notification, user)
     ‘M-n=/=<tab>’            Go to the next interesting thing that has an action
     ‘M-p=/=<S-tab>’          Go to the previous interesting thing that has an action
     ‘F’                      Open federated timeline (1 prefix arg: hide-replies, 2 prefix args: media only)
     ‘H’                      Open home timeline (1 prefix arg: hide-replies)
     ‘L’                      Open local timeline (1 prefix arg: hide-replies, 2 prefix args: media only)
     ‘N’                      Open notifications timeline
     ‘@’                      Open mentions-only notifications timeline
     ‘u’                      Update current timeline
     ‘T’                      Open thread for toot at point
     ‘#’                      Prompt for tag and open its timeline
     ‘A’                      Open author profile of toot at point
     ‘P’                      Open profile of user attached to toot at point
     ‘O’                      View own profile
     ‘U’                      update your profile bio note
     ‘;’                      view instance description for toot at point
     ‘:’                      view followed tags and load a tag timeline
     ‘C-:’                    view timeline of all followed tags
     ‘,’                      view favouriters of toot at point
     ‘.’                      view boosters of toot at point
     ‘/’                      switch between mastodon buffers
     ‘Z’                      report user/toot at point to instances moderators
                              *Other views*
     ‘s’                      search (posts, users, tags) (NB: only posts you have interacted with)
     ‘I’, ‘c’, ‘d’            view, create, and delete filters
     ‘R’, ‘a’, ‘j’            view/accept/reject follow requests
     ‘G’                      view follow suggestions
     ‘V’                      view your favourited toots
     ‘K’                      view bookmarked toots
     ‘X’                      view/edit/create/delete lists
     ‘S’                      view your scheduled toots
                              *Toot actions*
     ‘t’                      Compose a new toot
     ‘c’                      Toggle content warning content
     ‘b’                      Boost toot under ‘point’
     ‘f’                      Favourite toot under ‘point’
     ‘k’                      toggle bookmark of toot at point
     ‘r’                      Reply to toot under ‘point’
     ‘v’                      Vote on poll at point
     ‘C’                      copy url of toot at point
     ‘C-RET’                  play video/gif at point (requires ‘mpv’)
     ‘e’                      edit your toot at point
     ‘E’                      view edits of toot at point
     ‘i’                      (un)pin your toot at point
     ‘d’                      delete your toot at point, and reload current timeline
     ‘D’                      delete and redraft toot at point, preserving reply/CW/visibility
     (‘S-C-’) ‘W’, ‘M’, ‘B’   (un)follow, (un)mute, (un)block author of toot at point
                              *Profile view*
     ‘C-c C-c’                cycle between statuses, statuses without boosts, followers, and following
                              ‘mastodon-profile--account-account-to-list’ (see lists view)
                              *Notifications view*
     ‘a’, ‘j’                 accept/reject follow request
     ‘C-k’                    clear notification at point
                              see ‘mastodon-notifications--get-*’ functions for filtered views
                              *Quitting*
     ‘q’                      Quit mastodon buffer, leave window open
     ‘Q’                      Quit mastodon buffer and kill window
     ‘C-M-q’                  Quit and kill all mastodon buffers
  2. Toot byline legend
     Marker             Meaning
     --------------------------------------------
     ‘(🔁)’ (or          I boosted this toot
     ‘(B)’)
     ‘(⭐)’ (or          I favourited this toot
     ‘(F)’)
     ‘(🔖)’ (or          I bookmarked this toot
     (‘K’))

File: mastodon.info,  Node: Composing toots,  Next: Other commands and account settings,  Prev: Timelines,  Up: Usage
1.2.3 Composing toots
---------------------
‘M-x mastodon-toot’ (or ‘t’ from a mastodon.el buffer) opens a new
buffer/window in ‘text-mode’ and ‘mastodon-toot’ minor mode.  Enter the
contents of your toot here.  ‘C-c C-c’ sends the toot.  ‘C-c C-k’
cancels.  Both actions kill the buffer and window.  Further keybindings
are displayed in the buffer, and in the following subsection.
   Replies preserve visibility status/content warnings, and include
boosters by default.
   Server’s max toot length, and attachment previews, are shown.
   You can download and use your instance’s custom emoji
(‘mastodon-toot--download-custom-emoji’,
‘mastodon-toot--enable-custom-emoji’).
   The compose buffer uses ‘text-mode’ so any configuration you have for
that mode will be enabled.  If any of your existing config conflicts
with ‘mastodon-toot’, you can disable it in the
‘mastodon-toot-mode-hook’.  For example, the default value of that hook
is as follows:
     (add-hook 'mastodon-toot-mode-hook
               (lambda ()
                   (auto-fill-mode -1)))
  1. Keybindings
     Key         Action
     -------------------------------------------------
     ‘C-c C-c’   Send toot
     ‘C-c C-k’   Cancel toot
     ‘C-c C-w’   Add content warning
     ‘C-c C-v’   Change toot visibility
     ‘C-c C-n’   Add sensitive media/nsfw flag
     ‘C-c C-a’   Upload attachment(s)
     ‘C-c !’     Remove all attachments
     ‘C-c C-e’   Add emoji (if ‘emojify’ installed)
     ‘C-c C-p’   Create a poll
     ‘C-c C-l’   Set toot language
  2. Autocompletion of mentions and tags
     Autocompletion of mentions and tags is provided by
     ‘completion-at-point-functions’ (capf) backends.
     ‘mastodon-toot--enable-completion’ is enabled by default.  If you
     want to enable ‘company-mode’ in the toot compose buffer, set
     ‘mastodon-toot--use-company-for-completion’ to ‘t’.  (‘mastodon.el’
     used to run its own native company backends, but these have been
     removed in favour of capfs.)
     If you don’t run ‘company’ and want immediate, keyless completion,
     you’ll need to have another completion engine running that handles
     capfs.  A common combination is ‘consult’ and ‘corfu’.
  3. Draft toots
        • Compose buffer text is saved as you type, kept in
          ‘mastodon-toot-current-toot-text’.
        • ‘mastodon-toot--save-draft’: save the current toot as a draft.
        • ‘mastodon-toot--open-draft-toot’: Open a compose buffer and
          insert one of your draft toots.
        • ‘mastodon-toot--delete-draft-toot’: Delete a draft toot.
        • ‘mastodon-toot--delete-all-drafts’: Delete all your drafts.

File: mastodon.info,  Node: Other commands and account settings,  Next: Customization,  Prev: Composing toots,  Up: Usage
1.2.4 Other commands and account settings:
------------------------------------------
In addition to ‘mastodon’, the following three functions are autoloaded
and should work without first loading ‘mastodon.el’:
   • ‘mastodon-toot’: Compose new toot
   • ‘mastodon-notifications-get’: View all notifications
   • ‘mastodon-url-lookup’: Attempt to load a URL in ‘mastodon.el’.  URL
     may be at point or provided in the minibuffer.
   • ‘mastodon-tl--view-instance-description’: View information about
     the instance that the author of the toot at point is on.
   • ‘mastodon-tl--view-own-instance’: View information about your own
     instance.
   • ‘mastodon-search--trending-tags’: View a list of trending hashtags
     on your instance.
   • ‘mastodon-search--trending-statuses’: View a list of trending
     statuses on your instance.
   • ‘mastodon-tl--add-toot-account-at-point-to-list’: Add the account
     of the toot at point to a list.
   • ‘mastodon-tl--dm-user’: Send a direct message to one of the users
     at point.
   • ‘mastodon-profile--add-private-note-to-account’: Add a private note
     to another user’s account.
   • ‘mastodon-profile--view-account-private-note’: View a private note
     on a user’s account.
   • ‘mastodon-profile--show-familiar-followers’: Show a list of
     “familiar followers” for a given account.  Familiar followers are
     accounts that you follow, and that follow the account.
   • ‘mastodon-tl--follow-tag’: Follow a tag (works like following a
     user)
   • ‘mastodon-tl--unfollow-tag’: Unfollow a tag
   • ‘mastodon-tl--list-followed-tags’: View a list of tags you’re
     following.
   • ‘mastodon-tl--followed-tags-timeline’: View a timeline of all your
     followed tags.
   • ‘mastodon-tl--some-followed-tags-timleine’: View a timeline of
     multiple tags, from your followed tags or any other.
   • ‘mastodon-switch-to-buffer’: switch between mastodon buffers.
   • ‘mastodon-profile--update-display-name’: Update the display name
     for your account.
   • ‘mastodon-profile--update-user-profile-note’: Update your bio note.
   • ‘mastodon-profile--update-meta-fields’: Update your metadata
     fields.
   • ‘mastodon-profile--set-default-toot-visibility’: Set the default
     visibility for your toots.
   • ‘mastodon-profile--account-locked-toggle’: Toggle the locked status
     of your account.  Locked accounts have to manually approve follow
     requests.
   • ‘mastodon-profile--account-discoverable-toggle’: Toggle the
     discoverable status of your account.  Non-discoverable accounts are
     not listed in the profile directory.
   • ‘mastodon-profile--account-bot-toggle’: Toggle whether your account
     is flagged as a bot.
   • ‘mastodon-profile--account-sensitive-toggle’: Toggle whether your
     posts are marked as sensitive (nsfw) by default.

File: mastodon.info,  Node: Customization,  Next: Commands and variables index,  Prev: Other commands and account settings,  Up: Usage
1.2.5 Customization
-------------------
See ‘M-x customize-group RET mastodon’ to view all customize options.
   • Timeline options:
        • Use proportional fonts
        • Default number of posts displayed
        • Timestamp format
        • Relative timestamps
        • Display user avatars
        • Avatar image height
        • Enable image caching
        • Hide replies in timelines
        • Show toot stats in byline
   • Compose options:
        • Completion style for mentions and tags
        • Enable custom emoji
        • Display toot being replied to
        • Set default reply visibility

File: mastodon.info,  Node: Commands and variables index,  Next: Alternative timeline layout,  Prev: Customization,  Up: Usage
1.2.6 Commands and variables index
----------------------------------
An index of all user-facing commands and custom variables is available
here: mastodon-index.org (mastodon-index.org).

File: mastodon.info,  Node: Alternative timeline layout,  Next: Live-updating timelines mastodon-async-mode,  Prev: Commands and variables index,  Up: Usage
1.2.7 Alternative timeline layout
---------------------------------
The incomparable Nicholas Rougier has written an alternative timeline
layout for ‘mastodon.el’.
   The repo is at mastodon-alt
(https://github.com/rougier/mastodon-alt).

File: mastodon.info,  Node: Live-updating timelines mastodon-async-mode,  Next: Translating toots,  Prev: Alternative timeline layout,  Up: Usage
1.2.8 Live-updating timelines: ‘mastodon-async-mode’
----------------------------------------------------
(code taken from mastodon-future
(https://github.com/alexjgriffith/mastodon-future.el).)
   Works for federated, local, and home timelines and for notifications.
It’s a little touchy, one thing to avoid is trying to load a timeline
more than once at a time.  It can go off the rails a bit, but it’s still
pretty cool.  The current maintainer of ‘mastodon.el’ is unable to debug
or improve this feature.
   To enable, it, add ‘(require 'mastodon-async)’ to your ‘init.el’.
Then you can view a timeline with one of the commands that begin with
‘mastodon-async--stream-’.

File: mastodon.info,  Node: Translating toots,  Next: Bookmarks and mastodonel,  Prev: Live-updating timelines mastodon-async-mode,  Up: Usage
1.2.9 Translating toots
-----------------------
You can translate toots with ‘mastodon-toot--translate-toot-text’ (‘a’
in a timeline).  At the moment this requires lingva.el
(https://codeberg.org/martianh/lingva.el), a little interface I wrote to
lingva.ml (https://lingva.ml), to be installed to work.
   You could easily modify the simple function to use your Emacs
translator of choice (‘libretrans.el’ , ‘google-translate’, ‘babel’,
‘go-translate’, etc.), you just need to fetch the toot’s content with
‘(mastodon-tl--content toot)’ and pass it to your translator function as
its text argument.  Here’s what ‘mastodon-toot--translate-toot-text’
looks like:
     (defun mastodon-toot--translate-toot-text ()
       "Translate text of toot at point.
       Uses `lingva.el'."
         (interactive)
         (let* ((toot (mastodon-tl--property 'item-json)))
           (if toot
               (lingva-translate nil (mastodon-tl--content toot))
             (message "No toot to translate?"))))

File: mastodon.info,  Node: Bookmarks and mastodonel,  Prev: Translating toots,  Up: Usage
1.2.10 Bookmarks and ‘mastodon.el’
----------------------------------
‘mastodon.el’ doesn’t currently implement its own bookmark record and
handler, which means that emacs bookmarks will not work as is.  Until we
implement them, you can get bookmarks going immediately by using
bookmark+.el
(https://github.com/emacsmirror/emacswiki.org/blob/master/bookmark%2b.el).

File: mastodon.info,  Node: Dependencies,  Next: Network compatibility,  Prev: Usage,  Up: README
1.3 Dependencies
================
Hard dependencies (should all install with ‘mastodon.el’):
   • ‘request’ (for uploading attachments), emacs-request
     (https://github.com/tkf/emacs-request)
   • ‘persist’ for storing some settings across sessions
   Optional dependencies (install yourself, ‘mastodon.el’ can use them):
   • ‘emojify’ for inserting and viewing emojis
   • ‘mpv’ and ‘mpv.el’ for viewing videos and gifs
   • ‘lingva.el’ for translating toots

File: mastodon.info,  Node: Network compatibility,  Next: Contributing,  Prev: Dependencies,  Up: README
1.4 Network compatibility
=========================
‘mastodon.el’ should work with ActivityPub servers that implement the
Mastodon API.
   Apart from Mastodon itself, it is currently known to work with:
   • Pleroma (pleroma.social (https://pleroma.social/))
   • Akkoma (akkoma.social (https://akkoma.social/))
   • Gotosocial (gotosocial.org (https://gotosocial.org/))
   It does not support the non-Mastodon API servers Misskey (misskey.io
(https://misskey.io/)), Firefish (joinfirefish.org
(https://joinfirefish.org/), formerly Calkey) and Friendica, but it
should fully support displaying and interacting with posts and users on
those platforms.
   If you attempt to use ‘mastodon.el’ with a server and run into
problems, feel free to open an issue.

File: mastodon.info,  Node: Contributing,  Next: Supporting mastodonel,  Prev: Network compatibility,  Up: README
1.5 Contributing
================
PRs, issues, feature requests, and general feedback are very welcome!
* Menu:
* Bug reports::
* Fixes and features::
* Coding style::

File: mastodon.info,  Node: Bug reports,  Next: Fixes and features,  Up: Contributing
1.5.1 Bug reports
-----------------
  1. ‘mastodon.el’ has bugs, as well as lots of room for improvement.
  2. I receive very little feedback, so if I don’t run into the bug it
     often doesn’t get fixed.
  3. If you run into something that seems broken, first try running
     ‘mastodon.el’ in emacs with no init file (i.e.  ‘emacs -q’
     (instructions and code for doing this are here
     (https://codeberg.org/martianh/mastodon.el/issues/300)) to see if
     it also happens independently of your own config (it probably
     does).
  4. Enable debug on error (‘toggle-debug-on-error’), make the bug
     happen again, and copy the backtrace that appears.
  5. Open an issue here and explain what is going on.  Provide your
     emacs version and what kind of server your account is on.

File: mastodon.info,  Node: Fixes and features,  Next: Coding style,  Prev: Bug reports,  Up: Contributing
1.5.2 Fixes and features
------------------------
  1. Create an issue (https://codeberg.org/martianh/mastodon.el/issues)
     detailing what you’d like to do.
  2. Fork the repository and create a branch off of ‘develop’.
  3. Run the tests and ensure that your code doesn’t break any of them.
  4. Create a pull request referencing the issue created in step 1.

File: mastodon.info,  Node: Coding style,  Prev: Fixes and features,  Up: Contributing
1.5.3 Coding style
------------------
   • This library uses an unconvential double dash (‘--’) between file
     namespaces and function names, which contradicts normal Elisp
     style.  This needs to be respected until the whole library is
     changed.
   • Use ‘aggressive-indent-mode’ or similar to keep your code indented.
   • Single spaces end sentences in docstrings.
   • There’s no need for a blank line after the first docstring line
     (one is added automatically when documentation is displayed).

File: mastodon.info,  Node: Supporting mastodonel,  Next: Contributors,  Prev: Contributing,  Up: README
1.6 Supporting ‘mastodon.el’
============================
If you’d like to support continued development of ‘mastodon.el’, I
accept donations via paypal: paypal.me/martianh
(https://paypal.me/martianh).  If you would prefer a different payment
method, please write to me at <martianhiatus [at] riseup [dot] net> and
I can provide IBAN or other bank account details.
   I don’t have a tech worker’s income, so even a small tip would help
out.

File: mastodon.info,  Node: Contributors,  Prev: Supporting mastodonel,  Up: README
1.7 Contributors
================
‘mastodon.el’ is the work of a number of people.
   Some significant contributors are:
   • <https://github.com/jdenen> [original author]
   • <http://atomized.org>
   • <https://alexjgriffith.itch.io>
   • <https://github.com/hdurer>
   • <https://codeberg.org/Red_Starfish>

Tag Table:
Node: Top210
Node: README962
Node: Installation1378
Node: ELPA1667
Node: MELPA1895
Node: Repo2275
Node: Emoji2768
Node: Discover3099
Node: Usage3651
Node: Logging in to your instance4094
Node: Timelines5091
Ref: Keybindings5566
Ref: Toot byline legend10139
Node: Composing toots10448
Ref: Keybindings (1)11687
Ref: Autocompletion of mentions and tags12205
Ref: Draft toots12918
Node: Other commands and account settings13389
Node: Customization16547
Node: Commands and variables index17334
Node: Alternative timeline layout17654
Node: Live-updating timelines mastodon-async-mode18059
Node: Translating toots18911
Node: Bookmarks and mastodonel20093
Node: Dependencies20565
Node: Network compatibility21175
Node: Contributing22057
Node: Bug reports22346
Node: Fixes and features23252
Node: Coding style23735
Node: Supporting mastodonel24359
Node: Contributors24926

End Tag Table

Local Variables:
coding: utf-8
End:

;;; mastodon.el --- Client for fediverse services using the Mastodon API  -*- lexical-binding: t -*-
;; Copyright (C) 2017-2019 Johnson Denen
;; Copyright (C) 2020-2022 Marty Hiatt
;; Copyright (C) 2021 Abhiseck Paira <abhiseckpaira@disroot.org>
;; Author: Johnson Denen <johnson.denen@gmail.com>
;;         Marty Hiatt <martianhiatus@riseup.net>
;; Maintainer: Marty Hiatt <martianhiatus@riseup.net>
;; Version: 1.0.12
;; Package-Requires: ((emacs "27.1") (request "0.3.0") (persist "0.4"))
;; Homepage: https://codeberg.org/martianh/mastodon.el
;; This file is not part of GNU Emacs.
;; This file is part of mastodon.el.
;; mastodon.el is free software: you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation, either version 3 of the License, or
;; (at your option) any later version.
;; mastodon.el is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;; GNU General Public License for more details.
;; You should have received a copy of the GNU General Public License
;; along with mastodon.el.  If not, see <http://www.gnu.org/licenses/>.
;;; Commentary:
;; mastodon.el is a client for fediverse services that implement the Mastodon
;; API. See <https://github.com/mastodon/mastodon>.
;; See the readme file at https://codeberg.org/martianh/mastodon.el for set up
;; and usage details.
;;; Code:
(require 'cl-lib) ; for `cl-some' call in mastodon
(eval-when-compile (require 'subr-x))
(require 'mastodon-http)
(require 'mastodon-toot)
(require 'mastodon-search)
(require 'url)
(require 'thingatpt)
(require 'shr)
(declare-function discover-add-context-menu "discover")
(declare-function emojify-mode "emojify")
(declare-function request "request")
(autoload 'mastodon-auth--get-account-name "mastodon-auth")
(autoload 'mastodon-auth--user-acct "mastodon-auth")
(autoload 'mastodon-discover "mastodon-discover")
(autoload 'mastodon-notifications--follow-request-accept "mastodon-notifications")
(autoload 'mastodon-notifications--follow-request-reject "mastodon-notifications")
(autoload 'mastodon-notifications--get-mentions "mastodon-notifications")
(autoload 'mastodon-notifications--timeline "mastodon-notifications")
(autoload 'mastodon-profile--fetch-server-account-settings "mastodon-profile")
(autoload 'mastodon-profile--get-toot-author "mastodon-profile")
(autoload 'mastodon-profile--make-author-buffer "mastodon-profile")
(autoload 'mastodon-profile--my-profile "mastodon-profile")
(autoload 'mastodon-profile--show-user "mastodon-profile")
(autoload 'mastodon-profile--update-user-profile-note "mastodon-profile")
(autoload 'mastodon-profile--view-bookmarks "mastodon-profile")
(autoload 'mastodon-profile--view-favourites "mastodon-profile")
(autoload 'mastodon-tl--block-user "mastodon-tl")
(autoload 'mastodon-tl--follow-user "mastodon-tl")
(autoload 'mastodon-tl--followed-tags-timeline "mastodon-tl")
(autoload 'mastodon-tl--get-buffer-type "mastodon-tl")
(autoload 'mastodon-tl--get-federated-timeline "mastodon-tl")
(autoload 'mastodon-tl--get-home-timeline "mastodon-tl")
(autoload 'mastodon-tl--get-local-timeline "mastodon-tl")
(autoload 'mastodon-tl--get-tag-timeline "mastodon-tl")
(autoload 'mastodon-tl--goto-next-item "mastodon-tl")
(autoload 'mastodon-tl--goto-prev-item "mastodon-tl")
(autoload 'mastodon-tl--init-sync "mastodon-tl")
(autoload 'mastodon-tl--list-followed-tags "mastodon-tl")
(autoload 'mastodon-tl--mute-user "mastodon-tl")
(autoload 'mastodon-tl--next-tab-item "mastodon-tl")
(autoload 'mastodon-tl--poll-vote "mastodon-http")
(autoload 'mastodon-tl--previous-tab-item "mastodon-tl")
(autoload 'mastodon-tl--thread "mastodon-tl")
(autoload 'mastodon-tl--toggle-spoiler-text-in-toot "mastodon-tl")
(autoload 'mastodon-tl--unblock-user "mastodon-tl")
(autoload 'mastodon-tl--unfollow-user "mastodon-tl")
(autoload 'mastodon-tl--unmute-user "mastodon-tl")
(autoload 'mastodon-tl--report-to-mods "mastodon-tl")
(autoload 'mastodon-tl--update "mastodon-tl")
(autoload 'mastodon-toot--edit-toot-at-point "mastodon-toot")
(when (require 'lingva nil :no-error)
  (autoload 'mastodon-toot--translate-toot-text "mastodon-toot"))
(autoload 'mastodon-toot--view-toot-history "mastodon-tl")
(autoload 'mastodon-views--view-follow-suggestions "mastodon-views")
(autoload 'mastodon-views--view-filters "mastodon-views")
(autoload 'mastodon-views--view-follow-requests "mastodon-views")
(autoload 'mastodon-views--view-instance-description "mastodon-views")
(autoload 'mastodon-views--view-lists "mastodon-views")
(autoload 'mastodon-views--view-scheduled-toots "mastodon-views")
(autoload 'special-mode "simple")
(defvar mastodon-tl--highlight-current-toot)
(defvar mastodon-notifications--map)
(defgroup mastodon nil
  "Interface with Mastodon."
  :prefix "mastodon-"
  :group 'external)
(defcustom mastodon-instance-url "https://mastodon.social"
  "Base URL for the Mastodon instance you want to be active.
For example, if your mastodon username is
\"example_user@social.instance.org\", and you want this account
to be active, the value of this variable should be
\"https://social.instance.org\".
Also for completeness, the value of `mastodon-active-user' should
be \"example_user\".
After setting these variables you should restart Emacs for these
changes to take effect."
  :type 'string)
(defcustom mastodon-active-user nil
  "Username of the active user.
For example, if your mastodon username is
\"example_user@social.instance.org\", and you want this account
to be active, the value of this variable should be
\"example_user\".
Also for completeness, the value of `mastodon-instance-url'
should be \"https://social.instance.org\".
After setting these variables you should restart Emacs for these
changes to take effect."
  :type 'string)
(defcustom mastodon-toot-timestamp-format "%F %T"
  "Format to use for timestamps.
For valid formatting options see `format-time-string`.
The default value \"%F %T\" prints ISO8601-style YYYY-mm-dd HH:MM:SS.
Use. e.g. \"%c\" for your locale's date and time format."
  :type 'string)
(defvar mastodon-mode-map
  (let ((map (make-sparse-keymap)))
    ;; navigation inside a timeline
    (define-key map (kbd "n") #'mastodon-tl--goto-next-item)
    (define-key map (kbd "p") #'mastodon-tl--goto-prev-item)
    (define-key map (kbd "M-n") #'mastodon-tl--next-tab-item)
    (define-key map (kbd "M-p") #'mastodon-tl--previous-tab-item)
    (define-key map [?\t] #'mastodon-tl--next-tab-item)
    (define-key map [backtab] #'mastodon-tl--previous-tab-item)
    (define-key map [?\S-\t] #'mastodon-tl--previous-tab-item)
    (define-key map [?\M-\t] #'mastodon-tl--previous-tab-item)
    (define-key map (kbd "l") #'recenter-top-bottom)
    ;; navigation between timelines
    (define-key map (kbd "#") #'mastodon-tl--get-tag-timeline)
    (define-key map (kbd "\"") #'mastodon-tl--list-followed-tags)
    (define-key map (kbd "'") #'mastodon-tl--followed-tags-timeline)
    (define-key map (kbd "A") #'mastodon-profile--get-toot-author)
    (define-key map (kbd "F") #'mastodon-tl--get-federated-timeline)
    (define-key map (kbd "H") #'mastodon-tl--get-home-timeline)
    (define-key map (kbd "L") #'mastodon-tl--get-local-timeline)
    (define-key map (kbd "N") #'mastodon-notifications-get)
    (define-key map (kbd "@") #'mastodon-notifications--get-mentions)
    (define-key map (kbd "P") #'mastodon-profile--show-user)
    (define-key map (kbd "s") #'mastodon-search--query)
    (define-key map (kbd "/") #'mastodon-switch-to-buffer)
    ;; quitting mastodon
    (define-key map (kbd "q") #'kill-current-buffer)
    (define-key map (kbd "Q") #'kill-buffer-and-window)
    (define-key map (kbd "M-C-q") #'mastodon-kill-all-buffers)
    ;; toot actions
    (define-key map (kbd "c") #'mastodon-tl--toggle-spoiler-text-in-toot)
    (define-key map (kbd "b") #'mastodon-toot--toggle-boost)
    (define-key map (kbd "f") #'mastodon-toot--toggle-favourite)
    (define-key map (kbd "k") #'mastodon-toot--toggle-bookmark)
    (define-key map (kbd "r") #'mastodon-toot--reply)
    (define-key map (kbd "C") #'mastodon-toot--copy-toot-url)
    (define-key map (kbd "v") #'mastodon-tl--poll-vote)
    (define-key map (kbd "E") #'mastodon-toot--view-toot-edits)
    (define-key map (kbd "T") #'mastodon-tl--thread)
    (define-key map (kbd "m") #'mastodon-tl--dm-user)
    (when (require 'lingva nil :no-error)
      (define-key map (kbd "a") #'mastodon-toot--translate-toot-text))
    (define-key map (kbd ",") #'mastodon-toot--list-toot-favouriters)
    (define-key map (kbd ".") #'mastodon-toot--list-toot-boosters)
    (define-key map (kbd ";") #'mastodon-views--view-instance-description)
    ;; override special mode binding
    (define-key map (kbd "g") #'undefined)
    (define-key map (kbd "g") #'mastodon-tl--update)
    ;; this is now duplicated by 'g', cd remove/use for else:
    (define-key map (kbd "u") #'mastodon-tl--update)
    ;; own toot actions:
    (define-key map (kbd "t") #'mastodon-toot)
    (define-key map (kbd "d") #'mastodon-toot--delete-toot)
    (define-key map (kbd "D") #'mastodon-toot--delete-and-redraft-toot)
    (define-key map (kbd "i") #'mastodon-toot--pin-toot-toggle)
    (define-key map (kbd "e") #'mastodon-toot--edit-toot-at-point)
    ;; user actions
    (define-key map (kbd "W") #'mastodon-tl--follow-user)
    (define-key map (kbd "C-S-W") #'mastodon-tl--unfollow-user)
    (define-key map (kbd "B") #'mastodon-tl--block-user)
    (define-key map (kbd "C-S-B") #'mastodon-tl--unblock-user)
    (define-key map (kbd "M") #'mastodon-tl--mute-user)
    (define-key map (kbd "C-S-M") #'mastodon-tl--unmute-user)
    (define-key map (kbd "Z") #'mastodon-tl--report-to-mods)
    ;; own profile
    (define-key map (kbd "O") #'mastodon-profile--my-profile)
    (define-key map (kbd "U") #'mastodon-profile--update-user-profile-note)
    (define-key map (kbd "V") #'mastodon-profile--view-favourites)
    (define-key map (kbd "K") #'mastodon-profile--view-bookmarks)
    ;; minor views
    (define-key map (kbd "R") #'mastodon-views--view-follow-requests)
    (define-key map (kbd "S") #'mastodon-views--view-scheduled-toots)
    (define-key map (kbd "I") #'mastodon-views--view-filters)
    (define-key map (kbd "G") #'mastodon-views--view-follow-suggestions)
    (define-key map (kbd "X") #'mastodon-views--view-lists)
    (define-key map (kbd "SPC") #'mastodon-tl--scroll-up-command)
    map)
  "Keymap for `mastodon-mode'.")
(defcustom mastodon-mode-hook nil
  "Hook run when entering Mastodon mode."
  :type 'hook
  :options '(provide-discover-context-menu))
(defface mastodon-handle-face
  '((t :inherit default))
  "Face used for user handles in bylines.")
(defface mastodon-display-name-face
  '((t :inherit warning))
  "Face used for user display names.")
(defface mastodon-boosted-face
  '((t :inherit success :weight bold))
  "Face to indicate that a toot is boosted.")
(defface mastodon-boost-fave-face
  '((t :inherit success))
  "Face to indicate that you have boosted or favourited a toot.")
(defface mastodon-cw-face
  '((t :inherit success))
  "Face used for content warning.")
(defface mastodon-toot-docs-face
  `((t :inherit font-lock-comment-face))
  "Face used for documentation in toot compose buffer.
If `mastodon-tl--enable-proportional-fonts' is changed,
mastodon.el needs to be re-loaded for this to be correctly set.")
(defface mastodon-toot-docs-reply-text-face
  `((t :inherit font-lock-comment-face
       :family ,(face-attribute 'variable-pitch :family)))
  "Face used for reply text in toot compose buffer.
See `mastodon-toot-display-orig-in-reply-buffer'.")
(defface mastodon-cursor-highlight-face
  `((t :inherit highlight :extend t))
  "Face for `mastodon-tl--highlight-current-toot'.")
;;;###autoload
(defun mastodon ()
  "Connect Mastodon client to `mastodon-instance-url' instance."
  (interactive)
  (let* ((tls (list "home"
                    "local"
                    "federated"
                    (concat (mastodon-auth--user-acct) "-statuses") ; own profile
                    "favourites"
                    "search"))
         (buffer (or (cl-some (lambda (el)
                                (get-buffer (concat "*mastodon-" el "*")))
                              tls) ; return first buff that exists
                     (cl-some (lambda (x)
                                (when
                                    (string-prefix-p "*mastodon-" (buffer-name x))
                                  (get-buffer x)))
                              (buffer-list))))) ; catch any other masto buffer
    (mastodon-return-credential-account :force)
    (if buffer
        (switch-to-buffer buffer)
      (mastodon-tl--get-home-timeline)
      (message "Loading Mastodon account %s on %s..."
               (mastodon-auth--user-acct)
               mastodon-instance-url))))
(defvar mastodon-profile-credential-account nil)
(defun mastodon-return-credential-account (&optional force)
  "Return the CredentialAccount entity.
Either from `mastodon-profile-credential-account' or from the
server.
FORCE means to fetch from the server and update
`mastodon-profile-credential-account'."
  (let ((req '(mastodon-http--get-json
               (mastodon-http--api "accounts/verify_credentials")
               nil :silent)))
    (if force
        (setq mastodon-profile-credential-account
              (eval req))
      (or mastodon-profile-credential-account
          (setq mastodon-profile-credential-account
                (eval req))))))
;;;###autoload
(defun mastodon-toot (&optional user reply-to-id reply-json)
  "Update instance with new toot. Content is captured in a new buffer.
If USER is non-nil, insert after @ symbol to begin new toot.
If REPLY-TO-ID is non-nil, attach new toot to a conversation.
If REPLY-JSON is the json of the toot being replied to."
  (interactive)
  (mastodon-toot--compose-buffer user reply-to-id reply-json))
;;;###autoload
(defun mastodon-notifications-get (&optional type buffer-name force)
  "Display NOTIFICATIONS in buffer.
Optionally only print notifications of type TYPE, a string.
BUFFER-NAME is added to \"*mastodon-\" to create the buffer name.
FORCE means do not try to update an existing buffer, but fetch
from the server and load anew."
  (interactive)
  (let ((buffer (if buffer-name
                    (concat "*mastodon-" buffer-name "*")
                  "*mastodon-notifications*")))
    (if (and (not force)
             (get-buffer buffer))
        (progn (switch-to-buffer buffer)
               (mastodon-tl--update))
      (message "Loading your notifications...")
      (mastodon-tl--init-sync (or buffer-name "notifications")
                              "notifications"
                              'mastodon-notifications--timeline
                              type)
      (with-current-buffer buffer
        (use-local-map mastodon-notifications--map)))))
;; URL lookup: should be available even if `mastodon.el' not loaded:
;;;###autoload
(defun mastodon-url-lookup (&optional query-url)
  "If a URL resembles a mastodon link, try to load in `mastodon.el'.
Does a WebFinger lookup.
URL can be arg QUERY-URL, or URL at point, or provided by the user.
If a status or account is found, load it in `mastodon.el', if
not, just browse the URL in the normal fashion."
  (interactive)
  (let* ((query (or query-url
                    (thing-at-point-url-at-point)
                    (mastodon-tl--property 'shr-url :no-move)
                    (read-string "Lookup URL: "))))
    (if (not (mastodon--fedi-url-p query))
        ;; (shr-browse-url query) ; doesn't work (keep our shr keymap)
        (browse-url query)
      (message "Performing lookup...")
      (let* ((url (format "%s/api/v2/search" mastodon-instance-url))
             (params `(("q" . ,query)
                       ("resolve" . "t"))) ; webfinger
             (response (mastodon-http--get-json url params :silent)))
        (cond ((not (seq-empty-p
                     (alist-get 'statuses response)))
               (let* ((statuses (assoc 'statuses response))
                      (status (seq-first (cdr statuses)))
                      (status-id (alist-get 'id status)))
                 (mastodon-tl--thread status-id)))
              ((not (seq-empty-p
                     (alist-get 'accounts response)))
               (let* ((accounts (assoc 'accounts response))
                      (account (seq-first (cdr accounts))))
                 (mastodon-profile--make-author-buffer account)))
              (t
               (browse-url query)))))))
(defun mastodon--fedi-url-p (query)
  "Check if QUERY resembles a fediverse URL."
  ;; calqued off https://github.com/tuskyapp/Tusky/blob/c8fc2418b8f5458a817bba221d025b822225e130/app/src/main/java/com/keylesspalace/tusky/BottomSheetActivity.kt
  ;; thx to Conny Duck!
  (let* ((uri-parsed (url-generic-parse-url query))
         (query (url-filename uri-parsed)))
    (save-match-data
      (or (string-match "^/@[^/]+$" query)
          (string-match "^/@[^/]+/[[:digit:]]+$" query)
          (string-match "^/user[s]?/@?[[:alnum:]]+$" query) ; @: pleroma or soapbox
          (string-match "^/notice/[[:alnum:]]+$" query)
          (string-match "^/objects/[-a-f0-9]+$" query)
          (string-match "^/notes/[a-z0-9]+$" query)
          (string-match "^/display/[-a-f0-9]+$" query)
          (string-match "^/profile/[[:alpha:]]+$" query)
          (string-match "^/p/[[:alpha:]]+/[[:digit:]]+$" query)
          (string-match "^/[[:alpha:]]+$" query)
          (string-match "^/u/[[:alpha:]]+$" query)
          (string-match "^/c/[[:alnum:]]+$" query)
          (string-match "^/post/[[:digit:]]+$" query)
          (string-match "^/comment/[[:digit:]]+$" query) ; lemmy
          (string-match "^/user[s]?/[[:alnum:]]+/statuses/[[:digit:]]+$" query) ; hometown
          (string-match "^/notes/[[:alnum:]]+$" query))))) ; misskey post
(defun mastodon-live-buffers ()
  "Return a list of open mastodon buffers.
Calls `mastodon-tl--get-buffer-type', which see."
  (cl-loop for x in (buffer-list)
           when (with-current-buffer x (mastodon-tl--get-buffer-type))
           collect (get-buffer x)))
(defun mastodon-buffer-p (&optional buffer)
  "Non-nil if BUFFER or `current-buffer' is a mastodon one."
  (let ((buf (or buffer (current-buffer))))
    (member buf (mastodon-live-buffers))))
(defun mastodon-kill-all-buffers ()
  "Kill any and all open mastodon buffers, hopefully."
  (interactive)
  (let ((mastodon-buffers (mastodon-live-buffers)))
    (cl-loop for x in mastodon-buffers
             do (kill-buffer x))))
(defun mastodon-switch-to-buffer ()
  "Switch to a live mastodon buffer."
  (interactive)
  (let* ((bufs (mastodon-live-buffers))
         (buf-names (mapcar #'buffer-name bufs))
         (choice (completing-read "Switch to mastodon buffer: "
                                  buf-names)))
    (switch-to-buffer choice)))
(defun mastodon-mode-hook-fun ()
  "Function to add to `mastodon-mode-hook'."
  (when (require 'emojify nil :noerror)
    (emojify-mode t)
    (when mastodon-toot--enable-custom-instance-emoji
      (mastodon-toot--enable-custom-emoji)))
  (mastodon-profile--fetch-server-account-settings)
  (when mastodon-tl--highlight-current-toot
    (cursor-face-highlight-mode))) ; 29.1
;;;###autoload
(add-hook 'mastodon-mode-hook #'mastodon-mode-hook-fun)
(define-derived-mode mastodon-mode special-mode "Mastodon"
  "Major mode for Mastodon, the federated microblogging network."
  (read-only-mode 1))
(provide 'mastodon)
;;; mastodon.el ends here

;;; mastodon-views.el --- Minor views functions for mastodon.el  -*- lexical-binding: t -*-
;; Copyright (C) 2020-2022 Marty Hiatt
;; Author: Marty Hiatt <martianhiatus@riseup.net>
;; Maintainer: Marty Hiatt <martianhiatus@riseup.net>
;; Version: 1.0.0
;; Homepage: https://codeberg.org/martianh/mastodon.el
;; This file is not part of GNU Emacs.
;; This file is part of mastodon.el.
;; mastodon.el is free software: you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation, either version 3 of the License, or
;; (at your option) any later version.
;; mastodon.el is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;; GNU General Public License for more details.
;; You should have received a copy of the GNU General Public License
;; along with mastodon.el.  If not, see <http://www.gnu.org/licenses/>.
;;; Commentary:
;; mastodon-views.el provides minor views functions.
;; These are currently lists, follow suggestions, filters, scheduled toots,
;; follow requests, and instance descriptions.
;; It doesn't include favourites, bookmarks, preferences, trending tags, followed tags, toot edits,
;;; Code:
(require 'cl-lib)
(require 'mastodon-http)
(eval-when-compile
  (require 'mastodon-tl))
(defvar mastodon-mode-map)
(defvar mastodon-tl--horiz-bar)
(defvar mastodon-tl--timeline-posts-count)
(autoload 'mastodon-mode "mastodon")
(autoload 'mastodon-tl--init "mastodon-tl")
(autoload 'mastodon-tl--init-sync "mastodon-tl")
(autoload 'mastodon-tl--field "mastodon-tl")
(autoload 'mastodon-tl--property "mastodon-tl")
(autoload 'mastodon-tl--set-face "mastodon-tl")
(autoload 'mastodon-tl--buffer-type-eq "mastodon-tl")
(autoload 'mastodon-tl--profile-buffer-p "mastodon-tl")
(autoload 'mastodon-tl--goto-first-item "mastodon-tl")
(autoload 'mastodon-tl--do-if-item "mastodon-tl")
(autoload 'mastodon-tl--set-buffer-spec "mastodon-tl")
(autoload 'mastodon-tl--render-text "mastodon-tl")
(autoload 'mastodon-notifications--follow-request-accept "mastodon-notifications")
(autoload 'mastodon-notifications--follow-request-reject "mastodon-notifications")
(autoload 'mastodon-auth--get-account-id "mastodon-auth")
(autoload 'mastodon-toot--iso-to-human "mastodon-toot")
(autoload 'mastodon-toot--schedule-toot "mastodon-toot")
(autoload 'mastodon-toot--compose-buffer "mastodon-toot")
(autoload 'mastodon-toot--set-toot-properties "mastodon-toot")
(autoload 'mastodon-search--propertize-user "mastodon-search")
(autoload 'mastodon-search--insert-users-propertized "mastodon-search")
(autoload 'mastodon-tl--map-alist "mastodon-tl")
(autoload 'mastodon-tl--map-alist-vals-to-alist "mastodon-tl")

;;; KEYMAPS
;; we copy `mastodon-mode-map', as then all timeline functions are
;; available. this is helpful because if a minor view is the only buffer left
;; open, calling `mastodon' will switch to it, but then we will be unable to
;; switch to timlines without closing the minor view.
;; copying the mode map however means we need to avoid/unbind/override any
;; functions that might cause interfere with the minor view.
;; this is not redundant, as while the buffer -init function calls
;; `mastodon-mode', it gets overridden in some but not all cases.
(defvar mastodon-views-map
  (let ((map (make-sparse-keymap)))
    (set-keymap-parent map mastodon-mode-map)
    map)
  "Base keymap for minor mastodon views.")
(defvar mastodon-views--view-filters-keymap
  (let ((map (make-sparse-keymap)))
    (set-keymap-parent map mastodon-views-map)
    (define-key map (kbd "d") #'mastodon-views--delete-filter)
    (define-key map (kbd "c") #'mastodon-views--create-filter)
    (define-key map (kbd "g") #'mastodon-views--view-filters)
    map)
  "Keymap for viewing filters.")
(defvar mastodon-views--follow-suggestions-map
  (let ((map (make-sparse-keymap)))
    (set-keymap-parent map mastodon-views-map)
    (define-key map (kbd "g") #'mastodon-views--view-follow-suggestions)
    map)
  "Keymap for viewing follow suggestions.")
(defvar mastodon-views--view-lists-keymap
  (let ((map (make-sparse-keymap)))
    (set-keymap-parent map mastodon-views-map)
    (define-key map (kbd "D") #'mastodon-views--delete-list)
    (define-key map (kbd "C") #'mastodon-views--create-list)
    (define-key map (kbd "A") #'mastodon-views--add-account-to-list)
    (define-key map (kbd "R") #'mastodon-views--remove-account-from-list)
    (define-key map (kbd "E") #'mastodon-views--edit-list)
    (define-key map (kbd "g") #'mastodon-views--view-lists)
    map)
  "Keymap for viewing lists.")
(defvar mastodon-views--list-name-keymap
  (let ((map (make-sparse-keymap)))
    (define-key map (kbd "RET") #'mastodon-views--view-timeline-list-at-point)
    (define-key map (kbd "d") #'mastodon-views--delete-list-at-point)
    (define-key map (kbd "a") #'mastodon-views--add-account-to-list-at-point)
    (define-key map (kbd "r") #'mastodon-views--remove-account-from-list-at-point)
    (define-key map (kbd "e") #'mastodon-views--edit-list-at-point)
    map)
  "Keymap for when point is on list name.")
(defvar mastodon-views--scheduled-map
  (let ((map (make-sparse-keymap)))
    (set-keymap-parent map mastodon-views-map)
    (define-key map (kbd "r") #'mastodon-views--reschedule-toot)
    (define-key map (kbd "c") #'mastodon-views--cancel-scheduled-toot)
    (define-key map (kbd "e") #'mastodon-views--edit-scheduled-as-new)
    (define-key map (kbd "RET") #'mastodon-views--edit-scheduled-as-new)
    map)
  "Keymap for when point is on a scheduled toot.")
(defvar mastodon-views--view-follow-requests-keymap
  (let ((map (make-sparse-keymap)))
    (set-keymap-parent map mastodon-views-map)
    ;; make reject binding match the binding in notifs view
    ;; 'r' is then reserved for replying, even tho it is not avail
    ;; in foll-reqs view
    (define-key map (kbd "j") #'mastodon-notifications--follow-request-reject)
    (define-key map (kbd "a") #'mastodon-notifications--follow-request-accept)
    (define-key map (kbd "g") #'mastodon-views--view-follow-requests)
    map)
  "Keymap for viewing follow requests.")

;;; GENERAL FUNCTION
(defun mastodon-views--minor-view (view-name insert-fun data)
  "Load a minor view named VIEW-NAME.
BINDINGS-STRING is a string explaining the view's local bindings.
INSERT-FUN is the function to call to insert the view's elements.
DATA is the argument to insert-fun, usually JSON returned in a
request.
This function is used as the update-function to
`mastodon-tl--init-sync', which initializes a buffer for us and
provides the JSON data."
  ;; FIXME: this is not an update function as it inserts a heading and
  ;; possible bindings string
  ;; either it should go in init-sync, or possibly in each view function
  ;; but either way, this function does almost nothing for us.
  ;; could we call init-sync in here pehaps?
  ;; (mastodon-search--insert-heading view-name)
  ;; (when bindings-string
  ;;   (insert (mastodon-tl--set-face (concat "[" bindings-string "]\n\n")
  ;;                                  'font-lock-comment-face)))
  (if (seq-empty-p data)
      (insert (propertize
               (format "Looks like you have no %s for now." view-name)
               'face 'font-lock-comment-face
               'byline t
               'item-type 'no-item ; for nav
               'item-id "0")) ; so point can move here when no item
    (funcall insert-fun data)
    (goto-char (point-min)))
  ;; (when data
  ;; FIXME: this seems to trigger a new request, but ideally would run.
  ;; (mastodon-tl--goto-next-item))
  )

;;; LISTS
(defun mastodon-views--view-lists ()
  "Show the user's lists in a new buffer."
  (interactive)
  (mastodon-tl--init-sync "lists" "lists"
                          'mastodon-views--insert-lists
                          nil nil nil
                          "your lists"
                          "C - create a list\n D - delete a list\
     \n A/R - add/remove account from a list\
     \n E - edit a list\n n/p - go to next/prev item")
  (with-current-buffer "*mastodon-lists*"
    (use-local-map mastodon-views--view-lists-keymap)))
(defun mastodon-views--insert-lists (json)
  "Insert the user's lists from JSON."
  (mastodon-views--minor-view
   "lists"
   #'mastodon-views--print-list-set
   json))
(defun mastodon-views--print-list-set (lists)
  "Print each account plus a separator for each list in LISTS."
  (mapc (lambda (x)
          (mastodon-views--print-list-accounts x)
          (insert (propertize (concat " " mastodon-tl--horiz-bar "\n\n")
                              'face 'success)))
        lists))
(defun mastodon-views--print-list-accounts (list)
  "Insert the accounts in list named LIST, an alist."
  (let-alist list
    (let* ((accounts (mastodon-views--accounts-in-list .id)))
      (insert
       (propertize .title
                   'byline t ; so we nav here
                   'item-id "0" ; so we nav here
                   'item-type 'list
                   'help-echo "RET: view list timeline, d: delete this list, \
a: add account to this list, r: remove account from this list"
                   'list t
                   'face 'link
                   'keymap mastodon-views--list-name-keymap
                   'list-name .title
                   'list-id .id)
       (propertize (format " [replies: %s, exclusive %s]"
                           .replies_policy
                           (when (eq t .exclusive) "true"))
                   'face 'font-lock-comment-face)
       (propertize "\n\n"
                   'list t
                   'keymap mastodon-views--list-name-keymap
                   'list-name .title
                   'list-id .id)
       (propertize
        (mapconcat #'mastodon-search--propertize-user accounts
                   " ")
        'list t
        'keymap mastodon-views--list-name-keymap
        'list-name .title
        'list-id .id)))))
(defun mastodon-views--get-users-lists ()
  "Get the list of the user's lists from the server."
  (let ((url (mastodon-http--api "lists")))
    (mastodon-http--get-json url)))
(defun mastodon-views--get-lists-names ()
  "Return a list of the user's lists' names."
  (let ((lists (mastodon-views--get-users-lists)))
    (mastodon-tl--map-alist 'title lists)))
(defun mastodon-views--get-list-by-name (name)
  "Return the list data for list with NAME."
  (let* ((lists (mastodon-views--get-users-lists)))
    (cl-loop for list in lists
             if (string= (alist-get 'title list) name)
             return list)))
(defun mastodon-views--get-list-id (name)
  "Return id for list with NAME."
  (let ((list (mastodon-views--get-list-by-name name)))
    (alist-get 'id list)))
(defun mastodon-views--get-list-name (id)
  "Return name of list with ID."
  (let* ((url (mastodon-http--api (format "lists/%s" id)))
         (response (mastodon-http--get-json url)))
    (alist-get 'title response)))
(defun mastodon-views--edit-list-at-point ()
  "Edit list at point."
  (interactive)
  (let ((id (mastodon-tl--property 'list-id :no-move)))
    (mastodon-views--edit-list id)))
(defun mastodon-views--edit-list (&optional id)
  "Prompt for a list and edit the name and replies policy.
If ID is provided, use that list."
  (interactive)
  (let* ((list-names (unless id (mastodon-views--get-lists-names)))
         (name-old (if id
                       (mastodon-tl--property 'list-name :no-move)
                     (completing-read "Edit list: " list-names)))
         (id (or id (mastodon-views--get-list-id name-old)))
         (name-choice (read-string "List name: " name-old))
         (replies-policy (completing-read "Replies policy: " ; give this a proper name
                                          '("followed" "list" "none")
                                          nil t nil nil "list"))
         (exclusive (if (y-or-n-p "Exclude items from home timeline? ")
                        "true"
                      "false"))
         (url (mastodon-http--api (format "lists/%s" id)))
         (response (mastodon-http--put url
                                       `(("title" . ,name-choice)
                                         ("replies_policy" . ,replies-policy)
                                         ("exclusive" . ,exclusive)))))
    (mastodon-http--triage response
                           (lambda (_)
                             (with-current-buffer response
                               (let* ((json (mastodon-http--process-json))
                                      (name-new (alist-get 'title json)))
                                 (message "list %s edited to %s!" name-old name-new)))
                             (when (mastodon-tl--buffer-type-eq 'lists)
                               (mastodon-views--view-lists))))))
(defun mastodon-views--view-timeline-list-at-point ()
  "View timeline of list at point."
  (interactive)
  (let ((list-id (mastodon-tl--property 'list-id :no-move)))
    (mastodon-views--view-list-timeline list-id)))
(defun mastodon-views--view-list-timeline (&optional id)
  "Prompt for a list and view its timeline.
If ID is provided, use that list."
  (interactive)
  (let* ((list-names (unless id (mastodon-views--get-lists-names)))
         (list-name (unless id (completing-read "View list: " list-names)))
         (id (or id (mastodon-views--get-list-id list-name)))
         (endpoint (format "timelines/list/%s" id))
         (name (mastodon-views--get-list-name id))
         (buffer-name (format "list-%s" name)))
    (mastodon-tl--init buffer-name endpoint
                       'mastodon-tl--timeline
                       nil
                       `(("limit" . ,mastodon-tl--timeline-posts-count)))))
(defun mastodon-views--create-list ()
  "Create a new list.
Prompt for name and replies policy."
  (interactive)
  (let* ((title (read-string "New list name: "))
         (replies-policy (completing-read "Replies policy: " ; give this a proper name
                                          '("followed" "list" "none")
                                          nil t nil nil "list")) ; default
         (exclusive (when (y-or-n-p "Exclude items from home timeline? ")
                      "true"))
         (response (mastodon-http--post (mastodon-http--api "lists")
                                        `(("title" . ,title)
                                          ("replies_policy" . ,replies-policy)
                                          ("exclusive" . ,exclusive)))))
    (mastodon-views--list-action-triage
     response "list %s created!" title)))
(defun mastodon-views--delete-list-at-point ()
  "Delete list at point."
  (interactive)
  (let ((id (mastodon-tl--property 'list-id :no-move)))
    (mastodon-views--delete-list id)))
(defun mastodon-views--delete-list (&optional id)
  "Prompt for a list and delete it.
If ID is provided, delete that list."
  (interactive)
  (let* ((list-names (unless id (mastodon-views--get-lists-names)))
         (name (if id
                   (mastodon-views--get-list-name id)
                 (completing-read "Delete list: " list-names)))
         (id (or id (mastodon-views--get-list-id name)))
         (url (mastodon-http--api (format "lists/%s" id))))
    (when (y-or-n-p (format "Delete list %s?" name))
      (let ((response (mastodon-http--delete url)))
        (mastodon-views--list-action-triage
         response "list %s deleted!" name)))))
(defun mastodon-views--get-users-followings ()
  "Return the list of followers of the logged in account."
  (let* ((id (mastodon-auth--get-account-id))
         (url (mastodon-http--api (format "accounts/%s/following" id))))
    (mastodon-http--get-json url '(("limit" . "80"))))) ; max 80 accounts
(defun mastodon-views--add-account-to-list-at-point ()
  "Prompt for account and add to list at point."
  (interactive)
  (let ((id (mastodon-tl--property 'list-id :no-move)))
    (mastodon-views--add-account-to-list id)))
(defun mastodon-views--add-account-to-list (&optional id account-id handle)
  "Prompt for a list and for an account, add account to list.
If ID is provided, use that list.
If ACCOUNT-ID and HANDLE are provided use them rather than prompting."
  (interactive)
  (let* ((list-prompt (if handle
                          (format "Add %s to list: " handle)
                        "Add account to list: "))
         (list-name (if id
                        (mastodon-tl--property 'list-name :no-move)
                      (completing-read list-prompt
                                       (mastodon-views--get-lists-names) nil t)))
         (list-id (or id (mastodon-views--get-list-id list-name)))
         (followings (mastodon-views--get-users-followings))
         (handles (mastodon-tl--map-alist-vals-to-alist 'acct 'id followings))
         (account (or handle (completing-read "Account to add: "
                                              handles nil t)))
         (account-id (or account-id (alist-get account handles)))
         (url (mastodon-http--api (format "lists/%s/accounts" list-id)))
         (response (mastodon-http--post url `(("account_ids[]" . ,account-id)))))
    (mastodon-views--list-action-triage
     response "%s added to list %s!" account list-name)))
(defun mastodon-views--add-toot-account-at-point-to-list ()
  "Prompt for a list, and add the account of the toot at point to it."
  (interactive)
  (let* ((toot (mastodon-tl--property 'item-json))
         (account (mastodon-tl--field 'account toot))
         (account-id (mastodon-tl--field 'id account))
         (handle (mastodon-tl--field 'acct account)))
    (mastodon-views--add-account-to-list nil account-id handle)))
(defun mastodon-views--remove-account-from-list-at-point ()
  "Prompt for account and remove from list at point."
  (interactive)
  (let ((id (mastodon-tl--property 'list-id :no-move)))
    (mastodon-views--remove-account-from-list id)))
(defun mastodon-views--remove-account-from-list (&optional id)
  "Prompt for a list, select an account and remove from list.
If ID is provided, use that list."
  (interactive)
  (let* ((list-name (if id
                        (mastodon-tl--property 'list-name :no-move)
                      (completing-read "Remove account from list: "
                                       (mastodon-views--get-lists-names) nil t)))
         (list-id (or id (mastodon-views--get-list-id list-name)))
         (accounts (mastodon-views--accounts-in-list list-id))
         (handles (mastodon-tl--map-alist-vals-to-alist 'acct 'id accounts))
         (account (completing-read "Account to remove: "
                                   handles nil t))
         (account-id (alist-get account handles))
         (url (mastodon-http--api (format "lists/%s/accounts" list-id)))
         (args (mastodon-http--build-array-params-alist "account_ids[]" `(,account-id)))
         (response (mastodon-http--delete url args)))
    (mastodon-views--list-action-triage
     response "%s removed from list %s!" account list-name)))
(defun mastodon-views--list-action-triage (response &rest args)
  "Call `mastodon-http--triage' on RESPONSE and call message on ARGS."
  (mastodon-http--triage response
                         (lambda (_)
                           (when (mastodon-tl--buffer-type-eq 'lists)
                             (mastodon-views--view-lists))
                           (apply #'message args))))
(defun mastodon-views--accounts-in-list (list-id)
  "Return the JSON of the accounts in list with LIST-ID."
  (let* ((url (mastodon-http--api (format "lists/%s/accounts" list-id))))
    (mastodon-http--get-json url)))

;;; FOLLOW REQUESTS
(defun mastodon-views--insert-follow-requests (json)
  "Insert the user's current follow requests.
JSON is the data returned by the server."
  (mastodon-views--minor-view
   "follow requests"
   #'mastodon-views--insert-users-propertized-note
   json))
(defun mastodon-views--view-follow-requests ()
  "Open a new buffer displaying the user's follow requests."
  (interactive)
  (mastodon-tl--init-sync "follow-requests"
                          "follow_requests"
                          'mastodon-views--insert-follow-requests
                          nil
                          '(("limit" . "40")) ; server max is 80
                          :headers
                          "follow requests"
                          "a/j - accept/reject request at point\n\
 n/p - go to next/prev request")
  (mastodon-tl--goto-first-item)
  (with-current-buffer "*mastodon-follow-requests*"
    (use-local-map mastodon-views--view-follow-requests-keymap)))

;;; SCHEDULED TOOTS
(defun mastodon-views--view-scheduled-toots ()
  "Show the user's scheduled toots in a new buffer."
  (interactive)
  (mastodon-tl--init-sync "scheduled-toots"
                          "scheduled_statuses"
                          'mastodon-views--insert-scheduled-toots
                          nil nil nil
                          "your scheduled toots"
                          "n/p - prev/next\n r - reschedule\n\
 e/RET - edit toot\n c - cancel")
  (with-current-buffer "*mastodon-scheduled-toots*"
    (use-local-map mastodon-views--scheduled-map)))
(defun mastodon-views--insert-scheduled-toots (json)
  "Insert the user's scheduled toots, from JSON."
  (mastodon-views--minor-view
   "scheduled toots"
   #'mastodon-views--insert-scheduled-toots-list
   json))
(defun mastodon-views--insert-scheduled-toots-list (scheduleds)
  "Insert scheduled toots in SCHEDULEDS."
  (mapc #'mastodon-views--insert-scheduled-toot scheduleds))
(defun mastodon-views--insert-scheduled-toot (toot)
  "Insert scheduled TOOT into the buffer."
  (let-alist toot
    (insert
     (propertize (concat .params.text
                         " | "
                         (mastodon-toot--iso-to-human .scheduled_at))
                 'byline t ; so we nav here
                 'item-id "0" ; so we nav here
                 'face 'font-lock-comment-face
                 'keymap mastodon-views--scheduled-map
                 'scheduled-json toot
                 'id .id)
     "\n")))
(defun mastodon-views--get-scheduled-toots (&optional id)
  "Get the user's currently scheduled toots.
If ID, just return that toot."
  (let* ((endpoint (if id
                       (format "scheduled_statuses/%s" id)
                     "scheduled_statuses"))
         (url (mastodon-http--api endpoint)))
    (mastodon-http--get-json url)))
(defun mastodon-views--reschedule-toot ()
  "Reschedule the scheduled toot at point."
  (interactive)
  (let ((id (mastodon-tl--property 'id :no-move)))
    (if (null id)
        (message "no scheduled toot at point?")
      (mastodon-toot--schedule-toot :reschedule))))
(defun mastodon-views--copy-scheduled-toot-text ()
  "Copy the text of the scheduled toot at point."
  (interactive)
  (let* ((toot (mastodon-tl--property 'toot :no-move))
         (params (alist-get 'params toot))
         (text (alist-get 'text params)))
    (kill-new text)))
(defun mastodon-views--cancel-scheduled-toot (&optional id no-confirm)
  "Cancel the scheduled toot at point.
ID is that of the scheduled toot to cancel.
NO-CONFIRM means there is no ask or message, there is only do."
  (interactive)
  (let ((id (or id (mastodon-tl--property 'id :no-move))))
    (if (null id)
        (message "no scheduled toot at point?")
      (when (or no-confirm
                (y-or-n-p "Cancel scheduled toot?"))
        (let* ((url (mastodon-http--api (format "scheduled_statuses/%s" id)))
               (response (mastodon-http--delete url)))
          (mastodon-http--triage response
                                 (lambda (_)
                                   (mastodon-views--view-scheduled-toots)
                                   (unless no-confirm
                                     (message "Toot cancelled!")))))))))
(defun mastodon-views--edit-scheduled-as-new ()
  "Edit scheduled status as new toot."
  (interactive)
  (let ((id (mastodon-tl--property 'id :no-move)))
    (if (null id)
        (message "no scheduled toot at point?")
      (let* ((toot (mastodon-tl--property 'scheduled-json :no-move))
             (scheduled (alist-get 'scheduled_at toot)))
        (let-alist (alist-get 'params toot)
          ;; (poll (alist-get 'poll params))
          ;; (media (alist-get 'media_attachments toot)))
          (mastodon-toot--compose-buffer)
          (goto-char (point-max))
          (insert .text)
          ;; adopt properties from scheduled toot:
          (mastodon-toot--set-toot-properties
           .in_reply_to_id .visibility .spoiler_text .language scheduled id))))))

;;; FILTERS
(defun mastodon-views--view-filters ()
  "View the user's filters in a new buffer."
  (interactive)
  (mastodon-tl--init-sync "filters" "filters"
                          'mastodon-views--insert-filters
                          nil nil nil
                          "current filters"
                          "c - create filter\n d - delete filter at point\n\
 n/p - go to next/prev filter")
  (with-current-buffer "*mastodon-filters*"
    (use-local-map mastodon-views--view-filters-keymap)))
(defun mastodon-views--insert-filters (json)
  "Insert the user's current filters.
JSON is what is returned by by the server."
  (mastodon-views--minor-view
   "filters"
   #'mastodon-views--insert-filter-string-set
   json))
(defun mastodon-views--insert-filter-string-set (json)
  "Insert a filter string plus a blank line.
JSON is the filters data."
  (mapc #'mastodon-views--insert-filter-string json))
(defun mastodon-views--insert-filter-string (filter)
  "Insert a single FILTER."
  (let* ((phrase (alist-get 'phrase filter))
         (contexts (alist-get 'context filter))
         (id (alist-get 'id filter))
         (filter-string (concat "- \"" phrase "\" filtered in: "
                                (mapconcat #'identity contexts ", "))))
    (insert
     (propertize filter-string
                 'item-id id ;for goto-next-filter compat
                 'phrase phrase
                 'byline t) ;for goto-next-filter compat
     "\n\n")))
(defun mastodon-views--create-filter ()
  "Create a filter for a word.
Prompt for a context, must be a list containting at least one of \"home\",
\"notifications\", \"public\", \"thread\"."
  (interactive)
  (let* ((url (mastodon-http--api "filters"))
         (word (read-string
                (format "Word(s) to filter (%s): " (or (current-word) ""))
                nil nil (or (current-word) "")))
         (contexts
          (if (string-empty-p word)
              (user-error "You must select at least one word for a filter")
            (completing-read-multiple
             "Contexts to filter [TAB for options]: "
             '("home" "notifications" "public" "thread")
             nil t)))
         (contexts-processed
          (if (equal nil contexts)
              (user-error "You must select at least one context for a filter")
            (mapcar (lambda (x)
                      (cons "context[]" x))
                    contexts)))
         (response (mastodon-http--post url (push
                                             `("phrase" . ,word)
                                             contexts-processed))))
    (mastodon-http--triage response
                           (lambda (_)
                             (message "Filter created for %s!" word)
                             (when (mastodon-tl--buffer-type-eq 'filters)
                               (mastodon-views--view-filters))))))
(defun mastodon-views--delete-filter ()
  "Delete filter at point."
  (interactive)
  (let* ((filter-id (mastodon-tl--property 'item-id :no-move))
         (phrase (mastodon-tl--property 'phrase :no-move))
         (url (mastodon-http--api (format "filters/%s" filter-id))))
    (if (null phrase)
        (user-error "No filter at point?")
      (when (y-or-n-p (format "Delete filter %s? " phrase))
        (let ((response (mastodon-http--delete url)))
          (mastodon-http--triage
           response (lambda (_)
                      (mastodon-views--view-filters)
                      (message "Filter for \"%s\" deleted!" phrase))))))))

;;; FOLLOW SUGGESTIONS
;; No pagination: max 80 results
(defun mastodon-views--view-follow-suggestions ()
  "Display a buffer of suggested accounts to follow."
  (interactive)
  (mastodon-tl--init-sync "follow-suggestions"
                          "suggestions"
                          'mastodon-views--insert-follow-suggestions
                          nil
                          '(("limit" . "80")) ; server max
                          nil
                          "suggested accounts")
  (with-current-buffer "*mastodon-follow-suggestions*"
    (use-local-map mastodon-views--follow-suggestions-map)))
(defun mastodon-views--insert-follow-suggestions (json)
  "Insert follow suggestions into buffer.
JSON is the data returned by the server."
  (mastodon-views--minor-view
   "suggested accounts"
   #'mastodon-views--insert-users-propertized-note
   json))
(defun mastodon-views--insert-users-propertized-note (json)
  "Insert users list into the buffer, including profile note.
JSON is the users list data."
  (mastodon-search--insert-users-propertized json :note))

;;; INSTANCES
(defun mastodon-views--view-own-instance (&optional brief)
  "View details of your own instance.
BRIEF means show fewer details."
  (interactive)
  (mastodon-views--view-instance-description :user brief))
(defun mastodon-views--view-own-instance-brief ()
  "View brief details of your own instance."
  (interactive)
  (mastodon-views--view-instance-description :user :brief))
(defun mastodon-views--view-instance-description-brief ()
  "View brief details of the instance the current post's author is on."
  (interactive)
  (mastodon-views--view-instance-description nil :brief))
(defun mastodon-views--get-instance-url (url username &optional instance)
  "Return an instance base url from a user account URL.
USERNAME is the name to cull.
If INSTANCE is given, use that."
  (cond (instance
         (concat "https://" instance))
        ;; pleroma URL is https://instance.com/users/username
        ((string-suffix-p "users/" (url-basepath url))
         (string-remove-suffix "/users/"
                               (url-basepath url)))
        ;; friendica is https://instance.com/profile/user
        ((string-suffix-p "profile/" (url-basepath url))
         (string-remove-suffix "/profile/"
                               (url-basepath url)))
        ;; mastodon is https://instance.com/@user
        (t
         (string-remove-suffix (concat "/@" username)
                               url))))
(defun mastodon-views--view-instance-description
    (&optional user brief instance misskey)
  "View the details of the instance the current post's author is on.
USER means to show the instance details for the logged in user.
BRIEF means to show fewer details.
INSTANCE is an instance domain name.
MISSKEY means the instance is a Misskey or derived server."
  (interactive)
  (if user
      (let ((response (mastodon-http--get-json
                       (mastodon-http--api "instance") nil nil :vector)))
        (mastodon-views--instance-response-fun response brief instance))
    (mastodon-tl--do-if-item
     (let* ((toot (if (mastodon-tl--profile-buffer-p)
                      ;; we may be on profile description itself:
                      (or (mastodon-tl--property 'profile-json)
                          ;; or on profile account listings, or just toots:
                          (mastodon-tl--property 'item-json))
                    ;; normal timeline/account listing:
                    (mastodon-tl--property 'item-json)))
            (reblog (alist-get 'reblog toot))
            (account (or (alist-get 'account reblog)
                         (alist-get 'account toot)
                         toot)) ; else `toot' is already an account listing.
            ;; we may be at toots/boosts/users in a profile buffer.
            ;; profile-json is a defacto test for if point is on the profile
            ;; details at the top of a profile buffer.
            (profile-note-p (and (mastodon-tl--profile-buffer-p)
                                 ;; only call this in profile buffers:
                                 (mastodon-tl--property 'profile-json)))
            (url (if profile-note-p
                     (alist-get 'url toot) ; profile description
                   (alist-get 'url account)))
            (username (if profile-note-p
                          (alist-get 'username toot) ;; profile
                        (alist-get 'username account)))
            (instance (mastodon-views--get-instance-url url username instance)))
       (if misskey
           (let* ((params `(("detail" . ,(or brief t))))
                  (headers '(("Content-Type" . "application/json")))
                  (url (concat instance "/api/meta"))
                  (response
                   (with-current-buffer (mastodon-http--post url params headers t :json)
                     (mastodon-http--process-response))))
             (mastodon-views--instance-response-fun response brief instance :misskey))
         (let ((response (mastodon-http--get-json
                          (concat instance "/api/v1/instance") nil nil :vector)))
           ;; if non-misskey attempt errors, try misskey instance:
           ;; akkoma i guess should not error here.
           (if (eq 'error (caar response))
               (mastodon-views--instance-desc-misskey)
             (mastodon-views--instance-response-fun response brief instance))))))))
(defun mastodon-views--instance-desc-misskey (&optional user brief instance)
  "Show instance description for a misskey/firefish server.
USER, BRIEF, and INSTANCE are all for
`mastodon-views--view-instance-description', which see."
  (interactive)
  (mastodon-views--view-instance-description user brief instance :miskey))
(defun mastodon-views--instance-response-fun (response brief instance
                                                       &optional misskey)
  "Display instance description RESPONSE in a new buffer.
BRIEF means to show fewer details.
INSTANCE is the instance were are working with.
MISSKEY means the instance is a Misskey or derived server."
  (when response
    (let* ((domain (url-file-nondirectory instance))
           (buf (get-buffer-create
                 (format "*mastodon-instance-%s*" domain))))
      (with-mastodon-buffer buf #'special-mode :other-window
        (if misskey
            (mastodon-views--insert-json response)
          (condition-case nil
              (progn
                (when brief
                  (setq response
                        (list (assoc 'uri response)
                              (assoc 'title response)
                              (assoc 'short_description response)
                              (assoc 'email response)
                              (cons 'contact_account
                                    (list
                                     (assoc 'username
                                            (assoc 'contact_account response))))
                              (assoc 'rules response)
                              (assoc 'stats response))))
                (mastodon-views--print-json-keys response)
                (mastodon-tl--set-buffer-spec (buffer-name buf) "instance" nil)
                (goto-char (point-min)))
            (error ; just insert the raw response:
             (mastodon-views--insert-json response))))))))
(defun mastodon-views--insert-json (response)
  "Insert raw JSON RESPONSE in current buffer."
  (let ((inhibit-read-only t))
    (erase-buffer)
    (insert (prin1-to-string response))
    (pp-buffer)
    (goto-char (point-min))))
(defun mastodon-views--format-key (el pad)
  "Format a key of element EL, a cons, with PAD padding."
  (format (concat "%-"
                  (number-to-string pad)
                  "s: ")
          (propertize (prin1-to-string (car el))
                      'face '(:underline t))))
(defun mastodon-views--print-json-keys (response &optional ind)
  "Print the JSON keys and values in RESPONSE.
IND is the optional indentation level to print at."
  (let* ((cars (mapcar (lambda (x) (symbol-name (car x)))
                       response))
         (pad (1+ (cl-reduce #'max (mapcar #'length cars)))))
    (while response
      (let ((el (pop response)))
        (cond
         ((and (vectorp (cdr el)) ; vector of alists (fields, instance rules):
               (not (seq-empty-p (cdr el)))
               (consp (seq-elt (cdr el) 0)))
          (insert (mastodon-views--format-key el pad)
                  "\n\n")
          (seq-do #'mastodon-views--print-instance-rules-or-fields (cdr el))
          (insert "\n"))
         ((and (vectorp (cdr el)) ; vector of strings (media types):
               (not (seq-empty-p (cdr el)))
               (< 1 (seq-length (cdr el)))
               (stringp (seq-elt (cdr el) 0)))
          (when ind (indent-to ind))
          (insert (mastodon-views--format-key el pad)
                  "\n"
                  (seq-mapcat
                   (lambda (x) (concat x ", "))
                   (cdr el) 'string)
                  "\n\n"))
         ((consp (cdr el)) ; basic nesting:
          (when ind (indent-to ind))
          (insert (mastodon-views--format-key el pad)
                  "\n\n")
          (mastodon-views--print-json-keys
           (cdr el) (if ind (+ ind 4) 4)))
         (t ; basic handling of raw booleans:
          (let ((val (cond ((equal (cdr el) :json-false)
                            "no")
                           ((equal (cdr el) 't)
                            "yes")
                           (t
                            (cdr el)))))
            (when ind (indent-to ind))
            (insert (mastodon-views--format-key el pad)
                    " "
                    (mastodon-views--newline-if-long (cdr el))
                    ;; only send strings to --render-text (for hyperlinks):
                    (mastodon-tl--render-text
                     (if (stringp val) val (prin1-to-string val)))
                    "\n"))))))))
(defun mastodon-views--print-instance-rules-or-fields (alist)
  "Print ALIST of instance rules or contact account or emoji fields."
  (let-alist alist
    (let ((key (or .id .name .shortcode))
          (value (or .text .value .url)))
      (indent-to 4)
      (insert (format "%-5s: "
                      (propertize key 'face '(:underline t)))
              (mastodon-views--newline-if-long value)
              (format "%s" (mastodon-tl--render-text
                            value))
              "\n"))))
(defun mastodon-views--newline-if-long (el)
  "Return a newline string if the cdr of EL is over 50 characters long."
  (let ((rend (if (stringp el) (mastodon-tl--render-text el) el)))
    (if (and (sequencep rend)
             (< 50 (length rend)))
        "\n"
      "")))
(provide 'mastodon-views)
;;; mastodon-views.el ends here