Release 6.25c
[org-mode.git] / lisp / org-protocol.el
blob0df0c44e00c01b3c2564e7f6c4e208dbddfba735
1 ;;; org-protocol.el --- Intercept calls from emacsclient to trigger custom actions.
2 ;;
3 ;; Copyright (c) 2008, 2009
4 ;; Bastien Guerry <bzg AT altern DOT org>,
5 ;; Daniel German <dmg AT uvic DOT org>,
6 ;; Sebastian Rose <sebastian_rose AT gmx DOT de>,
7 ;; Ross Patterson <me AT rpatterson DOT net>
8 ;; David Moffat
9 ;; (will be FSF when done)
12 ;; Filename: org-protocol.el
13 ;; Version: 6.25c
14 ;; Author: Bastien Guerry <bzg AT altern DOT org>
15 ;; Author: Daniel M German <dmg AT uvic DOT org>
16 ;; Author: Sebastian Rose <sebastian_rose AT gmx DOT de>
17 ;; Author: Ross Patterson <me AT rpatterson DOT net>
18 ;; Maintainer: Sebastian Rose <sebastian_rose AT gmx DOT de>
19 ;; Keywords: org, emacsclient, wp
21 ;; This file is not part of GNU Emacs.
23 ;; This program is free software: you can redistribute it and/or modify
24 ;; it under the terms of the GNU General Public License as published by
25 ;; the Free Software Foundation, either version 3 of the License, or
26 ;; (at your option) any later version.
28 ;; This program is distributed in the hope that it will be useful,
29 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
30 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
31 ;; GNU General Public License for more details.
33 ;; See <http://www.gnu.org/licenses/>.
35 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
36 ;;; Commentary:
38 ;; Intercept calls from emacsclient to trigger custom actions.
40 ;; This is done by advising `server-visit-files' to scann the list of filenames
41 ;; for `org-protocol-the-protocol' and sub-procols defined in
42 ;; `org-protocol-protocol-alist' and `org-protocol-protocol-alist-default'.
44 ;; Any application that supports calling external programs with an URL
45 ;; as argument may be used with this functionality.
48 ;; Usage:
49 ;; ------
51 ;; 1.) Add this to your init file (.emacs probably):
53 ;; (add-to-list 'load-path "/path/to/org-protocol/")
54 ;; (require 'org-protocol)
56 ;; 3.) Ensure emacs-server is up and running.
57 ;; 4.) Try this from the command line (adjust the URL as needed):
59 ;; $ emacsclient \
60 ;; org-protocol://store-link://http:%2F%2Flocalhost%2Findex.html/The%20title
62 ;; 5.) Optionally add custom sub-protocols and handlers:
64 ;; (setq org-protocol-protocol-alist
65 ;; '(("my-protocol"
66 ;; :protocol "my-protocol"
67 ;; :function my-protocol-handler-fuction)))
69 ;; A "sub-protocol" will be found in URLs like this:
71 ;; org-protocol://sub-protocol://data
73 ;; If it works, you can now setup other applications for using this feature.
76 ;; As of March 2009 Firefox users follow the steps documented on
77 ;; http://kb.mozillazine.org/Register_protocol, Opera setup is described here:
78 ;; http://www.opera.com/support/kb/view/535/
81 ;; Documentation
82 ;; -------------
84 ;; org-protocol.el comes with and installs handlers to open sources of published
85 ;; online content, store and insert the browser's URLs and cite online content
86 ;; by clicking on a bookmark in Firefox, Opera and probably other browsers and
87 ;; applications:
89 ;; * `org-protocol-open-source' uses the sub-protocol \"open-source\" and maps
90 ;; URLs to local filenames defined in `org-protocol-project-alist'.
92 ;; * `org-protocol-store-link' stores an Org-link (if Org-mode is present) and
93 ;; pushes the browsers URL to the `kill-ring' for yanking. This handler is
94 ;; triggered through the sub-protocol \"store-link\".
96 ;; * Call `org-protocol-remember' by using the sub-protocol \"remember\". If
97 ;; Org-mode is loaded, emacs will popup a remember buffer and fill the
98 ;; template with the data provided. I.e. the browser's URL is inserted as an
99 ;; Org-link of which the page title will be the description part. If text
100 ;; was select in the browser, that text will be the body of the entry.
102 ;; You may use the same bookmark URL for all those standard handlers and just
103 ;; adjust the sub-protocol used:
105 ;; location.href='org-protocol://sub-protocol://'+
106 ;; encodeURIComponent(location.href)+'/'+
107 ;; encodeURIComponent(document.title)+'/'+
108 ;; encodeURIComponent(window.getSelection())
110 ;; The handler for the sub-protocol \"remember\" detects an optional template
111 ;; char that, if present, triggers the use of a special template.
112 ;; Example:
114 ;; location.href='org-protocol://sub-protocol://x/'+ ...
116 ;; use template ?x.
118 ;; Note, that using double shlashes is optional from org-protocol.el's point of
119 ;; view because emacsclient sqashes the slashes to one.
122 ;; provides: 'org-protocol
124 ;;; Code:
126 (require 'org)
127 (require 'url)
128 (eval-when-compile
129 (require 'cl))
131 (declare-function org-publish-initialize-files-alist "org-publish"
132 (&optional refresh))
133 (declare-function org-publish-get-project-from-filename "org-publish"
134 (filename &optional up))
135 (declare-function server-delete-client proc "server" (&optional noframe))
137 (defgroup org-protocol nil
138 "Intercept calls from emacsclient to trigger custom actions.
140 This is done by advising `server-visit-files' to scann the list of filenames
141 for `org-protocol-the-protocol' and sub-procols defined in
142 `org-protocol-protocol-alist' and `org-protocol-protocol-alist-default'."
143 :version "22.1"
144 :group 'convenience
145 :group 'org)
148 ;;; Variables:
150 (defconst org-protocol-protocol-alist-default
151 '(("org-remember" :protocol "remember" :function org-protocol-remember :kill-client t)
152 ("org-store-link" :protocol "store-link" :function org-protocol-store-link)
153 ("org-open-source" :protocol "open-source" :function org-protocol-open-source))
154 "Default protocols to use.
155 See `org-protocol-protocol-alist' for a description of this variable.")
158 (defconst org-protocol-the-protocol "org-protocol"
159 "This is the protocol to detect if org-protocol.el is loaded.
160 `org-protocol-protocol-alist-default' and `org-protocol-protocol-alist' hold the
161 sub-protocols that trigger the required action. You will have to define just one
162 protocol handler OS-wide (MS-Windows) or per application (Linux). That protocol
163 handler should call emacsclient.")
166 ;;; User variables:
168 (defcustom org-protocol-reverse-list-of-files t
169 "* The filenames passed on the commandline are passed to the emacs-server in
170 reversed order. Set to `t' (default) to re-reverse the list, i.e. use the
171 sequence on the command line. If nil, the sequence of the filenames is
172 unchanged."
173 :group 'org-protocol
174 :type 'boolean)
177 (defcustom org-protocol-project-alist nil
178 "* Map URLs to local filenames for `org-protocol-open-source' (open-source).
180 Each element of this list must be of the form:
182 (module-name :property value property: value ...)
184 where module-name is an arbitrary name. All the values are strings.
186 Possible properties are:
188 :online-suffix - the suffix to strip from the published URLs
189 :working-suffix - the replacement for online-suffix
190 :base-url - the base URL, e.g. http://www.example.com/project/
191 Last slash required.
192 :working-directory - the local working directory. This is, what base-url will
193 be replaced with.
195 Example:
197 (setq org-protocol-project-alist
198 '((\"http://orgmode.org/worg/\"
199 :online-suffix \".php\"
200 :working-suffix \".org\"
201 :base-url \"http://orgmode.org/worg/\"
202 :working-directory \"/home/user/org/Worg/\")
203 (\"http://localhost/org-notes/\"
204 :online-suffix \".html\"
205 :working-suffix \".org\"
206 :base-url \"http://localhost/org/\"
207 :working-directory \"/home/user/org/\")))
209 Consider using the interactive functions `org-protocol-create' and
210 `org-protocol-create-for-org' to help you filling this variable with valid contents."
211 :group 'org-protocol
212 :type 'alist)
215 (defcustom org-protocol-protocol-alist nil
216 "* Register custom handlers for org-protocol.
218 Each element of this list must be of the form:
220 (module-name :protocol protocol :function func :kill-client nil)
222 protocol - protocol to detect in a filename without trailing colon and slashes.
223 See rfc1738 section 2.1 for more on this.
224 If you define a protocol \"my-protocol\", `org-protocol-check-filename-for-protocol'
225 will search filenames for \"org-protocol:/my-protocol:/\"
226 and trigger your action for every match. `org-protocol' is defined in
227 `org-protocol-the-protocol'. Double and tripple slashes are compressed
228 to one by emacsclient.
230 function - function that handles requests with protocol and takes exactly one
231 argument: the filename with all protocols stripped. If the function
232 returns nil, emacsclient and -server do nothing. Any non-nil return
233 value is considered a valid filename and thus passed to the server.
235 `org-protocol.el provides some support for handling those filenames,
236 if you stay with the conventions used for the standard handlers in
237 `org-protocol-protocol-alist-default'. See `org-protocol-split-data'.
239 kill-client - If t, kill the client immediately, once the sub-protocol is
240 detected. This is neccessary for actions that can be interupted by
241 `C-g' to avoid dangeling emacsclients. Note, that all other command
242 line arguments but the this one will be discarded, greedy handlers
243 still receive the whole list of arguments though.
245 Here is an example:
247 (setq org-protocol-protocol-alist
248 '((\"my-protocol\"
249 :protocol \"my-protocol\"
250 :function my-protocol-handler-fuction)
251 (\"your-protocol\"
252 :protocol \"your-protocol\"
253 :function your-protocol-handler-fuction)))"
254 :group 'org-protocol
255 :type '(alist))
258 ;;; Helper functions:
260 (defun org-protocol-sanitize-uri (uri)
261 "emacsclient compresses double and tripple slashes.
262 Slashes are sanitized to double slashes here."
263 (when (string-match "^\\([a-z]+\\):/" uri)
264 (let* ((splitparts (split-string uri "/+")))
265 (setq uri (concat (car splitparts) "//" (mapconcat 'identity (cdr splitparts) "/")))))
266 uri)
269 (defun org-protocol-split-data(data &optional unhexify separator)
270 "Split, what a org-protocol handler function gets as only argument.
271 data is that one argument. Data is splitted at each occurrence of separator
272 (regexp). If no separator is specified or separator is nil, assume \"/+\".
273 The results of that splitting are return as a list. If unhexify is non-nil,
274 hex-decode each split part."
275 (let* ((sep (or separator "/+"))
276 (split-parts (split-string data sep)))
277 (if unhexify
278 (mapcar 'url-unhex-string split-parts)
279 split-parts)))
282 (defun org-protocol-flatten-greedy (param-list &optional strip-path replacement)
283 "Greedy handlers might recieve a list like this from emacsclient:
284 '( (\"/dir/org-protocol:/greedy:/~/path1\" (23 . 12)) (\"/dir/param\")
285 where \"/dir/\" is the absolute path to emacsclients working directory. This
286 function transforms it into a flat list utilizing `org-protocol-flatten' and
287 transforms the elements of that list as follows:
289 If strip-path is non-nil, remove the \"/dir/\" prefix from all members of
290 param-list.
292 If replacement is string, replace the \"/dir/\" prefix with it.
294 The first parameter, the one that contains the protocols, is always changed.
295 Everything up to the end of the protocols is stripped.
297 Note, that this function will not work, if you set
298 `org-protocol-reverse-list-of-files' to nil!"
299 (let* ((l (org-protocol-flatten param-list))
300 (trigger (car l))
301 (len 0)
303 ret)
304 (when (string-match "^\\(.*\\)\\(org-protocol:/+[a-zA-z0-9][-_a-zA-z0-9]*:/+\\\\(.*\\)" trigger)
305 (setq dir (match-string 1 trigger))
306 (setq len (length dir))
307 (setcar l (concat dir (match-string 3 trigger))))
308 (if strip-path
309 (progn
310 (dolist (e l ret)
311 (setq ret
312 (append ret
313 (list
314 (if (stringp e)
315 (if (stringp replacement)
316 (setq e (concat replacement (substring e len)))
317 (setq e (substring e len)))
318 e)))))
319 ret)
320 l)))
323 (defun org-protocol-flatten (l)
324 "Greedy handlers might recieve a list like this from emacsclient:
325 '( (\"/dir/org-protocol:/greedy:/~/path1\" (23 . 12)) (\"/dir/param\")
326 where \"/dir/\" is the absolute path to emacsclients working directory. This
327 function transforms it into a flat list."
328 (if (null l) ()
329 (if (listp l)
330 (append (org-protocol-flatten (car l)) (org-protocol-flatten (cdr l)))
331 (list l))))
333 ;;; Standard protocol handlers:
335 (defun org-protocol-store-link (fname)
336 "Process an org-protocol://store-link:// style url
337 and store a browser URL as an org link. Also pushes the links URL to the
338 `kill-ring'.
340 The location for a browser's bookmark has to look like this:
342 javascript:location.href='org-protocol://store-link://'+ \\
343 encodeURIComponent(location.href)
344 encodeURIComponent(document.title)+'/'+ \\
346 Don't use `escape()'! Use `encodeURIComponent()' instead. The title of the page
347 could contain slashes and the location definitely will.
349 The sub-protocol used to reach this function is set in
350 `org-protocol-protocol-alist'."
351 (let* ((splitparts (org-protocol-split-data fname t))
352 (uri (org-protocol-sanitize-uri (car splitparts)))
353 (title (cadr splitparts))
354 orglink)
355 (if (boundp 'org-stored-links)
356 (setq org-stored-links (cons (list uri title) org-stored-links)))
357 (kill-new uri)
358 (message "`%s' to insert new org-link, `%s' to insert `%s'"
359 (substitute-command-keys"\\[org-insert-link]")
360 (substitute-command-keys"\\[yank]")
361 uri))
362 nil)
365 (defun org-protocol-remember (info)
366 "Process an org-protocol://remember:// style url.
368 The sub-protocol used to reach this function is set in
369 `org-protocol-protocol-alist'.
371 This function detects an URL, title and optinal text, separated by '/'
372 The location for a browser's bookmark has to look like this:
374 javascript:location.href='org-protocol://remember://'+ \\
375 encodeURIComponent(location.href)+ \\
376 encodeURIComponent(document.title)+'/'+ \\
377 encodeURIComponent(window.getSelection())
379 By default the template character ?w is used. But you may prepend the encoded
380 URL with a character and a slash like so:
382 javascript:location.href='org-protocol://org-store-link://b/'+ ...
384 Now template ?b will be used."
386 (if (and (boundp 'org-stored-links)
387 (fboundp 'org-remember))
388 (let* ((parts (org-protocol-split-data info t))
389 (template (or (and (= 1 (length (car parts))) (pop parts)) "w"))
390 (url (org-protocol-sanitize-uri (car parts)))
391 (type (if (string-match "^\\([a-z]+\\):" url)
392 (match-string 1 url)))
393 (title (cadr parts))
394 (region (caddr parts))
395 (orglink (org-make-link-string url title))
396 remember-annotation-functions)
397 (setq org-stored-links
398 (cons (list url title) org-stored-links))
399 (kill-new orglink)
400 (org-store-link-props :type type
401 :link url
402 :description title
403 :initial region)
404 (raise-frame)
405 (org-remember nil (string-to-char template)))
407 (message "Org-mode not loaded."))
408 nil)
411 (defun org-protocol-open-source (fname)
412 "Process an org-protocol://open-source:// style url.
414 Change a filename by mapping URLs to local filenames as set
415 in `org-protocol-project-alist'.
417 The location for a browser's bookmark should look like this:
419 javascript:location.href='org-protocol://open-source://'+ \\
420 encodeURIComponent(location.href)"
422 ;; As we enter this function for a match on our protocol, the return value
423 ;; defaults to nil.
424 (let ((result nil)
425 (f (url-unhex-string fname)))
426 (catch 'result
427 (dolist (prolist org-protocol-project-alist)
428 (let* ((base-url (plist-get (cdr prolist) :base-url))
429 (wsearch (regexp-quote base-url)))
431 (when (string-match wsearch f)
432 (let* ((wdir (plist-get (cdr prolist) :working-directory))
433 (strip-suffix (plist-get (cdr prolist) :online-suffix))
434 (add-suffix (plist-get (cdr prolist) :working-suffix))
435 (start-pos (+ (string-match wsearch f) (length base-url)))
436 (end-pos (string-match
437 (concat (regexp-quote strip-suffix) "\\([?#].*\\)?$") f))
438 (the-file (concat wdir (substring f start-pos end-pos) add-suffix)))
439 (if (file-readable-p the-file)
440 (throw 'result the-file))
441 (if (file-exists-p the-file)
442 (message "%s: permission denied!" the-file)
443 (message "%s: no such file or directory." the-file))))))
444 result)))
447 ;;; Core functions:
449 (defun org-protocol-check-filename-for-protocol (fname restoffiles client)
450 "Detect if `org-protocol-the-protocol' and a known sub-protocol is used in fname.
451 Sub-protocols are registered in `org-protocol-protocol-alist' and
452 `org-protocol-protocol-alist-default'.
453 This is, how the matching is done:
455 (string-match \"protocol:/+sub-protocol:/+\" ...)
457 protocol and sub-protocol are regexp-quoted.
459 If a matching protcol is found, the protcol is stripped from fname and the
460 result is passed to the protocols function as the only parameter. If the
461 function returns nil, the filename is removed from the list of filenames
462 passed from emacsclient to the server.
463 If the function returns a non nil value, that value is passed to the server
464 as filename."
465 (let ((sub-protocols (append org-protocol-protocol-alist org-protocol-protocol-alist-default)))
466 (catch 'fname
467 (let ((the-protocol (concat (regexp-quote org-protocol-the-protocol) ":/+")))
468 (when (string-match the-protocol fname)
469 (dolist (prolist sub-protocols)
470 (let ((proto (concat the-protocol (regexp-quote (plist-get (cdr prolist) :protocol)) ":/+")))
471 (when (string-match proto fname)
472 (let* ((func (plist-get (cdr prolist) :function))
473 (greedy (plist-get (cdr prolist) :greedy))
474 (splitted (split-string fname proto))
475 (result (if greedy restoffiles (cadr splitted))))
476 (if (plist-get (cdr prolist) :kill-client)
477 (server-delete-client client t))
478 (when (fboundp func)
479 (unless greedy
480 (throw 'fname (funcall func result)))
481 (funcall func result)
482 (throw 'fname t))))))))
483 ;; (message "fname: %s" fname)
484 fname)))
487 (defadvice server-visit-files (before org-protocol-detect-protocol-server activate)
488 "Advice server-visit-flist to call `org-protocol-modify-filename-for-protocol'."
489 (let ((flist (if org-protocol-reverse-list-of-files
490 (reverse (ad-get-arg 0))
491 (ad-get-arg 0)))
492 (client (ad-get-arg 1)))
493 (catch 'greedy
494 (dolist (var flist)
495 (let ((fname (expand-file-name (car var)))) ;; `\' to `/' on windows. FIXME: could this be done any better?
496 (setq fname (org-protocol-check-filename-for-protocol fname (member var flist) client))
497 (if (eq fname t) ;; greedy? We need the `t' return value.
498 (progn
499 (ad-set-arg 0 nil)
500 (throw 'greedy t))
501 (if (stringp fname) ;; probably filename
502 (setcar var fname)
503 (ad-set-arg 0 (delq var (ad-get-arg 0))))))
504 ))))
506 ;;; Org specific functions:
508 (defun org-protocol-create-for-org ()
509 "Create a org-protocol project for the current file's Org-mode project.
510 This works, if the file visited is part of a publishing project in
511 `org-publish-project-alist'. This functions calls `org-protocol-create' to do
512 most of the work."
513 (interactive)
514 (require 'org-publish)
515 (org-publish-initialize-files-alist)
516 (let ((all (or (org-publish-get-project-from-filename buffer-file-name))))
517 (if all (org-protocol-create (cdr all))
518 (message "Not in an org-project. Did mean %s?"
519 (substitute-command-keys"\\[org-protocol-create]")))))
523 (defun org-protocol-create(&optional project-plist)
524 "Create a new org-protocol project interactively.
525 An org-protocol project is an entry in `org-protocol-project-alist'
526 which is used by `org-protocol-open-source'.
527 Optionally use project-plist to initialize the defaults for this worglet. If
528 project-plist is the CDR of an element in `org-publish-project-alist', reuse
529 :base-directory, :html-extension and :base-extension."
530 (interactive)
531 (let ((working-dir (expand-file-name(or (plist-get project-plist :base-directory) default-directory)))
532 (base-url "http://orgmode.org/worg/")
533 (strip-suffix (or (plist-get project-plist :html-extension) ".html"))
534 (working-suffix (if (plist-get project-plist :base-extension)
535 (concat "." (plist-get project-plist :base-extension))
536 ".org"))
538 (worglet-buffer nil)
540 (insert-default-directory t)
541 (minibuffer-allow-text-properties nil))
543 (setq base-url (read-string "Base URL of published content: " base-url nil base-url t))
544 (if (not (string-match "\\/$" base-url))
545 (setq base-url (concat base-url "/")))
547 (setq working-dir
548 (expand-file-name
549 (read-directory-name "Local working directory: " working-dir working-dir t)))
550 (if (not (string-match "\\/$" working-dir))
551 (setq working-dir (concat working-dir "/")))
553 (setq strip-suffix
554 (read-string
555 (concat "Extension to strip from published URLs ("strip-suffix"): ")
556 strip-suffix nil strip-suffix t))
558 (setq working-suffix
559 (read-string
560 (concat "Extension of editable files ("working-suffix"): ")
561 working-suffix nil working-suffix t))
563 (when (yes-or-no-p "Save the new worglet to your init file? ")
564 (setq org-protocol-project-alist
565 (cons `(,base-url . (:base-url ,base-url
566 :working-directory ,working-dir
567 :online-suffix ,strip-suffix
568 :working-suffix ,working-suffix))
569 org-protocol-project-alist))
570 (customize-save-variable 'org-protocol-project-alist org-protocol-project-alist))
573 (provide 'org-protocol)
574 ;;; org-protocol.el ends here