-
Notifications
You must be signed in to change notification settings - Fork 11
/
hywiki.el
2080 lines (1884 loc) · 86.5 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-Apr-24 at 22:41:13
;; Last-Mod: 19-Nov-24 at 00:21:19 by Bob Weiner
;;
;; SPDX-License-Identifier: GPL-3.0-or-later
;;
;; Copyright (C) 2024 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 of 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.
;;
;; 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 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 one implicit button type to Hyperbole:
;; `hywiki-word' - creates and displays HyWikiWord pages;
;; This 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}.
;;; Code:
;;; ************************************************************************
;;; Other required Elisp libraries
;;; ************************************************************************
(require 'cl-lib) ;; For `cl-find'
(require 'hargs)
(require 'hbut) ;; For `hbut:syntax-table'
(require 'hasht)
(require 'hpath)
(require 'hypb) ;; Requires `seq'
(require 'hproperty)
(require 'hsys-consult)
(require 'outline) ;; For `outline-mode-syntax-table'
(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"
(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 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 smart-treemacs-edit "hui-treemacs" (&optional dir))
;;; ************************************************************************
;;; 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-file-suffix ".org"
"File suffix (including period) to use when creating HyWiki pages.")
(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 (lambda (option value)
(set option (file-name-as-directory value))
(hywiki-org-set-publish-project))
:type 'string
:group 'hyperbole-hywiki)
(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 non-nil, 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 "theindex.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.
:makeindex nil
:publishing-function hywiki-org-publishing-function
:publishing-directory hywiki-org-publishing-directory
:section-numbers t
;; sitemap (TOC) is stored in "sitemap.html"
:sitemap-title hywiki-org-publishing-sitemap-title
:with-toc nil)))
(defvar-local hywiki-page-flag nil
"Set to t after a `find-file' of 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'.")
(defconst hywiki-word-regexp
"\\<\\([[:upper:]][[:alpha:]]+\\)\\>"
"Regexp that matches a HyWiki word only.")
(defconst hywiki-word-section-regexp
"\\(#[^][# \t\n\r\f]+\\)"
"Regexp that matches a HyWiki word #section extension.
After the first # character, this may contain any non-square-bracket,
non-# and non-whitespace characters.")
(defconst hywiki-word-with-optional-section-regexp
(concat hywiki-word-regexp hywiki-word-section-regexp "?")
"Regexp that matches a HyWiki word with an optional #section.
Section may not contain whitespace or square brackets. Use '-' to
substitute for spaces in the section/headline name. Grouping 1 is
the HyWiki word and grouping 2 is the #section with the # included.")
(defconst hywiki-word-with-optional-section-exact-regexp
(concat "\\`" hywiki-word-regexp "\\(#[^][\n\r\f]+\\)?\\'")
"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. Grouping 1 is
the HyWiki word and grouping 2 is the #section with the # included.")
(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."
:type 'face
:initialize #'custom-initialize-default
:group 'hyperbole-hywiki)
;;; ************************************************************************
;;; 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.")
(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--pages-hasht nil)
;; Globally set these values to avoid using 'let' with stack allocations
;; within `hywiki-maybe-highlight-page-name' frequently.
(defvar hywiki--any-page-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--highlighting-done-flag t)
(defvar hywiki--page-name nil)
(defvar hywiki--range nil)
(defvar hywiki--save-case-fold-search nil)
(defvar hywiki--save-org-link-type-required nil)
(defvar hywiki--start nil)
;;; ************************************************************************
;;; hywiki minor mode
;;; ************************************************************************
(defun hywiki-buttonize-character-commands ()
"Turn any HyWikiWords between point into highlighted Hyperbole buttons.
Triggered by `post-self-insert-hook' for self-inserting characters.
Highlight after inserting any non-word character."
(hywiki-maybe-highlight-between-page-names))
(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'."
(when (or (memq this-command hywiki-non-character-commands)
(and (symbolp this-command)
(string-match-p "^\\(org-\\)?delete-\\|insert\\(-\\|$\\)" (symbol-name this-command))))
(if (and (marker-position hywiki--buttonize-start)
(marker-position hywiki--buttonize-end))
(hywiki-maybe-highlight-page-names
hywiki--buttonize-start hywiki--buttonize-end)
(hywiki-maybe-highlight-between-page-names))
(set-marker hywiki--buttonize-start nil)
(set-marker hywiki--buttonize-end nil)))
(defun hywiki-debuttonize-non-character-commands ()
"Dehighlight any HyWikiWord before or after point.
Triggered by `pre-command-hook' for non-character-commands, including
deletion commands and those in `hywiki-non-character-commands'."
(when (or (memq this-command hywiki-non-character-commands)
(and (symbolp this-command)
(string-match-p "\\`\\(org-\\)?delete-" (symbol-name this-command))))
(cl-destructuring-bind (start end)
(hywiki-get-delimited-range)
;; Use these to store any range of a delimited HyWikiWord#section
(set-marker hywiki--buttonize-start start)
(set-marker hywiki--buttonize-end end)
;; Enable dehighlighting in HyWiki pages
(if (and start end)
(hywiki-maybe-dehighlight-page-names hywiki--buttonize-start
hywiki--buttonize-end)
;; Dehighlight any page name at point
(hywiki-maybe-dehighlight-between-page-names)))))
(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)
(= (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)))))))))))
;;;###autoload
(define-minor-mode hywiki-mode
"Toggle HyWiki global minor mode with \\[hywiki-mode].
The hywiki-mode minor mode auto-highlights and creates implicit
buttons from wiki words. Any such button jumps to the associated
HyWiki page or associated section when HyWikiWord#section is used.
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-page-names-in-frame'
(set-variable 'hywiki-word-highlight-flag t))
;; 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-page-names-in-frame t)))
;;; ************************************************************************
;;; Public Implicit Button and Action Types
;;; ************************************************************************
(defib hywiki-word ()
"When on a HyWiki word, display its page and optional section.
If the associated HyWiki page does not exist, create it automatically."
(let ((page-name (hywiki-word-at)))
(when page-name
(ibut:label-set page-name (match-beginning 0) (match-end 0))
(hact 'hywiki-find-page page-name))))
;;;###autoload
(defun hywiki-find-page (&optional page-name prompt-flag)
"Display HyWiki PAGE-NAME or a regular file with PAGE-NAME nil.
Return the absolute path to any page successfully found; nil if
failed or if displaying a regular file (read in via a `find-file'
call).
By default, create any non-existent page. When not in batch mode,
with optional PROMPT-FLAG t or if this is the first HyWiki page in
`hywiki-directory', prompt to create if non-existent. If
PROMPT-FLAG is :existing or with a prefix argument when called
interactively, return nil unless the page already exists. After
successfully finding a page and reading it into a buffer, run
`hywiki-find-page-hook'."
(interactive (list (if current-prefix-arg
(hywiki-read-page-name "Find existing HyWiki page: ")
(hywiki-read-new-page-name "Find HyWiki page: "))))
(let ((in-page-flag (null page-name))
(in-hywiki-directory-flag (hywiki-in-page-p)))
(if (or (stringp page-name) in-hywiki-directory-flag)
(progn
(when in-page-flag
;; Current buffer must be the desired page
(unless in-hywiki-directory-flag
(error "(hywiki-find-page): No `page-name' given; buffer file must be in `hywiki-directory', not %s"
default-directory))
(when (null buffer-file-name)
(error "(hywiki-find-page): No `page-name' given; buffer must have an attached file"))
(setq page-name (file-name-sans-extension (file-name-nondirectory buffer-file-name))))
(let* ((section (when (string-match "#" page-name)
(substring page-name (match-beginning 0))))
(page-name (if (string-match "#" page-name)
(substring page-name 0 (match-beginning 0))
page-name))
(page-file (or (hywiki-get-page page-name)
(hywiki-add-page page-name prompt-flag))))
(when page-file
;; Ensure highlight any page name at point in case called as a
;; Hyperbole action type
(hywiki-maybe-highlight-page-name t)
(unless in-page-flag (hpath:find (concat page-file section)))
(hywiki-maybe-highlight-page-names)
(run-hooks 'hywiki-find-page-hook)
page-file)))
;; When called without a page-name 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))))
;;; ************************************************************************
;;; 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)))
(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))))
;;;###autoload
(defun hywiki-add-link ()
"Insert at point a link to a HyWiki page."
(interactive "*")
(insert (hywiki-read-page-name "Link to HyWiki page: "))
(hywiki-maybe-highlight-page-name))
(defun hywiki-add-page (page-name &optional prompt-flag)
"Add or edit the HyWiki page for PAGE-NAME and return its file.
If file exists already, just return it. If PAGE-NAME is invalid,
trigger a `user-error' if called interactively or return nil if
not.
By default, create any non-existent page. When not in batch mode,
with optional PROMPT-FLAG t or if this is the first HyWiki page in
`hywiki-directory', prompt to create if non-existent. If
PROMPT-FLAG is :existing or with a prefix argument when called
interactively, return nil unless the page already exists. After
successfully adding a page, run `hywiki-add-page-hook'.
Use `hywiki-get-page' to determine whether a HyWiki page exists."
(interactive (list (hywiki-read-new-page-name "Add/Edit HyWiki page: ")
current-prefix-arg))
(if (hywiki-word-is-p page-name)
(unless (or (eq prompt-flag :existing)
(and prompt-flag (null noninteractive)
(not (y-or-n-p (concat "Create new HyWiki page `" page-name "'? ")))))
(when (match-string-no-properties 2 page-name)
;; Remove any #section suffix in PAGE-NAME.
(setq page-name (match-string-no-properties 1 page-name)))
(let* ((page-file (hywiki-get-file page-name))
(page-file-readable (file-readable-p page-file))
(pages-hasht (hywiki-get-page-hasht))
(page-in-hasht (hywiki-get-page page-name)))
(unless page-file-readable
(write-region "" nil page-file nil 0))
(unless page-in-hasht
(hash-add page-file page-name pages-hasht)
(setq hywiki--any-page-regexp-list nil))
(unless (or (hyperb:stack-frame '(hywiki-maybe-highlight-page-names-in-frame))
(and page-file-readable page-in-hasht))
(hywiki-directory-set-mod-time)
(hywiki-directory-set-checksum))
(run-hooks 'hywiki-add-page-hook)
page-file))
(when (called-interactively-p 'interactive)
(user-error "(hywiki-add-page): Invalid page name: '%s'; must be capitalized, all alpha" page-name))))
(defun hywiki-add-page-and-display (page-name)
"Add and display the HyWiki page for PAGE-NAME and return its file.
If file exists already, just return it. If PAGE-NAME is invalid,
trigger a `user-error'.
Use `hywiki-get-page' to determine whether a HyWiki page exists."
(interactive (list (hywiki-read-new-page-name "Add and display HyWiki page: ")))
(let ((page-file (hywiki-add-page page-name)))
(if page-file
(hywiki-find-page (file-name-base page-file))
(user-error "(hywiki-add-page-and-display): Invalid page name: '%s'; must be capitalized, all alpha" page-name))))
(defun hywiki-add-to-page (page-name text start-flag)
"Add to PAGE-NAME TEXT at page start with START-FLAG non-nil, else end.
Create page if it does not exist. If PAGE-NAME is invalid, return
nil, else return the file name of the page."
(let* ((page-file (hywiki-add-page page-name))
(page-buf (when page-file (find-file-noselect page-file))))
(when page-buf
(save-excursion
(with-current-buffer page-buf
(barf-if-buffer-read-only)
(save-restriction
(widen)
(goto-char (if start-flag (point-min) (point-max)))
(unless (bolp) (insert (newline)))
(insert text)
(unless (bolp) (insert (newline)))
(goto-char (if start-flag (point-min) (point-max)))
page-file))))))
(defun hywiki-at-tags-p (&optional at-tag-flag)
"Return non-nil if point is in a HyWiki buffer and at Org tags."
(and (or at-tag-flag (hsys-org-at-tags-p))
(or (hywiki-in-page-p) (string-prefix-p "*HyWiki Tags*" (buffer-name)))))
;;;###autoload
(defun hywiki-consult-grep (&optional regexp max-matches path-list)
"Interactively search `hywiki-directory' with a consult package grep command.
Search for optional REGEXP up to MAX-MATCHES in PATH-LIST or `hywiki-directory'.
Use ripgrep (rg) if found, otherwise, plain grep. Initialize search with
optional REGEXP and interactively prompt for changes. Limit matches
per file to the absolute value of MAX-MATCHES, if given and not 0. If
0, match to headlines only (lines that start with a '^[*#]+[ \t]+' regexp)."
(interactive "i\nP")
(let* ((grep-includes "--include *.org")
(ripgrep-globs "--glob *.org"))
(hsys-consult-grep grep-includes ripgrep-globs
regexp max-matches (or path-list (list hywiki-directory)))))
(defun hywiki-convert-words-to-org-links ()
"Convert all highlighted HyWiki words in current buffer to Org links."
(let ((make-index (hywiki-org-get-publish-property :makeindex))
wiki-word)
(hywiki-map-words (lambda (overlay)
(goto-char (overlay-end overlay))
(if make-index
(progn
(setq wiki-word (buffer-substring-no-properties
(overlay-start overlay)
(overlay-end overlay)))
(when (string-match (concat hywiki-org-link-type ":")
wiki-word)
(setq wiki-word (substring wiki-word (match-end 0))))
(insert "]]\n#+INDEX: " wiki-word "\n"))
(insert "]]"))
(goto-char (overlay-start overlay))
(if (looking-at (concat hywiki-org-link-type ":"))
(insert "[[")
(insert "[[" hywiki-org-link-type ":"))
(delete-overlay overlay)))))
(defun hywiki-maybe-at-wikiword-beginning ()
"Return non-nil if previous character is one preceding a HyWiki word.
Do not test whether or not a page exists for the HyWiki word.
Use `hywiki-get-page' to determine whether a HyWiki page exists."
;; Ignore wikiwords preceded by any non-whitespace character, except
;; any of these: [({<"'`'
(when (or (bolp) (cl-find (char-before) "\[\(\{\<\"'`\t\n\r\f "))
t))
(defun hywiki-word-activate (&optional arg)
"Display HyWiki page for wiki word at point, creating the page if needed.
If found, return the full path of the page.
If on a HyWikiWord without a wiki page, then prompt before creating
the page.
If not on a HyWikiWord and optional prefix ARG is null, emulate an
Action Key press; with a prefix ARG, emulate an Assist Key press."
(interactive "P")
(let ((word (hywiki-word-at)))
(if word
(hywiki-find-page word t)
(hkey-either arg))))
(defun hywiki-word-at ()
"Return HyWikiWord and optional #section at point or nil if not on one.
Point must be prior to any whitespace character within #section.
Return nil if the HyWikiWord is a prefixed, typed hy:HyWikiWord, since
these are handled by the Org mode link handler.
Do not test whether or not a page exists for the HyWiki word; call
`hywiki-page-exists-p' without an argument for that.
A call to `hywiki-active-in-current-buffer-p' at point must return non-nil
or this will return nil."
(when (hywiki-active-in-current-buffer-p)
(if (setq hywiki--range
(hproperty:char-property-range (point) 'face hywiki-word-face))
(buffer-substring-no-properties (car hywiki--range) (cdr hywiki--range))
(save-excursion
(let ((wikiword (progn (when (looking-at "\\[\\[")
(goto-char (+ (point) 2)))
(hargs:delimited "[[" "]]"))))
(if wikiword
;; Handle an Org link [[HyWikiWord]] [[hy:HyWikiWord]]
;; or [[HyWikiWord#section][Description Text]].
(progn
;; Get the HyWikiWord link reference, ignoring any
;; description given in the link
(setq wikiword (hywiki-strip-org-link wikiword))
(if (string-match (concat "\\`" hywiki-org-link-type ":") wikiword)
;; Ignore prefixed, typed hy:HyWikiWord since Org mode will
;; display those.
nil
;; Don't use next line so don't have to load all of Org
;; mode just to check for HyWikiWords; however, disables
;; support for Org mode aliases.
;; (setq wikiword (org-link-expand-abbrev (org-link-unescape (string-trim wikiword))))
(when (hywiki-word-is-p wikiword)
wikiword)))
;; Handle a HyWiki word with optional #section; if it is an Org
;; link, it may optionally have a hy: link-type prefix.
;; Ignore wikiwords preceded by any non-whitespace
;; character, except any of these: "([\"'`'"
(let ((case-fold-search nil)
start
end)
(skip-chars-backward "-_*#[:alnum:]")
(when (hywiki-maybe-at-wikiword-beginning)
(cond ((looking-at hywiki--word-and-buttonize-character-regexp)
(setq start (match-beginning 0)
end (match-beginning 3)
wikiword (string-trim
(buffer-substring-no-properties start end))))
((looking-at (concat hywiki-word-with-optional-section-regexp "\\'"))
(setq start (match-beginning 0)
end (match-end 0)
;; No following char
wikiword (string-trim
(buffer-substring-no-properties start end)))))
wikiword))))))))
;;;###autoload
(defun hywiki-word-consult-grep (word)
"Use `hywiki-consult-grep' to show occurrences of a prompted for HyWikiWord.
Default to any HyWikiWord at point."
(interactive (list (hywiki-read-page-name)))
(if (and (stringp word) (not (string-empty-p word)))
(hywiki-consult-grep (concat "\\b" (regexp-quote word) "\\b"))
(user-error "(hywiki-word-consult-grep): Invalid HyWikiWord: '%s'; must be capitalized, all alpha" word)))
(defun hywiki-word-is-p (word)
"Return non-nil if WORD is a HyWiki word and optional #section.
The page for the word may not yet exist. Use `hywiki-get-page'
to determine whether a HyWiki word page exists.
Return nil if WORD is a prefixed, typed hy:HyWikiWord, since
these are handled by the Org mode link handler."
(and (stringp word) (not (string-empty-p word))
(let (case-fold-search)
(or (string-match hywiki-word-with-optional-section-exact-regexp word)
(eq (string-match (concat "\\`" hywiki-word-with-optional-section-regexp "\\'") word)
0)))))
(defun hywiki-directory-edit ()
"Edit HyWiki pages in current `hywiki-directory'.
Use `dired' unless `action-key-modeline-buffer-id-function' is set to
`smart-treemacs-modeline', then use `treemacs'."
(interactive)
(if (eq action-key-modeline-buffer-id-function #'smart-treemacs-modeline)
(hywiki-directory-treemacs-edit)
(hywiki-directory-dired-edit)))
(defun hywiki-directory-dired-edit ()
"Use `dired' to edit HyWiki pages in current `hywiki-directory'."
(interactive)
(let ((case-fold-search nil)
(shell-name (or shell-file-name "")))
(if (string-match-p "bash\\(\\.exe\\)?$" shell-name)
(dired (concat hywiki-directory
"[[:upper:]][[:alpha:]]*"
(regexp-quote hywiki-file-suffix)))
(dired (cons hywiki-directory
(directory-files hywiki-directory nil
(format "^[A-Z][A-Za-z]*%s$"
(regexp-quote hywiki-file-suffix))))))))
(defun hywiki-directory-treemacs-edit ()
"Use `treemacs' to edit HyWiki pages in current `hywiki-directory'."
(interactive)
(require 'hui-treemacs)
(smart-treemacs-edit hywiki-directory))
(defun hywiki-directory-get-checksum ()
"Compute and return the checksum for the current set of HyWiki pages."
(let ((hywiki-page-files (hywiki-get-page-files)))
(when hywiki-page-files
(md5 (apply #'concat hywiki-page-files) nil nil nil t))))
(defun hywiki-directory-get-mod-time ()
"Return the last mod time for `hywiki-directory' or nil."
(when (file-readable-p hywiki-directory)
(time-convert (file-attribute-modification-time
(file-attributes hywiki-directory))
'list)))
(defun hywiki-directory-modified-p ()
"Return non-nil if any HyWiki page name change since last read."
(or (null hywiki--directory-mod-time)
;; Both dir mod-time and filename checksum over HyWiki page
;; files must have changed for this to be an update to report.
;; Don't change this logic as many other dir changes can occur
;; that should not be reported here.
(not (or (equal hywiki--directory-mod-time (hywiki-directory-get-mod-time))
(string-equal hywiki--directory-checksum (hywiki-directory-get-checksum))))))
(defun hywiki-directory-set-checksum ()
"Store the last page name checksum for `hywiki-directory' as a string."
(setq hywiki--directory-checksum (hywiki-directory-get-checksum)))
(defun hywiki-directory-set-mod-time ()
"Store the last page mod time for `hywiki-directory' as an integer."
(setq hywiki--directory-mod-time (hywiki-directory-get-mod-time)))
(defun hywiki-highlight-on-yank (_prop-value start end)
"Used in `yank-handled-properties' called with START and END pos of the text.
Have to add one character to the length of the yanked text so that any
needed word-separator after the last character is included to induce
highlighting any last HyWikiWord."
(hywiki-maybe-highlight-page-names start (min (1+ end) (point-max))))
(defun hywiki-map-words (func)
"Apply FUNC across all HyWikiWords in the current buffer and return nil.
FUNC takes 1 argument, the start and end buffer positions of each word
and its option #section."
(save-excursion
(mapc (lambda (overlay)
(when (eq (overlay-get overlay 'face) hywiki-word-face)
(funcall func overlay)))
(overlays-in (point-min) (point-max)))
nil))
(defun hywiki-get-delimited-range ()
"Before or after a balanced delimiter, return the delimited range list.
If no such range, return \\='(nil nil).
This includes the delimiters: (), {}, <>, [] and \"\" (double quotes)."
(save-excursion
(save-restriction
;; Limit balanced pair checks to the next two lines for speed
(narrow-to-region (line-beginning-position) (line-end-position 2))
(let ((result (ignore-errors
(cond ((memq (char-before) '(?\[ ?\<))
(goto-char (1- (point)))
(hywiki--get-delimited-range-forward))
((memq (char-after) '(?\[ ?\<))
(hywiki--get-delimited-range-forward))
((memq (char-before) '(?\( ?\{))
(goto-char (1- (point)))
(list (point) (scan-sexps (point) 1)))
((memq (char-after) '(?\( ?\{))
(list (point) (scan-sexps (point) 1)))
((and (eq (char-before) ?\")
(hypb:in-string-p))
(goto-char (1- (point)))
(list (point) (scan-sexps (point) 1)))
((and (eq (char-after) ?\")
(hypb:in-string-p))
(goto-char (1+ (point)))
(list (point) (scan-sexps (point) -1)))
((memq (char-before) '(?\] ?\>))
(hywiki--get-delimited-range-backward))
((memq (char-after) '(?\] ?\>))
(goto-char (1+ (point)))
(hywiki--get-delimited-range-backward))
((memq (char-before) '(?\) ?\}))
(list (point) (scan-sexps (point) -1)))
((memq (char-after) '(?\) ?\}))
(goto-char (1+ (point)))
(list (point) (scan-sexps (point) -1)))
((and (eq (char-before) ?\")
(not (hypb:in-string-p)))
(list (point) (scan-sexps (point) -1)))
((and (eq (char-after) ?\")
(not (hypb:in-string-p)))
(list (point) (scan-sexps (point) 1)))))))
(if result
(sort result #'<)
(list nil nil))))))
(defun hywiki-maybe-dehighlight-balanced-pairs ()
"Before or after a balanced delimiter, dehighlight HyWikiWords within.
Include: (), {}, <>, [] and \"\" (double quotes). Exclude Org links
and radio targets.
Ignore return value; it has no meaning."
(save-excursion
(save-restriction
(if (and (marker-position hywiki--buttonize-start)
(marker-position hywiki--buttonize-end))
(narrow-to-region hywiki--buttonize-start hywiki--buttonize-end)
;; Limit balanced pair checks to the next two lines for speed
(narrow-to-region (line-beginning-position) (line-end-position 2)))
;; char-before
(ignore-errors
(cond ((memq (char-before) '(?\[ ?\<))
(goto-char (1- (point)))
;; Dehighlight HyWikiWords within opening square or angle brackets
(hywiki-maybe-dehighlight-org-element-forward))
((memq (char-before) '(?\( ?\{))
;; Dehighlight HyWikiWords within opening parens or braces
(goto-char (1- (point)))
(hywiki-maybe-dehighlight-sexp 1))
((and (eq (char-before) ?\")
(hypb:in-string-p))
;; Dehighlight HyWikiWords in any string following point
(goto-char (1- (point)))
(hywiki-maybe-dehighlight-sexp 1))
((memq (char-before) '(?\] ?\>))
;; Dehighlight HyWikiWords within closing square or angle brackets
(hywiki-maybe-dehighlight-org-element-backward))
((memq (char-before) '(?\) ?\}))
;; Dehighlight HyWikiWords within closing parens or braces
(hywiki-maybe-dehighlight-sexp -1))
((and (eq (char-before) ?\")
(not (hypb:in-string-p)))
;; Dehighlight HyWikiWords in any string preceding point