From 6975628ebb3e73abb46929b4baae77ba576719f5 Mon Sep 17 00:00:00 2001 From: SqrtMinusOne Date: Fri, 11 Feb 2022 19:36:11 +0300 Subject: [PATCH] docs: some docstrings --- ivy-pass.el | 81 ++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 68 insertions(+), 13 deletions(-) diff --git a/ivy-pass.el b/ivy-pass.el index e663b40..88bc170 100644 --- a/ivy-pass.el +++ b/ivy-pass.el @@ -1,11 +1,11 @@ -;;; org-journal-tags.el --- TODO -*- lexical-binding: t -*- +;;; ivy-pass.el --- A simple pass frontend for Ivy -*- lexical-binding: t -*- ;; Copyright (C) 2022 Korytov Pavel ;; Author: Korytov Pavel ;; Maintainer: Korytov Pavel ;; Version: 0.1.0 -;; Package-Requires: ((emacs "27.1") ("ivy" 0.13.0)) +;; Package-Requires: ((emacs "27.1") (ivy "0.13.0")) ;; Homepage: https://github.com/SqrtMinusOne/org-journal-tags.el ;; This file is NOT part of GNU Emacs. @@ -25,17 +25,20 @@ ;;; Commentary: -;; TODO +;; A pass frontend based on Ivy, made primarily to use with EXWM. +;; +;; The only command is `ivy-pass'. ;;; Code: (require 'ivy) (require 'seq) (defgroup ivy-pass () - "An ivy-based pass frontend.") + "An ivy-based pass frontend." + :group 'password-store) (defcustom ivy-pass-initial-wait 250 - "How much miliseconds to wait before typing characters" + "How much miliseconds to wait before typing characters." :type 'integer :group 'ivy-pass) @@ -44,6 +47,8 @@ :type 'integer :group 'ivy-pass) +(setq ivy-pass-sequences nil) + (defcustom ivy-pass-sequences '((autotype . (wait (field . "username") @@ -53,8 +58,35 @@ (password . ((field . secret))) (username . ((field . "username"))) (url . ((field . "url")))) - "Sequences to execute by ivy-pass." - :group 'ivy-pass) + "Sequences to execute by `ivy-pass'. + +Take a look at `ivy-pass--get-commands' for available fields." + :group 'ivy-pass + :options '(autotype password username url) + :type '(alist :key-type (symbol :tag "Sequence name") + :value-type (repeat + :tag "Sequence contents" + (choice + (const :tag "Wait for `ivy-pass-initial-wait'" wait) + (cons + :tag "Wait for miliseconds" + (const :tag "Wait for miliseconds" wait) + (integer :tag "Number of miliseconds to wait")) + (cons + :tag "Enter a field" + (const :tag "Enter a field" field) + (choice + (const :tag "Password" secret) + (const :tag "Username" "username") + (const :tag "URL" "url") + (string :tag "Other field"))) + (cons + :tag "Press a key" + (const :tag "Press a key" key) + (choice + (const "Tab") + (const "Return") + (string :tag "Other key"))))))) (defun ivy-pass--async-command (command callback) "Run COMMAND in shell asyncronously. @@ -91,7 +123,9 @@ Call CALLBACK when the last command is executed." (number-to-string ivy-pass-delay))) (defun ivy-pass--get-wait-command (&optional miliseconds) - "Return a command to sleep for `ivy-pass-initial-wait'." + "Return a command to sleep for MILISECONDS. + +If MILISECONDS is nil, default to `ivy-pass-initial-wait'." (format "sleep %f" (/ (float (or miliseconds ivy-pass-initial-wait)) 1000))) (defun ivy-pass--get-key-command (key) @@ -110,7 +144,7 @@ ENTRY is an alist, FIELD is a symbol or string that can be a key of alist" SEQUENCE is a list of the following elements: - `wait'. Wait for `ivy-pass-initial-wait' miliseconds. -- `(wait )'. Wait for . +- `(wait )'. Wait for . - `(key )'. Type - `(field )'. Type of entry." (seq-filter @@ -130,10 +164,13 @@ SEQUENCE is a list of the following elements: "Get a pass entry by ENTRY-NAME." (let ((entry (auth-source-pass-parse-entry entry-name))) (unless entry - (user-error "The entry is empty. Perhaps password was incorrect?")) + (user-error "The entry is empty. Perhaps password was incorrect?")) entry)) (defun ivy-pass--get-sequence (entry sequence-name) + "Get a sequence from an ENTRY. + +SEQUENCE-NAME is a key of `ivy-pass-sequences'." (or (when-let ((str (alist-get (format "sequence-%s" (symbol-name sequence-name)) entry nil nil #'equal))) @@ -143,7 +180,17 @@ SEQUENCE is a list of the following elements: (alist-get sequence-name ivy-pass-sequences))) (defmacro ivy-pass--def-command (name &rest body) - (declare (doc-string 2) (indent 1)) + "Create functions to be invoked from `ivy-pass'. + +NAME is the base name. The first function created, NAME-command, +can be executed inside the `ivy-pass' completion interface. + +The second function, NAME-action, can be registered as an action, +e.g. with `ivy-set-actions'. + +BODY is put inside both functions, wrapped in the code that makes +the current entry available via the `entry' variable." + (declare (indent 1)) `(progn (defun ,(intern (format "%s-command" name)) () (interactive) @@ -206,13 +253,21 @@ SEQUENCE is a list of the following elements: (define-key map (kbd "M-u") #'ivy-pass--username-command) (define-key map (kbd "M-U") #'ivy-pass--url-command) (define-key map (kbd "M-f") #'ivy-pass--fields-command) - map)) + map) + "A keymap for `ivy-pass'.") (defvar ivy-pass-history nil - "History for `ivy-pass'") + "History for `ivy-pass'.") ;;;###autoload (defun ivy-pass () + "A frontend for pass. + +The command invokes Ivy to select an entry from the pass +database (with `password-store-list'). + +Available commands: +\\{ivy-pass-map}" (interactive) (ivy-read "Pass entry: " (password-store-list)