Christophe Weblog Wiki Code Publications Music
convenience Makefile for generating html from org files
[swankr.git] / README
1 #+TITLE: swankr: SWANK (and SLIME) for R
2 #+AUTHOR: Christophe Rhodes
3 #+EMAIL: csr21@cantab.net
4 * Introduction
5   This is swankr, an implementation of the swank[fn:1] protocol for
6   R[fn:2].  While the coverage of swank protocol functions is
7   currently limited, enough is implemented for swankr to be useful: at
8   the very minimum, it can be used to develop and extend itself.
9 ** Relationship with ESS
10    Emacs Speaks Statistics[fn:3] provides an interaction mode for R
11    (among other statistical software packages), including an interface
12    to R's toplevel, and keybindings to send input to R, to look up
13    documentation, and so on.  Where it differs most noticeably from
14    swankr is in the level of integration of various facilities with
15    emacs: ESS uses the browser() debugger, whereas swankr provides its
16    own debugger, sldb; swankr provides a custom REPL with hooks for
17    common commands; and so on.  On the other hand, ESS is mature,
18    feature-rich software, while swankr is only a little more advanced
19    than a proof-of-concept.  For Lisp programmers, perhaps the most
20    useful analogy is to say that swankr intends to be to ESS what
21    SLIME is to ILISP.  At present, ESS mode remains active in R source
22    buffers, providing font-locking functionality among other things.
23 * Installation
24 ** Running
25    To begin using swankr:
26
27    1. start R;
28    2. load the swank.R file:
29 #+BEGIN_SRC R
30       source("swank.R")
31 #+END_SRC
32    3. at the R prompt, run
33 #+BEGIN_SRC R
34       swank();
35 #+END_SRC
36    4. within emacs, load and initialize slime;
37 #+BEGIN_SRC emacs-lisp
38       (require 'slime)
39       (slime-setup '(slime-repl))
40 #+END_SRC
41    5. run =M-x slime-connect=, accepting the default host and port,
42       and acknowledging the protocol version mismatch.
43
44    At this point, an R REPL should appear.
45 ** Emacs customization
46    At a minimum, slime needs to be set up to function.  I've
47    used the following forms in my =~/.emacs=
48 #+BEGIN_SRC emacs-lisp
49    (require 'slime)
50    (slime-setup '(slime-repl slime-scratch slime-media))
51 #+END_SRC
52    The =slime-media= contrib is new and (at present) R-specific,
53    allowing for image results to be embedded in the REPL.
54
55    In addition, for keybindings like =C-c C-c= to work properly, emacs
56    needs to be told how to guess where a function definition begins.
57    This can be achieved with /e.g./
58 #+BEGIN_SRC emacs-lisp
59    (add-hook 'ess-mode-hook
60      (lambda () 
61        (setq defun-prompt-regexp "^\\(\\(\\sw\\|\\s_\\)+\\|\\s\"\\S\"+\\s\"\\)\\s-*\\(=\\|<-\\)\\s-*function\\s-*(.*)\\s-*")))
62 #+END_SRC
63    Fontification of quoted function names is suboptimal by default in
64    ESS; the following form in =~/.emacs= fixes that for ESS 5.11.
65 #+BEGIN_SRC emacs-lisp
66    (eval-after-load "ess-common"
67      (setq ess-R-mode-font-lock-keywords
68            (append 
69              (list '("\\(\\sw\\|\\s_\\)+\\s-*\\(=\\|<-\\)\\s-*function"
70                      1 font-lock-function-name-face t)
71                    '("\\s\"\\(\\S\"+\\)\\s\"\\s-*\\(=\\|<-\\)\\s-*function"
72                      1 font-lock-function-name-face t))
73              ess-R-mode-font-lock-keywords)))
74 #+END_SRC
75 * Development
76   swankr's primary development repository is a git repository,
77   accessible through
78   <http://common-lisp.net/r/users/crhodes/swankr.git> and
79   git://common-lisp.net/crhodes/swankr/swankr.git; a web view of the
80   development history is [[http://common-lisp.net/gitweb?p=users/crhodes/swankr.git][available through gitweb]].  You can also view
81   the current lists of [[file:BUGS.org]] and [[file:TODO.org]] items.
82 * Acknowledgments
83   Thanks to my colleagues at [[http://www.gold.ac.uk/][Goldsmiths, University of London]], for
84   suggesting that I investigate R for numerical and graphical
85   investigations, and to my colleagues at [[http://www.teclo.net/][Teclo Networks AG]] for giving
86   me motivation to get around to it.  Initial development was done at
87   the [[http://ismir2010.ismir.net/][International Symposium on Music Information Retrieval]], which I
88   attended (indirectly) thanks to the EPSRC-funded [[http://www.omras2.org/][OMRAS2]] research
89   project and the [[http://www.londoninternational.ac.uk][University of London External System]]; Helmut Eller's
90   partial implementation of swank for Ruby was an excellent blueprint
91   to get development started.
92 * Footnotes
93 [fn:1] part of SLIME, the Superior Lisp Interaction Mode for Emacs:
94 <http://common-lisp.net/project/slime/>.
95
96 [fn:2] a free software environment for statistical computing and
97 graphics: <http://www.r-project.org/>.
98
99 [fn:3] also known as ESS, an emacs mode for interacting with a number
100 of statistical software packages, including R:
101 <http://ess.r-project.org/>.
102 * COMMENT:
103 Local Variables:
104 mode: org;
105 End: