org-tutorials/org-protocol-custom-handler.org

   1 #+OPTIONS:    H:3 num:nil toc:t \n:nil @:t ::t |:t ^:t -:t f:t *:t TeX:t LaTeX:t skip:nil d:(HIDE) tags:not-in-toc
   2 #+STARTUP:    align fold nodlcheck hidestars oddeven lognotestate
   3 #+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
   4 #+TAGS:       Write(w) Update(u) Fix(f) Check(c)
   5 #+TITLE:      Defining custom handlers for use with org-protocol
   6 #+AUTHOR:     Sebastian Rose
   7 #+EMAIL:      sebastian_rose gmx de
   8 #+LANGUAGE:   en
   9 #+PRIORITIES: A C B
  10 #+CATEGORY:   worg-tutorial
  11
  12 [[file:index.org][{Back to Worg's tutorial index}]]
  13
  14 org-protocol intercepts calls from emacsclient to trigger custom actions without
  15 external dependencies. Please refer to [[file:../org-contrib/org-protocol.org][this file]] for the basic setup required.
  16
  17 You might want to watch the [[http://www.youtube.com/watch?v=h7Z2PiAcgh8][screencast]] on youTube.
  18
  19
  20 * Defining custom handlers
  21
  22   =org-protocol= scanns the list of filenames passed to the emacs-server for
  23   "=org-protocol:/sub-protocol:/=" and triggers actions assossiated with
  24   =sub-protocol= through the custom variable =org-protocol-protocol-alist=.
  25
  26   To defun a custom org-protocol handler basically means to define two basic
  27   elements:
  28
  29   1. a sub-protocol that triggers the action
  30   2. a function that consumes the data (i.e. the part of an URL that follows
  31      "=org-protocol://sub-protocol://=")
  32
  33   To install the custom handler's protocol, we add an entry to
  34   =org-protocol-protocol-alist=:
  35
  36 #+begin_src emacs-lisp
  37 (add-to-list 'org-protocol-protocol-alist
  38              '("Hello World"
  39                :protocol "hello-world"
  40                :function my-hello-world))
  41 #+end_src
  42
  43   The =:protocol= property is the sub-protocol, that triggers the action. Note,
  44   that names of protcols (or URL schemas) are only allowed to consist of a
  45   restricted set of characters. See [[http://www.ietf.org/rfc/rfc1738.txt][rfc1738]], section 2.1.
  46
  47   The =:function= is an arbitrary function that takes exactly one argument: the
  48   string that follows our protocol, found in a filename passed to emacs through
  49   emacsclient. All the three standard handlers split and decode that string
  50   using a helper function in =org-protocol.el=:
  51
  52 #+begin_src emacs-lisp
  53  org-protocol-split-data (data &optional unhexify separator)
  54 #+end_src
  55
  56   You may use different separators for your custom handlers and pass them to
  57   =org-protocol-split-data=.
  58
  59
  60
  61   Here is a simple definition:
  62
  63 #+begin_src emacs-lisp
  64 (defun hello-world (data)
  65   "Say hello to the world."
  66   (message data)
  67 nil)
  68 #+end_src
  69
  70   Now the URL =org-protocol://hello-world://encoded-data= will call our fuction
  71   with the string "=encoded-data=". Hence an
  72
  73   : emacsclient org-protocol://hello-world://encoded-data
  74
  75   will put "=encoded-data=" into the minibuffer.
  76
  77
  78 * Killing the client
  79
  80   If your handler uses interactive functions that could be canceld by the user
  81   by typing '=C-g=', consider to supply the '=:kill-client=' property when you
  82   define the protocol.
  83
  84   This is what we did for the remember handler:
  85
  86   : (defconst org-protocol-protocol-alist-default
  87   :   '(("org-remember" :protocol "remember"
  88   :                     :function org-protocol-remember
  89   :                     :kill-client t)
  90   :     ... ))
  91
  92   Otherwise, if the user has an interactive property defined in her remember
  93   template, discarding it through '=C-g=' would leed to emacsclient waiting for
  94   ever, thus to the appropriate questions when exiting emacs.
  95
  96   All filenames passing from emacsclient to the emacs will be ignored if you
  97   set =:kill-client= to a non-nil value.
  98
  99
 100 * Return values
 101
 102   Note, that our =hello-world= handler explicitly returns =nil=. This tells
 103   =org-protocol= to remove the filename from the list of files passed to the
 104   emacs-server. If more than one filename was supplied, all those filenames are
 105   searched for protocols. Only filenames without protocolls are passed to the
 106   emacs-server as usual.
 107
 108   Another possible return value is a string. If the string is a valid filename,
 109   and if that file can be read, =org-protocol= replaces the original filename with
 110   the one returned from the handler.
 111
 112
 113 * Using more than one value
 114
 115   Passing one argument to our custom handler is nice, but sometimes more
 116   parameters are needed. We would have to encode the the data and split it into
 117   parts using a separator.
 118
 119   This is where =org-protocol-split-data= comes into play. It takes a string as
 120   its first argument, an optional parameter to tell if the string should be
 121   considered URL-encoded UTF-8 text and finally an optional separator. By
 122   default, no URL-encoding is assumed and '=/=' is used as the separator.
 123
 124   The return value is a list of strings. If a non-nil value is supplied as the
 125   second argument, each elements of the returned list will be URL-decoded using
 126   =org-protocol-unhex-string=. If the second argument is a function, that function
 127   is used to decode each element of the list. The function should take a string
 128   as it's only parameter, and return the decoded value [fn:1].
 129
 130   This is a rewrite of our handler:
 131
 132 #+begin_src emacs-lisp
 133 (defun hello-world (data)
 134   "Say hello to the world."
 135   (let* ((parts (org-protocol-split-data data nil '::my-separator::'))
 136          (one (car parts))
 137          (two (cadr parts))
 138          (three (caddr parts)))
 139     ;; ... do something with one, two and three
 140     )
 141   nil)
 142 #+end_src
 143
 144
 145 * Using more than one value /the greedy way/
 146
 147   Finally, it is possible to define a /greedy/ handler. Basically it will discard
 148   _all_ the filenames from the servers list of files that follow the filename that
 149   triggered the handler.
 150
 151   A handler is greedy, if you add the =:greedy= property to
 152   =org-protocol-protocol-alist=, regardless of it's return value:
 153
 154 #+begin_src emacs-lisp
 155 (add-to-list 'org-protocol-protocol-alist
 156              '("Greedy"
 157                :protocol "greedy"
 158                :function my-greedy-handler
 159                :greedy t))
 160 #+end_src
 161
 162   The one argument to greedy handlers is the rest of the list of filenames, the
 163   one that triggered the handler included. But read on, please.
 164
 165
 166 ** The list of filenames
 167
 168    Here I have to admit, that I was lying all the time. emacsclient does not
 169    pass a list of filenames to the emacs-server. It's a list of lists. And the
 170    list is the list of emacsclient's arguments reversed.
 171
 172    As an example, the following commandline:
 173
 174    : emacsclient org-protocol:/greedy:/one two three +15:42
 175
 176    is passed as
 177
 178    : ((/dir/three (15 . 42)) (/dir/two) (/dir/org-protocol:/greedy:/one))
 179
 180    to the emacs-server, where =org-protocol= grabs it and reverses it to make it
 181    look like this:
 182
 183    : ((/dir/org-protocol:/greedy:/one) (/dir/two) (/dir/three  (15 . 42)))
 184
 185    This is now, what our greedy handler will receive as it's only parameter.
 186
 187    The "=/dir/=" prefix is added by emacsclient. It's the absolute path to its
 188    working directory.
 189
 190    You may set =org-protocol-reverse-list-of-files= to =nil= to inhibit the
 191    reversion. But that leads to unexpected results. In this example, the only
 192    filename left would be the one that triggered the actions. That seems not
 193    very greedy, and reversing the arguments on the commandline seems
 194    unnatural. Note though, that the sequence is not changed for the server.
 195
 196
 197 ** Flatten the list of arguments
 198
 199    =org-protocol.el= provides a function to flatten the list of arguments for
 200    greedy handlers:
 201
 202    : org-protocol-flatten-greedy (param-list &optional strip-path replacement)
 203
 204    This function takes the list of lists your greedy handler gets as its only
 205    parameter, and turns it into a flat list. Also, all prefixes and protocols
 206    are stripped from the element that triggered your handler.
 207
 208    This is, what the first parameter might look like:
 209
 210    : (("/dir/org-protocol:/greedy:/one") ("/dir/two") ("/dir/three" (15 . 42)))
 211
 212    If only the first parameter is supplied, =org-protocol-flatten-greedy= will
 213    return this list:
 214
 215    : ("/dir/one" "/dir/two" "/dir/three" 15 42)
 216
 217    If you supply a non-nil value as the second parameter for the function:
 218
 219    : ("one" "two" "three" 15 42)
 220
 221    And, last not least, if you supply a replacement "=REPL-=" (must be a string):
 222
 223    : ("REPL-one" "REPL-two" "REPL-three" 15 42)
 224
 225    Note, that this works exactly this way regardless of your setting of
 226    "=org-protocol-reverse-list-of-files=". The sequence of the returned list will
 227    always reflect the sequence of arguments on the command line.
 228
 229 * General remarks
 230
 231   emacsclient compresses double and tripple slashes to one. That's why it
 232   doesn't really matter how many slashes succeed the scheme part of the URL,
 233   also known as /protocol/.
 234
 235   This behaviour is the main reasons, why the slash was choosen as the
 236   default separator for data fields. Keeping the slashes is insecure, since some
 237   of the data fields could contain double or tripple slashes themselves.
 238
 239
 240
 241 * Footnotes
 242
 243 [fn:1]  The function feature was added with the Org-mode 6.26 release (commit
 244         6a9acfa9a3ec4ad889951d02c9809f55ac7491fb).