org-tag-eldoc.el

   1 ;;; org-tag-eldoc.el --- Display tag explanation in Eldoc -*- lexical-binding: t; -*-
   2 ;; -*- coding: utf-8 -*-
   3
   4 ;; Authors: stardiviner <numbchild@gmail.com>
   5 ;; Package-Requires: ((emacs "28.1") (request "0.3.3"))
   6 ;; Version: 0.1.0
   7 ;; Keywords: org
   8 ;; Homepage: https://repo.or.cz/org-tag-eldoc.git
   9
  10 ;; Copyright (C) 2024-2025 Christopher M. Miles, all rights reserved.
  11 ;;
  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.
  16 ;;
  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.
  21 ;;
  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/>.
  24
  25 ;;; Commentary:
  26
  27 ;;; Display tag explanation in Eldoc when point on tag.
  28
  29 ;;; Usage:
  30 ;;;
  31 ;;; (add-hook 'org-mode-hook #'org-tag-eldoc-setup)
  32
  33 ;;; Code:
  34 \f
  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)
  44
  45
  46 (defgroup org-tag-eldoc nil
  47   "Customize group of `org-tag-eldoc-mode'."
  48   :prefix "org-tag-eldoc-"
  49   :group 'org-tags)
  50
  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)
  62
  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)
  70
  71 (defcustom org-tag-eldoc-tag-explanations-alist
  72   '(("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.")
  73     ("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.")
  74     ("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)."))
  75   "Alist of cons cell with tag and explanation."
  76   :type 'alist
  77   :safe #'listp
  78   :group 'org-tag-eldoc)
  79
  80 (defcustom org-tag-eldoc-translation nil
  81   "Boolean value to toggle translation for explanation."
  82   :type 'boolean
  83   :safe #'booleanp)
  84
  85
  86 (defun org-tag-eldoc-translate (explanation)
  87   "Translate EXPLANATION."
  88   ;; TODO:
  89   (when org-tag-eldoc-translation
  90     )
  91   explanation)
  92
  93 (defun org-tag-eldoc--format-explanation (explanation)
  94   "Format the EXPLANATION string."
  95   ;; prettify display explanation long string.
  96   (if explanation
  97       (org-tag-eldoc-translate
  98        (string-fill
  99         (if (string-match-p "\n" explanation) ; if explanation is a large block of paragraphs.
 100             explanation
 101           ;; if only have single long line with several paragraphs, then break paragraphs into lines.
 102           (string-replace ". " ". \n\n" explanation))
 103         fill-column))
 104     (message "[org-tag-eldoc] `org-tag-eldoc--format-explanation' argument `explanation' is `nil'")))
 105
 106 (defun org-tag-eldoc-tag-explanation (&optional tag)
 107   "Display tag explanation in Eldoc when point on TAG."
 108   (let ((tag (or tag (substring-no-properties (thing-at-point 'symbol)))))
 109     (if-let ((explanation (cdr (assoc tag org-tag-eldoc-tag-explanations-alist))))
 110         (org-tag-eldoc--format-explanation explanation)
 111       (let ((explanation (seq-some
 112                           (lambda (f)
 113                             ;; reset `org-tag-eldoc--explanation' to avoid bellowing `seq-some' chaos.
 114                             (setq org-tag-eldoc--explanation nil)
 115                             (apply f (list tag))
 116                             (unless (string-equal org-tag-eldoc--explanation "nil")
 117                               org-tag-eldoc--explanation))
 118                           org-tag-eldoc-tag-explanation-functions)))
 119         ;; cache already queried result explanation into `org-tag-eldoc-tag-explanations-alist'.
 120         (if explanation
 121             (progn
 122               (add-to-list 'org-tag-eldoc-tag-explanations-alist (cons tag explanation))
 123               (org-tag-eldoc--format-explanation explanation))
 124           (error "[org-tag-eldoc] Still no `explanation' after backends from `org-tag-eldoc-tag-explanation-functions'"))))))
 125
 126 (defun org-tag-eldoc-function (&rest args)
 127   "The eldoc function to be added into `eldoc-documentation-functions' with ARGS."
 128   ;; NOTE: `org-element-at-point' return `headline' instead of `tags.' Need Org mode to implement it.
 129   ;; Use `thing-at-point' to workaround the missing `tags' syntax element node in `org-element-at-point' / `org-context'.
 130   (when-let* ((symbol (thing-at-point 'symbol))
 131               (tag (substring-no-properties symbol))
 132               (tags (org-get-tags nil 'local)))
 133     (when (member tag tags)
 134       (org-tag-eldoc-tag-explanation tag))))
 135
 136 ;;; `eldoc-documentation-function', `eldoc-documentation-functions'
 137 ;;;###autoload
 138 (defun org-tag-eldoc-setup ()
 139   "Setup `eldoc-documentation-functions'."
 140   (eldoc-mode t)
 141   (add-hook 'eldoc-documentation-functions #'org-tag-eldoc-function -10 t))
 142
 143 ;;;###autoload
 144 (defun org-tag-eldoc-enable ()
 145   "Enable `org-tag-eldoc-mode'."
 146   (add-hook 'org-mode-hook #'org-tag-eldoc-setup 100))
 147
 148 ;;;###autoload
 149 (defun org-tag-eldoc-disable ()
 150   "Disable `org-tag-eldoc-mode'."
 151   (remove-hook 'org-mode-hook #'org-tag-eldoc-setup))
 152
 153 ;;;###autoload
 154 (define-minor-mode org-tag-eldoc-mode
 155   "A minor mode that display Org tag explanation through Eldoc."
 156   :init-value nil
 157   :lighter nil
 158   :group 'org-tag-eldoc
 159   :global t
 160   (if org-tag-eldoc-mode
 161       (org-tag-eldoc-enable)
 162     (org-tag-eldoc-disable)))
 163
 164 ;;; TODO: Add mouse hover popup info support.
 165
 166
 167 \f
 168
 169 (provide 'org-tag-eldoc)
 170
 171 ;;; org-tag-eldoc.el ends here