code.delx.au - gnu-emacs/blob - lisp/net/quickurl.el

   1 ;;; quickurl.el --- insert a URL based on text at point in buffer
   2
   3 ;; Copyright (C) 1999-2013 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 (convert-standard-filename "~/.quickurls")
  98   "File that contains the URL list."
  99   :type  'file
 100   :group 'quickurl)
 101
 102 (defcustom quickurl-format-function (lambda (url) (format "<URL:%s>" (quickurl-url-url url)))
 103   "Function to format the URL before insertion into the current buffer."
 104   :type  'function
 105   :group 'quickurl)
 106
 107 (defcustom quickurl-sort-function (lambda (list)
 108                                     (sort list
 109                                           (lambda (x y)
 110                                             (string<
 111                                              (downcase (quickurl-url-description x))
 112                                              (downcase (quickurl-url-description y))))))
 113   "Function to sort the URL list."
 114   :type  'function
 115   :group 'quickurl)
 116
 117 (defcustom quickurl-grab-lookup-function #'current-word
 118   "Function to grab the thing to lookup."
 119   :type  'function
 120   :group 'quickurl)
 121
 122 (defcustom quickurl-assoc-function #'assoc-ignore-case
 123   "Function to use for alist lookup into `quickurl-urls'."
 124   :type  'function
 125   :group 'quickurl)
 126
 127 (defcustom quickurl-completion-ignore-case t
 128   "Should `quickurl-ask' ignore case when doing the input lookup?"
 129   :type  'boolean
 130   :group 'quickurl)
 131
 132 (defcustom quickurl-prefix ";; -*- lisp -*-\n\n"
 133   "Text to write to `quickurl-url-file' before writing the URL list."
 134   :type  'string
 135   :group 'quickurl)
 136
 137 (defcustom quickurl-postfix ""
 138   "Text to write to `quickurl-url-file' after writing the URL list.
 139
 140 See the constant `quickurl-reread-hook-postfix' for some example text that
 141 could be used here."
 142   :type  'string
 143   :group 'quickurl)
 144
 145 (defcustom quickurl-list-mode-hook nil
 146   "Hooks for `quickurl-list-mode'."
 147   :type  'hook
 148   :group 'quickurl)
 149
 150 ;; Constants.
 151
 152 ;;;###autoload
 153 (defconst quickurl-reread-hook-postfix
 154     "
 155 ;; Local Variables:
 156 ;; eval: (progn (require 'quickurl) (add-hook 'local-write-file-hooks (lambda () (quickurl-read) nil)))
 157 ;; End:
 158 "
 159   "Example `quickurl-postfix' text that adds a local variable to the
 160 `quickurl-url-file' so that if you edit it by hand it will ensure that
 161 `quickurl-urls' is updated with the new URL list.
 162
 163 To make use of this do something like:
 164
 165   (setq quickurl-postfix quickurl-reread-hook-postfix)
 166
 167 in your init file (after loading/requiring quickurl).")
 168
 169 ;; Non-customize variables.
 170
 171 (defvar quickurl-urls nil
 172   "URL alist for use with `quickurl' and `quickurl-ask'.")
 173
 174 (defvar quickurl-list-mode-map
 175   (let ((map (make-sparse-keymap)))
 176     (suppress-keymap map t)
 177     (define-key map "a"           #'quickurl-list-add-url)
 178     (define-key map [(control m)] #'quickurl-list-insert-url)
 179     (define-key map "u"           #'quickurl-list-insert-naked-url)
 180     (define-key map " "           #'quickurl-list-insert-with-lookup)
 181     (define-key map "l"           #'quickurl-list-insert-lookup)
 182     (define-key map "d"           #'quickurl-list-insert-with-desc)
 183     (define-key map [(control g)] #'quickurl-list-quit)
 184     (define-key map "q"           #'quickurl-list-quit)
 185     (define-key map [mouse-2]     #'quickurl-list-mouse-select)
 186     (define-key map "?"           #'describe-mode)
 187     map)
 188   "Local keymap for a `quickurl-list-mode' buffer.")
 189
 190 (defvar quickurl-list-buffer-name "*quickurl-list*"
 191   "Name for the URL listing buffer.")
 192
 193 (defvar quickurl-list-last-buffer nil
 194   "`current-buffer' when `quickurl-list' was called.")
 195
 196 ;; Functions for working with a URL entry.
 197
 198 (defun quickurl-url-commented-p (url)
 199   "Does the URL have a comment?"
 200   (listp (cdr url)))
 201
 202 (defun quickurl-make-url (keyword url &optional comment)
 203   "Create a URL from KEYWORD, URL and (optionally) COMMENT."
 204   (if (and comment (not (zerop (length comment))))
 205       (list keyword url comment)
 206     (cons keyword url)))
 207
 208 (defalias 'quickurl-url-keyword #'car
 209   "Return the keyword for the URL.
 210 \n\(fn URL)")
 211
 212 (defun quickurl-url-url (url)
 213   "Return the actual URL of the URL.
 214
 215 Note that this function is a setfable place."
 216   (declare (gv-setter (lambda (store)
 217                         `(setf (if (quickurl-url-commented-p ,url)
 218                                    (cadr ,url)
 219                                  (cdr ,url))
 220                                ,store))))
 221   (if (quickurl-url-commented-p url)
 222       (cadr url)
 223     (cdr url)))
 224
 225 (defun quickurl-url-comment (url)
 226   "Get the comment from a URL.
 227
 228 If the URL has no comment an empty string is returned. Also note that this
 229 function is a setfable place."
 230   (declare
 231    (gv-setter (lambda (store)
 232                 `(if (quickurl-url-commented-p ,url)
 233                      (if (zerop (length ,store))
 234                          (setf (cdr ,url) (cadr ,url))
 235                        (setf (nth 2 ,url) ,store))
 236                    (unless (zerop (length ,store))
 237                      (setf (cdr ,url) (list (cdr ,url) ,store)))))))
 238   (if (quickurl-url-commented-p url)
 239       (nth 2 url)
 240     ""))
 241
 242 (defun quickurl-url-description (url)
 243   "Return a description for the URL.
 244
 245 If the URL has a comment then this is returned, otherwise the keyword is
 246 returned."
 247   (let ((desc (quickurl-url-comment url)))
 248     (if (zerop (length desc))
 249         (quickurl-url-keyword url)
 250       desc)))
 251
 252 ;; Main code:
 253
 254 (cl-defun quickurl-read (&optional buffer)
 255   "`read' the URL list from BUFFER into `quickurl-urls'.
 256
 257 BUFFER, if nil, defaults to current buffer.
 258 Note that this function moves point to `point-min' before doing the `read'
 259 It also restores point after the `read'."
 260   (save-excursion
 261     (goto-char (point-min))
 262     (setq quickurl-urls (funcall quickurl-sort-function
 263                                  (read (or buffer (current-buffer)))))))
 264
 265 (defun quickurl-load-urls ()
 266   "Load the contents of `quickurl-url-file' into `quickurl-urls'."
 267   (when (file-exists-p quickurl-url-file)
 268     (with-temp-buffer
 269       (insert-file-contents quickurl-url-file)
 270       (quickurl-read))))
 271
 272 (defun quickurl-save-urls ()
 273   "Save the contents of `quickurl-urls' to `quickurl-url-file'."
 274   (with-temp-buffer
 275     (let ((standard-output (current-buffer))
 276           (print-length nil))
 277       (princ quickurl-prefix)
 278       (pp quickurl-urls)
 279       (princ quickurl-postfix)
 280       (write-region (point-min) (point-max) quickurl-url-file nil 0))))
 281
 282 (defun quickurl-find-url (lookup)
 283   "Return URL associated with key LOOKUP.
 284
 285 The lookup is done by looking in the alist `quickurl-urls' and the `cons'
 286 for the URL is returned. The actual method used to look into the alist
 287 depends on the setting of the variable `quickurl-assoc-function'."
 288   (funcall quickurl-assoc-function lookup quickurl-urls))
 289
 290 (defun quickurl-insert (url &optional silent)
 291   "Insert URL, formatted using `quickurl-format-function'.
 292
 293 Also display a `message' saying what the URL was unless SILENT is non-nil."
 294   (insert (funcall quickurl-format-function url))
 295   (unless silent
 296     (message "Found %s" (quickurl-url-url url))))
 297
 298 ;;;###autoload
 299 (cl-defun quickurl (&optional lookup)
 300   "Insert a URL based on LOOKUP.
 301
 302 If not supplied LOOKUP is taken to be the word at point in the current
 303 buffer, this default action can be modified via
 304 `quickurl-grab-lookup-function'."
 305   (interactive)
 306   (when (or lookup
 307             (setq lookup (funcall quickurl-grab-lookup-function)))
 308     (quickurl-load-urls)
 309     (let ((url (quickurl-find-url lookup)))
 310       (if (null url)
 311           (error "No URL associated with \"%s\"" lookup)
 312         (when (looking-at "\\w")
 313           (skip-syntax-forward "\\w"))
 314         (insert " ")
 315         (quickurl-insert url)))))
 316
 317 ;;;###autoload
 318 (defun quickurl-ask (lookup)
 319   "Insert a URL, with `completing-read' prompt, based on LOOKUP."
 320   (interactive
 321    (list
 322     (progn
 323       (quickurl-load-urls)
 324       (let ((completion-ignore-case quickurl-completion-ignore-case))
 325         (completing-read "Lookup: " quickurl-urls nil t)))))
 326   (let ((url (quickurl-find-url lookup)))
 327     (when url
 328       (quickurl-insert url))))
 329
 330 (defun quickurl-grab-url ()
 331   "Attempt to grab a word/URL pair from point in the current buffer.
 332
 333 Point should be somewhere on the URL and the word is taken to be the thing
 334 that is returned from calling `quickurl-grab-lookup-function' once a
 335 `backward-word' has been issued at the start of the URL.
 336
 337 It is assumed that the URL is either \"unguarded\" or is wrapped inside an
 338 <URL:...> wrapper."
 339   (let ((url (thing-at-point 'url)))
 340     (when url
 341       (save-excursion
 342         (beginning-of-thing 'url)
 343         ;; `beginning-of-thing' doesn't take you to the start of a marked-up
 344         ;; URL, only to the start of the URL within the "markup". So, we
 345         ;; need to do a little more work to get to where we want to be.
 346         (when (thing-at-point-looking-at thing-at-point-markedup-url-regexp)
 347           (search-backward "<URL:"))
 348         (backward-word 1)
 349         (let ((word (funcall quickurl-grab-lookup-function)))
 350           (when word
 351             (quickurl-make-url
 352              ;; The grab function may return the word with properties. I don't
 353              ;; want the properties. I couldn't find a method of stripping
 354              ;; them from a "string" so this will have to do. If you know of
 355              ;; a better method of doing this I'd love to know.
 356              (with-temp-buffer
 357                (insert word)
 358                (buffer-substring-no-properties (point-min) (point-max)))
 359              url)))))))
 360
 361 ;;;###autoload
 362 (defun quickurl-add-url (word url comment)
 363   "Allow the user to interactively add a new URL associated with WORD.
 364
 365 See `quickurl-grab-url' for details on how the default word/URL combination
 366 is decided."
 367   (interactive (let ((word-url (quickurl-grab-url)))
 368                  (list (read-string "Word: "    (quickurl-url-keyword word-url))
 369                        (read-string "URL: "     (quickurl-url-url word-url))
 370                        (read-string "Comment: " (quickurl-url-comment word-url)))))
 371   (if (zerop (length word))
 372       (error "You must specify a WORD for lookup")
 373     (quickurl-load-urls)
 374     (let* ((current-url (quickurl-find-url word))
 375            (add-it      (if current-url
 376                             (if (called-interactively-p 'interactive)
 377                                 (y-or-n-p (format "\"%s\" exists, replace URL? " word))
 378                               t)
 379                           t)))
 380       (when add-it
 381         (if current-url
 382             (progn
 383               (setf (quickurl-url-url current-url) url)
 384               (setf (quickurl-url-comment current-url) comment))
 385           (push (quickurl-make-url word url comment) quickurl-urls))
 386         (setq quickurl-urls (funcall quickurl-sort-function quickurl-urls))
 387         (quickurl-save-urls)
 388         (when (get-buffer quickurl-list-buffer-name)
 389           (quickurl-list-populate-buffer))
 390         (when (called-interactively-p 'interactive)
 391           (message "Added %s" url))))))
 392
 393 ;;;###autoload
 394 (defun quickurl-browse-url (&optional lookup)
 395   "Browse the URL associated with LOOKUP.
 396
 397 If not supplied LOOKUP is taken to be the word at point in the
 398 current buffer, this default action can be modified via
 399 `quickurl-grab-lookup-function'."
 400   (interactive)
 401   (when (or lookup
 402             (setq lookup (funcall quickurl-grab-lookup-function)))
 403     (quickurl-load-urls)
 404     (let ((url (quickurl-find-url lookup)))
 405       (if url
 406           (browse-url (quickurl-url-url url))
 407         (error "No URL associated with \"%s\"" lookup)))))
 408
 409 ;;;###autoload
 410 (defun quickurl-browse-url-ask (lookup)
 411   "Browse the URL, with `completing-read' prompt, associated with LOOKUP."
 412   (interactive (list
 413                 (progn
 414                   (quickurl-load-urls)
 415                   (completing-read "Browse: " quickurl-urls nil t))))
 416   (let ((url (quickurl-find-url lookup)))
 417     (when url
 418       (browse-url (quickurl-url-url url)))))
 419
 420 ;;;###autoload
 421 (defun quickurl-edit-urls ()
 422   "Pull `quickurl-url-file' into a buffer for hand editing."
 423   (interactive)
 424   (find-file quickurl-url-file))
 425
 426 ;; quickurl-list mode.
 427
 428 (put 'quickurl-list-mode 'mode-class 'special)
 429
 430 ;;;###autoload
 431 (defun quickurl-list-mode ()
 432   "A mode for browsing the quickurl URL list.
 433
 434 The key bindings for `quickurl-list-mode' are:
 435
 436 \\{quickurl-list-mode-map}"
 437   (interactive)
 438   (kill-all-local-variables)
 439   (use-local-map quickurl-list-mode-map)
 440   (setq major-mode 'quickurl-list-mode
 441         mode-name  "quickurl list")
 442   (run-mode-hooks 'quickurl-list-mode-hook)
 443   (setq buffer-read-only t
 444         truncate-lines   t))
 445
 446 ;;;###autoload
 447 (defun quickurl-list ()
 448   "Display `quickurl-list' as a formatted list using `quickurl-list-mode'."
 449   (interactive)
 450   (quickurl-load-urls)
 451   (unless (string= (buffer-name) quickurl-list-buffer-name)
 452     (setq quickurl-list-last-buffer (current-buffer)))
 453   (pop-to-buffer quickurl-list-buffer-name)
 454   (quickurl-list-populate-buffer)
 455   (quickurl-list-mode))
 456
 457 (defun quickurl-list-populate-buffer ()
 458   "Populate the `quickurl-list' buffer."
 459   (with-current-buffer (get-buffer quickurl-list-buffer-name)
 460     (let* ((sizes (or (cl-loop for url in quickurl-urls
 461                                collect (length (quickurl-url-description url)))
 462                       (list 20)))
 463            (fmt (format "%%-%ds %%s\n" (apply #'max sizes)))
 464            (inhibit-read-only t))
 465       (erase-buffer)
 466       (cl-loop for url in quickurl-urls
 467                do (let ((start (point)))
 468                     (insert (format fmt (quickurl-url-description url)
 469                                     (quickurl-url-url url)))
 470                     (add-text-properties
 471                      start (1- (point))
 472                      '(mouse-face highlight
 473                        help-echo "mouse-2: insert this URL"))))
 474       (goto-char (point-min)))))
 475
 476 (defun quickurl-list-add-url (word url comment)
 477   "Wrapper for `quickurl-add-url' that doesn't guess the parameters."
 478   (interactive "sWord: \nsURL: \nsComment: ")
 479   (quickurl-add-url word url comment))
 480
 481 (defun quickurl-list-quit ()
 482   "Kill the buffer named `quickurl-list-buffer-name'."
 483   (interactive)
 484   (kill-buffer quickurl-list-buffer-name)
 485   (switch-to-buffer quickurl-list-last-buffer)
 486   (delete-other-windows))
 487
 488 (defun quickurl-list-mouse-select (event)
 489   "Select the URL under the mouse click."
 490   (interactive "e")
 491   (goto-char (posn-point (event-end event)))
 492   (quickurl-list-insert-url))
 493
 494 (defun quickurl-list-insert (type)
 495   "Insert the URL under cursor into `quickurl-list-last-buffer'.
 496 TYPE dictates what will be inserted, options are:
 497   `url'         - Insert the URL as <URL:url>
 498   `naked-url'   - Insert the URL with no formatting
 499   `with-lookup' - Insert \"lookup <URL:url>\"
 500   `with-desc'   - Insert \"description <URL:url>\"
 501   `lookup'      - Insert the lookup for that URL"
 502   (let ((url (nth (count-lines (point-min) (line-beginning-position))
 503                   quickurl-urls)))
 504     (if url
 505         (with-current-buffer quickurl-list-last-buffer
 506           (insert
 507            (pcase type
 508              (`url         (funcall quickurl-format-function url))
 509              (`naked-url   (quickurl-url-url url))
 510              (`with-lookup (format "%s <URL:%s>"
 511                                    (quickurl-url-keyword url)
 512                                    (quickurl-url-url url)))
 513              (`with-desc   (format "%S <URL:%s>"
 514                                    (quickurl-url-description url)
 515                                    (quickurl-url-url url)))
 516              (`lookup      (quickurl-url-keyword url)))))
 517       (error "No URL details on that line"))
 518     url))
 519
 520 (defmacro quickurl-list-make-inserter (type)
 521   "Macro to make a key-response function for use in `quickurl-list-mode-map'."
 522   `(defun ,(intern (format "quickurl-list-insert-%S" type)) ()
 523     ,(format "Insert the result of calling `quickurl-list-insert' with `%s'." type)
 524     (interactive)
 525     (when (quickurl-list-insert ',type)
 526       (quickurl-list-quit))))
 527
 528 (quickurl-list-make-inserter url)
 529 (quickurl-list-make-inserter naked-url)
 530 (quickurl-list-make-inserter with-lookup)
 531 (quickurl-list-make-inserter with-desc)
 532 (quickurl-list-make-inserter lookup)
 533
 534 (provide 'quickurl)
 535
 536 ;;; quickurl.el ends here