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    1. start R;
  27    2. load the swank.R file:
  28 #+BEGIN_SRC R
  29       source("swank.R")
  30 #+END_SRC
  31    3. at the R prompt, run
  32 #+BEGIN_SRC R
  33       swank();
  34 #+END_SRC
  35    4. within emacs, load and initialize slime;
  36    5. run slime-connect, accepting the default host and port, and
  37       acknowledging the protocol version mismatch.
  38    At this point, a R REPL should appear.
  39 ** Emacs customization
  40    At a minimum, slime needs to be set up to function.  I've
  41    used the following forms in my =~/.emacs=
  42 #+BEGIN_SRC emacs-lisp
  43    (require 'slime)
  44    (slime-setup '(slime-repl slime-scratch))
  45 #+END_SRCA
  46    In addition, for keybindings like =C-c C-c= to work properly, emacs
  47    needs to be told how to guess where a function definition begins.
  48    This can be achieved with /e.g./
  49 #+BEGIN_SRC emacs-lisp
  50    (add-hook 'ess-mode-hook
  51      (lambda ()
  52        (setq defun-prompt-regexp "^\\(\\(\\sw\\|\\s_\\)+\\|\\s\"\\S\"+\\s\"\\)\\s-*\\(=\\|<-\\)\\s-*function\\s-*(.*)\\s-*")))
  53 #+END_SRC
  54    Fontification of quoted function names is suboptimal by default in
  55    ESS; the following form in =~/.emacs= fixes that for ESS 5.11.
  56 #+BEGIN_SRC emacs-lisp
  57    (eval-after-load "ess-common"
  58      (setq ess-R-mode-font-lock-keywords
  59            (append
  60              (list '("\\(\\sw\\|\\s_\\)+\\s-*\\(=\\|<-\\)\\s-*function"
  61                      1 font-lock-function-name-face t)
  62                    '("\\s\"\\(\\S\"+\\)\\s\"\\s-*\\(=\\|<-\\)\\s-*function"
  63                      1 font-lock-function-name-face t))
  64              ess-R-mode-font-lock-keywords)))
  65 #+END_SRC
  66 * Development
  67   swankr's primary development repository is a git repository,
  68   accessible through
  69   <http://common-lisp.net/r/users/crhodes/swankr.git> and
  70   git://common-lisp.net/crhodes/swankr/swankr.git; a web view of the
  71   development history is [[http://common-lisp.net/gitweb?p=users/crhodes/swankr.git][available through gitweb]].
  72 * Acknowledgments
  73   Thanks to my colleagues at [[http://www.gold.ac.uk/][Goldsmiths, University of London]], for
  74   suggesting that I investigate R for numerical and graphical
  75   investigations, and to my colleagues at [[http://www.teclo.net/][Teclo Networks AG]] for giving
  76   me motivation to get around to it.  Initial development was done at
  77   the [[http://ismir2010.ismir.net/][International Symposium on Music Information Retrieval]], which I
  78   attended (indirectly) thanks to the EPSRC-funded [[http://www.omras2.org/][OMRAS2]] research
  79   project and the [[http://www.londoninternational.ac.uk][University of London External System]]; Helmut Eller's
  80   partial implementation of swank for Ruby was an excellent blueprint
  81   to get development started.
  82 * Footnotes
  83 [fn:1] part of SLIME, the Superior Lisp Interaction Mode for Emacs:
  84 <http://common-lisp.net/project/slime/>.
  85
  86 [fn:2] a free software environment for statistical computing and
  87 graphics: <http://www.r-project.org/>.
  88
  89 [fn:3] also known as ESS, an emacs mode for interacting with a number
  90 of statistical software packages, including R:
  91 <http://ess.r-project.org/>.
  92 * COMMENT:
  93 Local Variables:
  94 mode: org;
  95 End: