-
Notifications
You must be signed in to change notification settings - Fork 11
/
Copy pathhywiki.el
3648 lines (3274 loc) · 150 KB
/
hywiki.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
;;; hywiki.el --- Hyperbole's auto-wikiword note-taking system -*- lexical-binding: t -*-
;;
;; Author: Bob Weiner
;;
;; Orig-Date: 21-Acpr-24 at 22:41:13
;; Last-Mod: 19-Apr-25 at 22:52:58 by Bob Weiner
;;
;; SPDX-License-Identifier: GPL-3.0-or-later
;;
;; Copyright (C) 2024-2025 Free Software Foundation, Inc.
;; See the "HY-COPY" file for license information.
;;
;; This file is part of GNU Hyperbole.
;;; Commentary:
;;
;; This is Hyperbole's markup-free personal Wiki system for note-taking
;; and automatic wiki word highlighting and hyperlinking. It uses Org
;; mode for note taking and adds automatic hyperlinking of HyWikiWords
;; within Org files in `hywiki-directory' (default = "~/hywiki"), where
;; a HyWikiWord is a capitalized word that contains upper and lowercase
;; letters only and has a corresponding HyWikiWord.org wiki page file
;; below `hywiki-directory'. HyWikiWords require no delimiters.
;;
;; HyWikiWords are also recognized in text buffers after the global
;; minor mode, `hywiki-mode' is enabled via {M-x hywiki-mode RET}. To
;; create or jump to a HyWiki page, simply type out a potential
;; HyWikiWord or move point onto one and press the Action Key {M-RET}.
;; This will create the associated page if it does not exist. This
;; also highlights any other instances of HyWikiWords across all
;; visible Emacs windows. HyWiki is built for scalability and has been
;; tested to be performant with 10,000 HyWikiWords.
;;
;; Once Hyperbole has been loaded and activated, HyWikiWords (with or
;; without delimiters) are automatically highlighted and active in
;; the following contexts:
;; - HyWiki page buffers;
;; - non-special text buffers, when `hywiki-mode' is enabled;
;; - comments and strings in programming buffers, when
;; `hywiki-mode' is enabled.
;;
;; As HyWikiWords are typed, highlighting occurs after a trailing
;; whitespace or punctuation character is added, or when it is
;; surrounded by a matching pair of characters such as curly braces
;; or single square brackets. Since Org links use double square
;; brackets and Org targets use double or triple angle brackets,
;; HyWikiWords within these delimiters are ignored.
;;
;; You can also create Org links to HyWikiWords in any non-special text
;; buffer by surrounding them with double square brackets and the
;; 'hy:' prefix, as in: [[hy:MyWikiWord]]. If you set
;; `hywiki-org-link-type-required' to `nil', then you don't need the
;; prefix, e.g. [[MyWikiWord]]; existing HyWiki page names then will
;; override Org's standard handling of such links. To prevent Org
;; mode's binding of {M-RET} from splitting lines and creating new
;; headlines when on a HyWiki word whose page has not yet been
;; created, set `hsys-org-enable-smart-keys' to `t' so that
;; Hyperbole's Action Key does the right thing in this context.
;;
;; HyWikiWord links can also link to a section headline within a page
;; by simply following the page name with a '#' character and then the
;; section headline name. For example, if your Emacs page has a "Major
;; Modes" section, then either Emacs#Major-Modes or [[hy:Emacs#Major
;; Modes]] will work as a link to that section. Note that without the
;; square bracket delimiters, you must convert spaces in section names
;; to '-' characters. As long as the page exists, section links are
;; highlighted regardless of whether associated sections exist or not.
;; When activating a link with a section reference, you will get an
;; error if the section does not exist.
;;
;; The custom setting, `hywiki-word-highlight-flag' (default = t),
;; means HyWikiWords will be auto-highlighted within HyWiki pages.
;; Outside of such pages, `hywiki-mode' must also be enabled for such
;; auto-highlighting. Auto-highlighting depends on pre- and
;; `post-command-hook' settings. If an error occurs running one of
;; these, the associated hook is removed. To restore the auto-highlight
;; hooks either use {M-x hywiki-word-set-auto-highlighting RET} or
;; {C-u C-h h h h m} to toggle `hywiki-mode'; this also enables
;; auto-highlighting if `hywiki-word-highlight-flag' is non-nil.
;; The custom setting, `hywiki-exclude-major-modes' (default = nil), is
;; a list of major modes to exclude from HyWikiWord auto-highlighting
;; and recognition.
;;
;; Within programming modes, HyWikiWords are highlighted/hyperlinked
;; within comments and double-quoted strings only. For programming
;; modes in which you want HyWikiWords recognized everywhere, add
;; them to the custom setting, `hywiki-highlight-all-in-prog-modes'
;; (default = '(lisp-interaction-mode)).
;;
;; HyWiki adds two implicit button types to Hyperbole:
;; `hywiki-word' - creates and displays HyWikiWord referents;
;; `hywiki-existing-word' - display an existing HyWikiWord referent.
;;
;; `hywiki-word' is one of the lowest priority implicit button types
;; so that it triggers only when other types are not recognized first.
;;
;; A HyWiki can be exported to HTML for publishing to the web via Org
;; mode's publish a project feature. {M-x hywiki-publish-to-html RET}
;; will and that's it! Add a prefix argument to force regeneration of all
;; HyWiki pages, rather than only those that have been updated.
;;
;; The full set of HyWiki-specific Org publish properties are set in
;; the variable `hywiki-org-publish-project-alist'. When the HyWiki
;; code is loaded into Emacs, it automatically integrates these
;; properties with Org's publishing framework, so when in a HyWiki
;; page, you can use the standard {C-c C-e P p} current project publish
;; command.
;;
;; There are a few publishing settings you can customize prior to
;; loading Hyperbole's HyWiki code.
;;
;; HyWiki html files are saved in:
;; (hywiki-org-get-publish-property :publishing-directory)
;; Customize this directory with:
;; {M-x customize-variable RET hywiki-org-publishing-directory RET}.
;;
;; HyWiki html files are generated by the function given by:
;; (hywiki-org-get-publish-property :publishing-function)
;; Customize the value of this function if necessary with:
;; {M-x customize-variable RET hywiki-org-publishing-function RET}.
;;
;; This section summarizes HyWikiWord Actions based on the
;;
;; hywiki-referent-prompt-flag When nil When t
;; -------------------------------------------------------------------------------------
;; Action Key hywiki-word-create-and-display
;; or HyWiki/Create Create Page and Display Create Referent and Display
;; Assist Key hywiki-word-create-and-display
;; or C-u HyWiki/Create Create Referent and Display Create Page and Display
;; hywiki-word-create hywiki-create-page with Msg hywiki-create-referent with Msg
;; C-u hywiki-word-create hywiki-create-referent with Msg hywiki-create-page with Msg
;;; Code:
;;; ************************************************************************
;;; Other required Elisp libraries
;;; ************************************************************************
(require 'hactypes) ;; For `link-to-file-interactively'
(require 'hargs)
(require 'hasht)
(require 'hbut) ;; For `hbut:syntax-table'
;; (unless (featurep 'hibtypes)
;; (require 'hibtypes)) ;; For `pathname' and `pathname-line-and-column'
(require 'hpath)
(require 'hproperty)
(require 'hsys-consult)
(require 'hui) ;; For `hui:actype'
(require 'hui-mini) ;; For `hui:menu-act'
(require 'hypb) ;; Requires `seq'
(require 'outline) ;; For `outline-mode-syntax-table'
(require 'seq) ;; For 'seq-contains-p' and 'seq-difference'
(require 'subr-x) ;; For `string-remove-prefix'
(require 'thingatpt)
(eval-and-compile
'(when (require 'company nil t)
(add-to-list 'company-backends 'hywiki-company-hasht-backend)))
;;; ************************************************************************
;;; Public declarations
;;; ************************************************************************
(defvar action-key-modeline-buffer-id-function) ;; "hui-mouse.el"
(defvar bookmark-current-bookmark) ;; "bookmark.el"
(defvar hkey-value) ;; "hui-mouse.el"
(defvar hywiki-referent-menu nil) ;; "hywiki.el"
(defvar org-agenda-buffer-tmp-name) ;; "org-agenda.el"
(defvar org-export-with-broken-links) ;; "ox.el"
(defvar org-publish-project-alist) ;; "ox-publish.el"
(declare-function activities-completing-read "activities" (:prompt prompt :default default))
(declare-function activities-new "activities" (name))
(declare-function activities-resume "activities" (activity :resetp resetp))
(declare-function bookmark-completing-read "bookmark" (prompt &optional default))
(declare-function bookmark-location "bookmark" (bookmark-name-or-record))
(declare-function hsys-org-at-tags-p "hsys-org")
(declare-function org-link-store-props "ol" (&rest plist))
(declare-function org-publish-property "ox-publish" (property project &optional default))
(declare-function org-roam-node-from-title-or-alias "org-roam-node" (s &optional nocase))
(declare-function org-roam-node-open "org-roam" (note &optional cmd force))
(declare-function org-roam-node-read "org-roam" (&optional initial-input filter-fn sort-fn require-match prompt))
(declare-function org-roam-node-title "org-roam-node" (node))
(declare-function smart-treemacs-edit "hui-treemacs" (&optional dir))
;;; ************************************************************************
;;; Private variables
;;; ************************************************************************
;; Must be set after `hywiki-get-buttonize-characters' is defined
(defconst hywiki--buttonize-characters nil
"String of single character keys bound to `hywiki-buttonize-character-commands'.
Each such key self-inserts before highlighting any prior HyWiki word
in `hywiki-mode'.")
(defconst hywiki--buttonize-character-regexp nil
"Regexp matching a single separating character following a HyWiki word.")
(defconst hywiki--word-and-buttonize-character-regexp nil
"Regexp matching HyWikiWord#section plus a valid word separating character.
Group 1 is the entire HyWikiWord#section:Lnum:Cnum expression.")
(defvar hywiki--directory-checksum ""
"String checksum for `hywiki-directory' page names.")
(defvar hywiki--directory-mod-time nil
"Last mod time for `hywiki-directory' or nil if the value has not been read.
See `current-time' function for the mod time format.")
;; Redefine the `org-mode-syntax-table' for use in `hywiki-get-buttonize-characters'
;; so do not have to load all of Org mode there.
(defvar hywiki--org-mode-syntax-table
(let ((st (make-syntax-table outline-mode-syntax-table)))
(modify-syntax-entry ?\" "\"" st)
(modify-syntax-entry ?\\ "_" st)
(modify-syntax-entry ?~ "_" st)
(modify-syntax-entry ?< "(>" st)
(modify-syntax-entry ?> ")<" st)
st)
"Standard syntax table for Org mode buffers with HyWiki support.")
(defvar hywiki--pages-directory nil)
(defvar hywiki--referent-alist nil
"HyWiki alist generated from `hywiki--referent-hasht' for storage in cache.
Each element is of the form: (wikiword . (referent-type . referent-value)).")
(defvar hywiki--referent-hasht nil
"HyWiki hash table for fast WikiWord referent lookup.")
;; Globally set these values to avoid using 'let' with stack allocations
;; within `hywiki-maybe-highlight-page-name' frequently.
(defvar hywiki--any-wikiword-regexp-list nil)
(defvar hywiki--buts nil)
(defvar hywiki--but-end nil)
(defvar hywiki--but-start nil)
(defvar hywiki--buttonize-end (make-marker)) ;; This must always stay a marker
(defvar hywiki--buttonize-start (make-marker)) ;; This must always stay a marker
(defvar hywiki--current-page nil)
(defvar hywiki--end nil)
(defvar hywiki--flag nil)
(defvar hywiki--highlighting-done-flag t)
(defvar hywiki--word-pre-command nil)
(defvar hywiki--word-only nil)
(defvar hywiki--range nil)
(defvar hywiki--save-case-fold-search nil)
(defvar hywiki--save-org-link-type-required nil)
(defvar hywiki--start nil)
;;; ************************************************************************
;;; Public variables
;;; ************************************************************************
(defcustom hywiki-word-highlight-flag t
"The default, non-nil value treats HyWikiWords in HyWiki pages as hyperlinks.
A nil value disables HyWikiWord hyperlink buttons in both HyWiki
pages and all other buffers (since it also disables `hywiki-mode').
Outside of HyWiki pages, the global minor mode `hywiki-mode' must be
manually enabled for auto-HyWikiWord highlighting; programmatically,
use `(hywiki-mode 1) to enable it.
Use `hywiki-active-in-current-buffer-p' to determine if HyWikiWord
hyperlinks are currently active in a buffer or not.
Regardless of this flag, HyWikiWords in Org links and targets are not
highlighted nor treated as hyperlinks; they are handled normally by Org."
:type 'boolean
:initialize #'custom-initialize-default
:group 'hyperbole-hywiki)
(defcustom hywiki-exclude-major-modes nil
"List of major modes to exclude from HyWiki word highlighting and recognition."
:type '(list symbol)
:group 'hyperbole-hywiki)
(defcustom hywiki-highlight-all-in-prog-modes '(lisp-interaction-mode)
"List of programming major modes to highlight HyWikiWords outside of comments."
:type '(list symbol)
:group 'hyperbole-hywiki)
(defcustom hywiki-mode-lighter " HyWiki"
"String to display in mode line when the HyWiki global minor mode is enabled.
Use nil for no HyWiki mode indicator."
:type 'string
:group 'hyperbole-hywiki)
(defvar hywiki-allow-suffix-referent-types '(page path-link)
"List of referent type symbols that support # and :L line number suffixes.")
(defvar hywiki-file-suffix ".org"
"File suffix (including period) to use when creating HyWiki pages.")
;;;###autoload
(defun hywiki-let-directory (option value)
(set option value)
(hywiki-clear-referent-hasht)
(hywiki-make-referent-hasht))
;;;###autoload
(defun hywiki-set-directory (option value)
(unless (and (boundp 'hywiki-directory)
(equal hywiki-directory (file-name-as-directory value))
(hash-table-p hywiki--referent-hasht))
(set-default option (file-name-as-directory value))
(hywiki-clear-referent-hasht)
(hywiki-make-referent-hasht))
(hywiki-org-set-publish-project))
(defcustom hywiki-directory "~/hywiki/"
"Directory that holds all HyWiki pages in Org format.
See `hywiki-org-publishing-directory' for exported pages in html format."
:initialize #'custom-initialize-default
:set #'hywiki-set-directory
:type 'string
:group 'hyperbole-hywiki)
(defun hywiki-directory-changed (option set-to-value operation _where)
"Watch function for variable `hywiki-directory'.
Function is called with 4 arguments: (OPTION SET-TO-VALUE OPERATION WHERE)."
(if (memq operation '(let unlet)) ;; not setting global value
(hywiki-let-directory option set-to-value)
(hywiki-set-directory option set-to-value)))
;; This next line is needed to invoke `hywiki-set-directory' when
;; `hywiki-directory' is changed via `setq' or `let' rather than
;; `customize-set-variable'.
(add-variable-watcher 'hywiki-directory #'hywiki-directory-changed)
(defvar-local hywiki-buffer-highlighted-state nil
"State of HyWikiWords highlighting in the associated buffer.
\\='h means the buffer was already highlighted;
\\='d means the buffer was dehighlighted;
nil means no full buffer highlighting has occurred.")
(defvar hywiki-non-character-commands
'(;; Org mode
org-cycle ;; TAB
org-open-line ;; C-o
org-return ;; RET, \r
org-return-and-maybe-indent ;; C-j, \n
;; Markdown mode
markdown-cycle ;; TAB
markdown-enter-key ;; RET, \r
electric-newline-and-maybe-indent ;; C-j, \n
;; Global
newline ;; RET, \r
newline-and-indent ;; RET, \r
open-line ;; C-o
quoted-insert ;; C-q
)
"Commands that insert characters but whose input events do not
arrive as characters or that quote another character for input.")
;; Define the keymap for hywiki-mode.
(defvar hywiki-mode-map nil
"Keymap for `hywiki-mode'.
Presently, there are no key bindings; this is for future use.")
(defconst hywiki-org-link-type "hy"
"HyWiki string prefix type for Org links. Excludes trailing colon.")
(defvar hywiki-org-link-type-required t
"When t, [[hy:HyWiki Org links]] must start with `hywiki-org-link-type':.
Otherwise, this prefix is not needed and HyWiki word Org links
override standard Org link lookups. See \"(org)Internal Links\".")
(defcustom hywiki-org-publishing-broken-links 'mark
"HyWiki Org publish option that determines how invalid links are handled.
The default is \\='mark.
When this option is non-nil, broken HyWiki links are ignored,
without stopping the export process. If it is set to \\='mark,
broken links are marked with a string like:
[BROKEN LINK: path]
where PATH is the un-resolvable reference."
:initialize #'custom-initialize-default
:set (lambda (option value)
(set option value)
(hywiki-org-set-publish-project))
:type 'symbol
:group 'hyperbole-hywiki)
(defcustom hywiki-org-publishing-directory "~/public_hywiki"
"Directory where HyWiki pages are converted into html and published."
:initialize #'custom-initialize-default
:set (lambda (option value)
(set option value)
(hywiki-org-set-publish-project))
:type 'string
:group 'hyperbole-hywiki)
(defcustom hywiki-org-publishing-function 'org-html-publish-to-html
"HyWiki Org publish function used to export a HyWiki page to html."
:initialize #'custom-initialize-default
:set (lambda (option value)
(set option value)
(hywiki-org-set-publish-project))
:type 'symbol
:group 'hyperbole-hywiki)
(defcustom hywiki-org-publishing-sitemap-title
(let ((dir-name (file-name-base
(directory-file-name
(file-name-as-directory hywiki-directory)))))
(if (equal dir-name "hywiki")
"HyWiki"
dir-name))
"HyWiki Org publish sitemap title."
:initialize #'custom-initialize-default
:set (lambda (option value)
(set option value)
(hywiki-org-set-publish-project))
:type 'string
:group 'hyperbole-hywiki)
(defvar hywiki-org-publish-project-alist nil
"HyWiki-specific export properties added to `org-publish-project-alist'.")
(defun hywiki-org-make-publish-project-alist ()
(setq org-export-with-broken-links hywiki-org-publishing-broken-links
hywiki-org-publish-project-alist
(list
"hywiki"
:auto-sitemap t
:base-directory (expand-file-name hywiki-directory)
:html-head (format
"<link rel=\"stylesheet\" type=\"text/css\" href=\"%sman/hyperbole.css\"/>"
hyperb:dir)
:html-link-home "index.html"
;; :html-link-up "theindex.html"
;; !! TODO: The :makeindex property is disabled for now, until a process is
;; developed to force the Org publish process to regenerate the
;; index after index entries are inserted into the temporary Org
;; buffer prior to export to HTML.
:html-postamble t
:html-postable-format '(("en" "<p class=\"author\">Author: %a (%e)</p>
<p class=\"last-mod\">Last Modified: %C</p>
<p class=\"creator\">%c</p>"))
:makeindex nil
:publishing-directory hywiki-org-publishing-directory
:publishing-function hywiki-org-publishing-function
:section-numbers t
:shell "shell-command"
:sitemap-filename "index.org"
;; sitemap (TOC) is stored in "sitemap.html"
:sitemap-title hywiki-org-publishing-sitemap-title
:with-date t
:with-toc nil)))
(defvar-local hywiki-page-flag nil
"Set to t after finding a HyWiki page file, else nil.
The file must be below `hywiki-directory'.
For reference, this is set when `window-buffer-change-functions' calls
`hywiki-maybe-highlight-page-names' which calls `hywiki-in-page-p'.")
(defcustom hywiki-referent-prompt-flag nil
"When t, the Action Key and HyWiki/Create always prompt for referent type.
Nil by default."
:type 'boolean
:initialize #'custom-initialize-default
:group 'hyperbole-hywiki)
(defconst hywiki-word-regexp
"\\<\\([[:upper:]][[:alpha:]]+\\)\\>"
"Regexp that matches a HyWiki word only.
Do not use a start or end line/string anchor in this regexp.")
(defconst hywiki-word-section-regexp
"\\(#[^][# \t\n\r\f]+\\)"
"Regexp that matches a non-delimited HyWiki word #section extension.
After the first # character, this may contain any non-square-bracket,
non-# and non-whitespace characters.")
(defconst hywiki-word-line-and-column-numbers-regexp
(concat "\\(" hpath:line-and-column-numbers "\\)")
"Group 2 is the 1-based line number.
Group 4 is the optional 0-based column number.")
(defconst hywiki-word-with-optional-suffix-regexp
(concat hywiki-word-regexp hywiki-word-section-regexp "??"
hywiki-word-line-and-column-numbers-regexp "?")
"Regexp for a HyWiki word with an optional #section, :Lline-num, :Ccol-num.
Section may not contain whitespace or square brackets. Use '-' to
substitute for spaces in the section/headline name.
Group 1 is the HyWiki word.
Group 2 is any optional #section with the # included.
Group 4 is any optional 1-based line number to jump to for any
file-based referents (relative to any section given).
Group 6 is any optional 0-based column number to jump to for any
file-based referents.")
(defconst hywiki-word-with-optional-suffix-exact-regexp
(concat "\\`" hywiki-word-regexp "\\(#[^][\n\r\f]+\\)??"
hywiki-word-line-and-column-numbers-regexp "?\\'")
"Exact match regexp for a HyWiki word with an optional #section.
The section may contain spaces or tabs but not square brackets;
it is preferable, however, to substitute '-' for whitespace in
the section/headline name to simplify recognition.
Group 1 is the HyWiki word.
Group 2 is any optional #section with the # included.
Group 4 is any optional 1-based line number to jump to for any
file-based referents (relative to any section given).
Group 6 is any optional 0-based column number to jump to for any
file-based referents.")
(defconst hywiki-word-suffix-regexp "\\(#\\|::\\|:L\\)\\(.+\\)\\'"
"Regexp matching any trailing part of a HyWikiWord reference.
It may be a section or a line number reference. Group one is the type
of reference and group two is the rest of the suffix reference.")
(defface hywiki--word-face
'((((min-colors 88) (background dark)) (:foreground "orange"))
(((background dark)) (:background "orange" :foreground "black"))
(((min-colors 88)) (:foreground "orange"))
(t (:background "orange")))
"Face for HyWiki word highlighting."
:group 'hyperbole-hywiki)
(defcustom hywiki-word-face 'hywiki--word-face
"Hyperbole face for HyWiki word highlighting."
:initialize #'custom-initialize-default
:type 'face
:group 'hyperbole-hywiki)
(defcustom hywiki-display-page-function #'hpath:find
"Hyperbole function to display HyWiki page pathnames.
Only argument is the page's pathname."
:initialize #'custom-initialize-default
:type 'string
:group 'hyperbole-hywiki)
(defcustom hywiki-allow-plurals-flag t
"Non-nil means plural HyWikiWords have the same referent as the singular form.
Non-nil is the default."
:initialize #'custom-initialize-default
:set (lambda (option value)
(set option value)
(setq hywiki--any-wikiword-regexp-list nil))
:type 'boolean
:group 'hyperbole-hywiki)
;;; ************************************************************************
;;; hywiki minor mode and text edit command hooks
;;; ************************************************************************
(defun hywiki-debuttonize-non-character-commands ()
"Store any HyWikiWord before or after point for later comparison.
Triggered by `pre-command-hook' for non-character -commands, including
deletion commands and those in `hywiki-non-character-commands'."
(setq hywiki--word-pre-command nil)
(set-marker hywiki--buttonize-start nil)
(set-marker hywiki--buttonize-end nil)
(unless (hywiki-non-hook-context-p)
;; Record the WikiWord from any WikiWord ref that point is on
(setq hywiki--word-pre-command (hywiki-get-singular-wikiword (hywiki-word-at)))
(when (or (memq this-command hywiki-non-character-commands)
(and (symbolp this-command)
(string-match-p "^\\(org-\\)?\\(delete-\\|kill-\\)\\|\\(-delete\\|-kill\\)\\(-\\|$\\)" (symbol-name this-command))))
;; Test if at delimiters surrounding a WikiWord and if so,
;; record those for use by post hooks.
(cl-destructuring-bind (start end)
;; Get delimited region only if before or after delimiters,
;; else return (nil nil).
(hywiki-at-range-delimiter) ;; includes delimiters
;; Use these to store any range of a delimited HyWikiWord#section
(set-marker hywiki--buttonize-start start)
(set-marker hywiki--buttonize-end end)
start)))
(setq hywiki--flag nil))
(defun hywiki-buttonize-non-character-commands ()
"Highlight any HyWikiWord before or after point as a Hyperbole button.
Triggered by `post-command-hook' for non-character-commands, including
deletion commands and those in `hywiki-non-character-commands'."
(unless (or hywiki--flag (hywiki-non-hook-context-p))
(when (or (memq this-command hywiki-non-character-commands)
(and (symbolp this-command)
(string-match-p "^\\(org-\\)?\\(delete-\\|kill-\\)\\|\\(-delete\\|-kill\\)\\(-\\|$\\)" (symbol-name this-command))))
(setq hywiki--range nil)
;; Dehighlight any previously highlighted WikiWord at point
;; before we move to the start of any current WikiWord and
;; rehighlight that.
(hywiki--maybe-dehighlight-at-point)
(save-excursion
(cond ((marker-position hywiki--buttonize-start)
;; Point was before or after a WikiWord delimiter
(goto-char (1+ hywiki--buttonize-start)))
((setq hywiki--range (hywiki-word-at :range))
(cl-destructuring-bind (_ start end)
hywiki--range
(if (and start end)
(progn
;; On a non-delimited HyWikiWord
(set-marker hywiki--buttonize-start start)
(set-marker hywiki--buttonize-end end)
(goto-char start)
(skip-chars-backward "-" (line-beginning-position))
t)
(setq hywiki--range nil)))))
(hywiki--maybe-rehighlight-at-point)))))
(defun hywiki-buttonize-character-commands ()
"Turn any HyWikiWords between point into highlighted Hyperbole buttons.
Triggered by `post-self-insert-hook' after self-inserting one or more
characters after `post-command-hook' has run."
;; If `hywiki--flag' is set non-nil below, then
;; `hywiki-buttonize-non-character-commands' on `post-command-hook'
;; does nothing.
(unless (setq hywiki--flag (hywiki-non-hook-context-p))
(setq hywiki--range nil)
;; Dehighlight any previously highlighted WikiWord at point
;; before we move to the start of any current WikiWord and
;; rehighlight that.
(hywiki--maybe-dehighlight-at-point)
(save-excursion
(cond ((marker-position hywiki--buttonize-start)
;; Point was before or after a WikiWord delimiter
(goto-char hywiki--buttonize-start)
(skip-chars-backward "-" (line-beginning-position))
(goto-char (1- (point))))
((not (equal (setq hywiki--range (hywiki-word-at :range))
'(nil nil nil)))
(cl-destructuring-bind (_ start end)
hywiki--range
(if (and start end)
(progn
;; On a non-delimited HyWikiWord
(set-marker hywiki--buttonize-start start)
(set-marker hywiki--buttonize-end end)
(goto-char start)
(skip-chars-backward "-" (line-beginning-position))
t)
(setq hywiki--range nil))))
((not (equal (setq hywiki--range (hywiki-at-range-delimiter)) ;; includes delimiters
'(nil nil)))
;; At delimiters surrounding a WikiWord
(let ((start (nth 0 hywiki--range))
(end (nth 1 hywiki--range)))
(when (and start end)
;; Use these to store any range of a delimited HyWikiWord#section
(set-marker hywiki--buttonize-start (1+ start))
(set-marker hywiki--buttonize-end (1- end))))))
;; This first rehighlighting is needed to ensure
;; any wikiword before an inserted whitespace character is
;; properly highlighted when separating two words or after a
;; closing delimiter.
(save-excursion
(goto-char (max (1- (point)) (point-min)))
(hywiki--maybe-rehighlight-at-point))
(hywiki--maybe-rehighlight-at-point))))
(defun hywiki-buttonize-word (func start end face)
"Create a HyWikiWord button by calling FUNC with START and END positions.
Function may apply FACE to highlight the button or may transform it
into an Org link, etc. Function operates on the current buffer and
takes 3 arguments: `range-start', `range-end' and `face' to apply to
the button."
(funcall func start end face))
(defun hywiki-get-buttonize-characters ()
"Return a string of Org self-insert keys that have punctuation/symbol syntax."
(let (key
cmd
key-cmds
result)
;; Org and other text mode self-insert-command bindings are just
;; remaps inherited from global-map. Create key-cmds list of
;; parsable (key . cmd) combinations where key may be a
;; (start-key . end-key) range of keys.
(map-keymap (lambda (key cmd) (setq key-cmds (cons (cons key cmd) key-cmds))) (current-global-map))
(dolist (key-cmd key-cmds (concat (seq-difference (nreverse result)
"-_*#:" #'=)))
(setq key (car key-cmd)
cmd (cdr key-cmd))
(when (eq cmd 'self-insert-command)
(cond ((and (characterp key)
(eq (char-syntax key) ?.))
;; char with punctuation/symbol syntax
(setq result (cons key result)))
((and (consp key)
(characterp (car key))
(characterp (cdr key))
(<= (cdr key) 256))
;; ASCII char range, some of which has punctuation/symbol syntax
(with-syntax-table hywiki--org-mode-syntax-table
(dolist (k (number-sequence (car key) (cdr key)))
(when (memq (char-syntax k) '(?. ?_))
(setq result (cons k result)))))))))))
(defun hywiki-non-hook-context-p ()
(or (minibuffer-window-active-p (selected-window))
(and (boundp 'edebug-active) edebug-active
(active-minibuffer-window))
(and (derived-mode-p 'prog-mode)
(not (apply #'derived-mode-p hywiki-highlight-all-in-prog-modes))
;; Not inside a comment or a string
(not (or (nth 4 (syntax-ppss)) (hypb:in-string-p))))))
;;;###autoload
(define-minor-mode hywiki-mode
"Toggle HyWiki global minor mode with \\[hywiki-mode].
HyWiki automatically highlights and turns instances of known
HyWikiWords into implicit buttons if they are within buffers with
files attached from `hywiki-directory'. Such buttons either link
to HyWiki pages or activate typed referents such as bookmarks.
HyWiki Minor Mode enables the same behavior in most other text and
programming buffers except those with a major mode in
`hywiki-exclude-major-modes'.
HyWikiWord references may also include optional suffixes:
- a #section reference that links to a HyWiki page Org headline or
other outline file. Spaces in the headline must be converted
to dash characters for proper recognition;
- optionally followed by :L<line-number>:C<column-number>
where the column part is also optional. If a section is
given, the line number is relative to the section and the
section headline is line 1.
When hywiki-mode is enabled, the `hywiki-mode' variable is
non-nil.
See the Info documentation at \"(hyperbole)HyWiki\".
\\{hywiki-mode-map}"
:global t
:lighter hywiki-mode-lighter
:keymap hywiki-mode-map
:group 'hyperbole-hywiki
(if hywiki-mode
;; enable mode
(progn
;; Need hyperbole-mode
(require 'hyperbole)
(unless hyperbole-mode
(hyperbole-mode 1))
(unless hywiki-mode-map
(setq hywiki-mode-map (make-sparse-keymap)))
;; Next line triggers a call to `hywiki-maybe-highlight-wikiwords-in-frame'
(set-variable 'hywiki-word-highlight-flag t)
(hywiki-word-set-auto-highlighting 1))
;; disable mode
;; Dehighlight HyWikiWords in this buffer when 'hywiki-mode' is
;; disabled and this is not a HyWiki page buffer. If this is a
;; HyWiki page buffer, then dehighlight when
;; `hywiki-word-highlight-flag' is nil.
(hywiki-maybe-highlight-wikiwords-in-frame t)))
;;; ************************************************************************
;;; Public Implicit Button and Action Types
;;; ************************************************************************
(defib hywiki-word ()
"When on a non-existing HyWikiWord, create it and display its referent.
If the associated HyWiki referent is a page, create it automatically
unless it is the first HyWiki page to be created, in which case,
prompt the user whether to create it, to prevent any unexpected HyWiki
use.
Existing HyWikiWords are handled by the implicit button type
`hywiki-existing-word'."
(let* ((wikiword-start-end (hywiki-word-at t))
(wikiword (nth 0 wikiword-start-end))
(start (nth 1 wikiword-start-end))
(end (nth 2 wikiword-start-end)))
(when wikiword
(unless (or (ibtypes::pathname-line-and-column)
(ibtypes::pathname))
(ibut:label-set wikiword start end)
(hact 'hywiki-word-create-and-display wikiword)))))
(defun hywiki-display-referent-type (wikiword referent)
"Display WIKIWORD REFERENT, a cons of (<referent-type> . <referent-value>).
Function used to display is \"hywiki-display-<referent-type>\"."
(let* ((referent-type (car referent)) ;; a symbol
(referent-value (cdr referent))
(display-function (intern-soft (concat "hywiki-display-"
(symbol-name referent-type)))))
(when (equal (hywiki-get-singular-wikiword wikiword) (hywiki-word-at-point))
;; Set referent attributes of current implicit button
(hattr:set 'hbut:current 'referent-type referent-type)
(hattr:set 'hbut:current 'referent-value referent-value))
(cond ((fboundp display-function)
(funcall display-function wikiword referent-value))
((symbolp referent-type)
(error "(hywiki-display-referent-type): No hywiki-display function for referent type '%s'" referent-type))
(t
(error "(hywiki-display-referent-type): Referent type must be a symbol, not %s" referent-type)))))
(defun hywiki-display-referent (&optional wikiword prompt-flag)
"Display HyWiki WIKIWORD or a regular file with WIKIWORD nil.
Return the WIKIWORD's referent if successfully found or nil otherwise.
The referent is a cons of (<referent-type> . <referent-value>).
For further details, see documentation for `hywiki-find-referent'.
After successfully finding a page and reading it into a buffer, run
`hywiki-display-referent-hook'."
(let ((in-page-flag (null wikiword))
(in-hywiki-directory-flag (hywiki-in-page-p)))
(if (or (stringp wikiword) in-hywiki-directory-flag)
(progn
(when in-page-flag
;; Current buffer must be the desired page
(unless in-hywiki-directory-flag
(error "(hywiki-display-referent): No `wikiword' given; buffer file must be in `hywiki-directory', not %s"
default-directory))
(unless (hypb:buffer-file-name)
(error "(hywiki-display-referent): No `wikiword' given; buffer must have an attached file"))
(setq wikiword (file-name-sans-extension (file-name-nondirectory (hypb:buffer-file-name)))))
(let* ((_suffix (when (string-match hywiki-word-suffix-regexp wikiword)
(substring wikiword (match-beginning 0))))
(referent (cond (prompt-flag
(hywiki-create-referent wikiword))
((hywiki-get-referent wikiword))
(t (hywiki-add-page wikiword)))))
(if (not referent)
(error "(hywiki-display-referent): Invalid `%s' referent: %s"
wikiword referent)
;; Ensure highlight any page name at point in case called as a
;; Hyperbole action type
(hywiki-maybe-highlight-page-name t)
(hywiki-display-referent-type wikiword referent)
(hywiki-maybe-highlight-page-names)
(run-hooks 'hywiki-display-referent-hook)
referent)))
;; When called without a wikiword and outside hywiki-directory,
;; just find as a regular file and use next line to highlight
;; HyWikiWords only if buffer was not previously highlighted.
(hywiki-maybe-highlight-page-names)
nil)))
;;; ************************************************************************
;;; Public referent menus and utility functions
;;; ************************************************************************
(unless hywiki-referent-menu
(makunbound 'hywiki-referent-menu))
(defcustom hywiki-referent-menu
(delq nil
(list
'("HyWiki Add>")
(when (fboundp #'activities-new)
'("Activity" (hywiki-add-activity hkey-value)
"Add a HyWikiWord that activates a saved activity from the Activities package."))
'("Bookmark" (hywiki-add-bookmark hkey-value)
"Add a HyWikiWord that jumps to an Emacs bookmark.")
'("Command" (hywiki-add-command hkey-value)
"Add a HyWikiWord that runs an Emacs command or Hyperbole action type.")
'("Find" (hywiki-add-find hkey-value)
"Add a HyWikiWord that greps through `hywiki-directory' for its matches.")
;; "<(global explicit button name)>"
;; "<[global implicit button name]>"
'("Gbut" (hywiki-add-global-button hkey-value)
"Add a HyWikiWord that activates a named Hyperbole global button.")
'("HyRolo" (hywiki-add-hyrolo hkey-value)
"Add a HyWikiWord that searches `hyrolo-file-list' for matches.")
;; "(hyperbole)action implicit button"
'("InfoIndex" (hywiki-add-info-index hkey-value)
"Add a HyWikiWord that displays an Info index item.")
;; "{key series}" wikiword
'("Keys" (hywiki-add-key-series hkey-value)
"Add a HyWikiWord that executes a key series.")
'("pathLink" (hywiki-add-path-link hkey-value)
"Add a HyWikiWord that links to a path and possible position.")
;; "(hyperbole)Smart Keys"
'("infoNode" (hywiki-add-info-node hkey-value)
"Add a HyWikiWord that displays an Info node.")
;; "ID: org-id"
'("OrgID" (hywiki-add-org-id hkey-value)
"Add a HyWikiWord that displays an Org section given its Org ID.")
;; "pathname:line:col"
;; "#in-buffer-section"
'("Page" (hywiki-add-page hkey-value)
"Add/Reset a HyWikiWord to link to its standard HyWiki page.")
;; e.g. (kbd "key sequence")
'("orgRoamNode" (hywiki-add-org-roam-node hkey-value)
"Add a HyWikiWord that displays an Org Roam node given its title.")
'("Sexp" (hywiki-add-sexpression hkey-value)
"Add a HyWikiWord that evaluates an Elisp sexpression.")))
"*Menu of HyWikiWord custom referent types of the form:
\(LABEL-STRING ACTION-SEXP DOC-STR)."
:set (lambda (var value) (set-default var value))
:type '(cons (list string) (repeat (list string sexp string)))
:group 'hyperbole-buttons)
(defun hywiki-add-referent (wikiword referent)
"Add WIKIWORD (sans any suffix) that displays REFERENT to HyWiki.
Return REFERENT if WIKIWORD is of valid format, otherwise return nil.
REFERENT must be a cons of (<referent-type> . <referent-value>) or
an error is triggered."
(hywiki-validate-referent referent)
(when (hywiki-word-is-p wikiword)
(when (match-string-no-properties 2 wikiword)
;; Remove any #section suffix in PAGE-NAME.
(setq wikiword (match-string-no-properties 1 wikiword)))
(unless (hash-add referent (hywiki-get-singular-wikiword wikiword)
(hywiki-get-referent-hasht))
(error "(hywiki-add-referent): Failed: (hash-add %s %s %s)"
referent (hywiki-get-singular-wikiword wikiword)
(hywiki-get-referent-hasht)))
(setq hywiki--any-wikiword-regexp-list nil)
(unless (hyperb:stack-frame '(hywiki-maybe-highlight-wikiwords-in-frame))
(hywiki-cache-save))
(run-hooks 'hywiki-add-referent-hook)
referent))
(defun hywiki-create-referent (wikiword &optional message-flag)
"Prompt for, add to HyWiki lookups and return a WIKIWORD custom referent.
With optional prefix arg MESSAGE-FLAG non-nil, display a minibuffer message
with the referent."
(interactive (list nil current-prefix-arg))
(unless (stringp wikiword)
(setq wikiword (hywiki-word-read-new "Create/Edit HyWikiWord: ")))
(setq hkey-value wikiword)
(let ((referent
(hui:menu-act 'hywiki-referent-menu
(list (cons 'hywiki-referent-menu
(cons (list (format "%s RefType>"
(if (string-match hywiki-word-suffix-regexp wikiword)
(substring wikiword 0 (match-beginning 0))
wikiword)))
(cdr hywiki-referent-menu)))))))
(if referent
(when (or message-flag (called-interactively-p 'interactive))
(message "HyWikiWord '%s' referent: %S" wikiword referent))
(user-error "(hywiki-create-referent): Invalid HyWikiWord: '%s'; must be capitalized, all alpha" wikiword))
referent))
;;; ************************************************************************
;;; Public functions
;;; ************************************************************************
(defun hywiki-active-in-current-buffer-p ()
"Return non-nil if HyWiki word links are active in the current buffer.
Exclude the minibuffer if selected and return nil."
(and hywiki-word-highlight-flag
(not (minibuffer-window-active-p (selected-window)))
(not (and (boundp 'edebug-active) edebug-active (active-minibuffer-window)))
(or (derived-mode-p 'kotl-mode)
(not (eq (get major-mode 'mode-class) 'special)))
(not (apply #'derived-mode-p hywiki-exclude-major-modes))
(or hywiki-mode (hywiki-in-page-p))))
(defun hywiki-add-activity (wikiword)
"Make WIKIWORD resume a prompted for activity.
If WIKIWORD is invalid, trigger a `user-error' if called interactively
or return nil if not.
After successfully adding the activity, run `hywiki-add-referent-hook'.
Use `hywiki-get-referent' to determine whether WIKIWORD exists prior to
calling this function."
(interactive (list (or (hywiki-word-at)
(hywiki-word-read-new "Add/Edit HyWikiWord: "))))
(hypb:require-package 'activities)
(let ((activity (activities-completing-read :prompt "Resume activity" :default nil)))
(hywiki-add-referent wikiword (cons 'activity activity))))
(defun hywiki-display-activity (_wikiword activity)
(activities-resume activity :resetp nil))
(defun hywiki-add-bookmark (wikiword)
"Make WIKIWORD display a bookmark and return the action.
If WIKIWORD is invalid, trigger a `user-error' if called interactively
or return nil if not.
After successfully adding the bookmark, run `hywiki-add-referent-hook'.
Use `hywiki-get-referent' to determine whether WIKIWORD exists prior to
calling this function."
(interactive (list (or (hywiki-word-at)
(hywiki-word-read-new "Add/Edit HyWikiWord: "))))
(require 'bookmark)
(let ((bookmark (bookmark-completing-read "Bookmark: "
bookmark-current-bookmark)))
(if (string-empty-p bookmark)
(error "(hywiki-add-bookmark): No bookmark specified")
(hywiki-add-referent wikiword (cons 'bookmark bookmark)))))
(defun hywiki-display-bookmark (_wikiword bookmark)
(let ((loc (bookmark-location bookmark)))
;; Use Hyperbole-specified display location
(cond ((bufferp loc)
(hpath:display-buffer loc))