Christophe Weblog Wiki Code Publications Music
record resolutions of things in BUGS and TODO
[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 ** Emacs configuration
25 *** Installing SLIME
26     [[http://common-lisp.net/project/slime/][SLIME]] is required separately from swankr.  To install slime,
27     perhaps the simplest is to pull the [[https://github.com/slime/slime][git sources]] into a
28     user-specific site directory, and arrange for that to be on the
29     emacs =load-path=; something like the following:
30 #+begin_src sh
31 mkdir -p ~/.emacs.d/site-lisp
32 cd ~/.emacs.d/site-lisp
33 git clone https://github.com/slime/slime.git
34 #+end_src
35
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
39 ;;; ~/.emacs.d/
40 (let ((default-directory (concat user-emacs-directory (convert-standard-filename "site-lisp/"))))
41   (normal-top-level-add-subdirs-to-load-path))
42
43 ;;; SLIME
44 (require 'slime)
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" "--interactive")
51            :init (lambda (port-filename coding-system) 
52                    (load "/home/csr21/src/R/swankr/swankr")
53                    (format
54                     "source('/home/csr21/src/R/swankr/swank.R', keep.source=TRUE, chdir=TRUE)\nstartSwank('%s')\n" port-filename)))))
55 (global-set-key (kbd "s-s") 'slime-selector)
56 #+end_src
57 *** Additional refinements
58    In addition, for keybindings like =C-c C-c= to work properly, emacs
59    needs to be told how to guess where a function definition begins.
60    This can be achieved with /e.g./
61 #+BEGIN_SRC emacs-lisp
62    (add-hook 'ess-mode-hook
63      (lambda () 
64        (setq defun-prompt-regexp "^\\(\\(\\sw\\|\\s_\\)+\\|\\s\"\\S\"+\\s\"\\)\\s-*\\(=\\|<-\\)\\s-*function\\s-*(.*)\\s-*")))
65 #+END_SRC
66    Fontification of quoted function names is suboptimal by default in
67    ESS; the following form in =~/.emacs= fixes that for ESS 5.11.
68 #+BEGIN_SRC emacs-lisp
69    (eval-after-load "ess-common"
70      (setq ess-R-mode-font-lock-keywords
71            (append 
72              (list '("\\(\\sw\\|\\s_\\)+\\s-*\\(=\\|<-\\)\\s-*function"
73                      1 font-lock-function-name-face t)
74                    '("\\s\"\\(\\S\"+\\)\\s\"\\s-*\\(=\\|<-\\)\\s-*function"
75                      1 font-lock-function-name-face t))
76              ess-R-mode-font-lock-keywords)))
77 #+END_SRC
78 *** Running
79     After performing the installation steps above, =M-- M-x slime RET R
80     RET= should start swank.  You will be prompted to accept a version
81     mismatch -- simply accept -- then the SLIME REPL should start up,
82     giving a prompt.  Enjoy!
83 * Development
84   swankr's primary development repository is a git repository,
85   accessible through
86   <http://common-lisp.net/r/users/crhodes/swankr.git> and
87   git://common-lisp.net/users/crhodes/swankr.git; a web view of the
88   development history is [[http://common-lisp.net/gitweb?p=users/crhodes/swankr.git][available through gitweb]].  You can also view
89   the current lists of [[file:BUGS.org]] and [[file:TODO.org]] items.
90 * Acknowledgments
91   Thanks to my colleagues at [[http://www.gold.ac.uk/][Goldsmiths, University of London]], for
92   suggesting that I investigate R for numerical and graphical
93   investigations, and to my colleagues at [[http://www.teclo.net/][Teclo Networks AG]] for giving
94   me motivation to get around to it.  Initial development was done at
95   the [[http://ismir2010.ismir.net/][International Symposium on Music Information Retrieval]], which I
96   attended (indirectly) thanks to the EPSRC-funded [[http://www.omras2.org/][OMRAS2]] research
97   project and the [[http://www.londoninternational.ac.uk][University of London External System]]; Helmut Eller's
98   partial implementation of swank for Ruby was an excellent blueprint
99   to get development started.
100 * Footnotes
101 [fn:1] part of SLIME, the Superior Lisp Interaction Mode for Emacs:
102 <http://common-lisp.net/project/slime/>.
103
104 [fn:2] a free software environment for statistical computing and
105 graphics: <http://www.r-project.org/>.
106
107 [fn:3] also known as ESS, an emacs mode for interacting with a number
108 of statistical software packages, including R:
109 <http://ess.r-project.org/>.
110 * COMMENT:
111 Local Variables:
112 mode: org;
113 End: