1 #+TITLE: swankr: SWANK (and SLIME) for R
2 #+AUTHOR: Christophe Rhodes
3 #+EMAIL: csr21@cantab.net
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.
24 ** Emacs configuration
26 SLIME is required separately from swankr. To install slime,
27 perhaps the simplest is to pull the CVS sources into a
28 user-specific site directory, and arrange for that to be on the
29 emacs =load-path=; I did
31 mkdir -p ~/.emacs.d/site-lisp
32 cd ~/.emacs.d/site-lisp
33 cvs -z3 -d:pserver:anonymous:anonymous@common-lisp.net:/project/slime/cvsroot co slime
36 Following that, I have in my =~/.emacs= (you will need to adjust
37 paths to executables and source files):
38 #+begin_src emacs-lisp
40 (let ((default-directory (concat user-emacs-directory (convert-standard-filename "site-lisp/"))))
41 (normal-top-level-add-subdirs-to-load-path))
45 (setq slime-net-coding-system 'utf-8-unix)
46 (slime-setup '(slime-asdf slime-repl slime-scratch slime-presentations slime-media))
47 (setq slime-lisp-implementations
48 '((sbcl ("sbcl" "--dynamic-space-size" "2048" "--load" "/home/csr21/src/lisp/quicklisp/setup.lisp"))
49 (git-sbcl ("sh" "/home/csr21/src/lisp/sbcl/run-sbcl.sh" "--dynamic-space-size" "2048"))
50 (R ("R" "--no-save" "--max-vsize=4096M")
51 :init (lambda (port-filename coding-system)
53 "source('/home/csr21/src/R/swankr/swank.R', keep.source=TRUE, chdir=TRUE)\nstartSwank('%s')\n" port-filename)))))
54 (global-set-key (kbd "s-s") 'slime-selector)
56 *** Additional refinements
57 In addition, for keybindings like =C-c C-c= to work properly, emacs
58 needs to be told how to guess where a function definition begins.
59 This can be achieved with /e.g./
60 #+BEGIN_SRC emacs-lisp
61 (add-hook 'ess-mode-hook
63 (setq defun-prompt-regexp "^\\(\\(\\sw\\|\\s_\\)+\\|\\s\"\\S\"+\\s\"\\)\\s-*\\(=\\|<-\\)\\s-*function\\s-*(.*)\\s-*")))
65 Fontification of quoted function names is suboptimal by default in
66 ESS; the following form in =~/.emacs= fixes that for ESS 5.11.
67 #+BEGIN_SRC emacs-lisp
68 (eval-after-load "ess-common"
69 (setq ess-R-mode-font-lock-keywords
71 (list '("\\(\\sw\\|\\s_\\)+\\s-*\\(=\\|<-\\)\\s-*function"
72 1 font-lock-function-name-face t)
73 '("\\s\"\\(\\S\"+\\)\\s\"\\s-*\\(=\\|<-\\)\\s-*function"
74 1 font-lock-function-name-face t))
75 ess-R-mode-font-lock-keywords)))
78 After performing the installation steps above, =M-- M-x slime RET R
79 RET= should start swank. You will be prompted to accept a version
80 mismatch -- simply accept -- then the SLIME REPL should start up,
81 giving a prompt. Enjoy!
82 ** Proof-of-concept (OBSOLETE)
83 [ The instructions here are for the seriously impatient, and do not
84 give as good an experience ]
86 To begin using swankr:
89 2. load the swank.R file:
93 3. at the R prompt, run
97 4. within emacs, load and initialize slime;
98 #+BEGIN_SRC emacs-lisp
100 (slime-setup '(slime-repl slime-presentations slime-media))
102 5. run =M-x slime-connect=, accepting the default host and port,
103 and acknowledging the protocol version mismatch.
105 At this point, an R REPL should appear.
107 swankr's primary development repository is a git repository,
109 <http://common-lisp.net/r/users/crhodes/swankr.git> and
110 git://common-lisp.net/users/crhodes/swankr.git; a web view of the
111 development history is [[http://common-lisp.net/gitweb?p=users/crhodes/swankr.git][available through gitweb]]. You can also view
112 the current lists of [[file:BUGS.org]] and [[file:TODO.org]] items.
114 Thanks to my colleagues at [[http://www.gold.ac.uk/][Goldsmiths, University of London]], for
115 suggesting that I investigate R for numerical and graphical
116 investigations, and to my colleagues at [[http://www.teclo.net/][Teclo Networks AG]] for giving
117 me motivation to get around to it. Initial development was done at
118 the [[http://ismir2010.ismir.net/][International Symposium on Music Information Retrieval]], which I
119 attended (indirectly) thanks to the EPSRC-funded [[http://www.omras2.org/][OMRAS2]] research
120 project and the [[http://www.londoninternational.ac.uk][University of London External System]]; Helmut Eller's
121 partial implementation of swank for Ruby was an excellent blueprint
122 to get development started.
124 [fn:1] part of SLIME, the Superior Lisp Interaction Mode for Emacs:
125 <http://common-lisp.net/project/slime/>.
127 [fn:2] a free software environment for statistical computing and
128 graphics: <http://www.r-project.org/>.
130 [fn:3] also known as ESS, an emacs mode for interacting with a number
131 of statistical software packages, including R:
132 <http://ess.r-project.org/>.