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     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
  30 #+begin_src sh
  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
  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")
  51            :init (lambda (port-filename coding-system)
  52                    (format
  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)
  55 #+end_src
  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
  62      (lambda ()
  63        (setq defun-prompt-regexp "^\\(\\(\\sw\\|\\s_\\)+\\|\\s\"\\S\"+\\s\"\\)\\s-*\\(=\\|<-\\)\\s-*function\\s-*(.*)\\s-*")))
  64 #+END_SRC
  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
  70            (append
  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)))
  76 #+END_SRC
  77 *** Running
  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 ]
  85
  86    To begin using swankr:
  87
  88    1. start R;
  89    2. load the swank.R file:
  90 #+BEGIN_SRC R
  91       source("swank.R")
  92 #+END_SRC
  93    3. at the R prompt, run
  94 #+BEGIN_SRC R
  95       swank();
  96 #+END_SRC
  97    4. within emacs, load and initialize slime;
  98 #+BEGIN_SRC emacs-lisp
  99       (require 'slime)
 100       (slime-setup '(slime-repl slime-presentations slime-media))
 101 #+END_SRC
 102    5. run =M-x slime-connect=, accepting the default host and port,
 103       and acknowledging the protocol version mismatch.
 104
 105    At this point, an R REPL should appear.
 106 * Development
 107   swankr's primary development repository is a git repository,
 108   accessible through
 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.
 113 * Acknowledgments
 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.
 123 * Footnotes
 124 [fn:1] part of SLIME, the Superior Lisp Interaction Mode for Emacs:
 125 <http://common-lisp.net/project/slime/>.
 126
 127 [fn:2] a free software environment for statistical computing and
 128 graphics: <http://www.r-project.org/>.
 129
 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/>.
 133 * COMMENT:
 134 Local Variables:
 135 mode: org;
 136 End: