From 63e0558d969ff03a234dee71caad1ef0ad09053c Mon Sep 17 00:00:00 2001 From: Jethro Kuan Date: Sun, 8 Mar 2020 15:58:13 +0800 Subject: [PATCH] (chore): Cleanups for MELPA release (#251) * (chore): require minimum Org version 9.3 * fix bytecompile errors for org-roam.el * fix checkdoc errors * fix more things --- org-roam-protocol.el | 4 +- org-roam.el | 160 ++++++++++++++++++++++--------------------- 2 files changed, 85 insertions(+), 79 deletions(-) diff --git a/org-roam-protocol.el b/org-roam-protocol.el index d7bd6e5..6235b45 100644 --- a/org-roam-protocol.el +++ b/org-roam-protocol.el @@ -5,7 +5,7 @@ ;; URL: https://github.com/jethrokuan/org-roam ;; Keywords: org-mode, roam, convenience ;; Version: 1.0.0-rc1 -;; Package-Requires: ((emacs "26.1") (org "9.0")) +;; Package-Requires: ((emacs "26.1") (org "9.3")) ;; This file is NOT part of GNU Emacs. @@ -67,7 +67,7 @@ It opens or creates a note with the given ref. (val (cdr k.v))) (cons key (org-link-decode val)))) alist))) (unless (assoc 'ref decoded-alist) - (error "No ref key provided.")) + (error "No ref key provided")) (when-let ((title (cdr (assoc 'title decoded-alist)))) (push (cons 'slug (org-roam--title-to-slug title)) decoded-alist)) (let* ((org-roam-capture-templates org-roam-ref-capture-templates) diff --git a/org-roam.el b/org-roam.el index 19810f4..0061d0f 100644 --- a/org-roam.el +++ b/org-roam.el @@ -6,7 +6,7 @@ ;; URL: https://github.com/jethrokuan/org-roam ;; Keywords: org-mode, roam, convenience ;; Version: 1.0.0-rc1 -;; Package-Requires: ((emacs "26.1") (dash "2.13") (f "0.17.2") (s "1.12.0") (org "9.0") (emacsql "3.0.0") (emacsql-sqlite "1.0.0")) +;; Package-Requires: ((emacs "26.1") (dash "2.13") (f "0.17.2") (s "1.12.0") (org "9.3") (emacsql "3.0.0") (emacsql-sqlite "1.0.0")) ;; This file is NOT part of GNU Emacs. @@ -80,7 +80,7 @@ Valid values are :group 'org-roam) (defcustom org-roam-link-title-format "%s" - "The format string used when inserting org-roam links that use their title." + "The format string used when inserting Org-roam links that use their title." :type 'string :group 'org-roam) @@ -161,6 +161,8 @@ Performs a database upgrade when required." ;;;; Entrypoint: (org-roam-sql) (defun org-roam-sql (sql &rest args) + "Run SQL query on Org-roam database with ARGS. +SQL can be either the emacsql vector representation, or a string." (if (stringp sql) (emacsql (org-roam-db) (apply #'format sql args)) (apply #'emacsql (org-roam-db) sql args))) @@ -188,24 +190,30 @@ Performs a database upgrade when required." (file :not-null)]))) (defun org-roam--db-init (db) + "Initialize database DB with the correct schema and user version." (emacsql-with-transaction db (pcase-dolist (`(,table . ,schema) org-roam--db-table-schemata) (emacsql db [:create-table $i1 $S2] table schema)) (emacsql db (format "PRAGMA user_version = %s" org-roam--db-version)))) (defun org-roam--db-maybe-update (db version) + "Upgrades the database schema for DB, if VERSION is old." (emacsql-with-transaction db 'ignore ;; Do nothing now version)) (defun org-roam--db-close (&optional db) + "Closes the database connection for database DB. +If DB is nil, closes the database connection for the database in +the current `org-roam-directory'." (unless db (setq db (org-roam--get-db-connection))) (when (and db (emacsql-live-p db)) (emacsql-close db))) (defun org-roam--db-close-all () + "Closes all database connections made by Org-roam." (dolist (conn (hash-table-values org-roam--db-connection)) (org-roam--db-close conn))) @@ -218,7 +226,7 @@ Performs a database upgrade when required." 0))) (defun org-roam--db-ensure-built () - "Ensures that org-roam cache is built." + "Ensures that Org-roam cache is built." (unless (org-roam--db-initialized-p) (error "[Org-roam] your cache isn't built yet! Please run org-roam-build-cache"))) @@ -254,21 +262,21 @@ This is equivalent to removing the node from the graph." ;;;;; Insertion (defun org-roam--db-insert-links (links) - "Insert LINK into the org-roam cache." + "Insert LINKS into the Org-roam cache." (org-roam-sql [:insert :into file-links :values $v1] links)) (defun org-roam--db-insert-titles (file titles) - "Insert TITLES into the org-roam-cache." + "Insert TITLES for a FILE into the Org-roam cache." (org-roam-sql [:insert :into titles :values $v1] (list (vector file titles)))) (defun org-roam--db-insert-ref (file ref) - "Insert REF into the Org-roam cache." + "Insert REF for FILE into the Org-roam cache." (org-roam-sql [:insert :into refs :values $v1] @@ -276,7 +284,7 @@ This is equivalent to removing the node from the graph." ;;;;; Fetching (defun org-roam--get-current-files () - "Return a hash-table of file to buffer-string hash." + "Return a hash-table of file to the hash of its file contents." (let* ((current-files (org-roam-sql [:select * :from files])) (ht (make-hash-table :test #'equal))) (dolist (row current-files) @@ -318,7 +326,7 @@ This is equivalent to removing the node from the graph." (org-roam--db-insert-links links)))) (defun org-roam--db-update-file (&optional file-path) - "Update org-roam caches for the FILE-PATH." + "Update Org-roam cache for FILE-PATH." (let (buf) (if file-path (setq buf (find-file-noselect file-path)) @@ -383,12 +391,12 @@ This is equivalent to removing the node from the graph." :titles (length all-titles) :refs (length all-refs) :deleted (length (hash-table-keys current-files))))) - (message (format "files: %s, links: %s, titles: %s, refs: %s, deleted: %s" - (plist-get stats :files) - (plist-get stats :links) - (plist-get stats :titles) - (plist-get stats :refs) - (plist-get stats :deleted))) + (message "files: %s, links: %s, titles: %s, refs: %s, deleted: %s" + (plist-get stats :files) + (plist-get stats :links) + (plist-get stats :titles) + (plist-get stats :refs) + (plist-get stats :deleted)) stats))) ;;; Utilities @@ -433,7 +441,7 @@ https://github.com/kaushalmodi/ox-hugo/blob/a80b250987bc770600c424a10b3bca6ff728 (defun org-roam--file-name-extension (filename) "Return file name extension for FILENAME. -Like file-name-extension, but does not strip version number." +Like `file-name-extension', but does not strip version number." (save-match-data (let ((file (file-name-nondirectory filename))) (if (and (string-match "\\.[^.]*\\'" file) @@ -449,8 +457,8 @@ Like file-name-extension, but does not strip version number." (string= (org-roam--file-name-extension (file-name-sans-extension path)) "org"))))) (defun org-roam--org-roam-file-p (&optional file) - "Return t if FILE is part of org-roam system, return nil otherwise. -If FILE is not specified, use the current-buffer file path." + "Return t if FILE is part of Org-roam system, nil otherwise. +If FILE is not specified, use the current buffer's file-path." (let ((path (or file (buffer-file-name (current-buffer))))) (and path @@ -471,7 +479,7 @@ Ignores hidden files and directories." (dolist (file files) (cond ((file-directory-p file) - (when (not (string-match dir-ignore-regexp file)) + (unless (string-match dir-ignore-regexp file) (setq result (append (org-roam--list-files file) result)))) ((and (file-readable-p file) (org-roam--org-file-p file)) @@ -479,7 +487,7 @@ Ignores hidden files and directories." result))) (defun org-roam--list-all-files () - "Return a list of all org-roam files within `org-roam-directory'." + "Return a list of all Org-roam files within `org-roam-directory'." (org-roam--list-files (file-truename org-roam-directory))) ;;;; Org extraction functions @@ -560,10 +568,10 @@ specified via the #+ROAM_ALIAS property." (defun org-roam--title-to-slug (title) "Convert TITLE to a filename-suitable slug." (cl-flet* ((nonspacing-mark-p (char) - (eq 'Mn (get-char-code-property char 'general-category))) + (eq 'Mn (get-char-code-property char 'general-category))) (strip-nonspacing-marks (s) - (apply #'string (seq-remove #'nonspacing-mark-p - (ucs-normalize-NFD-string s)))) + (apply #'string (seq-remove #'nonspacing-mark-p + (ucs-normalize-NFD-string s)))) (replace (title pair) (replace-regexp-in-string (car pair) (cdr pair) title))) (let* ((pairs `(("[^[:alnum:][:digit:]]" . "_") ;; convert anything not alphanumeric @@ -584,24 +592,24 @@ specified via the #+ROAM_ALIAS property." org-roam-directory))) (defvar org-roam--capture-file-name-default "%<%Y%m%d%H%M%S>" - "The default file name format for org-roam templates.") + "The default file name format for Org-roam templates.") (defvar org-roam--capture-header-default "#+TITLE: ${title}\n" - "The default capture header for org-roam templates.") + "The default capture header for Org-roam templates.") (defvar org-roam--capture-file-path nil - "The file path for the Org-roam capture. This variable is set -during the Org-roam capture process.") + "The file path for the Org-roam capture. +This variable is set during the Org-roam capture process.") (defvar org-roam--capture-info nil - "An alist of additional information passed to the org-roam -template. This variable is populated dynamically, and is only -non-nil during the org-roam capture process.") + "An alist of additional information passed to the Org-roam template. +This variable is populated dynamically, and is only non-nil +during the Org-roam capture process.") (defvar org-roam--capture-context nil "A symbol, that reflects the context for obtaining the exact point in a file. This variable is populated dynamically, and is only active during -an org-roam capture process. +an Org-roam capture process. The `title' context is used in `org-roam-insert' and `org-roam-find-file', where the capture process is triggered upon @@ -617,8 +625,10 @@ note with the given `ref'.") :file-name "%<%Y%m%d%H%M%S>-${slug}" :head "#+TITLE: ${title}\n" :unnarrowed t)) - "Capture templates for Org-roam. The capture templates are an extension of -`org-capture-templates', and the documentation there also applies. + "Capture templates for Org-roam. +The capture templates are an extension of +`org-capture-templates', and the documentation there also +applies. `org-capture-templates' are extended in 3 ways: @@ -637,7 +647,7 @@ This is an extension of org-capture's template expansion. First, it expands ${var} occurences in STR, using the INFO alist. If there is a ${var} with no matching var in the alist, the value -of var is prompted for via completing-read. +of var is prompted for via `completing-read'. Next, it expands the remaining template string using `org-capture-fill-template'." @@ -648,8 +658,9 @@ Next, it expands the remaining template string using (org-capture-fill-template))) (defun org-roam--capture-new-file () - "Creates a new file, by reading the file-name attribute of the -currently active org-roam template. Returns the path to the new file." + "Create a new file and return the file path. +This is achieved by reading the file-name attribute of the +currently active Org-roam template." (let* ((name-templ (or (org-capture-get :file-name) org-roam--capture-file-name-default)) (new-id (s-trim (org-roam--fill-template @@ -657,7 +668,7 @@ currently active org-roam template. Returns the path to the new file." org-roam--capture-info))) (file-path (org-roam--file-path-from-id new-id))) (when (file-exists-p file-path) - (error (format "File exists at %s, aborting." file-path))) + (error (format "File exists at %s, aborting" file-path))) (org-roam--touch-file file-path) (write-region (org-roam--fill-template (or (org-capture-get :head) @@ -668,11 +679,11 @@ currently active org-roam template. Returns the path to the new file." file-path)) (defun org-roam--capture-get-point () - "Returns exact point to file for org-capture-template. + "Return exact point to file for org-capture-template. The file to use is dependent on the context: If the search is via title, it is assumed that the file does not -yet exist, and org-roam will attempt to create new file. +yet exist, and Org-roam will attempt to create new file. If the search is via ref, it is matched against the Org-roam database. If there is no file with that ref, a file with that ref is created. @@ -698,9 +709,10 @@ This function is used solely in Org-roam's capture templates: see (_ (error "Invalid org-roam-capture-context")))) (defun org-roam-capture (&optional goto keys) - "Create a new file using an Org-roam template, and returns the -path to the edited file. The templates are defined at -`org-roam-capture-templates'." + "Create a new file, and return the path to the edited file. +The templates are defined at `org-roam-capture-templates'. The +GOTO and KEYS argument have the same functionality as +`org-capture'." (let ((org-capture-templates org-roam-capture-templates) file-path) (when (= (length org-capture-templates) 1) @@ -716,7 +728,7 @@ path to the edited file. The templates are defined at "The point to jump to after the call to `org-roam-insert'.") (defun org-roam-insert (prefix) - "Find an org-roam file, and insert a relative org link to it at point. + "Find an Org-roam file, and insert a relative org link to it at point. If PREFIX, downcase the title before insertion." (interactive "P") (let* ((region (and (region-active-p) @@ -758,7 +770,7 @@ If PREFIX, downcase the title before insertion." (defun org-roam--capture-advance-point () "Advances the point if it is updated. -We need this function because typically org-capture prevents the +We need this function because typically `org-capture' prevents the point from being advanced, whereas when a link is inserted, the point moves some characters forward. This is added as a hook to `org-capture-after-finalize-hook'." @@ -784,7 +796,7 @@ point moves some characters forward. This is added as a hook to res)) (defun org-roam-find-file () - "Find and open an org-roam file." + "Find and open an Org-roam file." (interactive) (let* ((completions (org-roam--get-title-path-completions)) (title (completing-read "File: " completions)) @@ -805,7 +817,7 @@ point moves some characters forward. This is added as a hook to (cadr row))) rows))) (defun org-roam-find-ref (&optional info) - "Find and open an org-roam file from a ref. + "Find and open an Org-roam file from a ref. INFO is an alist containing additional information." (interactive) (let* ((completions (org-roam--get-ref-path-completions)) @@ -815,14 +827,14 @@ INFO is an alist containing additional information." ;;;; org-roam-switch-to-buffer (defun org-roam--get-roam-buffers () - "Return a list of buffers that are org-roam files." + "Return a list of buffers that are Org-roam files." (--filter (and (with-current-buffer it (derived-mode-p 'org-mode)) (buffer-file-name it) (org-roam--org-roam-file-p (buffer-file-name it))) (buffer-list))) (defun org-roam-switch-to-buffer () - "Switch to an existing org-roam buffer." + "Switch to an existing Org-roam buffer." (interactive) (let* ((roam-buffers (org-roam--get-roam-buffers)) (names-and-buffers (mapcar (lambda (buffer) @@ -896,36 +908,28 @@ Applies `org-roam-link-face' if PATH correponds to a Roam file." 'org-roam-link 'org-link)) -(defun org-roam--setup-file-links () - "Set up `file:' Org links with org-roam-link-face." - (unless (version< org-version "9.2") - (org-link-set-parameters "file" :face 'org-roam--roam-link-face))) - -(defun org-roam--teardown-file-links () - "Teardown the setup done by Org-roam on file links. -This sets `file:' Org links to have the org-link face." - (unless (version< org-version "9.2") - (org-link-set-parameters "file" :face 'org-link))) - ;;;; org-roam-backlinks-mode +(defvar org-roam-backlinks-mode-map + (let ((km (make-sparse-keymap))) + (define-key km [mouse-1] 'org-roam-open-at-point) + (define-key km (kbd "RET") 'org-roam-open-at-point) + km) + "Keymap for `org-roam-backlinks-mode'.") + (define-derived-mode org-roam-backlinks-mode org-mode "Backlinks" - "Major mode for the org-roam backlinks buffer + "Major mode for the `org-roam-buffer'. -Bindings: \\{org-roam-backlinks-mode-map}") -(define-key org-roam-backlinks-mode-map [mouse-1] 'org-roam-open-at-point) -(define-key org-roam-backlinks-mode-map (kbd "RET") 'org-roam-open-at-point) - (defun org-roam-open-at-point () "Open a link at point. -When point is on an org-roam link, open the link in the org-roam window. +When point is on an Org-roam link, open the link in the Org-roam window. -When point is on the org-roam preview text, open the link in the org-roam +When point is on the Org-roam preview text, open the link in the Org-roam window, and navigate to the point. -If item at point is not org-roam specific, default to Org behaviour." +If item at point is not Org-roam specific, default to Org behaviour." (interactive) (let ((context (org-element-context))) (catch 'ret @@ -955,6 +959,7 @@ If item at point is not org-roam specific, default to Org behaviour." (find-file file))) (defun org-roam--get-backlinks (file) + "Return the backlinks for FILE." (org-roam-sql [:select [file-from, file-to, properties] :from file-links :where (= file-to $s1)] file)) @@ -979,7 +984,7 @@ If item at point is not org-roam specific, default to Org behaviour." (cons '(file . org-roam--find-file) org-link-frame-setup)) (let ((inhibit-read-only t)) (erase-buffer) - (when (not (eq major-mode 'org-roam-backlinks-mode)) + (unless (eq major-mode 'org-roam-backlinks-mode) (org-roam-backlinks-mode)) (make-local-variable 'org-return-follows-link) (setq org-return-follows-link t) @@ -997,7 +1002,7 @@ If item at point is not org-roam specific, default to Org behaviour." file-from (org-roam--get-title-or-slug file-from))) (dolist (backlink bls) - (pcase-let ((`(,file-from ,file-to ,props) backlink)) + (pcase-let ((`(,file-from _ ,props) backlink)) (insert (propertize (s-trim (s-replace "\n" " " (plist-get props :content))) @@ -1012,7 +1017,8 @@ If item at point is not org-roam specific, default to Org behaviour." (cl-defun org-roam--maybe-update-buffer (&key redisplay) "Reconstructs `org-roam-buffer'. This needs to be quick or infrequent, because this is run at -`post-command-hook'." +`post-command-hook'. If REDISPLAY, force an update of +`org-roam-buffer'." (let ((buffer (window-buffer))) (when (and (or redisplay (not (eq org-roam--current-buffer buffer))) @@ -1034,7 +1040,7 @@ Valid states are 'visible, 'exists and 'none." (t 'none)))) (defun org-roam--set-width (width) - "Set the width of the org-roam buffer to `WIDTH'." + "Set the width of `org-roam-buffer' to `WIDTH'." (unless (one-window-p) (let ((window-size-fixed) (w (max width window-min-width))) @@ -1139,7 +1145,7 @@ into a digraph." (buffer-string)))) (defun org-roam-show-graph (&optional prefix) - "Generates and displays the Org-roam graph using `org-roam-graph-viewer'. + "Generate and displays the Org-roam graph using `org-roam-graph-viewer'. If PREFIX, then the graph is generated but the viewer is not invoked." (interactive "P") (declare (indent 0)) @@ -1161,7 +1167,7 @@ If PREFIX, then the graph is generated but the viewer is not invoked." ;;; The global minor org-roam-mode (defvar org-roam-mode-map (make-sparse-keymap) - "Keymap for org-roam commands.") + "Keymap for `org-roam-mode'.") ;;;###autoload (define-minor-mode org-roam-mode @@ -1199,26 +1205,26 @@ Otherwise, behave as if called interactively." ;; Disable local hooks for all org-roam buffers (dolist (buf (org-roam--get-roam-buffers)) (with-current-buffer buf - (org-roam--teardown-file-links) + (org-link-set-parameters "file" :face 'org-link) (remove-hook 'post-command-hook #'org-roam--maybe-update-buffer t) (remove-hook 'after-save-hook #'org-roam--db-update-file t)))))) (defun org-roam--find-file-hook-function () - "Called by `find-file-hook' when `org-roam-mode' is on." + "Called by `find-file-hook' when mode `org-roam-mode' is on." (when (org-roam--org-roam-file-p) (setq org-roam-last-window (get-buffer-window)) (add-hook 'post-command-hook #'org-roam--maybe-update-buffer nil t) (add-hook 'after-save-hook #'org-roam--db-update-file nil t) - (org-roam--setup-file-links) + (org-link-set-parameters "file" :face 'org-roam--roam-link-face) (org-roam--maybe-update-buffer :redisplay nil))) (defun org-roam--delete-file-advice (file &optional _trash) - "Advice for maintaining cache consistency during file deletes." + "Advice for maintaining cache consistency when FILE is deleted." (when (and (not (auto-save-file-name-p file)) (org-roam--org-roam-file-p file)) (org-roam--db-clear-file (file-truename file)))) -(defun org-roam--rename-file-advice (file new-file &rest args) +(defun org-roam--rename-file-advice (file new-file &rest _args) "Rename backlinks of FILE to refer to NEW-FILE." (when (and (not (auto-save-file-name-p file)) (not (auto-save-file-name-p new-file))