lisp/net/quickurl.el

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