forked from protesilaos/denote
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathdenote.el
4713 lines (3982 loc) · 189 KB
/
denote.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
;;; denote.el --- Simple notes with an efficient file-naming scheme -*- lexical-binding: t -*-
;; Copyright (C) 2022-2024 Free Software Foundation, Inc.
;; Author: Protesilaos Stavrou <[email protected]>
;; Maintainer: Protesilaos Stavrou <[email protected]>
;; URL: https://github.com/protesilaos/denote
;; Version: 2.2.4
;; Package-Requires: ((emacs "28.1"))
;; This file is NOT 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
;; (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.
;;
;; You should have received a copy of the GNU General Public License
;; along with this program. If not, see <https://www.gnu.org/licenses/>.
;;; Commentary:
;; Denote aims to be a simple-to-use, focused-in-scope, and effective
;; note-taking and file-naming tool for Emacs.
;;
;; Denote is based on the idea that files should follow a predictable
;; and descriptive file-naming scheme. The file name must offer a
;; clear indication of what the contents are about, without reference
;; to any other metadata. Denote basically streamlines the creation
;; of such files or file names while providing facilities to link
;; between them (where those files are editable).
;;
;; Denote's file-naming scheme is not limited to "notes". It can be used
;; for all types of file, including those that are not editable in Emacs,
;; such as videos. Naming files in a consistent way makes their
;; filtering and retrieval considerably easier. Denote provides relevant
;; facilities to rename files, regardless of file type.
;;
;; The manual describes all the technicalities about the file-naming
;; scheme, points of entry to creating new notes, commands to check
;; links between notes, and more: ;; <https://protesilaos.com/emacs/denote>.
;; If you have the info manual available, evaluate:
;;
;; (info "(denote) Top")
;;
;; What follows is a general overview of its core core design
;; principles (again: please read the manual for the technicalities):
;;
;; * Predictability :: File names must follow a consistent and
;; descriptive naming convention (see the manual's "The file-naming
;; scheme"). The file name alone should offer a clear indication of
;; what the contents are, without reference to any other metadatum.
;; This convention is not specific to note-taking, as it is pertinent
;; to any form of file that is part of the user's long-term storage
;; (see the manual's "Renaming files").
;;
;; * Composability :: Be a good Emacs citizen, by integrating with other
;; packages or built-in functionality instead of re-inventing
;; functions such as for filtering or greping. The author of Denote
;; (Protesilaos, aka "Prot") writes ordinary notes in plain text
;; (`.txt'), switching on demand to an Org file only when its expanded
;; set of functionality is required for the task at hand (see the
;; manual's "Points of entry").
;;
;; * Portability :: Notes are plain text and should remain portable.
;; The way Denote writes file names, the front matter it includes in
;; the note's header, and the links it establishes must all be
;; adequately usable with standard Unix tools. No need for a databse
;; or some specialised software. As Denote develops and this manual
;; is fully fleshed out, there will be concrete examples on how to do
;; the Denote-equivalent on the command-line.
;;
;; * Flexibility :: Do not assume the user's preference for a
;; note-taking methodology. Denote is conceptually similar to the
;; Zettelkasten Method, which you can learn more about in this
;; detailed introduction: <https://zettelkasten.de/introduction/>.
;; Notes are atomic (one file per note) and have a unique identifier.
;; However, Denote does not enforce a particular methodology for
;; knowledge management, such as a restricted vocabulary or mutually
;; exclusive sets of keywords. Denote also does not check if the user
;; writes thematically atomic notes. It is up to the user to apply
;; the requisite rigor and/or creativity in pursuit of their preferred
;; workflow (see the manual's "Writing metanotes").
;;
;; * Hackability :: Denote's code base consists of small and reusable
;; functions. They all have documentation strings. The idea is to
;; make it easier for users of varying levels of expertise to
;; understand what is going on and make surgical interventions where
;; necessary (e.g. to tweak some formatting). In this manual, we
;; provide concrete examples on such user-level configurations (see
;; the manual's "Keep a journal or diary").
;;
;; Now the important part... "Denote" is the familiar word, though it
;; also is a play on the "note" concept. Plus, we can come up with
;; acronyms, recursive or otherwise, of increasingly dubious utility
;; like:
;;
;; + Don't Ever Note Only The Epiphenomenal
;; + Denote Everything Neatly; Omit The Excesses
;;
;; But we'll let you get back to work. Don't Eschew or Neglect your
;; Obligations, Tasks, and Engagements.
;;; Code:
(require 'seq)
(require 'xref)
(require 'dired)
(eval-when-compile (require 'subr-x))
(defgroup denote ()
"Simple notes with an efficient file-naming scheme."
:group 'files
:link '(info-link "(denote) Top")
:link '(url-link :tag "Homepage" "https://protesilaos.com/emacs/denote"))
;;;; User options
;; About the autoload: (info "(elisp) File Local Variables")
(define-obsolete-variable-alias
'denote-user-enforced-denote-directory
'denote-directory
"3.0.0")
;;;###autoload (put 'denote-directory 'safe-local-variable (lambda (val) (or (stringp val) (eq val 'local) (eq val 'default-directory))))
(defcustom denote-directory (expand-file-name "~/Documents/notes/")
"Directory for storing personal notes.
If you intend to reference this variable in Lisp, consider using
the function `denote-directory' instead."
:group 'denote
:safe (lambda (val) (or (stringp val) (eq val 'local) (eq val 'default-directory)))
:package-version '(denote . "2.0.0")
:link '(info-link "(denote) Maintain separate directories for notes")
:type 'directory)
(defcustom denote-save-buffer-after-creation nil
"Control whether commands that creeate new notes save their buffer outright.
The default behaviour of commands such as `denote' (or related)
is to not save the buffer they create. This gives the user the
chance to review the text before writing it to a file. The user
may choose to delete the unsaved buffer, thus not creating a new
note.
If this user option is set to a non-nil value, such buffers are
saved automatically."
:group 'denote
:package-version '(denote . "3.0.0")
:type 'boolean)
(defcustom denote-known-keywords
'("emacs" "philosophy" "politics" "economics")
"List of strings with predefined keywords for `denote'.
Also see user options: `denote-infer-keywords',
`denote-sort-keywords', `denote-file-name-slug-functions'."
:group 'denote
:package-version '(denote . "0.1.0")
:type '(repeat string))
(defcustom denote-infer-keywords t
"Whether to infer keywords from existing notes' file names.
When non-nil, search the file names of existing notes in the
variable `denote-directory' for their keyword field and extract
the entries as \"inferred keywords\". These are combined with
`denote-known-keywords' and are presented as completion
candidates while using `denote' and related commands
interactively.
If nil, refrain from inferring keywords. The aforementioned
completion prompt only shows the `denote-known-keywords'. Use
this if you want to enforce a restricted vocabulary.
The user option `denote-excluded-keywords-regexp' can be used to
exclude keywords that match a regular expression.
Inferred keywords are specific to the value of the variable
`denote-directory'. If a silo with a local value is used, as
explained in that variable's doc string, the inferred keywords
are specific to the given silo.
For advanced Lisp usage, the function `denote-keywords' returns
the appropriate list of strings."
:group 'denote
:package-version '(denote . "0.1.0")
:type 'boolean)
(defcustom denote-prompts '(title keywords)
"Specify the prompts of the `denote' command for interactive use.
The value is a list of symbols, which includes any of the following:
- `title': Prompt for the title of the new note.
- `keywords': Prompts with completion for the keywords of the new
note. Available candidates are those specified in the user
option `denote-known-keywords'. If the user option
`denote-infer-keywords' is non-nil, keywords in existing note
file names are included in the list of candidates. The
`keywords' prompt uses `completing-read-multiple', meaning that
it can accept multiple keywords separated by a comma (or
whatever the value of `crm-separator' is).
- `file-type': Prompts with completion for the file type of the
new note. Available candidates are those specified in the user
option `denote-file-type'. Without this prompt, `denote' uses
the value of `denote-file-type'.
- `subdirectory': Prompts with completion for a subdirectory in
which to create the note. Available candidates are the value
of the user option `denote-directory' and all of its
subdirectories. Any subdirectory must already exist: Denote
will not create it.
- `date': Prompts for the date of the new note. It will expect
an input like 2022-06-16 or a date plus time: 2022-06-16 14:30.
Without the `date' prompt, the `denote' command uses the
`current-time'. (To leverage the more sophisticated Org
method, see the `denote-date-prompt-use-org-read-date'.)
- `template': Prompts for a KEY among `denote-templates'. The
value of that KEY is used to populate the new note with
content, which is added after the front matter.
- `signature': Prompts for an arbitrary string that can be used
to establish a sequential relationship between files (e.g. 1,
1a, 1b, 1b1, 1b2, ...). Signatures have no strictly defined
function and are up to the user to apply as they see fit. One
use-case is to implement Niklas Luhmann's Zettelkasten system
for a sequence of notes (Folgezettel). Signatures are not
included in a file's front matter. They are reserved solely
for creating a sequence in a file listing, at least for the
time being. To insert a link that includes the signature, use
the command `denote-link-with-signature'.
The prompts occur in the given order.
If the value of this user option is nil, no prompts are used.
The resulting file name will consist of an identifier (i.e. the
date and time) and a supported file type extension (per
`denote-file-type').
Recall that Denote's standard file-naming scheme is defined as
follows (read the manual for the technicalities):
DATE--TITLE__KEYWORDS.EXT
Depending on the inclusion of the `title', `keywords', and
`signature' prompts, file names will be any of those
permutations:
DATE.EXT
DATE--TITLE.EXT
DATE__KEYWORDS.EXT
DATE==SIGNATURE.EXT
DATE==SIGNATURE--TITLE.EXT
DATE==SIGNATURE--TITLE__KEYWORDS.EXT
DATE==SIGNATURE__KEYWORDS.EXT
When in doubt, always include the `title' and `keywords'
prompts (the default style).
Finally, this user option only affects the interactive use of the
`denote' command (advanced users can call it from Lisp). For
ad-hoc interactive actions that do not change the default
behaviour of the `denote' command, users can invoke these
convenience commands: `denote-type', `denote-subdirectory',
`denote-date', `denote-template', `denote-signature'."
:group 'denote
:package-version '(denote . "2.0.0")
:link '(info-link "(denote) The denote-prompts option")
:type '(radio (const :tag "Use no prompts" nil)
(set :tag "Available prompts" :greedy t
(const :tag "Title" title)
(const :tag "Keywords" keywords)
(const :tag "Date" date)
(const :tag "File type extension" file-type)
(const :tag "Subdirectory" subdirectory)
(const :tag "Template" template)
(const :tag "Signature" signature))))
(defcustom denote-sort-keywords t
"Whether to sort keywords in new files.
When non-nil, the keywords of `denote' are sorted with
`string-collate-lessp' regardless of the order they were inserted at the
minibuffer prompt.
If nil, show the keywords in their given order."
:group 'denote
:package-version '(denote . "0.1.0")
:type 'boolean)
(make-obsolete
'denote-allow-multi-word-keywords
'denote-file-name-letter-casing
"2.1.0")
(defcustom denote-file-type nil
"The file type extension for new notes.
By default (a nil value), the file type is that of Org mode.
Though the `org' symbol can be specified for the same effect.
When the value is the symbol `markdown-yaml', the file type is
that of Markdown mode and the front matter uses YAML notation.
Similarly, `markdown-toml' is Markdown but has TOML syntax in the
front matter.
When the value is `text', the file type is that of Text mode.
Any other non-nil value is the same as the default.
NOTE: Expert users can change the supported file-types by editing
the value of `denote-file-types'. That variable, which is not a
user option, controls the behaviour of all file-type-aware
functions (creating notes, renaming them, inserting front matter,
formatting a link, etc.). Consult its documentation for the
technicalities."
:type '(choice
(const :tag "Unspecified (defaults to Org)" nil)
(const :tag "Org mode (default)" org)
(const :tag "Markdown (YAML front matter)" markdown-yaml)
(const :tag "Markdown (TOML front matter)" markdown-toml)
(const :tag "Plain text" text))
:package-version '(denote . "0.6.0")
:group 'denote)
(defcustom denote-date-format nil
"Date format in the front matter (file header) of new notes.
When nil (the default value), use a file-type-specific
format (also check `denote-file-type'):
- For Org, an inactive timestamp is used, such as [2022-06-30 Wed
15:31].
- For Markdown, the RFC3339 standard is applied:
2022-06-30T15:48:00+03:00.
- For plain text, the format is that of ISO 8601: 2022-06-30.
If the value is a string, ignore the above and use it instead.
The string must include format specifiers for the date. These
are described in the doc string of `format-time-string'."
:type '(choice
(const :tag "Use appropiate format for each file type" nil)
(string :tag "Custom format for `format-time-string'"))
:package-version '(denote . "0.2.0")
:group 'denote)
(defcustom denote-date-prompt-use-org-read-date nil
"Whether to use `org-read-date' in date prompts.
If non-nil, use `org-read-date'. If nil, input the date as a
string, as described in `denote'.
This option is relevant when `denote-prompts' includes a `date'
and/or when the user invokes the command `denote-date'."
:group 'denote
:package-version '(denote . "0.6.0")
:type 'boolean)
(defcustom denote-org-store-link-to-heading t
"Determine whether `org-store-link' links to the current Org heading.
When non-nil store link to the current Org heading inside the
Denote file. If the heading does not have a CUSTOM_ID, create it
and include it in its PROPERTIES drawer. If a CUSTOM_ID exists,
take it as-is.
Make the resulting link a combination of the `denote:' link type,
pointing to the identifier of the current file, plus the value of
the heading's CUSTOM_ID, such as:
- [[denote:20240118T060608][Some test]]
- [[denote:20240118T060608::#h:eed0fb8e-4cc7-478f][Some test::Heading text]]
Both lead to the same Denote file, but the latter jumps to the
heading with the given CUSTOM_ID. Notice that the link to the
heading also has a different description, which includes the
heading text.
The value of the CUSTOM_ID is determined by the Org user option
`org-id-method'. The sample shown above uses the default UUID
infrastructure (though I deleted a few characters to not get
complaints from the byte compiler about long lines in the doc
string...).
If this user option is set to nil, only store links to the Denote
file (using its identifier), but not to the given heading. This
is what Denote was doing in versions prior to 3.0.0.
What `org-store-link' does is merely collect a link. To actually
insert it, use the command `org-insert-link'.
[ This feature only works in Org mode files, as other file types
do not have a linking mechanism that handles unique identifiers
for headings or other patterns to jump to. If `org-store-link'
is invoked in one such file, it captures only the Denote
identifier of the file, even if this user option is set to a
non-nil value. ]"
:group 'denote
:package-version '(denote . "3.0.0")
:type 'boolean)
(defcustom denote-templates nil
"Alist of content templates for new notes.
A template is arbitrary text that Denote will add to a newly
created note right below the front matter.
Templates are expressed as a (KEY . STRING) association.
- The KEY is the name which identifies the template. It is an
arbitrary symbol, such as `report', `memo', `statement'.
- The STRING is ordinary text that Denote will insert as-is. It
can contain newline characters to add spacing. The manual of
Denote contains examples on how to use the `concat' function,
beside writing a generic string.
The user can choose a template either by invoking the command
`denote-template' or by changing the user option `denote-prompts'
to always prompt for a template when calling the `denote'
command."
:type '(alist :key-type symbol :value-type string)
:package-version '(denote . "0.5.0")
:link '(info-link "(denote) The denote-templates option")
:group 'denote)
(defcustom denote-backlinks-show-context nil
"When non-nil, show link context in the backlinks buffer.
The context is the line a link to the current note is found in.
The context includes multiple links to the same note, if those
are present.
When nil, only show a simple list of file names that link to the
current note."
:group 'denote
:package-version '(denote . "1.2.0")
:type 'boolean)
(defcustom denote-rename-no-confirm nil
"Make renaming commands not prompt for confirmation and save buffers outright.
This affects the behaviour of the commands `denote-rename-file',
`denote-dired-rename-files', `denote-rename-file-using-front-matter',
`denote-dired-rename-marked-files-with-keywords',
`denote-dired-rename-marked-files-using-front-matter',
`denote-keywords-add', `denote-keywords-remove', and any other
command that builds on top of them.
The default behaviour of the `denote-rename-file' command (and
others like it) is to ask for an affirmative answer as a final
step before changing the file name and, where relevant, inserting
or updating the corresponding front matter. It also does not
save the affected file's buffer to let the user inspect and
confirm the changes (such as by invoking the command
`diff-buffer-with-file').
With this user option bound to a non-nil value, buffers are saved
as well. The assumption is that the user who opts in to this
feature is familiar with the `denote-rename-file' operation (or
related) and knows it is reliable.
Specialised commands that build on top of `denote-rename-file' (or related)
may internally bind this user option to a non-nil value in order
to perform their operation (e.g. `denote-dired-rename-files' goes
through each marked Dired file, prompting for the information to
use, but carries out the renaming without asking for confirmation)."
:group 'denote
:package-version '(denote . "3.0.0")
:type 'boolean)
(defcustom denote-excluded-directories-regexp nil
"Regular expression of directories to exclude from all operations.
Omit matching directories from file prompts and also exclude them
from all functions that check the contents of the variable
`denote-directory'. The regexp needs to match only the name of
the directory, not its full path.
File prompts are used by several commands, such as `denote-link'
and `denote-subdirectory'.
Functions that check for files include `denote-directory-files'
and `denote-directory-subdirectories'.
The match is performed with `string-match-p'."
:group 'denote
:package-version '(denote . "1.2.0")
:type 'string)
(defcustom denote-excluded-keywords-regexp nil
"Regular expression of keywords to not infer.
Keywords are inferred from file names and provided at relevant
prompts as completion candidates when the user option
`denote-infer-keywords' is non-nil.
The match is performed with `string-match-p'."
:group 'denote
:package-version '(denote . "1.2.0")
:type 'string)
(defcustom denote-after-new-note-hook nil
"Normal hook that runs after the `denote' command.
This also covers all convenience functions that call `denote'
internally, such as `denote-signature' and `denote-type' (check
the default value of the user option `denote-commands-for-new-notes')."
:group 'denote
:package-version '(denote . "2.1.0")
:type 'hook)
(defcustom denote-after-rename-file-hook nil
"Normal hook called after a succesful Denote rename operation.
This affects the behaviour of the commands `denote-rename-file',
`denote-dired-rename-files', `denote-rename-file-using-front-matter',
`denote-dired-rename-marked-files-with-keywords',
`denote-dired-rename-marked-files-using-front-matter',
`denote-keywords-add', `denote-keywords-remove', and any other
command that builds on top of them."
:group 'denote
:package-version '(denote . "3.0.0")
:type 'hook)
(defcustom denote-region-after-new-note-functions nil
"Abnormal hook called after `denote-region'.
Functions in this hook are called with two arguments,
representing the beginning and end buffer positions of the region
that was inserted in the new note. These are called only if
`denote-region' is invoked while a region is active.
A common use-case is to call `org-insert-structure-template'
after a region is inserted. This case does not actually require
the aforementioned arguments, in which case the function can
simply declare them as ignored by prefixing the argument names
with an underscore. For example, the following will prompt for a
structure template as soon as `denote-region' is done:
(defun my-denote-region-org-structure-template (_beg _end)
(when (derived-mode-p \\='org-mode)
(activate-mark)
(call-interactively \\='org-insert-structure-template)))
(add-hook \\='denote-region-after-new-note-functions
#\\='my-denote-region-org-structure-template)"
:group 'denote
:package-version '(denote . "2.1.0")
:link '(info-link "(denote) Create a note with the region's contents")
:type 'hook)
(defcustom denote-commands-for-new-notes
'(denote
denote-date
denote-subdirectory
denote-template
denote-type
denote-signature)
"List of commands for `denote-command-prompt' that create a new note.
These are used by commands such as `denote-open-or-create-with-command'
and `denote-link-after-creating-with-command'."
:group 'denote
:package-version '(denote . "2.1.0")
:link '(info-link "(denote) Choose which commands to prompt for")
:type '(repeat symbol))
(defvar denote-file-name-slug-functions
'((title . denote-sluggify-title)
(signature . denote-sluggify-signature)
(keyword . denote-sluggify-keyword))
"Specify the method Denote uses to format the components of the file name.
The value is an alist where each element is a cons cell of the
form (COMPONENT . METHOD).
- The COMPONENT is an unquoted symbol among `title', `signature',
`keyword' (notice the absence of `s', see below), which
refers to the corresponding component of the file name.
- The METHOD is the function to be used to format the given
component. This function should take a string as its parameter
and return the string formatted for the file name. In the case
of the `keyword' component, the function receives a SINGLE
string representing a single keyword and return it formatted
for the file name. Joining the keywords together is handled by
Denote.
Note that the `keyword' function is also applied to the keywords
of the front matter.
By default, if a function is not specified for a component, we
use `denote-sluggify-title', `denote-sluggify-keyword' and
`denote-sluggify-signature'.")
(make-obsolete
'denote-file-name-letter-casing
'denote-file-name-slug-functions
"3.0.0")
(defvar denote-file-name-deslug-functions
'((title . denote-desluggify-title)
(signature . denote-desluggify-signature)
(keyword . denote-desluggify-keyword))
"Specify the method Denote uses to reverse the process of `denote-sluggify'.
Since `denote-sluggify' is destructive, this is just an attempt
to get back a more human-friendly component. This is useful when
you want to retrieve a title or signature from the file name and
display it as the default input in commands such as
`denote-rename-file'.
See the documentation of `denote-file-name-slug-functions'.
By default, if a function is not specified for a component, we
use `denote-desluggify-title', `denote-desluggify-keyword' and
`denote-desluggify-signature'.")
;;;; Main variables
;; For character classes, evaluate: (info "(elisp) Char Classes")
(defconst denote-id-format "%Y%m%dT%H%M%S"
"Format of ID prefix of a note's filename.
The note's ID is derived from the date and time of its creation.")
(defconst denote-id-regexp "\\([0-9]\\{8\\}\\)\\(T[0-9]\\{6\\}\\)"
"Regular expression to match `denote-id-format'.")
(defconst denote-signature-regexp "==\\([^.]*?\\)\\(--.*\\|__.*\\|\\..*\\)*$"
"Regular expression to match the SIGNATURE field in a file name.")
(defconst denote-title-regexp "--\\([^.]*?\\)\\(--.*\\|__.*\\|\\..*\\)*$"
"Regular expression to match the TITLE field in a file name.")
(defconst denote-keywords-regexp "__\\([^.]*?\\)\\(--.*\\|__.*\\|\\..*\\)*$"
"Regular expression to match the KEYWORDS field in a file name.")
(defconst denote-excluded-punctuation-regexp "[][{}!@#$%^&*()=+'\"?,.\|;:~`‘’“”/]*"
"Punctionation that is removed from file names.
We consider those characters illegal for our purposes.")
(defvar denote-excluded-punctuation-extra-regexp nil
"Additional punctuation that is removed from file names.
This variable is for advanced users who need to extend the
`denote-excluded-punctuation-regexp'. Once we have a better
understanding of what we should be omitting, we will update
things accordingly.")
;;;; File helper functions
(defun denote--completion-table (category candidates)
"Pass appropriate metadata CATEGORY to completion CANDIDATES."
(lambda (string pred action)
(if (eq action 'metadata)
`(metadata (category . ,category))
(complete-with-action action candidates string pred))))
(defun denote--completion-table-no-sort (category candidates)
"Pass appropriate metadata CATEGORY to completion CANDIDATES.
Like `denote--completion-table' but also disable sorting."
(lambda (string pred action)
(if (eq action 'metadata)
`(metadata (category . ,category)
(display-sort-function . ,#'identity))
(complete-with-action action candidates string pred))))
(defun denote--default-directory-is-silo-p ()
"Return path to silo if `default-directory' is a silo."
(when-let ((dir-locals (dir-locals-find-file default-directory))
((alist-get 'denote-directory dir-local-variables-alist)))
(cond
((listp dir-locals)
(car dir-locals))
((stringp dir-locals)
dir-locals))))
(defun denote--make-denote-directory ()
"Make the variable `denote-directory' and its parents, if needed."
(when (not (file-directory-p denote-directory))
(make-directory denote-directory :parents)))
(defun denote-directory ()
"Return path of variable `denote-directory' as a proper directory.
Custom Lisp code can `let' bind the variable `denote-directory'
to override what this function returns."
;; TODO 2024-02-09: Remove this condition eventually.
(if-let (((or (eq denote-directory 'default-directory) (eq denote-directory 'local)))
(silo-dir (denote--default-directory-is-silo-p)))
silo-dir
(let ((denote-directory (file-name-as-directory (expand-file-name denote-directory))))
(denote--make-denote-directory)
denote-directory)))
(defun denote--slug-no-punct (str &optional extra-characters)
"Remove punctuation from STR.
Concretely, replace with an empty string anything that matches
the `denote-excluded-punctuation-regexp' and
`denote-excluded-punctuation-extra-regexp'.
EXTRA-CHARACTERS is an optional string that has the same meaning
as the aforementioned variables."
(dolist (regexp (list denote-excluded-punctuation-regexp
denote-excluded-punctuation-extra-regexp
extra-characters))
(when (stringp regexp)
(setq str (replace-regexp-in-string regexp "" str))))
str)
(defun denote--slug-no-punct-for-signature (str &optional extra-characters)
"Remove punctuation (except = signs) from STR.
This works the same way as `denote--slug-no-punct', except that =
signs are not removed from STR.
EXTRA-CHARACTERS is an optional string. See
`denote--slug-no-punct' for its documentation."
(dolist (regexp (list denote-excluded-punctuation-regexp
denote-excluded-punctuation-extra-regexp
extra-characters))
(when (stringp regexp)
(setq str (replace-regexp-in-string (string-replace "=" "" regexp) "" str))))
str)
(defun denote--slug-hyphenate (str)
"Replace spaces and underscores with hyphens in STR.
Also replace multiple hyphens with a single one and remove any
leading and trailing hyphen."
(replace-regexp-in-string
"^-\\|-$" ""
(replace-regexp-in-string
"-\\{2,\\}" "-"
(replace-regexp-in-string "_\\|\s+" "-" str))))
(defun denote--remove-dot-characters (str)
"Remove the dot character from STR."
(replace-regexp-in-string "\\." "" str))
(defun denote--trim-right-token-characters (str)
"Remove =, - and _ from the end of STR."
(string-trim-right str "[=_-]+"))
(defun denote--replace-consecutive-token-characters (str)
"Replace consecutive characters with a single one in STR.
Spaces, underscores and equal signs are replaced with a single
one in str."
(replace-regexp-in-string
"-\\{2,\\}" "-"
(replace-regexp-in-string
"_\\{2,\\}" "_"
(replace-regexp-in-string
"=\\{2,\\}" "=" str))))
(defun denote-sluggify (component str)
"Make STR an appropriate slug for file name COMPONENT.
Apply the function specified in `denote-file-name-slug-function'
to COMPONENT which is one of `title', `signature', `keyword'. If
the resulting string still contains consecutive -,_ or =, they
are replaced by a single occurence of the character. If
COMPONENT is `keyword', remove underscores from STR as they are
used as the keywords separator in file names."
(let* ((slug-function (alist-get component denote-file-name-slug-functions))
(str-slug (cond ((eq component 'title)
(funcall (or slug-function #'denote-sluggify-title) str))
((eq component 'keyword)
(replace-regexp-in-string
"_" ""
(funcall (or slug-function #'denote-sluggify-keyword) str)))
((eq component 'signature)
(funcall (or slug-function #'denote-sluggify-signature) str)))))
(denote--trim-right-token-characters
(denote--replace-consecutive-token-characters
(denote--remove-dot-characters str-slug)))))
(make-obsolete
'denote-letter-case
'denote-sluggify
"3.0.0")
(defun denote--slug-put-equals (str)
"Replace spaces and underscores with equals signs in STR.
Also replace multiple equals signs with a single one and remove
any leading and trailing signs."
(replace-regexp-in-string
"^=\\|=$" ""
(replace-regexp-in-string
"=\\{2,\\}" "="
(replace-regexp-in-string "_\\|\s+" "=" str))))
(defun denote-sluggify-title (str)
"Make STR an appropriate slug for title."
(downcase (denote--slug-hyphenate (denote--slug-no-punct str))))
(defun denote-sluggify-signature (str)
"Make STR an appropriate slug for signature."
(downcase (denote--slug-put-equals (denote--slug-no-punct-for-signature str "-+"))))
(defun denote-sluggify-keyword (str)
"Sluggify STR while joining separate words."
(downcase
(replace-regexp-in-string
"-" ""
(denote--slug-hyphenate (denote--slug-no-punct str)))))
(make-obsolete
'denote-sluggify-and-join
'denote-sluggify-keyword
"3.0.0")
(defun denote-sluggify-keywords (keywords)
"Sluggify KEYWORDS, which is a list of strings."
(mapcar (lambda (keyword)
(denote-sluggify 'keyword keyword))
keywords))
(defun denote-desluggify (component str)
"Attempt to reverse the process of `denote-sluggify' for STR on COMPONENT.
Apply the function specified in `denote-file-name-deslug-function'
to COMPONENT which is one of `title', `signature', `keyword'."
(let ((deslug-function (alist-get component denote-file-name-deslug-functions)))
(cond ((eq component 'title)
(funcall (or deslug-function #'denote-desluggify-title) str))
((eq component 'keyword)
(funcall (or deslug-function #'denote-desluggify-keyword) str))
((eq component 'signature)
(funcall (or deslug-function #'denote-desluggify-signature) str)))))
(defun denote-desluggify-title (str)
"Upcase first char in STR and dehyphenate STR, inverting `denote-sluggify'.
The intent of this function is to be used on individual strings,
such as the TITLE component of a Denote file name, but not on the
entire file name."
(let ((str (replace-regexp-in-string "-" " " str)))
(aset str 0 (upcase (aref str 0)))
str))
;; NOTE 2024-01-01: This is not used for now.
(defun denote-desluggify-signature (str)
"Reverse of `denote-sluggify-signature' for STR."
str)
;; NOTE 2023-12-25: This is not used for now.
(defun denote-desluggify-keyword (str)
"Reverse of `denote-sluggify-keyword' for STR."
str)
(defun denote--file-empty-p (file)
"Return non-nil if FILE is empty."
(zerop (or (file-attribute-size (file-attributes file)) 0)))
(defun denote-file-has-identifier-p (file)
"Return non-nil if FILE has a Denote identifier."
(denote-retrieve-filename-identifier file))
(defun denote-file-has-supported-extension-p (file)
"Return non-nil if FILE has supported extension.
Also account for the possibility of an added .gpg suffix.
Supported extensions are those implied by `denote-file-type'."
(seq-some (lambda (e)
(string-suffix-p e file))
(denote-file-type-extensions-with-encryption)))
(defun denote-filename-is-note-p (filename)
"Return non-nil if FILENAME is a valid name for a Denote note.
For our purposes, its path must be part of the variable
`denote-directory', it must have a Denote identifier in its name,
and use one of the extensions implied by `denote-file-type'."
(and (string-prefix-p (denote-directory) (expand-file-name filename))
(denote-file-has-identifier-p filename)
(denote-file-has-supported-extension-p filename)))
(defun denote-file-is-note-p (file)
"Return non-nil if FILE is an actual Denote note.
For our purposes, a note must not be a directory, must satisfy
`file-regular-p' and `denote-filename-is-note-p'."
(and (not (file-directory-p file))
(file-regular-p file)
(denote-filename-is-note-p file)))
(defun denote-file-has-signature-p (file)
"Return non-nil if FILE has a Denote identifier."
(denote-retrieve-filename-signature file))
(make-obsolete 'denote-file-directory-p nil "2.0.0")
(defun denote--file-regular-writable-p (file)
"Return non-nil if FILE is regular and writable."
(and (file-regular-p file)
(file-writable-p file)))
(defun denote-file-is-writable-and-supported-p (file)
"Return non-nil if FILE is writable and has supported extension."
(and (denote--file-regular-writable-p file)
(denote-file-has-supported-extension-p file)))
(defun denote-get-file-name-relative-to-denote-directory (file)
"Return name of FILE relative to the variable `denote-directory'.
FILE must be an absolute path."
(when-let ((dir (denote-directory))
((file-name-absolute-p file))
(file-name (expand-file-name file))
((string-prefix-p dir file-name)))
(substring-no-properties file-name (length dir))))
(defun denote-extract-id-from-string (string)
"Return existing Denote identifier in STRING, else nil."
(when (string-match denote-id-regexp string)
(match-string-no-properties 0 string)))
(define-obsolete-function-alias
'denote--default-dir-has-denote-prefix
'denote--dir-in-denote-directory-p
"2.1.0")
(defun denote--exclude-directory-regexp-p (file)
"Return non-nil if FILE matches `denote-excluded-directories-regexp'."
(and denote-excluded-directories-regexp
(string-match-p denote-excluded-directories-regexp file)))
(defun denote--directory-files-recursively-predicate (file)
"Predicate used by `directory-files-recursively' on FILE.
Return t if FILE is valid, else return nil."
(let ((rel (denote-get-file-name-relative-to-denote-directory file)))
(cond
((string-match-p "\\`\\." rel) nil)
((string-match-p "/\\." rel) nil)
((denote--exclude-directory-regexp-p rel) nil)
((file-readable-p file)))))
(defun denote--directory-all-files-recursively ()
"Return list of all files in variable `denote-directory'.
Avoids traversing dotfiles (unconditionally) and whatever matches
`denote-excluded-directories-regexp'."
(directory-files-recursively
(denote-directory)
directory-files-no-dot-files-regexp
:include-directories
#'denote--directory-files-recursively-predicate
:follow-symlinks))
(defun denote--directory-get-files ()
"Return list with full path of valid files in variable `denote-directory'.
Consider files that satisfy `denote-file-has-identifier-p' and
are not backups."
(mapcar
#'expand-file-name
(seq-filter
(lambda (file)
(and (denote-file-has-identifier-p file)
(not (backup-file-name-p file))))
(denote--directory-all-files-recursively))))
(defun denote-directory-files (&optional files-matching-regexp omit-current text-only)
"Return list of absolute file paths in variable `denote-directory'.
Files only need to have an identifier. The return value may thus
include file types that are not implied by `denote-file-type'.
Remember that the variable `denote-directory' accepts a dir-local
value, as explained in its doc string.
With optional FILES-MATCHING-REGEXP, restrict files to those
matching the given regular expression.
With optional OMIT-CURRENT as a non-nil value, do not include the
current Denote file in the returned list.
With optional TEXT-ONLY as a non-nil value, limit the results to
text files that satisfy `denote-file-is-note-p'."
(let ((files (denote--directory-get-files)))
(when (and omit-current buffer-file-name (denote-file-has-identifier-p buffer-file-name))
(setq files (delete buffer-file-name files)))
(when files-matching-regexp
(setq files (seq-filter
(lambda (f)
(string-match-p files-matching-regexp (denote-get-file-name-relative-to-denote-directory f)))
files)))
(when text-only
(setq files (seq-filter #'denote-file-is-note-p files)))
files))
;; NOTE 2023-11-30: We are declaring `denote-directory-text-only-files'
;; obsolete, though we keep it around for the foreseeable future. It
;; WILL BE REMOVED ahead of version 3.0.0 of Denote, whenever that
;; happens.
(make-obsolete 'denote-directory-text-only-files 'denote-directory-files "2.2.0")
(defun denote-directory-text-only-files ()
"Return list of text files in variable `denote-directory'.
Filter `denote-directory-files' using `denote-file-is-note-p'."
(denote-directory-files nil nil :text-only))