lisp/net/quickurl.el

   1 ;;; quickurl.el --- insert a URL based on text at point in buffer
   2
   3 ;; Copyright (C) 1999-2017 Free Software Foundation, Inc.
   4
   5 ;; Author: Dave Pearson <davep@davep.org>
   6 ;; Maintainer: Dave Pearson <davep@davep.org>
   7 ;; Created: 1999-05-28
   8 ;; Keywords: hypermedia
   9
  10 ;; This file is part of GNU Emacs.
  11
  12 ;; GNU Emacs is free software: you can redistribute it and/or modify
  13 ;; it under the terms of the GNU General Public License as published by
  14 ;; the Free Software Foundation, either version 3 of the License, or
  15 ;; (at your option) any later version.
  16
  17 ;; GNU Emacs is distributed in the hope that it will be useful,
  18 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  19 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  20 ;; GNU General Public 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 <http://www.gnu.org/licenses/>.
  24
  25 ;;; Commentary:
  26 ;;
  27 ;; This package provides a simple method of inserting a URL based on the
  28 ;; text at point in the current buffer. This is part of an on-going effort
  29 ;; to increase the information I provide people while reducing the amount
  30 ;; of typing I need to do. No-doubt there are undiscovered Emacs packages
  31 ;; out there that do all of this and do it better, feel free to point me to
  32 ;; them, in the mean time I'm having fun playing with Emacs Lisp.
  33 ;;
  34 ;; The URLs are stored in an external file as a list of either cons cells,
  35 ;; or lists. A cons cell entry looks like this:
  36 ;;
  37 ;;    (<Lookup> . <URL>)
  38 ;;
  39 ;; where <Lookup> is a string that acts as the keyword lookup and <URL> is
  40 ;; the URL associated with it. An example might be:
  41 ;;
  42 ;;    ("GNU" . "http://www.gnu.org/")
  43 ;;
  44 ;; A list entry looks like:
  45 ;;
  46 ;;    (<Lookup> <URL> <Comment>)
  47 ;;
  48 ;; where <Lookup> and <URL> are the same as with the cons cell and <Comment>
  49 ;; is any text you like that describes the URL. This description will be
  50 ;; used when presenting a list of URLS using `quickurl-list'. An example
  51 ;; might be:
  52 ;;
  53 ;;    ("FSF" "http://www.fsf.org/" "The Free Software Foundation")
  54 ;;
  55 ;; Given the above, your quickurl file might look like:
  56 ;;
  57 ;; (("GNU"    . "http://www.gnu.org/")
  58 ;;  ("FSF"      "http://www.fsf.org/" "The Free Software Foundation")
  59 ;;  ("emacs"  . "http://www.emacs.org/")
  60 ;;  ("davep"    "http://www.davep.org/" "Dave's homepage"))
  61 ;;
  62 ;; In case you're wondering about the mixture of cons cells and lists,
  63 ;; quickurl started life using just the cons cells, there were no comments.
  64 ;; URL comments are a later addition and so there is a mixture to keep
  65 ;; backward compatibility with existing URL lists.
  66 ;;
  67 ;; The name and location of the file is up to you, the default name used by
  68 ;; `quickurl' is stored in `quickurl-url-file'.
  69 ;;
  70 ;; quickurl is always available from:
  71 ;;
  72 ;;   <URL:http://www.davep.org/emacs/quickurl.el>
  73
  74 ;;; TODO:
  75 ;;
  76 ;; o The quickurl-browse-url* functions pretty much duplicate their non
  77 ;;   browsing friends. It would feel better if a more generic solution could
  78 ;;   be found.
  79
  80 ;;; Code:
  81
  82 ;; Things we need:
  83
  84 (eval-when-compile (require 'cl-lib))
  85 (require 'thingatpt)
  86 (require 'pp)
  87 (require 'browse-url)
  88
  89 ;; Customize options.
  90
  91 (defgroup quickurl nil
  92   "Insert a URL based on text at point in buffer."
  93   :version "21.1"
  94   :group  'abbrev
  95   :prefix "quickurl-")
  96
  97 (defcustom quickurl-url-file
  98   (locate-user-emacs-file "quickurls" ".quickurls")
  99   "File that contains the URL list."
 100   :version "24.4"                       ; added locate-user-emacs-file
 101   :type  'file
 102   :group 'quickurl)
 103
 104 (defcustom quickurl-format-function #'quickurl-format-url
 105   "Function to format the URL before insertion into the current buffer."
 106   :type  'function
 107   :group 'quickurl)
 108
 109 (defcustom quickurl-sort-function #'quickurl-sort-urls
 110   "Function to sort the URL list."
 111   :type  'function
 112   :group 'quickurl)
 113
 114 (defcustom quickurl-grab-lookup-function #'current-word
 115   "Function to grab the thing to lookup."
 116   :type  'function
 117   :group 'quickurl)
 118
 119 (defcustom quickurl-assoc-function #'assoc-ignore-case
 120   "Function to use for alist lookup into `quickurl-urls'."
 121   :type  'function
 122   :group 'quickurl)
 123
 124 (defcustom quickurl-completion-ignore-case t
 125   "Should `quickurl-ask' ignore case when doing the input lookup?"
 126   :type  'boolean
 127   :group 'quickurl)
 128
 129 (defcustom quickurl-prefix ";; -*- lisp -*-\n\n"
 130   "Text to write to `quickurl-url-file' before writing the URL list."
 131   :type  'string
 132   :group 'quickurl)
 133
 134 (defcustom quickurl-postfix ""
 135   "Text to write to `quickurl-url-file' after writing the URL list.
 136
 137 See the constant `quickurl-reread-hook-postfix' for some example text that
 138 could be used here."
 139   :type  'string
 140   :group 'quickurl)
 141
 142 (defcustom quickurl-list-mode-hook nil
 143   "Hooks for `quickurl-list-mode'."
 144   :type  'hook
 145   :group 'quickurl)
 146
 147 ;; Constants.
 148
 149 ;;;###autoload
 150 (defconst quickurl-reread-hook-postfix
 151     "
 152 ;; Local Variables:
 153 ;; eval: (progn (require 'quickurl) (add-hook 'local-write-file-hooks (lambda () (quickurl-read) nil)))
 154 ;; End:
 155 "
 156   "Example `quickurl-postfix' text that adds a local variable to the
 157 `quickurl-url-file' so that if you edit it by hand it will ensure that
 158 `quickurl-urls' is updated with the new URL list.
 159
 160 To make use of this do something like:
 161
 162   (setq quickurl-postfix quickurl-reread-hook-postfix)
 163
 164 in your init file (after loading/requiring quickurl).")
 165
 166 ;; Non-customize variables.
 167
 168 (defvar quickurl-urls nil
 169   "URL alist for use with `quickurl' and `quickurl-ask'.")
 170
 171 (defvar quickurl-list-mode-map
 172   (let ((map (make-sparse-keymap)))
 173     (define-key map "a"           #'quickurl-list-add-url)
 174     (define-key map [(control m)] #'quickurl-list-insert-url)
 175     (define-key map "u"           #'quickurl-list-insert-naked-url)
 176     (define-key map " "           #'quickurl-list-insert-with-lookup)
 177     (define-key map "l"           #'quickurl-list-insert-lookup)
 178     (define-key map "d"           #'quickurl-list-insert-with-desc)
 179     (define-key map [(control g)] #'quickurl-list-quit)
 180     (define-key map "q"           #'quickurl-list-quit)
 181     (define-key map [mouse-2]     #'quickurl-list-mouse-select)
 182     map)
 183   "Local keymap for a `quickurl-list-mode' buffer.")
 184
 185 (defvar quickurl-list-buffer-name "*quickurl-list*"
 186   "Name for the URL listing buffer.")
 187
 188 (defvar quickurl-list-last-buffer nil
 189   "`current-buffer' when `quickurl-list' was called.")
 190
 191 ;; Functions for working with a URL entry.
 192
 193 (defun quickurl-url-commented-p (url)
 194   "Does the URL have a comment?"
 195   (listp (cdr url)))
 196
 197 (defun quickurl-make-url (keyword url &optional comment)
 198   "Create a URL from KEYWORD, URL and (optionally) COMMENT."
 199   (if (and comment (not (zerop (length comment))))
 200       (list keyword url comment)
 201     (cons keyword url)))
 202
 203 (defalias 'quickurl-url-keyword #'car
 204   "Return the keyword for the URL.
 205 \n\(fn URL)")
 206
 207 (defun quickurl-url-url (url)
 208   "Return the actual URL of the URL.
 209
 210 Note that this function is a setfable place."
 211   (declare (gv-setter (lambda (store)
 212                         `(setf (if (quickurl-url-commented-p ,url)
 213                                    (cadr ,url)
 214                                  (cdr ,url))
 215                                ,store))))
 216   (if (quickurl-url-commented-p url)
 217       (cadr url)
 218     (cdr url)))
 219
 220 (defun quickurl-url-comment (url)
 221   "Get the comment from a URL.
 222
 223 If the URL has no comment an empty string is returned. Also note that this
 224 function is a setfable place."
 225   (declare
 226    (gv-setter (lambda (store)
 227                 `(if (quickurl-url-commented-p ,url)
 228                      (if (zerop (length ,store))
 229                          (setf (cdr ,url) (cadr ,url))
 230                        (setf (nth 2 ,url) ,store))
 231                    (unless (zerop (length ,store))
 232                      (setf (cdr ,url) (list (cdr ,url) ,store)))))))
 233   (if (quickurl-url-commented-p url)
 234       (nth 2 url)
 235     ""))
 236
 237 (defun quickurl-url-description (url)
 238   "Return a description for the URL.
 239
 240 If the URL has a comment then this is returned, otherwise the keyword is
 241 returned."
 242   (let ((desc (quickurl-url-comment url)))
 243     (if (zerop (length desc))
 244         (quickurl-url-keyword url)
 245       desc)))
 246
 247 ;; Main code:
 248
 249 (defun quickurl-format-url (url)
 250   (format "<URL:%s>" (quickurl-url-url url)))
 251
 252 (defun quickurl-sort-urls (list)
 253   "Sort URLs in LIST according to their `quickurl-url-description'."
 254   (sort list
 255         (lambda (x y)
 256           (string<
 257            (downcase (quickurl-url-description x))
 258            (downcase (quickurl-url-description y))))))
 259
 260 (defun quickurl-read (&optional buffer)
 261   "`read' the URL list from BUFFER into `quickurl-urls'.
 262
 263 BUFFER, if nil, defaults to current buffer.
 264 Note that this function moves point to `point-min' before doing the `read'
 265 It also restores point after the `read'."
 266   (save-excursion
 267     (goto-char (point-min))
 268     (setq quickurl-urls (funcall quickurl-sort-function
 269                                  (read (or buffer (current-buffer)))))))
 270
 271 (defun quickurl-load-urls ()
 272   "Load the contents of `quickurl-url-file' into `quickurl-urls'."
 273   (when (file-exists-p quickurl-url-file)
 274     (with-temp-buffer
 275       (insert-file-contents quickurl-url-file)
 276       (quickurl-read))))
 277
 278 (defun quickurl-save-urls ()
 279   "Save the contents of `quickurl-urls' to `quickurl-url-file'."
 280   (with-temp-buffer
 281     (let ((standard-output (current-buffer))
 282           (print-length nil))
 283       (princ quickurl-prefix)
 284       (pp quickurl-urls)
 285       (princ quickurl-postfix)
 286       (write-region (point-min) (point-max) quickurl-url-file nil 0))))
 287
 288 (defun quickurl-find-url (lookup)
 289   "Return URL associated with key LOOKUP.
 290
 291 The lookup is done by looking in the alist `quickurl-urls' and the `cons'
 292 for the URL is returned. The actual method used to look into the alist
 293 depends on the setting of the variable `quickurl-assoc-function'."
 294   (funcall quickurl-assoc-function lookup quickurl-urls))
 295
 296 (defun quickurl-insert (url &optional silent)
 297   "Insert URL, formatted using `quickurl-format-function'.
 298
 299 Also display a `message' saying what the URL was unless SILENT is non-nil."
 300   (insert (funcall quickurl-format-function url))
 301   (unless silent
 302     (message "Found %s" (quickurl-url-url url))))
 303
 304 ;;;###autoload
 305 (defun quickurl (&optional lookup)
 306   "Insert a URL based on LOOKUP.
 307
 308 If not supplied LOOKUP is taken to be the word at point in the current
 309 buffer, this default action can be modified via
 310 `quickurl-grab-lookup-function'."
 311   (interactive)
 312   (when (or lookup
 313             (setq lookup (funcall quickurl-grab-lookup-function)))
 314     (quickurl-load-urls)
 315     (let ((url (quickurl-find-url lookup)))
 316       (if (null url)
 317           (error "No URL associated with \"%s\"" lookup)
 318         (when (looking-at "\\w")
 319           (skip-syntax-forward "\\w"))
 320         (insert " ")
 321         (quickurl-insert url)))))
 322
 323 ;;;###autoload
 324 (defun quickurl-ask (lookup)
 325   "Insert a URL, with `completing-read' prompt, based on LOOKUP."
 326   (interactive
 327    (list
 328     (progn
 329       (quickurl-load-urls)
 330       (let ((completion-ignore-case quickurl-completion-ignore-case))
 331         (completing-read "Lookup: " quickurl-urls nil t)))))
 332   (let ((url (quickurl-find-url lookup)))
 333     (when url
 334       (quickurl-insert url))))
 335
 336 (defun quickurl-grab-url ()
 337   "Attempt to grab a word/URL pair from point in the current buffer.
 338
 339 Point should be somewhere on the URL and the word is taken to be the thing
 340 that is returned from calling `quickurl-grab-lookup-function' once a
 341 `backward-word' has been issued at the start of the URL.
 342
 343 It is assumed that the URL is either \"unguarded\" or is wrapped inside an
 344 <URL:...> wrapper."
 345   (let ((url (thing-at-point 'url)))
 346     (when url
 347       (save-excursion
 348         (beginning-of-thing 'url)
 349         ;; `beginning-of-thing' doesn't take you to the start of a marked-up
 350         ;; URL, only to the start of the URL within the "markup". So, we
 351         ;; need to do a little more work to get to where we want to be.
 352         (when (thing-at-point-looking-at thing-at-point-markedup-url-regexp)
 353           (search-backward "<URL:"))
 354         (backward-word-strictly 1)
 355         (let ((word (funcall quickurl-grab-lookup-function)))
 356           (when word
 357             (quickurl-make-url
 358              ;; The grab function may return the word with properties. I don't
 359              ;; want the properties. I couldn't find a method of stripping
 360              ;; them from a "string" so this will have to do. If you know of
 361              ;; a better method of doing this I'd love to know.
 362              (with-temp-buffer
 363                (insert word)
 364                (buffer-substring-no-properties (point-min) (point-max)))
 365              url)))))))
 366
 367 ;;;###autoload
 368 (defun quickurl-add-url (word url comment)
 369   "Allow the user to interactively add a new URL associated with WORD.
 370
 371 See `quickurl-grab-url' for details on how the default word/URL combination
 372 is decided."
 373   (interactive (let ((word-url (quickurl-grab-url)))
 374                  (list (read-string "Word: "    (quickurl-url-keyword word-url))
 375                        (read-string "URL: "     (quickurl-url-url word-url))
 376                        (read-string "Comment: " (quickurl-url-comment word-url)))))
 377   (if (zerop (length word))
 378       (error "You must specify a WORD for lookup")
 379     (quickurl-load-urls)
 380     (let* ((current-url (quickurl-find-url word))
 381            (add-it      (if current-url
 382                             (if (called-interactively-p 'interactive)
 383                                 (y-or-n-p (format "\"%s\" exists, replace URL? " word))
 384                               t)
 385                           t)))
 386       (when add-it
 387         (if current-url
 388             (progn
 389               (setf (quickurl-url-url current-url) url)
 390               (setf (quickurl-url-comment current-url) comment))
 391           (push (quickurl-make-url word url comment) quickurl-urls))
 392         (setq quickurl-urls (funcall quickurl-sort-function quickurl-urls))
 393         (quickurl-save-urls)
 394         (when (get-buffer quickurl-list-buffer-name)
 395           (quickurl-list-populate-buffer))
 396         (when (called-interactively-p 'interactive)
 397           (message "Added %s" url))))))
 398
 399 ;;;###autoload
 400 (defun quickurl-browse-url (&optional lookup)
 401   "Browse the URL associated with LOOKUP.
 402
 403 If not supplied LOOKUP is taken to be the word at point in the
 404 current buffer, this default action can be modified via
 405 `quickurl-grab-lookup-function'."
 406   (interactive)
 407   (when (or lookup
 408             (setq lookup (funcall quickurl-grab-lookup-function)))
 409     (quickurl-load-urls)
 410     (let ((url (quickurl-find-url lookup)))
 411       (if url
 412           (browse-url (quickurl-url-url url))
 413         (error "No URL associated with \"%s\"" lookup)))))
 414
 415 ;;;###autoload
 416 (defun quickurl-browse-url-ask (lookup)
 417   "Browse the URL, with `completing-read' prompt, associated with LOOKUP."
 418   (interactive (list
 419                 (progn
 420                   (quickurl-load-urls)
 421                   (completing-read "Browse: " quickurl-urls nil t))))
 422   (let ((url (quickurl-find-url lookup)))
 423     (when url
 424       (browse-url (quickurl-url-url url)))))
 425
 426 ;;;###autoload
 427 (defun quickurl-edit-urls ()
 428   "Pull `quickurl-url-file' into a buffer for hand editing."
 429   (interactive)
 430   (find-file quickurl-url-file))
 431
 432 ;; quickurl-list mode.
 433
 434 ;;;###autoload
 435 (define-derived-mode quickurl-list-mode special-mode "Quickurl"
 436   "A mode for browsing the quickurl URL list.
 437
 438 The key bindings for `quickurl-list-mode' are:
 439
 440 \\{quickurl-list-mode-map}"
 441   (setq truncate-lines t))
 442
 443 ;;;###autoload
 444 (defun quickurl-list ()
 445   "Display `quickurl-list' as a formatted list using `quickurl-list-mode'."
 446   (interactive)
 447   (quickurl-load-urls)
 448   (unless (string= (buffer-name) quickurl-list-buffer-name)
 449     (setq quickurl-list-last-buffer (current-buffer)))
 450   (pop-to-buffer quickurl-list-buffer-name)
 451   (quickurl-list-populate-buffer)
 452   (quickurl-list-mode))
 453
 454 (defun quickurl-list-populate-buffer ()
 455   "Populate the `quickurl-list' buffer."
 456   (with-current-buffer (get-buffer quickurl-list-buffer-name)
 457     (let* ((sizes (or (cl-loop for url in quickurl-urls
 458                                collect (length (quickurl-url-description url)))
 459                       (list 20)))
 460            (fmt (format "%%-%ds %%s\n" (apply #'max sizes)))
 461            (inhibit-read-only t))
 462       (erase-buffer)
 463       (dolist (url quickurl-urls)
 464         (let ((start (point)))
 465           (insert (format fmt (quickurl-url-description url)
 466                           (quickurl-url-url url)))
 467           (add-text-properties
 468            start (1- (point))
 469            '(mouse-face highlight help-echo "mouse-2: insert this URL"))))
 470       (goto-char (point-min)))))
 471
 472 (defun quickurl-list-add-url (word url comment)
 473   "Wrapper for `quickurl-add-url' that doesn't guess the parameters."
 474   (interactive "sWord: \nsURL: \nsComment: ")
 475   (quickurl-add-url word url comment))
 476
 477 (defun quickurl-list-quit ()
 478   "Kill the buffer named `quickurl-list-buffer-name'."
 479   (interactive)
 480   (quit-window t))
 481
 482 (defun quickurl-list-mouse-select (event)
 483   "Select the URL under the mouse click."
 484   (interactive "e")
 485   (goto-char (posn-point (event-end event)))
 486   (quickurl-list-insert-url))
 487
 488 (defun quickurl-list-insert (type)
 489   "Insert the URL under cursor into `quickurl-list-last-buffer'.
 490 TYPE dictates what will be inserted, options are:
 491   `url'         - Insert the URL as <URL:url>
 492   `naked-url'   - Insert the URL with no formatting
 493   `with-lookup' - Insert \"lookup <URL:url>\"
 494   `with-desc'   - Insert \"description <URL:url>\"
 495   `lookup'      - Insert the lookup for that URL"
 496   (let ((url (nth (count-lines (point-min) (line-beginning-position))
 497                   quickurl-urls)))
 498     (if url
 499         (with-current-buffer quickurl-list-last-buffer
 500           (insert
 501            (pcase type
 502              (`url         (funcall quickurl-format-function url))
 503              (`naked-url   (quickurl-url-url url))
 504              (`with-lookup (format "%s <URL:%s>"
 505                                    (quickurl-url-keyword url)
 506                                    (quickurl-url-url url)))
 507              (`with-desc   (format "%S <URL:%s>"
 508                                    (quickurl-url-description url)
 509                                    (quickurl-url-url url)))
 510              (`lookup      (quickurl-url-keyword url)))))
 511       (error "No URL details on that line"))
 512     url))
 513
 514 (defmacro quickurl-list-make-inserter (type)
 515   "Macro to make a key-response function for use in `quickurl-list-mode-map'."
 516   `(defun ,(intern (format "quickurl-list-insert-%S" type)) ()
 517     ,(format "Insert the result of calling `quickurl-list-insert' with `%s'." type)
 518     (interactive)
 519     (when (quickurl-list-insert ',type)
 520       (quickurl-list-quit))))
 521
 522 (quickurl-list-make-inserter url)
 523 (quickurl-list-make-inserter naked-url)
 524 (quickurl-list-make-inserter with-lookup)
 525 (quickurl-list-make-inserter with-desc)
 526 (quickurl-list-make-inserter lookup)
 527
 528 (provide 'quickurl)
 529
 530 ;;; quickurl.el ends here