1 ;;; quickurl.el --- insert a URL based on text at point in buffer
3 ;; Copyright (C) 1999-2018 Free Software Foundation, Inc.
5 ;; Author: Dave Pearson <davep@davep.org>
6 ;; Maintainer: Dave Pearson <davep@davep.org>
8 ;; Keywords: hypermedia
10 ;; This file is part of GNU Emacs.
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.
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.
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/>.
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.
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:
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:
42 ;; ("GNU" . "https://www.gnu.org/")
44 ;; A list entry looks like:
46 ;; (<Lookup> <URL> <Comment>)
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
53 ;; ("FSF" "https://www.fsf.org/" "The Free Software Foundation")
55 ;; Given the above, your quickurl file might look like:
57 ;; (("GNU" . "https://www.gnu.org/")
58 ;; ("FSF" "https://www.fsf.org/" "The Free Software Foundation")
59 ;; ("emacs" . "http://www.emacs.org/")
60 ;; ("davep" "http://www.davep.org/" "Dave's homepage"))
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.
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'.
70 ;; quickurl is always available from:
72 ;; <URL:http://www.davep.org/emacs/quickurl.el>
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
84 (eval-when-compile (require 'cl-lib
))
91 (defgroup quickurl nil
92 "Insert a URL based on text at point in buffer."
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
104 (defcustom quickurl-format-function
#'quickurl-format-url
105 "Function to format the URL before insertion into the current buffer."
109 (defcustom quickurl-sort-function
#'quickurl-sort-urls
110 "Function to sort the URL list."
114 (defcustom quickurl-grab-lookup-function
#'current-word
115 "Function to grab the thing to lookup."
119 (defun quickurl--assoc-function (key alist
)
120 "Default function for `quickurl-assoc-function'."
121 (assoc-string key alist t
))
123 (defcustom quickurl-assoc-function
#'quickurl--assoc-function
124 "Function to use for alist lookup into `quickurl-urls'."
125 :version
"26.1" ; was the obsolete assoc-ignore-case
129 (defcustom quickurl-completion-ignore-case t
130 "Should `quickurl-ask' ignore case when doing the input lookup?"
134 (defcustom quickurl-prefix
";; -*- lisp -*-\n\n"
135 "Text to write to `quickurl-url-file' before writing the URL list."
139 (defcustom quickurl-postfix
""
140 "Text to write to `quickurl-url-file' after writing the URL list.
142 See the constant `quickurl-reread-hook-postfix' for some example text that
147 (defcustom quickurl-list-mode-hook nil
148 "Hooks for `quickurl-list-mode'."
155 (defconst quickurl-reread-hook-postfix
158 ;; eval: (progn (require 'quickurl) (add-hook 'write-file-functions (lambda () (quickurl-read) nil) nil t))
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.
165 To make use of this do something like:
167 (setq quickurl-postfix quickurl-reread-hook-postfix)
169 in your init file (after loading/requiring quickurl).")
171 ;; Non-customize variables.
173 (defvar quickurl-urls nil
174 "URL alist for use with `quickurl' and `quickurl-ask'.")
176 (defvar quickurl-list-mode-map
177 (let ((map (make-sparse-keymap)))
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
)
188 "Local keymap for a `quickurl-list-mode' buffer.")
190 (defvar quickurl-list-buffer-name
"*quickurl-list*"
191 "Name for the URL listing buffer.")
193 (defvar quickurl-list-last-buffer nil
194 "`current-buffer' when `quickurl-list' was called.")
196 ;; Functions for working with a URL entry.
198 (defun quickurl-url-commented-p (url)
199 "Does the URL have a comment?"
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
)
208 (defalias 'quickurl-url-keyword
#'car
209 "Return the keyword for the URL.
212 (defun quickurl-url-url (url)
213 "Return the actual URL of the URL.
215 Note that this function is a setfable place."
216 (declare (gv-setter (lambda (store)
217 `(setf (if (quickurl-url-commented-p ,url
)
221 (if (quickurl-url-commented-p url
)
225 (defun quickurl-url-comment (url)
226 "Get the comment from a URL.
228 If the URL has no comment an empty string is returned. Also note that this
229 function is a setfable place."
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
)
242 (defun quickurl-url-description (url)
243 "Return a description for the URL.
245 If the URL has a comment then this is returned, otherwise the keyword is
247 (let ((desc (quickurl-url-comment url
)))
248 (if (zerop (length desc
))
249 (quickurl-url-keyword url
)
254 (defun quickurl-format-url (url)
255 (format "<URL:%s>" (quickurl-url-url url
)))
257 (defun quickurl-sort-urls (list)
258 "Sort URLs in LIST according to their `quickurl-url-description'."
262 (downcase (quickurl-url-description x
))
263 (downcase (quickurl-url-description y
))))))
265 (defun quickurl-read (&optional buffer
)
266 "`read' the URL list from BUFFER into `quickurl-urls'.
268 BUFFER, if nil, defaults to current buffer.
269 Note that this function moves point to `point-min' before doing the `read'
270 It also restores point after the `read'."
272 (goto-char (point-min))
273 (setq quickurl-urls
(funcall quickurl-sort-function
274 (read (or buffer
(current-buffer)))))))
276 (defun quickurl-load-urls ()
277 "Load the contents of `quickurl-url-file' into `quickurl-urls'."
278 (when (file-exists-p quickurl-url-file
)
280 (insert-file-contents quickurl-url-file
)
283 (defun quickurl-save-urls ()
284 "Save the contents of `quickurl-urls' to `quickurl-url-file'."
286 (let ((standard-output (current-buffer))
288 (princ quickurl-prefix
)
290 (princ quickurl-postfix
)
291 (write-region (point-min) (point-max) quickurl-url-file nil
0))))
293 (defun quickurl-find-url (lookup)
294 "Return URL associated with key LOOKUP.
296 The lookup is done by looking in the alist `quickurl-urls' and the `cons'
297 for the URL is returned. The actual method used to look into the alist
298 depends on the setting of the variable `quickurl-assoc-function'."
299 (funcall quickurl-assoc-function lookup quickurl-urls
))
301 (defun quickurl-insert (url &optional silent
)
302 "Insert URL, formatted using `quickurl-format-function'.
304 Also display a `message' saying what the URL was unless SILENT is non-nil."
305 (insert (funcall quickurl-format-function url
))
307 (message "Found %s" (quickurl-url-url url
))))
310 (defun quickurl (&optional lookup
)
311 "Insert a URL based on LOOKUP.
313 If not supplied LOOKUP is taken to be the word at point in the current
314 buffer, this default action can be modified via
315 `quickurl-grab-lookup-function'."
318 (setq lookup
(funcall quickurl-grab-lookup-function
)))
320 (let ((url (quickurl-find-url lookup
)))
322 (error "No URL associated with \"%s\"" lookup
)
323 (when (looking-at "\\w")
324 (skip-syntax-forward "\\w"))
326 (quickurl-insert url
)))))
329 (defun quickurl-ask (lookup)
330 "Insert a URL, with `completing-read' prompt, based on LOOKUP."
335 (let ((completion-ignore-case quickurl-completion-ignore-case
))
336 (completing-read "Lookup: " quickurl-urls nil t
)))))
337 (let ((url (quickurl-find-url lookup
)))
339 (quickurl-insert url
))))
341 (defun quickurl-grab-url ()
342 "Attempt to grab a word/URL pair from point in the current buffer.
344 Point should be somewhere on the URL and the word is taken to be the thing
345 that is returned from calling `quickurl-grab-lookup-function' once a
346 `backward-word' has been issued at the start of the URL.
348 It is assumed that the URL is either \"unguarded\" or is wrapped inside an
350 (let ((url (thing-at-point 'url
)))
353 (beginning-of-thing 'url
)
354 ;; `beginning-of-thing' doesn't take you to the start of a marked-up
355 ;; URL, only to the start of the URL within the "markup". So, we
356 ;; need to do a little more work to get to where we want to be.
357 (when (thing-at-point-looking-at thing-at-point-markedup-url-regexp
)
358 (search-backward "<URL:"))
359 (backward-word-strictly 1)
360 (let ((word (funcall quickurl-grab-lookup-function
)))
363 ;; The grab function may return the word with properties. I don't
364 ;; want the properties. I couldn't find a method of stripping
365 ;; them from a "string" so this will have to do. If you know of
366 ;; a better method of doing this I'd love to know.
369 (buffer-substring-no-properties (point-min) (point-max)))
373 (defun quickurl-add-url (word url comment
)
374 "Allow the user to interactively add a new URL associated with WORD.
376 See `quickurl-grab-url' for details on how the default word/URL combination
378 (interactive (let ((word-url (quickurl-grab-url)))
379 (list (read-string "Word: " (quickurl-url-keyword word-url
))
380 (read-string "URL: " (quickurl-url-url word-url
))
381 (read-string "Comment: " (quickurl-url-comment word-url
)))))
382 (if (zerop (length word
))
383 (error "You must specify a WORD for lookup")
385 (let* ((current-url (quickurl-find-url word
))
386 (add-it (if current-url
387 (if (called-interactively-p 'interactive
)
388 (y-or-n-p (format "\"%s\" exists, replace URL? " word
))
394 (setf (quickurl-url-url current-url
) url
)
395 (setf (quickurl-url-comment current-url
) comment
))
396 (push (quickurl-make-url word url comment
) quickurl-urls
))
397 (setq quickurl-urls
(funcall quickurl-sort-function quickurl-urls
))
399 (when (get-buffer quickurl-list-buffer-name
)
400 (quickurl-list-populate-buffer))
401 (when (called-interactively-p 'interactive
)
402 (message "Added %s" url
))))))
405 (defun quickurl-browse-url (&optional lookup
)
406 "Browse the URL associated with LOOKUP.
408 If not supplied LOOKUP is taken to be the word at point in the
409 current buffer, this default action can be modified via
410 `quickurl-grab-lookup-function'."
413 (setq lookup
(funcall quickurl-grab-lookup-function
)))
415 (let ((url (quickurl-find-url lookup
)))
417 (browse-url (quickurl-url-url url
))
418 (error "No URL associated with \"%s\"" lookup
)))))
421 (defun quickurl-browse-url-ask (lookup)
422 "Browse the URL, with `completing-read' prompt, associated with LOOKUP."
426 (completing-read "Browse: " quickurl-urls nil t
))))
427 (let ((url (quickurl-find-url lookup
)))
429 (browse-url (quickurl-url-url url
)))))
432 (defun quickurl-edit-urls ()
433 "Pull `quickurl-url-file' into a buffer for hand editing."
435 (find-file quickurl-url-file
))
437 ;; quickurl-list mode.
440 (define-derived-mode quickurl-list-mode special-mode
"Quickurl"
441 "A mode for browsing the quickurl URL list.
443 The key bindings for `quickurl-list-mode' are:
445 \\{quickurl-list-mode-map}"
446 (setq truncate-lines t
))
449 (defun quickurl-list ()
450 "Display `quickurl-list' as a formatted list using `quickurl-list-mode'."
453 (unless (string= (buffer-name) quickurl-list-buffer-name
)
454 (setq quickurl-list-last-buffer
(current-buffer)))
455 (pop-to-buffer quickurl-list-buffer-name
)
456 (quickurl-list-populate-buffer)
457 (quickurl-list-mode))
459 (defun quickurl-list-populate-buffer ()
460 "Populate the `quickurl-list' buffer."
461 (with-current-buffer (get-buffer quickurl-list-buffer-name
)
462 (let* ((sizes (or (cl-loop for url in quickurl-urls
463 collect
(length (quickurl-url-description url
)))
465 (fmt (format "%%-%ds %%s\n" (apply #'max sizes
)))
466 (inhibit-read-only t
))
468 (dolist (url quickurl-urls
)
469 (let ((start (point)))
470 (insert (format fmt
(quickurl-url-description url
)
471 (quickurl-url-url url
)))
474 '(mouse-face highlight help-echo
"mouse-2: insert this URL"))))
475 (goto-char (point-min)))))
477 (defun quickurl-list-add-url (word url comment
)
478 "Wrapper for `quickurl-add-url' that doesn't guess the parameters."
479 (interactive "sWord: \nsURL: \nsComment: ")
480 (quickurl-add-url word url comment
))
482 (defun quickurl-list-quit ()
483 "Kill the buffer named `quickurl-list-buffer-name'."
487 (defun quickurl-list-mouse-select (event)
488 "Select the URL under the mouse click."
490 (goto-char (posn-point (event-end event
)))
491 (quickurl-list-insert-url))
493 (defun quickurl-list-insert (type)
494 "Insert the URL under cursor into `quickurl-list-last-buffer'.
495 TYPE dictates what will be inserted, options are:
496 `url' - Insert the URL as <URL:url>
497 `naked-url' - Insert the URL with no formatting
498 `with-lookup' - Insert \"lookup <URL:url>\"
499 `with-desc' - Insert \"description <URL:url>\"
500 `lookup' - Insert the lookup for that URL"
501 (let ((url (nth (count-lines (point-min) (line-beginning-position))
504 (with-current-buffer quickurl-list-last-buffer
507 (`url
(funcall quickurl-format-function url
))
508 (`naked-url
(quickurl-url-url url
))
509 (`with-lookup
(format "%s <URL:%s>"
510 (quickurl-url-keyword url
)
511 (quickurl-url-url url
)))
512 (`with-desc
(format "%S <URL:%s>"
513 (quickurl-url-description url
)
514 (quickurl-url-url url
)))
515 (`lookup
(quickurl-url-keyword url
)))))
516 (error "No URL details on that line"))
519 (defmacro quickurl-list-make-inserter
(type)
520 "Macro to make a key-response function for use in `quickurl-list-mode-map'."
521 `(defun ,(intern (format "quickurl-list-insert-%S" type
)) ()
522 ,(format "Insert the result of calling `quickurl-list-insert' with `%s'." type
)
524 (when (quickurl-list-insert ',type
)
525 (quickurl-list-quit))))
527 (quickurl-list-make-inserter url
)
528 (quickurl-list-make-inserter naked-url
)
529 (quickurl-list-make-inserter with-lookup
)
530 (quickurl-list-make-inserter with-desc
)
531 (quickurl-list-make-inserter lookup
)
535 ;;; quickurl.el ends here