[elpa] externals/srht e464826002 23/27: Clean up the code, enhance README, update headers for ELPA.

[ELPA Syncer]

branch: externals/srht
commit e4648260024bef41006bc77b18a598623e7d7201
Author: Aleksandr Vityazev <avityazev@posteo.org>
Commit: Aleksandr Vityazev <avityazev@posteo.org>

    Clean up the code, enhance README, update headers for ELPA.
    
    * README.org: Add Installation and Commands sections.
    * srht (srht-file-name-concat): Remove. (srht-username): New defcustom.
    * .elpaignore: New file.
---
 .elpaignore        |  5 ++++
 Eldev              |  4 +--
 README.md          | 82 ++++++++++++++++++++++++++++++++++++++++++++++++++++--
 README.org         | 43 ++++++++++++++++++++++++++--
 lisp/srht-git.el   | 44 +++++++++++++++++------------
 lisp/srht-paste.el | 17 ++++++-----
 lisp/srht-pkg.el   | 13 ---------
 lisp/srht.el       | 43 ++++++++++++----------------
 tests/test.el      |  3 +-
 9 files changed, 182 insertions(+), 72 deletions(-)

diff --git a/.elpaignore b/.elpaignore
new file mode 100644
index 0000000000..b4cc52091e
--- /dev/null
+++ b/.elpaignore
@@ -0,0 +1,5 @@
+Makefile
+.build.yml
+.envrc
+guix.scm
+Eldev
diff --git a/Eldev b/Eldev
index 4a88e7024b..ee372ea0ea 100644
--- a/Eldev
+++ b/Eldev
@@ -1,7 +1,7 @@
 ; -*- mode: emacs-lisp; lexical-binding: t -*-
 
 ;; Uncomment some calls below as needed for your project.
-;(eldev-use-package-archive 'gnu)
+(eldev-use-package-archive 'gnu)
 ;(eldev-use-package-archive 'nongnu)
 ;(eldev-use-package-archive 'melpa)
 
@@ -10,4 +10,4 @@
 (add-to-list 'load-path "./lisp/")
 (setq eldev-project-main-file "./lisp/srht.el")
 ;; FIXME: outdated version, not support 'delete method
-(eldev-use-local-dependency 
"/gnu/store/amblp4x1r03xkzjda8hjha6bj1p5p8ms-emacs-plz-0.1-pre-1.7e45663/share/emacs/site-lisp/plz-0.1-pre-1.7e45663/")
+;; (eldev-use-local-dependency 
"/gnu/store/amblp4x1r03xkzjda8hjha6bj1p5p8ms-emacs-plz-0.1-pre-1.7e45663/share/emacs/site-lisp/plz-0.1-pre-1.7e45663/")
diff --git a/README.md b/README.md
index e360179feb..e2e3ea8139 100644
--- a/README.md
+++ b/README.md
@@ -9,6 +9,22 @@
 GNU Emacs [sourcehut](https://sr.ht) API client.
 
 
+# Installation
+
+
+## With Guix
+
+    git clone https://git.sr.ht/~akagi/srht.el srht
+    cd srth
+    guix package -f guix.scm
+
+
+## Manual
+
+`srht` depends on the HTTP library `plz` which is available in ELPA. After
+installing it, place files from /lisp folder in `load-path`.
+
+
 # Setup
 
 To use this client, you need to 
[generate](https://meta.sr.ht/oauth/personal-token) a personal access token. 
This token
@@ -19,10 +35,70 @@ After creating the token:
 
     (setq srht-token TOKEN)
 
-It is also possible to store the token using auth-source.el, the host must be
-set to paste.sr.ht.
+It is also possible to store the token using `auth-source.el`, the host must be
+set to sr.ht.
+
+    machine sr.ht password TOKEN
+
+You also need to set srht-username:
+
+    (setq srht-username USERNAME)
+
+
+# Commands
+
+<table border="2" cellspacing="0" cellpadding="6" rules="groups" 
frame="hsides">
+
+
+<colgroup>
+<col  class="org-left" />
+
+<col  class="org-left" />
+</colgroup>
+<thead>
+<tr>
+<th scope="col" class="org-left">Function</th>
+<th scope="col" class="org-left">Description</th>
+</tr>
+</thead>
+
+<tbody>
+<tr>
+<td class="org-left"><code>srht-git-repo-update</code></td>
+<td class="org-left">Update information for git repository</td>
+</tr>
+
+
+<tr>
+<td class="org-left"><code>srht-git-repo-delete</code></td>
+<td class="org-left">Delete existing git repository</td>
+</tr>
+
+
+<tr>
+<td class="org-left"><code>srht-git-repo-create</code></td>
+<td class="org-left">Create git repository</td>
+</tr>
+
+
+<tr>
+<td class="org-left"><code>srht-paste-link</code></td>
+<td class="org-left">Kill the link of the selected paste</td>
+</tr>
+
+
+<tr>
+<td class="org-left"><code>srht-paste-delete</code></td>
+<td class="org-left">Detete paste with SHA</td>
+</tr>
+
 
-    machine paste.sr.ht password TOKEN
+<tr>
+<td class="org-left"><code>srht-paste-region</code></td>
+<td class="org-left">Paste region or buffer to sourcehut</td>
+</tr>
+</tbody>
+</table>
 
 
 # License
diff --git a/README.org b/README.org
index 518329329b..134f22edd1 100644
--- a/README.org
+++ b/README.org
@@ -6,6 +6,21 @@
 * About
 GNU Emacs [[https://sr.ht][sourcehut]] API client.
 
+* Installation
+
+** With Guix
+
+#+begin_src sh
+git clone https://git.sr.ht/~akagi/srht.el srht
+cd srth
+guix package -f guix.scm
+#+end_src
+
+** Manual
+
+~srht~ depends on the HTTP library ~plz~ which is available in ELPA. After
+installing it, place files from /lisp folder in ~load-path~.
+
 * Setup
 
 To use this client, you need to 
[[https://meta.sr.ht/oauth/personal-token][generate]] a personal access token. 
This token
@@ -18,13 +33,35 @@ After creating the token:
 (setq srht-token TOKEN)
 #+end_src
 
-It is also possible to store the token using `auth-source.el', the host must be
-set to paste.sr.ht.
+It is also possible to store the token using =auth-source.el=, the host must be
+set to sr.ht.
 
 #+begin_example
-machine paste.sr.ht password TOKEN
+machine sr.ht password TOKEN
 #+end_example
 
+You also need to set srht-username:
+
+#+begin_src elisp :lexical t
+(setq srht-username USERNAME)
+#+end_src
+
+* Commands
+
+| Function             | Description                           |
+|----------------------+---------------------------------------|
+| =srht-git-repo-update= | Update information for git repository |
+| =srht-git-repo-delete= | Delete existing git repository        |
+| =srht-git-repo-create= | Create git repository                 |
+| =srht-paste-link=      | Kill the link of the selected paste   |
+| =srht-paste-delete=    | Detete paste with SHA                 |
+| =srht-paste-region=    | Paste region or buffer to sourcehut   |
+
+
 * License
 
 GPLv3
+
+# Local Variables:
+# eval: (require 'ox-md)
+# End:
diff --git a/lisp/srht-git.el b/lisp/srht-git.el
index d7be8a82f4..96fd7a3e19 100644
--- a/lisp/srht-git.el
+++ b/lisp/srht-git.el
@@ -1,9 +1,11 @@
 ;;; srht-git.el --- Sourcehut git                    -*- lexical-binding: t; 
-*-
 
-;; Copyright © 2022 Aleksandr Vityazev <avityazev@posteo.org>
+;; Copyright © 2022  Free Software Foundation, Inc.
 
 ;; Created: <2022-04-26 Tue>
 
+;; This file is part of GNU Emacs.
+
 ;; 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
@@ -37,9 +39,8 @@ FORM is a content type."
 (defun srht-git-user (&optional username)
   "Retrieves a user resource.
 If USERNAME is nil, the authenticated user is assumed."
-  ;; TODO: tilda in username
   (let ((path (if username
-                  (concat "/api/user/" username)
+                  (concat "/api/user/~" (string-trim-left username "~"))
                 "/api/user")))
     (srht-git--make-crud path)))
 
@@ -47,7 +48,7 @@ If USERNAME is nil, the authenticated user is assumed."
   "Retrive list of repository resources owned by this USERNAME.
 If USERNAME is nil the authenticated user is assumed."
   (let ((path (if username
-                  (format "/api/%s/repos" username)
+                  (format "/api/~%s/repos" (string-trim-left username "~"))
                 "/api/repos")))
     (srht-git--make-crud path)))
 
@@ -77,54 +78,58 @@ When creating repository omit REPO-NAME and specify DETAILS
 \(see `srht-git-make'\)."
   (cond
    ((and (stringp repo-name) (stringp username))
-    (srht-git--make-crud (format "/api/%s/repos/%s" username repo-name)))
+    (srht-git--make-crud
+     (format "/api/~%s/repos/%s" (string-trim-left username "~") repo-name)))
    ((and (stringp repo-name) details)
     (srht-git--make-crud (format "/api/repos/%s" repo-name)
                          (apply #'srht-git-make details)))
    ((stringp repo-name) (srht-git--make-crud (format "/api/repos/%s" 
repo-name)))
    (t (srht-git--make-crud "/api/repos" (apply #'srht-git-make details)))))
 
-(defmacro srht-git--endpoints (endpoint name username &optional body form)
+(defmacro srht-git--endpoint (endpoint name username &optional body form)
   "Generate crud for ENDPOINT and repository NAME.
 If USERNAME is nil the authenticated user is assumed.
 BODY is the body sent to the URI.
 FORM is a content type."
   (let ((path (gensym "path")))
     `(let ((,path (if ,username
-                      (format "/api/%s/repos/%s/%s" ,username ,name ,endpoint)
+                      (format "/api/~%s/repos/%s/%s"
+                              (string-trim-left ,username "~") ,name ,endpoint)
                     (format "/api/repos/%s/%s" ,name ,endpoint))))
        (srht-git--make-crud ,path ,body ,form))))
 
-(defun srht-git--endpoint-widen (func name end &optional username body)
-  "TODO: doc."
+(defun srht-git--endpoint-widen (endpoint name end &optional username body)
+  "Extends the ENDPOINT for the repository NAME to include END.
+If USERNAME is nil the authenticated user is assumed.
+BODY is the body sent to the URI."
   (let* ((plist (if body
-                    (funcall func name username body)
-                  (funcall func name username)))
+                    (funcall endpoint name username body)
+                  (funcall endpoint name username)))
          (path (plist-get plist :path)))
     (setf (plist-get plist :path)
           (concat path "/" end))
     plist))
 
 (defun srht-git--artifact (name username body)
-  "TODO: doc."
-  (srht-git--endpoints "artifacts" name username body "multipart/form-data"))
+  "Helper function for `srht-git-repo-artifact'."
+  (srht-git--endpoint "artifacts" name username body "multipart/form-data"))
 
 (defun srht-git-repo-readme (name &optional username body form)
   "Retrieve, update or delete README override for repository NAME.
 
 If USERNAME is nil the authenticated user is assumed.
 BODY is the body sent to the URI.  FORM is a content type."
-  (srht-git--endpoints "readme" name username body form))
+  (srht-git--endpoint "readme" name username body form))
 
 (defun srht-git-repo-refs (name &optional username)
   "Endpoints for fetching git data from repository NAME.
 If USERNAME is nil the authenticated user is assumed."
-  (srht-git--endpoints "refs" name username))
+  (srht-git--endpoint "refs" name username))
 
 (defun srht-git-repo-log (name &optional username)
   "List of the latest commit log for repository NAME.
 If USERNAME is nil the authenticated user is assumed."
-  (srht-git--endpoints "log" name username))
+  (srht-git--endpoint "log" name username))
 
 (defun srht-git-repo-artifact (name ref body &optional username)
   "Attaches a file artifact to the specified REF and repository NAME.
@@ -156,7 +161,7 @@ is assumed."
   "Return the tree resource for the latest commit to the default branch.
 NAME is a repository name.  If USERNAME is nil the authenticated user
 is assumed."
-  (srht-git--endpoints "tree" name username))
+  (srht-git--endpoint "tree" name username))
 
 (defun srht-git--candidates ()
   "Return completion candidates."
@@ -220,6 +225,7 @@ Called when the request fails with one argument, a 
‘plz-error’ struct PLZ-ER
                               :visibility visibility
                               :name name
                               :description description)
+               :then (lambda (_r))
                :else #'srht-git--else))
 
 (defun srht-git--find-info (repo-name)
@@ -269,7 +275,9 @@ Set VISIBILITY, NEW-NAME and DESCRIPTION."
   (interactive (list (srht-git--repo-name-read)))
   (when (yes-or-no-p
          (format "This action cannot be undone.\n Delete %s repository?" name))
-    (srht-delete (srht-git-repo name) :else #'srht-git--else)))
+    (srht-delete (srht-git-repo name)
+                 :then (lambda (_r))
+                 :else #'srht-git--else)))
 
 (provide 'srht-git)
 ;;; srht-git.el ends here
diff --git a/lisp/srht-paste.el b/lisp/srht-paste.el
index 1ee4bff9f6..ce3ea13dfa 100644
--- a/lisp/srht-paste.el
+++ b/lisp/srht-paste.el
@@ -1,6 +1,8 @@
 ;;; srht-paste.el --- Sourcehut paste                -*- lexical-binding: t; 
-*-
 
-;; Copyright © 2022 Aleksandr Vityazev <avityazev@posteo.org>
+;; Copyright © 2022  Free Software Foundation, Inc.
+
+;; This file is part of GNU Emacs.
 
 ;; 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
@@ -128,7 +130,7 @@ Called when the request fails with one argument, a 
‘plz-error’ struct PLZ-ER
   (let ((content (srht-paste--get-content)))
     (srht-create
      (srht-paste nil :visibility visibility :filename filename :contents 
content)
-     :then (lambda (_resp))
+     :then (lambda (_r))
      :else #'srht-paste--else)))
 
 ;;;###autoload
@@ -137,15 +139,16 @@ Called when the request fails with one argument, a 
‘plz-error’ struct PLZ-ER
   (interactive
    (list (srht-paste--sha)))
   (srht-delete (srht-paste sha)
-               :then (lambda (resp)
-                       (message "%s" resp))
+               :then (lambda (_r))
                :else #'srht-paste--else))
 
 ;;;###autoload
-(defun srht-paste-link (user)
+(defun srht-paste-link ()
   "Kill the link of the selected paste owned by the USER."
-  (interactive (list (read-string "User: ")))
-  (srht-kill-link 'paste user (srht-paste--sha)))
+  (interactive)
+  (when (string-empty-p srht-username)
+    (error "`srht-username' must be set"))
+  (srht-kill-link 'paste (concat "~" srht-username) (srht-paste--sha)))
 
 (provide 'srht-paste)
 ;;; srht-paste.el ends here
diff --git a/lisp/srht-pkg.el b/lisp/srht-pkg.el
deleted file mode 100644
index 17f71d54ad..0000000000
--- a/lisp/srht-pkg.el
+++ /dev/null
@@ -1,13 +0,0 @@
-;;; -*- no-byte-compile: t -*-
-(define-package
-  "srht"
-  "0.1.0"
-  "Sourcehut"
-  '((emacs "27.1") (plz "0.1-pre"))
-  :authors '(("Aleksandr Vityazev" . "avityazev@posteo.org"))
-  :maintainer '("Aleksandr Vityazev" . "avityazev@posteo.org")
-  :keywords '("comm"))
-
-;; Local Variables:
-;; eval: (flymake-mode -1)
-;; End:
diff --git a/lisp/srht.el b/lisp/srht.el
index 0737f4527d..0aa96911d2 100644
--- a/lisp/srht.el
+++ b/lisp/srht.el
@@ -1,13 +1,16 @@
 ;;; srht.el --- Sourcehut               -*- lexical-binding: t; -*-
 
-;; Copyright © 2022 Aleksandr Vityazev <avityazev@posteo.org>
+;; Copyright © 2022  Free Software Foundation, Inc.
 
 ;; Author: Aleksandr Vityazev <avityazev@posteo.org>
-;; Keywords: comm
-;; Package-Version: 0.1.0
+;; Maintainer: Aleksandr Vityazev <avityazev@posteo.org>
+;; Keywords: comm vc
+;; Package-Version: 0.1
 ;; Homepage: https://sr.ht/~akagi/srht.el/
 ;; Keywords: comm
-;; Package-Requires: ((emacs "27.1") (plz "0.1-pre"))
+;; Package-Requires: ((emacs "27.1") (plz "0.1"))
+
+;; This file is part of GNU Emacs.
 
 ;; 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
@@ -43,13 +46,18 @@
   :group 'srht)
 
 (defcustom srht-token
-  (if-let ((f (plist-get (car (auth-source-search :host "paste.sr.ht"))
+  (if-let ((f (plist-get (car (auth-source-search :host "sr.ht"))
                          :secret)))
       (funcall f) "")
   "Personal access token for Sourcehut instance."
   :type 'string
   :group 'srht)
 
+(defcustom srht-username ""
+  "Sourcehut username."
+  :type 'string
+  :group 'srht)
+
 (cl-defun srht--build-uri-string (scheme &key host path query)
   "Construct a URI string.
 SCHEME should be a symbol.  HOST should be strings or nil
@@ -177,35 +185,20 @@ The function should take one argument, STRING, which is a 
possible completion."
              (complete-with-action action collection string pred)))))
     (completing-read prompt table)))
 
-(defalias 'srht-file-name-concat
-  (if (fboundp 'file-name-concat)
-      #'file-name-concat
-    (lambda (directory &rest components)
-      (let ((components (cl-remove-if (lambda (el)
-                                        (or (null el) (equal "" el)))
-                                      components))
-            file-name-handler-alist)
-        (if (null components)
-            directory
-          (apply #'srht-file-name-concat
-                 (concat (unless (or (equal "" directory) (null directory))
-                           (file-name-as-directory directory))
-                         (car components))
-                 (cdr components)))))))
-
 (defun srht-kill-link (service name resource)
   "Make URL the latest kill in the kill ring.
 Constructed from SERVICE, NAME and RESOURCE."
-  (kill-new (srht-file-name-concat (srht--make-uri service nil nil) name 
resource))
+  (kill-new (srht--make-uri service (format "/%s/%s" name resource) nil))
   (message "URL in kill-ring"))
 
-(defmacro srht-with-json-read-from-string (string matching-pattern &rest body)
-  "TODO: doc."
+(defmacro srht-with-json-read-from-string (string pattern &rest body)
+  "Read the JSON object contained in STRING.
+Bind it with the ‘pcase’ PATTERN and do BODY."
   (declare (indent 1))
   `(pcase-let* ((json-object-type 'plist)
                 (json-key-type 'keyword)
                 (json-array-type 'list)
-                (,matching-pattern (json-read-from-string ,string)))
+                (,pattern (json-read-from-string ,string)))
      ,@body))
 
 (provide 'srht)
diff --git a/tests/test.el b/tests/test.el
index a5d431449b..86c77c0b67 100644
--- a/tests/test.el
+++ b/tests/test.el
@@ -1,8 +1,9 @@
 ;;; test.el --- Tests                                -*- lexical-binding: t; 
-*-
 
-;; Copyright © 2022 Aleksandr Vityazev <avityazev@posteo.org>
+;; Copyright © 2022  Free Software Foundation, Inc.
 
 ;; Author: Aleksandr Vityazev <avityazev@posteo.org>
+;; Maintainer: Aleksandr Vityazev <avityazev@posteo.org>
 ;; Keywords: tests
 
 ;; This program is free software; you can redistribute it and/or modify