From 69742c3d5145f2cfbf126d28437274e7ae9fb555 Mon Sep 17 00:00:00 2001 From: Jethro Kuan Date: Sun, 16 Jan 2022 13:30:13 -0800 Subject: [PATCH] (feat)db: add customizability of extra element link parsing (#2042) Adds two customizable variables: org-roam-db-extra-links-elements and org-roam-db-extra-links-exclude-keys, which govern which elements are to be considered for link parsing by Org-roam. Also added sane defaults to org-roam-db-extra-links-exclude-keys. --- CHANGELOG.md | 1 + doc/org-roam.org | 29 +++++++++++++++++++++++++++++ doc/org-roam.texi | 31 +++++++++++++++++++++++++++++++ org-roam-db.el | 35 +++++++++++++++++++++++++++++------ 4 files changed, 90 insertions(+), 6 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 970f756..a4abb5d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,7 @@ # Changelog ## TBD ### Added +- [#2042](https://github.com/org-roam/org-roam/pull/2042) Add `org-roam-db-extra-links-elements` and `org-roam-db-extra-links-exclude-keys` for fine-grained control over additional link parsing. ### Removed ### Fixed ### Changed diff --git a/doc/org-roam.org b/doc/org-roam.org index 500fdae..53db2e2 100644 --- a/doc/org-roam.org +++ b/doc/org-roam.org @@ -490,6 +490,35 @@ all headlines with the ~ATTACH~ tag from the Org-roam database, one can set: (not (member "ATTACH" (org-get-tags))))) #+end_src +Org-roam relied on the obtained Org AST for the buffer to parse links. However, +links appearing in some places (e.g. within property drawers) are not considered +by the Org AST to be links. Therefore, Org-roam takes special care of +additionally trying to process these links. Use +~org-roam-db-extra-links-elements~ to specify which additional Org AST element +types to consider. + +- Variable: org-roam-db-extra-links-elements + + The list of Org element types to include for parsing by Org-roam. + + By default, when parsing Org's AST, links within keywords and + property drawers are not parsed as links. Sometimes however, it + is desirable to parse and cache these links (e.g. hiding links in + a property drawer). + +Additionally, one may want to ignore certain keys from being excluded within +property drawers. For example, we would not want ~ROAM_REFS~ links to be +self-referential. Hence, to exclude specific keys, we use +~org-roam-db-extra-links-exclude-keys~. + +- Variable: org-roam-db-extra-links-exclude-keys + + Keys to ignore when mapping over links. + + The car of the association list is the Org element type (e.g. keyword). The + cdr is a list of case-insensitive strings to exclude from being treated as + links. + ** When to cache By default, Org-roam is eager in caching: each time an Org-roam file is modified diff --git a/doc/org-roam.texi b/doc/org-roam.texi index 03f58fd..43914b7 100644 --- a/doc/org-roam.texi +++ b/doc/org-roam.texi @@ -791,6 +791,37 @@ all headlines with the @code{ATTACH} tag from the Org-roam database, one can set (not (member "ATTACH" (org-get-tags))))) @end example +Org-roam relied on the obtained Org AST for the buffer to parse links. However, +links appearing in some places (e.g. within property drawers) are not considered +by the Org AST to be links. Therefore, Org-roam takes special care of +additionally trying to process these links. Use +@code{org-roam-db-extra-links-elements} to specify which additional Org AST element +types to consider. + +@defvar org-roam-db-extra-links-elements + +The list of Org element types to include for parsing by Org-roam. + +By default, when parsing Org's AST, links within keywords and +property drawers are not parsed as links. Sometimes however, it +is desirable to parse and cache these links (e.g. hiding links in +a property drawer). +@end defvar + +Additionally, one may want to ignore certain keys from being excluded within +property drawers. For example, we would not want @code{ROAM_REFS} links to be +self-referential. Hence, to exclude specific keys, we use +@code{org-roam-db-extra-links-exclude-keys}. + +@defvar org-roam-db-extra-links-exclude-keys + +Keys to ignore when mapping over links. + +The car of the association list is the Org element type (e.g. keyword). The +cdr is a list of case-insensitive strings to exclude from being treated as +links. +@end defvar + @node When to cache @section When to cache diff --git a/org-roam-db.el b/org-roam-db.el index 381206d..6526fd0 100644 --- a/org-roam-db.el +++ b/org-roam-db.el @@ -98,6 +98,32 @@ slow." :type 'boolean :group 'org-roam) +(defcustom org-roam-db-extra-links-elements '(node-property keyword) + "The list of Org element types to include for parsing by Org-roam. + +By default, when parsing Org's AST, links within keywords and +property drawers are not parsed as links. Sometimes however, it +is desirable to parse and cache these links (e.g. hiding links in +a property drawer)." + :package-version '(org-roam . "2.2.0") + :group 'org-roam + :type '(set (const :tag "keywords" keyword) + (const :tag "property drawers" node-property))) + +(defcustom org-roam-db-extra-links-exclude-keys '((node-property . ("ROAM_REFS")) + (keyword . ("transclude"))) + "Keys to ignore when mapping over links. + +The car of the association list is the Org element type (e.g. +keyword). The cdr is a list of case-insensitive strings to +exclude from being treated as links. + +For example, we use this to prevent self-referential links in +ROAM_REFS." + :package-version '(org-roam . "2.2.0") + :group 'org-roam + :type '(alist)) + ;;; Variables (defconst org-roam-db-version 18) @@ -353,15 +379,12 @@ If UPDATE-P is non-nil, first remove the file in the database." ;; Links correctly recognized by Org Mode ((eq type 'link) (setq link element)) - ;; Prevent self-referencing links in ROAM_REFS - ((and (eq type 'node-property) - (org-roam-string-equal (org-element-property :key element) "ROAM_REFS")) - nil) ;; Links in property drawers and lines starting with #+. Recall that, as for Org Mode v9.4.4, the ;; org-element-type of links within properties drawers is "node-property" and for lines starting with ;; #+ is "keyword". - ((and (or (eq type 'node-property) - (eq type 'keyword)) + ((and (member type org-roam-db-extra-links-elements) + (not (member-ignore-case (org-element-property :key element) + (cdr (assoc type org-roam-db-extra-links-exclude-keys)))) (setq bounds (org-in-regexp org-link-any-re)) (setq link (buffer-substring-no-properties (car bounds)