lisp/net/quickurl.el

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