-
Notifications
You must be signed in to change notification settings - Fork 7
/
Copy pathorg-node.el
3912 lines (3440 loc) · 162 KB
/
org-node.el
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
;;; org-node.el --- Fast org-roam replacement -*- lexical-binding: t; -*-
;; Copyright (C) 2024-2025 Martin Edström
;;
;; This file 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, 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.
;;
;; For a full copy of the GNU General Public License
;; see <http://www.gnu.org/licenses/>.
;; Author: Martin Edström <meedstrom91@gmail.com>
;; URL: https://github.com/meedstrom/org-node
;; Created: 2024-04-13
;; Keywords: org, hypermedia
;; Package-Requires: ((emacs "29.1") (llama "0.5.0") (el-job "1.0.5") (magit-section "4.3.0"))
;; NOTE: Looking for Package-Version? Consult the Git tag.
;; For reference, 2.0.0 was released on 20250303, i.e. March 3.
;;; Commentary:
;; If you were the sort of person to prefer "id:" links,
;; over "file:" links, radio-targets or any other type of link,
;; you're in the right place!
;; Now you can worry less about mentally tracking subtree hierarchies
;; and directory structures. Once you've assigned an ID to something,
;; you can find it later.
;; The philosophy is the same as org-roam: if you assign an ID every
;; time you make an entry that you know you might want to link to from
;; elsewhere, then it tends to work out that the `org-node-find' command
;; can jump to more-or-less every entry you'd ever want to jump to.
;; That's just the core of it as described to someone not familiar with
;; zettelkasten-inspired software. In fact, out of the simplicity
;; arises something powerful, more to be experienced than explained.
;; Compared to org-roam:
;; + Compatible (you can use both packages and compare)
;; + Fast
;; + No SQLite
;; + Never again sit through a slow `org-id-update-id-locations'
;; + If you want, opt out of those file-level :PROPERTIES: drawers
;; + Set `org-node-prefer-with-heading'
;; + Try to rely in a bare-metal way on upstream org-id and org-capture
;; + Extra utilities, notably to auto-rename files and links
;; + An alternative way to display backlinks
;; - No support for "roam:" links
;; - No `org-roam-db-query'
;; - There's an elisp API, but if you're more familiar with SQL,
;; it's still a downgrade
;; Compared to denote:
;; + Compatible (you can use both packages and compare)
;; + No mandatory filename style (can match Denote format if you like)
;; + You can have as many "notes" as you want inside one file.
;; + You could possibly use Denote for coarse browsing,
;; and org-node for more granular browsing.
;; - No support for "denote:" links
;; - No support for Markdown or other file types
;; Finally, an oddity:
;; Due to relying on the org-id table, if a vendor README.org or other
;; downloaded Org file has a heading with an ID, it's considered part of
;; your collection -- simply because of the 1:1 correspondence, that if
;; it's known to org-id, it's known to org-node.
;;
;; These headings can be filtered after-the-fact by `org-node-filter-fn',
;; so that you do not see them in org-node commands.
;;; Code:
;; Built-in
(require 'seq)
(require 'cl-lib)
(require 'subr-x)
(require 'org)
(require 'org-id)
(require 'org-macs)
(require 'org-element)
;; External
(require 'llama)
(require 'el-job)
(require 'org-node-parser)
(require 'org-node-changes)
;; Yes officer, I know these names.
(defvar consult-ripgrep-args)
(defvar org-roam-capture-templates)
(defvar org-node-backlink-mode)
(declare-function org-node-backlink--fix-nearby "org-node-backlink")
(declare-function tramp-tramp-file-p "tramp")
(declare-function org-lint "org-lint")
(declare-function consult--grep "ext:consult")
(declare-function consult--grep-make-builder "ext:consult")
(declare-function consult--ripgrep-make-builder "ext:consult")
;;;; Options
(defgroup org-node nil
"Support a zettelkasten of org-id files and subtrees."
:group 'org)
(defcustom org-node-data-dir user-emacs-directory
"Directory in which to persist data between sessions."
:type `(choice (const :value ,user-emacs-directory)
directory)
:package-version '(org-node . "2.0.0"))
(defcustom org-node-rescan-functions nil
"Hook run after scanning specific files.
Not run after a full cache reset, only after e.g. a file is
saved or renamed causing an incremental update to the cache.
Called with one argument: the list of files re-scanned. It may
include deleted files."
:type 'hook)
(defcustom org-node-prefer-with-heading nil
"Make a heading even when creating isolated file nodes.
If nil, write a #+TITLE and a file-level property-drawer instead.
In other words:
- if nil, make file with no heading (outline level 0)
- if t, make file with heading (outline level 1)
This affects the behavior of `org-node-new-file',
`org-node-extract-subtree', and `org-node-capture-target'.
If you change your mind about this setting, you can
transition the files you already have with the Org-roam commands
`org-roam-promote-entire-buffer' and `org-roam-demote-entire-buffer'."
:type 'boolean)
(defcustom org-node-link-types
'("http" "https" "id")
"Link types that may result in backlinks.
While org-node is built around the \"id\" link type, and the ID property
is mandatory because it acts as a singular identifier, the
concept can be generalized.
Org-node also looks at the ROAM_REFS property, which in another universe
might have been called \"EXTRA_IDS\", because in many ways it is just a
list of additional IDs for the same node.
For performance reasons, not just any string of text is accepted in the
ROAM_REFS property -- it must have valid links per Org syntax, such as
\"[[https://gnu.org]]\" or \"https://gnu.org\".
Use the command \\[org-node-add-refs] for convenience.
Finally, this variable controls which link types are permitted.
The fewer types, the faster your \\[org-node-reset].
Tip: eval `(org-link-types)' to see all built-in link types. But you
can add your own types.
What\\='s it actually used for: if you insert \"https://gnu.org\" in the
body text of another node, then that results in a new backlink, even
though no reference was made to a proper ID!
People often use this to write notes about a specific web-page or PDF
file, and call it a ref-node for that web-page. See also
`org-node-try-visit-ref-node' and \\[org-node-list-reflinks].
As a special case, citation keys such as \"@ioannidis2005\" also work in
ROAM_REFS, and correspond to citations like \"[cite:@ioannidis2005]\".
There is no need to add the \"cite\" type."
:type '(repeat string)
:package-version '(org-node . "0.7"))
;; Reverted to defvar for now.
;; Make it a defcustom if ever we finish support for .org.gpg files.
(defvar org-node-inject-variables (list)
"Alist of variable-value pairs that child processes should set.
May be useful for injecting your authinfo and EasyPG settings so
that org-node can scan for ID-nodes inside .org.gpg files. Also,
`org-node-perf-keep-file-name-handlers' should include the EPG
handler.
I do not use EPG, so that is probably not enough to make it work.
Report an issue on https://github.com/meedstrom/org-node/issues
or drop me a line on Mastodon: @meedstrom@hachyderm.io"
;; :type 'alist
)
;; Reverted to defvar for now.
;; Make it a defcustom if ever we finish support for .org.gpg files.
(defvar org-node-perf-keep-file-name-handlers nil
"Which file handlers to respect while scanning for ID-nodes.
Normally, `file-name-handler-alist' changes the behavior of many Emacs
functions when passed some file names: TRAMP paths, compressed files or
.org.gpg files.
It slows down the access of very many files, since it is a series of
regexps applied to every file name passed. The fewer items in this
list, the faster `org-node-reset'.
There is probably no point adding items for now, as org-node will
need other changes to support TRAMP and encryption."
;; :type '(set
;; (function-item jka-compr-handler)
;; (function-item epa-file-handler)
;; ;; REVIEW: Chesterton's Fence. I don't understand why
;; ;; `tramp-archive-autoload-file-name-handler' exists
;; ;; (look in emacs -Q), when these two already have autoloads?
;; (function-item tramp-file-name-handler)
;; (function-item tramp-archive-file-name-handler)
;; (function-item file-name-non-special))
)
;; TODO: Probably deprecate. This was more important back when we scanned
;; synchronously (ever so long ago, April 2024).
(defvar org-node-perf-assume-coding-system nil
"Presumed coding system of all Org files while scanning.
Picking a specific system can speed up `org-node-reset' somewhat.
Set nil to let Emacs figure it out anew on every file.
This setting is likely only noticeable with a low
`num-processors' \(1-3) or you have a gigantic Org file.
On MS Windows this probably should be nil. Same if you access
your files from multiple platforms.
Modern GNU/Linux, BSD and MacOS systems almost always encode new files
as `utf-8-unix'. Verify this is true of your existing files with the
helper command \\[org-node-list-file-coding-systems]."
;; :type '(choice coding-system (const nil))
)
(defun org-node--set-and-remind-reset (sym val)
"Set SYM to VAL.
Then remind the user to run \\[org-node-reset]."
(let ((caller (cadr (backtrace-frame 5))))
(when (and (boundp 'org-node--first-init)
(not org-node--first-init)
;; TIL: loading a theme calls ALL custom-setters?!
(not (memq caller '(custom-theme-recalc-variable load-theme))))
(lwarn 'org-node :debug
"org-node--set-and-remind-reset called by %s" caller)
(run-with-timer
.1 nil #'message
"Remember to run M-x org-node-reset after configuring %S" sym)))
(custom-set-default sym val))
(defcustom org-node-filter-fn
(lambda (node)
(not (assoc "ROAM_EXCLUDE" (org-node-get-properties node))))
"Predicate returning non-nil to include a node, or nil to exclude it.
The filtering only has an impact on the table
`org-node--candidate<>node', which forms the basis for
completions in the minibuffer, and `org-node--title<>id', used
by `org-node-complete-at-point-mode'.
In other words, passing nil means the user cannot autocomplete to the
node, but Lisp code can still find it in the \"main\" table
`org-node--id<>node', and backlinks are discovered normally.
This function is applied once for every ID-node found, and
receives the node data as a single argument: an object which form
you can observe in examples from \\[org-node-peek] and specified
in the type `org-node' (C-h o org-node RET).
See the following example for a way to filter out nodes with a
ROAM_EXCLUDE property, or that have any kind of TODO state, or
are tagged :drill:, or where the full file path contains a
directory named \"archive\".
\(setq org-node-filter-fn
(lambda (node)
(not (or (assoc \"ROAM_EXCLUDE\" (org-node-get-properties node))
(org-node-get-todo node)
(string-search \"/archive/\" (org-node-get-file node))
(member \"drill\" (org-node-get-tags node))))))"
:type 'function
:set #'org-node--set-and-remind-reset)
(defcustom org-node-insert-link-hook '()
"Hook run after inserting a link to an Org-ID node.
Called with point in the new link."
:type 'hook)
(defcustom org-node-creation-hook '(org-node-put-created)
"Hook run with point in the newly created buffer or entry.
Applied by `org-node-new-file', `org-node-capture-target',
`org-node-insert-heading', `org-node-nodeify-entry' and
`org-node-extract-subtree'.
NOT applied by `org-node-fakeroam-new-via-roam-capture' -- see
org-roam\\='s `org-roam-capture-new-node-hook' instead.
A good function for this hook is `org-node-put-created', since
the default `org-node-datestamp-format' is empty.
In the author\\='s experience, recording the creation-date somewhere may
prove useful later on, e.g. when publishing to a blog.
Filesystem creation-time cannot be relied on."
:type 'hook)
(defcustom org-node-extra-id-dirs nil
"Directories in which to search Org files for IDs.
Essentially like variable `org-id-extra-files', but take directories.
You could already do this by adding directories to variable
`org-agenda-files', but that only checks the directories once. This
variable causes the directories to be checked again over time in order
to find new files that have appeared, e.g. files moved by terminal
commands or created by other instances of Emacs.
These directories are only checked as long as `org-node-cache-mode' is
active. They are checked recursively (looking in subdirectories,
sub-subdirectories etc).
EXCEPTION: Subdirectories that start with a dot, such as \".emacs.d/\",
are not checked. To check these, add them explicitly.
To avoid accidentally picking up duplicate files such as versioned
backups, causing org-id to complain about duplicate IDs, configure
`org-node-extra-id-dirs-exclude'."
:type '(repeat directory)
:set #'org-node--set-and-remind-reset)
;; TODO: Figure out how to permit .org.gpg and fail gracefully if
;; the EPG settings are insufficient. easier to test with .org.gz first
(defcustom org-node-extra-id-dirs-exclude
'("/logseq/bak/"
"/logseq/version-files/"
"/node_modules/"
".sync-conflict-")
"Path substrings of files that should not be searched for IDs.
This option only influences which files under `org-node-extra-id-dirs'
should be scanned. It is meant as a way to avoid collecting IDs inside
versioned backup files and other noise.
For all other \"excludey\" purposes, you probably mean to configure
`org-node-filter-fn' instead.
If you have accidentally let org-id add a directory of backup files, try
\\[org-node-forget-dir].
It is not necessary to exclude backups or autosaves that end in ~ or #
or .bak, since the workhorse `org-node-list-files' only considers files
that end in precisely \".org\" anyway.
You can eke out a performance boost by excluding directories with a
humongous amount of files, such as the infamous \"node_modules\", even
if they contain no Org files. However, directories that start with a
period are always ignored, so no need to specify e.g. \"~/.local/\" or
\".git/\" for that reason."
:type '(repeat string))
;;;; Pretty completion
(defcustom org-node-alter-candidates nil
"Whether to alter completion candidates instead of affixating.
This means that org-node will concatenate the results of
`org-node-affixation-fn' into a single string, so what the user types in
the minibuffer can match against the prefix and suffix as well as
against the node title.
In other words: you can match against the node's outline path, if
as `org-node-affixation-fn' is set to `org-node-prefix-with-olp'
\(default).
\(Tip: users of the \"orderless\" library do not need this
setting, they can always match against the prefix and suffix via
`orderless-annotation', bound to the character \& by default.)
Another consequence: this setting can lift the uniqueness constraint on
note titles: you\\='ll be able to have two nodes with the same name, so
long as their prefix or suffix differ in some way.
After changing this setting, run \\[org-node-reset]."
:type 'boolean
:set #'org-node--set-and-remind-reset)
;; NOTE: For context see :affixation-function in `completion-extra-properties',
;; however the following function is expected to operate on one candidate at a
;; time, instead of a list. The code flow is a bit roundabout, but the results
;; are ultimately used by `org-node-collection'.
(defcustom org-node-affixation-fn #'org-node-prefix-with-olp
"Function to give prefix and suffix to completion candidates.
The results will style the appearance of completions during
\\[org-node-find], \\[org-node-insert-link] et al.
Built-in choices:
- `org-node-affix-bare'
- `org-node-prefix-with-olp'
- `org-node-prefix-with-tags'
- `org-node-affix-with-olp-and-tags'
After changing this setting, run \\[org-node-reset].
------
Info for writing a custom function
The function receives two arguments: NODE and TITLE, and it must return
a list of three strings: title, prefix and suffix. Of those three, the
title should be TITLE unmodified.
NODE is an object which form you can observe in examples from
\\[org-node-peek] and specified in type `org-node'
\(for docs, type \\[describe-symbol] org-node RET).
If a node has aliases, the same node is passed to this function
again for every alias, in which case TITLE is actually one of the
aliases."
:type '(radio
(function-item org-node-affix-bare)
(function-item org-node-prefix-with-olp)
(function-item org-node-prefix-with-tags)
(function-item org-node-affix-with-olp-and-tags)
(function :tag "Custom function"
:value (lambda (node title) (list title "" ""))))
:package-version '(org-node . "0.9")
:set #'org-node--set-and-remind-reset)
(defun org-node-affix-bare (_node title)
"Use TITLE as-is.
For use as `org-node-affixation-fn'."
(list title "" ""))
(defun org-node-prefix-with-tags (node title)
"Prepend NODE's tags to TITLE.
For use as `org-node-affixation-fn'."
(list title
(let ((tags (org-node-get-tags node)))
(if tags
(propertize (concat "(" (string-join tags ", ") ") ")
'face 'org-tag)
""))
""))
(defun org-node-prefix-with-olp (node title)
"Prepend NODE's outline path to TITLE.
For use as `org-node-affixation-fn'."
(list title
(if-let* ((fontified-ancestors
(cl-loop
for anc in (org-node-get-olp-full node t)
collect (propertize anc 'face 'completions-annotations))))
(concat (string-join fontified-ancestors " > ") " > ")
"")
""))
(defun org-node-affix-with-olp-and-tags (node title)
"Prepend NODE's outline path to TITLE, and append NODE's tags.
For use as `org-node-affixation-fn'."
(let ((prefix-len 0))
(list title
(if (org-node-is-subtree node)
(let ((ancestors (org-node-get-olp-full node t))
(result nil))
(dolist (anc ancestors)
(push (propertize anc 'face 'completions-annotations) result)
(push " > " result))
(setq result (apply #'concat (nreverse result)))
(setq prefix-len (length result))
result)
"")
(let ((tags (org-node-get-tags node)))
(if tags
(progn
(setq tags (propertize (concat (string-join tags ":"))
'face 'org-tag))
(concat (make-string
(max 2 (- (default-value 'fill-column)
(+ prefix-len (length title) (length tags))))
?\s)
tags))
"")))))
(defvar org-node--title<>affixation-triplet (make-hash-table :test 'equal)
"1:1 table mapping titles or aliases to affixation triplets.")
(defun org-node--affixate-collection (coll)
"From list COLL, make an alist of affixated members."
(cl-loop for title in coll
collect (gethash title org-node--title<>affixation-triplet)))
;; TODO: Assign a category `org-node', then add an embark action to embark?
;; TODO: Bind a custom exporter to `embark-export'
(defun org-node-collection (str pred action)
"Custom COLLECTION for `completing-read'.
Ahead of time, org-node takes titles and aliases from
`org-node--title<>id', runs `org-node-affixation-fn' on each, and
depending on the user option `org-node-alter-candidates', it
either saves the affixated thing directly into
`org-node--candidate<>node', or into a secondary table
`org-node--title<>affixation-triplet'. Finally, this function
then either simply reads candidates off the candidates table, or
attaches the affixes in realtime.
Regardless of which, all completions are guaranteed to be keys of
`org-node--candidate<>node', but remember that it is possible for
`completing-read' to exit with user-entered input that didn\\='t
match anything.
Arguments STR, PRED and ACTION are handled behind the scenes,
see Info node `(elisp)Programmed Completion'."
(if (eq action 'metadata)
(cons 'metadata (unless org-node-alter-candidates
(list (cons 'affixation-function
#'org-node--affixate-collection))))
(complete-with-action action org-node--candidate<>node str pred)))
(defvar org-node-hist nil
"Minibuffer history.")
;; Boost this completion hist to at least 1000 elements, unless user has nerfed
;; the global `history-length'.
;; Because you often narrow down the completions majorly, and still want to
;; sort among what's left.
(and (>= history-length (car (get 'history-length 'standard-value)))
(< history-length 1000)
(put 'org-node-hist 'history-length 1000))
;;;; The metadata struct
(cl-defstruct (org-node (:constructor org-node--make-obj)
(:copier nil)
(:conc-name org-node-get-))
"An org-node object holds information about an Org ID node.
By the term 'Org ID node', we mean either a subtree with
an ID property, or a file with a file-level ID property.
The information is stored in fields listed above.
For each field, there exists a getter function \"org-node-get-FIELD\".
For example, field \"deadline\" has a getter `org-node-get-deadline'.
Given a NODE object, you would type this to get the deadline:
(org-node-get-deadline NODE)
To list all existing node objects, you can eval:
(hash-table-values org-nodes)
For examples of real-world usage, see
the documentation of `org-node-filter-fn'
or the README available as Info node `(org-node)'."
(aliases nil :read-only t :type list :documentation
"List of ROAM_ALIASES registered on the node.")
(deadline nil :read-only t :type string :documentation
"Node's DEADLINE state.")
(file nil :read-only t :type string :documentation
"Abbreviated truename of file that contains this node.")
(file-title nil :read-only t :type string :documentation
"The #+title of the file that contains this node. May be nil.
See also `org-node-get-file-title-or-basename', which is always a string
and never nil.")
(id nil :read-only t :type string :documentation
"Node's ID property.")
(level nil :read-only t :type integer :documentation
"Amount of stars in the node heading. A file-level node has 0.
See also `org-node-is-subtree'.")
(lnum nil :read-only t :type integer :documentation
"Line number.")
(olp nil :read-only t :type list :documentation
"Outline path to this node, i.e. a list of ancestor headings.
Excludes file title. To include it, try `org-node-get-olp-full'.")
(pos nil :read-only t :type integer :documentation
"Char position of the node inside its file.
For a file-level node, always 1.
For a subtree node, the position of the first asterisk.")
(priority nil :read-only t :type string :documentation
"Org priority state such as \"[#A]\".")
(properties nil :read-only t :type alist :documentation
"Alist of properties from the :PROPERTIES: drawer, verbatim.")
(refs nil :read-only t :type list :documentation
"List of ROAM_REFS registered on the node.")
(scheduled nil :read-only t :type string :documentation
"Node's SCHEDULED state.")
(tags-local nil :read-only t :type list :documentation
"List of tags local to the node.")
(tags-inherited nil :read-only t :type list :documentation
"List of inherited tags.
See also `org-node-get-tags'.")
(title nil :read-only t :type string :documentation
"The node's heading, or #+title if it is a file-level node.
In the latter case, there is no difference from `file-title'.")
(todo nil :read-only t :type string :documentation
"Node's TODO state."))
(defun org-node-get-tags (node)
"Return all tags for NODE, local and inherited.
Also respect `org-tags-exclude-from-inheritance'."
(delete-dups (append (org-node-get-tags-local node)
(org-node-get-tags-inherited node))))
(defun org-node-get-file-title-or-basename (node)
"Return the #+title of file where NODE is, or file name if absent."
(or (org-node-get-file-title node)
(file-name-nondirectory (org-node-get-file node))))
(defun org-node-is-subtree (node)
"Return t if NODE is a subtree instead of a file."
(> (org-node-get-level node) 0))
(defun org-node-get-olp-with-self (node)
"Get outline path to NODE, including NODE itself.
See `org-get-outline-path' WITH-SELF parameter."
(append (org-node-get-olp node) (list (org-node-get-title node))))
;; ... is this my life
(defun org-node-get-olp-with-self-full (node &optional filename-fallback)
"Get outline path to NODE, including file title and NODE itself.
FILENAME-FALLBACK as in `org-node-get-olp-full'."
(append (org-node-get-olp-full node filename-fallback)
(list (org-node-get-title node))))
(defun org-node-get-olp-full (node &optional filename-fallback)
"Get outline path to NODE, and include the file title if present.
If FILENAME-FALLBACK is t, use the filename if title absent."
(if (org-node-is-subtree node)
(let ((top (if filename-fallback
(org-node-get-file-title-or-basename node)
(org-node-get-file-title node))))
(if top
(cons top (org-node-get-olp node))
(org-node-get-olp node)))
nil))
(defun org-node-get-nodes-in-files (files)
"List all nodes in FILES."
(setq files (ensure-list files))
(cl-loop for node being the hash-values of org-nodes
when (member (org-node-get-file node) files)
collect node))
;; Should the names be shortened?
(defalias 'org-node-get-props #'org-node-get-properties)
;; (defalias 'org-node-get-prio #'org-node-get-priority)
;; (defalias 'org-node-get-sched #'org-node-get-scheduled)
;; (defalias 'org-node-get-lvl #'org-node-get-level)
;;;; Tables
(defvaralias 'org-nodes 'org-node--id<>node)
(defvar org-node--id<>node (make-hash-table :test 'equal)
"1:1 table mapping IDs to nodes.
To peek on the contents, try \\[org-node-peek] a few times, which
can demonstrate the data format. See also the type `org-node'.")
(defvar org-node--candidate<>node (make-hash-table :test 'equal)
"1:1 table mapping completion candidates to nodes.")
(defvar org-node--title<>id (make-hash-table :test 'equal)
"1:1 table mapping raw titles (and ROAM_ALIASES) to IDs.")
(defvar org-node--ref<>id (make-hash-table :test 'equal)
"1:1 table mapping ROAM_REFS members to the nearby ID property.
The exact form of such a member is determined by
`org-node-parser--split-refs-field'.")
(defvar org-node--ref-path<>ref-type (make-hash-table :test 'equal)
"1:1 table mapping //paths to types:.
While the same path can be found with multiple types \(e.g. http and
https), this table will in that case store a random one of these, since
that is good enough to make completions look less outlandish.
This is a smaller table than you might think, since it only contains
entries for links found in a :ROAM_REFS: field, instead of all links
found anywhere.
To see all links found anywhere, try \\[org-node-list-reflinks].")
(defvar org-node--dest<>links (make-hash-table :test 'equal)
"1:N table of links.
The table keys are destinations, i.e. values from a node's ID or
ROAM_REFS property. In practice, that means a dest is an org-id, URI
path or a citekey.
For each table key, the corresponding table value is a list of
`org-node-link' records describing each link to that destination, with
info such as from which ID-node the link originates.
For more info see `org-node-get-id-links-to'.")
;; As of 2024-10-06, the MTIME is not used for anything except supporting
;; `org-node-fakeroam-db-feed-mode'.
;; However, `org-node-list-files' needs a hash table anyway for best perf,
;; else it could simply have reused `org-id-files'.
;; Additionally, the MTIME is often useful downstream.
(defvar org-node--file<>mtime (make-hash-table :test 'equal)
"1:1 table mapping file paths to last-modification times.
The mtimes are expressed as integer Unix time.
New files are initialized with value 0, until scanned.
So do not assume that 0 means 1970-01-01T00:00:00.")
(defun org-node-get-id-links-to (node)
"List all links with :type \"id\" that point to NODE.
Each link is a plist with these fields:
:origin - ID of origin node (where the link was found)
:pos - buffer position where the link was found
:dest - ID of destination node, or a ref that belongs to it
:type - link type, such as \"https\", \"ftp\", \"info\" or
\"man\". For ID-links this is always \"id\". For a
citation this is always nil.
This function only returns the ID-links, so you can always expect :dest
to equal the ID of NODE. To return other link types, use
`org-node-get-reflinks-to'."
(gethash (org-node-get-id node) org-node--dest<>links))
(defun org-node-get-reflinks-to (node)
"List all reflinks pointing to NODE.
Typical reflinks are URLs or @citekeys occurring in any document,
and they are considered to point to NODE when NODE has a
:ROAM_REFS: property that includes that same string.
The reflink plist has the same shape as an ID-link plist
\(see `org-node-get-id-links-to'), but instead of an org-id in :dest,
you have a \"ref\" such as a web address.
Small gotcha: for a web address such as \"http://gnu.org\",
the :dest field holds only \"//gnu.org\",
while the :type field holds \"http\".
Citations such as \"@gelman2001\" have :type nil, so you can
distinguish citations from other links this way."
(cl-loop for ref in (org-node-get-refs node)
append (gethash ref org-node--dest<>links)))
(defun org-node-peek (&optional ht)
"Print some random values of table `org-nodes'.
For reference, see type `org-node'.
When called from Lisp, peek on any hash table HT."
(interactive)
(let ((rows (hash-table-values (or ht org-nodes)))
(print-length nil))
(dotimes (_ 3)
(print '----------------------------)
(cl-prin1 (nth (random (length rows)) rows)))))
;;;; The mode
(defvar org-node--time-elapsed 1.0
"Duration of the last cache reset.")
(defvar org-node--idle-timer (timer-create)
"Timer for intermittently checking `org-node-extra-id-dirs'.
for new, changed or deleted files, then resetting the cache.
This redundant behavior helps detect changes made by something
other than the current instance of Emacs, such as an user typing
rm on the command line instead of using \\[delete-file].
This timer is set by `org-node--maybe-adjust-idle-timer'.
Override that function to configure timer behavior.")
(defun org-node--maybe-adjust-idle-timer ()
"Adjust `org-node--idle-timer' based on duration of last scan.
If not running, start it."
(let ((new-delay (* 25 (1+ org-node--time-elapsed))))
(when (or (not (member org-node--idle-timer timer-idle-list))
;; Don't enter an infinite loop -- idle timers can be a footgun.
(not (> (float-time (or (current-idle-time) 0))
new-delay)))
(cancel-timer org-node--idle-timer)
(setq org-node--idle-timer
(run-with-idle-timer new-delay t #'org-node--scan-all)))))
;; TODO: The idle timer will detect new files appearing, created by other
;; emacsen, but won't run the hook `org-node-rescan-functions' on them,
;; which would be good to do. So check for new files and then try to
;; use `org-node--scan-targeted', since that runs the hook, but it is
;; easy to imagine a pitfall where the list of new files is just all
;; files, and then we do NOT want to run the hook. So use a heuristic
;; cutoff like 10 files.
;; (defun org-node--catch-unknown-modifications ()
;; (let ((new (-difference (org-node-list-files) (org-node-list-files t)))))
;; (if (> 10 )
;; (org-node--scan-all)
;; (org-node--scan-targeted))
;; )
;;;###autoload
(define-minor-mode org-node-cache-mode
"Instruct various hooks to keep the cache updated.
-----"
:global t
(remove-hook 'org-mode-hook #'org-node-cache-mode) ;; Old install instruction
(if org-node-cache-mode
(progn
(add-hook 'org-node-creation-hook #'org-node--dirty-ensure-node-known -50)
(add-hook 'org-node-insert-link-hook #'org-node--dirty-ensure-link-known -50)
(add-hook 'org-roam-post-node-insert-hook #'org-node--dirty-ensure-link-known -50)
(advice-add 'org-insert-link :after #'org-node--dirty-ensure-link-known)
(add-hook 'window-buffer-change-functions #'org-node--kill-blank-unsaved-buffers)
(add-hook 'after-save-hook #'org-node--handle-save)
(advice-add 'rename-file :after #'org-node--handle-rename)
(advice-add 'delete-file :after #'org-node--handle-delete)
(org-node-cache-ensure 'must-async t)
(org-node--maybe-adjust-idle-timer))
(cancel-timer org-node--idle-timer)
(remove-hook 'org-node-creation-hook #'org-node--dirty-ensure-node-known)
(remove-hook 'org-node-insert-link-hook #'org-node--dirty-ensure-link-known)
(remove-hook 'org-roam-post-node-insert-hook #'org-node--dirty-ensure-link-known)
(advice-remove 'org-insert-link #'org-node--dirty-ensure-link-known)
(remove-hook 'window-buffer-change-functions #'org-node--kill-blank-unsaved-buffers)
(remove-hook 'after-save-hook #'org-node--handle-save)
(advice-remove 'rename-file #'org-node--handle-rename)
(advice-remove 'delete-file #'org-node--handle-delete)))
(defun org-node--tramp-file-p (file)
"Pass FILE to `tramp-tramp-file-p' if Tramp is loaded."
(when (featurep 'tramp)
(tramp-tramp-file-p file)))
(defun org-node--handle-save ()
"Arrange to re-scan nodes and links in current buffer."
(when (and (string-suffix-p ".org" buffer-file-truename)
(not (backup-file-name-p buffer-file-truename))
(not (org-node--tramp-file-p buffer-file-truename)))
(org-node--scan-targeted buffer-file-truename)))
(defun org-node--handle-rename (file newname &rest _)
"Arrange to scan NEWNAME for nodes and links, and forget FILE."
(org-node--scan-targeted
(thread-last (list file newname)
(seq-filter (##string-suffix-p ".org" %))
(seq-remove #'backup-file-name-p)
(seq-remove #'org-node--tramp-file-p)
;; REVIEW: May not apply right to oldname?
(mapcar #'file-truename)
(org-node-abbrev-file-names))))
(defun org-node--handle-delete (file &optional _trash)
"Arrange to forget nodes and links in FILE."
(when (string-suffix-p ".org" file)
(unless (org-node--tramp-file-p file)
(setq file (org-node-abbrev-file-names file))
;; Used to just hand the file to `org-node--scan-targeted' which will
;; have the same effect if the file is gone, but sometimes it is not
;; gone, thanks to `delete-by-moving-to-trash'.
(org-node--forget-id-locations (list file))
(org-node--dirty-forget-files (list file))
(org-node--dirty-forget-completions-in (list file))
(org-node--dirty-forget-links-from
(mapcar #'org-node-get-id (org-node-get-nodes-in-files file))))))
(defvar org-node--new-unsaved-buffers nil
"List of buffers created to hold a new node.")
(defun org-node--kill-blank-unsaved-buffers (&rest _)
"Kill buffers created by org-node that have become blank.
Only applicable if the buffer\\='s file had not yet been written to
disk, and the buffer is unmodified.
This exists to allow you to create a node, especially a journal note for
today via library \"org-node-seq\", change your mind, do an `undo' to
empty the buffer, then browse to the previous day\\='s note. When later
you want to create today\\='s note after all, the seq\\='s :creator
function should be made to run again, but it will not do so if the
buffer appears to already exist, thus this hook."
(unless (minibufferp)
(dolist (buf org-node--new-unsaved-buffers)
(if (or (not (buffer-live-p buf))
(file-exists-p (buffer-file-name buf)))
;; Stop checking the buffer
(setq org-node--new-unsaved-buffers
(delq buf org-node--new-unsaved-buffers))
(with-current-buffer buf
(when (and (not (get-buffer-window buf t))
(not (buffer-modified-p))
(string-blank-p (buffer-string)))
(when buffer-auto-save-file-name
;; Hopefully throw away a stale autosave
;; since its existence annoys the user on re-creating the file
(do-auto-save nil t))
(org-node--dirty-forget-completions-in (list buffer-file-truename))
(org-node--dirty-forget-files (list buffer-file-truename))
(kill-buffer buf)))))))
;; Fixed in 036e8dcf0463517749f8b32ca828b923e584625f (Emacs 31+).
(define-advice org-id-locations-load
(:after () org-node--abbrev-org-id-locations)
"Maybe abbreviate all filenames in `org-id-locations'.
Due to an oversight, `org-id-locations-load' before Org 9.7.17 does not
re-abbreviate filenames after reconstructing them if
`org-id-locations-file-relative' is t.
For example, a path ~/org/file.org becomes /home/me/org/file.org after
loading back from disk. That would at best cause duplicate entries in
org-node\\='s tables since they almost never ensure `file-equal-p'."
(when org-id-locations-file-relative
(maphash (lambda (id file)
(puthash id (org-node-abbrev-file-names file) org-id-locations))
org-id-locations)))
;; Undo above patch if not needed.
(when (and (bound-and-true-p org-version) (version<= "9.7.17" org-version))
(advice-remove 'org-id-locations-load
'org-id-locations-load@org-node--abbrev-org-id-locations))
;;;; Scanning files to cache info about them
(defvar org-node--temp-extra-fns nil
"Extra functions to run at the end of a full scan.
The list is emptied on each use. Primarily exists to give the
interactive command `org-node-reset' a way to print the time
elapsed.")
;;;###autoload
(defun org-node-reset ()
"Wipe and rebuild the cache."
(interactive)
(cl-pushnew #'org-node--print-elapsed org-node--temp-extra-fns)
(org-node-cache-ensure nil t))
(defun org-node-cache-ensure (&optional synchronous force)
"Ensure that org-node is ready for use.
Specifically, do the following:
- Run `org-node--init-ids'.
- \(Re-)build the cache if it is empty, or if FORCE is t.
The primary use case is at the start of autoloaded commands.
Optional argument SYNCHRONOUS t means that if a cache build is
needed or already ongoing, block Emacs until it is done.
When SYNCHRONOUS is nil, return immediately and let the caching
proceed in the background. As that may take a few seconds, that
would mean that the `org-node--id<>node' table could be still outdated
by the time you query it, but that is acceptable in many
situations such as in an user command since the table is mostly
correct - and fully correct by the time of the next invocation.
If the `org-node--id<>node' table is currently empty, behave as if
SYNCHRONOUS t, unless SYNCHRONOUS is the symbol `must-async'."
(unless (eq synchronous 'must-async)
;; The warn-function becomes a no-op after the first run, so gotta
;; run it as late as possible in case of late variable settings. By
;; running it here, we've waited until the user runs a command.
(org-node-changes--warn-and-copy))
(org-node--init-ids)
(when (hash-table-empty-p org-nodes)
(setq synchronous (if (eq synchronous 'must-async) nil t))
(setq force t))
(when force
;; Launch the async processes
(org-node--scan-all))
(when (eq t synchronous)
;; Block until all processes finish
(if org-node-cache-mode
(el-job-await 'org-node 9 "org-node caching...")
(el-job-await 'org-node 9 "org-node caching... (Hint: Avoid this hang by enabling org-node-cache-mode early)"))))
;; BUG: A heisenbug lurks inside (or is revealed by) org-id.
;; https://emacs.stackexchange.com/questions/81794/
;; When it appears, backtrace will show this, which makes no sense -- it's
;; clearly called on a list:
;; Debugger entered--Lisp error: (wrong-type-argument listp #<hash-table equal 3142/5277) 0x190d581ba129>
;; org-id-alist-to-hash((("/home/kept/roam/semantic-tabs-in-2024.org" "f21c984c-13f3-428c-8223-0dc1a2a694df") ("/home/kept/roam/semicolons-make-javascript-h..." "b40a0757-bff4-4188-b212-e17e3fc54e13") ...))
;; org-node--init-ids()
;; ...
(defun org-node--init-ids ()