detect current point at tags position
[org-tag-eldoc.git] / org-tag-eldoc.el
blobb093b63db0c653cee77c09bec1565c9ab625e6e3
1 ;;; org-tag-eldoc.el --- Display tag explanation in Eldoc -*- lexical-binding: t; -*-
2 ;; -*- coding: utf-8 -*-
4 ;; Authors: stardiviner <numbchild@gmail.com>
5 ;; Package-Requires: ((emacs "28.1") (request "0.3.3"))
6 ;; Version: 0.1.0
7 ;; Keywords: text org
8 ;; Homepage: https://repo.or.cz/org-tag-eldoc.git
10 ;; Copyright (C) 2024-2025 Christopher M. Miles, all rights reserved.
12 ;; org-tag-eldoc is free software; you can redistribute it and/or modify it
13 ;; under the terms of the GNU General Public License as published by
14 ;; the Free Software Foundation; either version 3, or (at your option)
15 ;; any later version.
17 ;; org-tag-eldoc is distributed in the hope that it will be useful, but WITHOUT
18 ;; ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
19 ;; or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public
20 ;; License for more details.
22 ;; You should have received a copy of the GNU General Public License
23 ;; along with GNU Emacs. If not, see <https://www.gnu.org/licenses/>.
25 ;;; Commentary:
27 ;;; Display tag explanation in Eldoc when point on tag.
29 ;;; Usage:
30 ;;;
31 ;;; (add-hook 'org-mode-hook #'org-tag-eldoc-setup)
33 ;;; Code:
35 (require 'org)
36 (require 'org-tag-eldoc-common)
37 (require 'org-tag-eldoc-database)
38 (require 'org-tag-eldoc-wikipedia)
39 (require 'org-tag-eldoc-baidu-baike)
40 (require 'org-tag-eldoc-urban-dictionary)
41 (require 'org-tag-eldoc-pixiv-encyclopedia)
42 (require 'org-tag-eldoc-moegirl)
43 (require 'subr-x)
46 (defgroup org-tag-eldoc nil
47 "Customize group of `org-tag-eldoc-mode'."
48 :prefix "org-tag-eldoc-"
49 :group 'org-tags)
51 (defcustom org-tag-eldoc-tag-explanation-functions
52 '(org-tag-eldoc-database-query
53 org-tag-eldoc-wikipedia-query
54 org-tag-eldoc-urban-dictionary-query
55 org-tag-eldoc-baidu-baike-query
56 org-tag-eldoc-moegirl-query
57 org-tag-eldoc-pixiv-encyclopedia-query)
58 "A list of functions to be executed for query tag explanation."
59 :type 'list
60 :safe #'listp
61 :group 'org-tag-eldoc)
63 (defcustom org-tag-eldoc-request-proxy
64 (or url-proxy-services
65 '(("http" . "127.0.0.1:7890")
66 ("https" . "127.0.0.1:7890")))
67 "The proxy services inherited from `url-proxy-services'."
68 :type 'alist
69 :group 'org-tag-eldoc)
71 (defcustom org-tag-eldoc-display-backend 'sideline
72 "The backend for displaying org-tag-eldoc explanation."
73 :type '(choice (symbol :tag "Eldoc" 'eldoc)
74 (symbol :tag "sideline" 'sideline))
75 :safe #'symbolp
76 :group 'org-tag-eldoc)
78 (defcustom org-tag-eldoc-tag-explanations-alist
79 '(("Linux" . "Linux (/ˈlɪnʊks/ LIN-uuks) is a family of open-source Unix-like operating systems based on the Linux kernel, an operating system kernel first released on September 17, 1991, by Linus Torvalds.")
80 ("Emacs" . "Emacs /ˈiːmæks/ ⓘ, originally named EMACS (an acronym for \"Editor Macros\"), is a family of text editors that are characterized by their extensibility. The manual for the most widely used variant, GNU Emacs, describes it as \"the extensible, customizable, self-documenting, real-time display editor\". Development of the first Emacs began in the mid-1970s, and work on GNU Emacs, directly descended from the original, is ongoing; its latest version is 29.2, released January 2024.")
81 ("GNU" . "GNU (/ɡnuː/ ⓘ) is an extensive collection of free software (385 packages as of September 2023), which can be used as an operating system or can be used in parts with other operating systems. The use of the completed GNU tools led to the family of operating systems popularly known as Linux. Most of GNU is licensed under the GNU Project's own General Public License (GPL)."))
82 "Alist of cons cell with tag and explanation."
83 :type 'alist
84 :safe #'listp
85 :group 'org-tag-eldoc)
87 (defcustom org-tag-eldoc-translation nil
88 "Boolean value to toggle translation for explanation."
89 :type 'boolean
90 :safe #'booleanp)
93 (defun org-tag-eldoc-translate (explanation)
94 "Translate EXPLANATION."
95 ;; TODO:
96 (when org-tag-eldoc-translation
98 explanation)
100 (defun org-tag-eldoc--format-explanation (explanation)
101 "Format the EXPLANATION string."
102 ;; prettify display explanation long string.
103 (if explanation
104 (org-tag-eldoc-translate
105 (string-fill
106 (if (string-match-p "\n" explanation) ; if explanation is a large block of paragraphs.
107 explanation
108 ;; if only have single long line with several paragraphs, then break paragraphs into lines.
109 (string-replace ". " ". \n\n" explanation))
110 fill-column))
111 (message "[org-tag-eldoc] `org-tag-eldoc--format-explanation' argument `explanation' is `nil'")))
113 (defun org-tag-eldoc-tag-explanation (&optional tag)
114 "Display tag explanation in Eldoc when point on TAG."
115 (let ((tag (or tag (substring-no-properties (thing-at-point 'symbol)))))
116 (if-let ((explanation (cdr (assoc tag org-tag-eldoc-tag-explanations-alist))))
117 (org-tag-eldoc--format-explanation explanation)
118 (let ((explanation (seq-some
119 (lambda (f)
120 (apply f (list tag))
121 (unless (string-equal org-tag-eldoc--explanation "nil")
122 org-tag-eldoc--explanation))
123 org-tag-eldoc-tag-explanation-functions)))
124 (when explanation
125 ;; cache already queried result explanation into `org-tag-eldoc-tag-explanations-alist'.
126 (add-to-list 'org-tag-eldoc-tag-explanations-alist (cons tag explanation))
127 (org-tag-eldoc--format-explanation explanation))))))
130 (defun org-tag-eldoc-tag-explanation-at-point ()
131 "Get tag explanation at point."
132 ;; NOTE: `org-element-at-point' return `headline' instead of `tags.' Need Org mode to implement it.
133 ;; Use `thing-at-point' to workaround the missing `tags' syntax element node in `org-element-at-point' / `org-context'.
134 (when-let* ((symbol (thing-at-point 'symbol))
135 (tag (substring-no-properties symbol))
136 (tags (org-get-tags nil 'local)))
137 (when (member tag tags) ; detect current point at tags position.
138 (org-tag-eldoc-tag-explanation tag))))
140 (defun org-tag-eldoc-function (&rest args)
141 "The eldoc function to be added into `eldoc-documentation-functions' with ARGS."
142 ;; NOTE: `org-element-at-point' return `headline' instead of `tags.' Need Org mode to implement it.
143 ;; Use `thing-at-point' to workaround the missing `tags' syntax element node in `org-element-at-point' / `org-context'.
144 (let ((explanation (org-tag-eldoc-tag-explanation-at-point)))
145 (cl-case org-tag-eldoc-display-backend
146 (sideline explanation)
147 (quick-peek (quick-peek-show explanation (point) 1)))))
149 (defun org-tag-eldoc-sideline (command)
150 "Display org-tag-eldoc explanation based on COMMAND in sideline.
151 Backend for sideline.
152 Argument COMMAND is required in sideline backend."
153 (cl-case command
154 (`candidates (when (and (derived-mode-p 'org-mode)
155 ;; detect current point at tags position.
156 (member (thing-at-point 'symbol) (org-get-local-tags)))
157 (list (or (org-tag-eldoc-tag-explanation-at-point) "??"))))
158 (`action 'org-tag-eldoc-database-update-row)
159 (`face 'org-tag)
160 (`name "org-tag-eldoc")))
162 (defun org-tag-eldoc-sideline-async (command)
163 "Display org-tag-eldoc explanation based on COMMAND in sideline in async.
164 Backend for sideline.
165 Argument COMMAND is required in sideline backend."
166 (cl-case command
167 (`candidates (cons :async (list (org-tag-eldoc-tag-explanation-at-point))))
168 (`action 'org-tag-eldoc-database-update-row)
169 (`face 'org-tag)
170 (`name "org-tag-eldoc")))
172 ;;;###autoload
173 (defun org-tag-eldoc-enable ()
174 "Enable `org-tag-eldoc-mode'."
175 ;; use `pre-command-hook' to implement another child-frame popup displayer function.
176 (cl-case org-tag-eldoc-display-backend
177 (sideline
178 ;; NOTE: if use `sideline', then `eldoc-mode' is not needed to enable,
179 ;; because `org-tag-eldoc-sideline' do the query tag logic.
180 (add-to-list 'sideline-backends-right 'org-tag-eldoc-sideline 'append) ; `org-tag-eldoc-sideline-async'
181 (sideline-mode 1))
182 (eldoc
183 (eldoc-mode 1)
184 ;; `eldoc-documentation-function', `eldoc-documentation-functions'
185 (add-hook 'eldoc-documentation-functions #'org-tag-eldoc-function -10 t))))
187 ;;;###autoload
188 (defun org-tag-eldoc-disable ()
189 "Disable `org-tag-eldoc-mode'."
190 (eldoc-mode -1)
191 (remove-hook 'eldoc-documentation-functions #'org-tag-eldoc-function)
192 (cl-case org-tag-eldoc-display-backend
193 (sideline (sideline-mode -1))
194 (eldoc (eldoc-mode -1))))
196 ;;;###autoload
197 (define-minor-mode org-tag-eldoc-mode
198 "A minor mode that display Org tag explanation through Eldoc."
199 :init-value nil
200 :lighter nil
201 :group 'org-tag-eldoc
202 :global t
203 (if org-tag-eldoc-mode
204 (org-tag-eldoc-enable)
205 (org-tag-eldoc-disable)))
207 ;;; TODO: Add mouse hover popup info support.
212 (provide 'org-tag-eldoc)
214 ;;; org-tag-eldoc.el ends here