From ef10f15e9092a3f42406de34919e7c30150f75cf Mon Sep 17 00:00:00 2001 From: Christophe Rhodes Date: Thu, 26 Aug 2010 11:39:18 +0100 Subject: [PATCH] add README --- README | 93 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 93 insertions(+) create mode 100644 README diff --git a/README b/README new file mode 100644 index 0000000..e7ebd91 --- /dev/null +++ b/README @@ -0,0 +1,93 @@ +#+TITLE: swankr: SWANK (and SLIME) for R +#+AUTHOR: Christophe Rhodes +#+EMAIL: csr21@cantab.net +* Introduction + This is swankr, an implementation of the swank[fn:1] protocol for + R[fn:2]. While the coverage of swank protocol functions is + currently limited, enough is implemented for swankr to be useful: at + the very minimum, it can be used to develop and extend itself. +** Relationship with ESS + Emacs Speaks Statistics[fn:3] provides an interaction mode for R + (among other statistical software packages), including an interface + to R's toplevel, and keybindings to send input to R, to look up + documentation, and so on. Where it differs most noticeably from + swankr is in the level of integration of various facilities with + emacs: ESS uses the browser() debugger, whereas swankr provides its + own debugger, sldb; swankr provides a custom REPL with hooks for + common commands; and so on. For Lisp programmers, perhaps the most + useful analogy is to say that swankr is to ESS what SLIME is to + ILISP. At present, however, ESS mode remains active in R source + buffers, providing font-locking functionality among other things. +* Installation +** Running + To begin using swankr: + 1. start R; + 2. load the swank.R file: +#+BEGIN_SRC R + source("swank.R") +#+END_SRC + 3. at the R prompt, run +#+BEGIN_SRC R + swank(); +#+END_SRC + 4. within emacs, load and initialize slime; + 5. run slime-connect, accepting the default host and port, and + acknowledging the protocol version mismatch. + At this point, a R REPL should appear. +** Emacs customization + At a minimum, slime needs to be set up to function. I've + used the following forms in my =~/.emacs= +#+BEGIN_SRC emacs-lisp + (require 'slime) + (slime-setup '(slime-repl slime-scratch)) +#+END_SRCA + In addition, for keybindings like =C-c C-c= to work properly, emacs + needs to be told how to guess where a function definition begins. + This can be achieved with /e.g./ +#+BEGIN_SRC emacs-lisp + (add-hook 'ess-mode-hook + (lambda () + (setq defun-prompt-regexp "^\\(\\(\\sw\\|\\s_\\)+\\|\\s\"\\S\"+\\s\"\\)\\s-*\\(=\\|<-\\)\\s-*function\\s-*(.*)\\s-*"))) +#+END_SRC + Fontification of quoted function names is suboptimal by default in + ESS; the following form in =~/.emacs= fixes that for ESS 5.11. +#+BEGIN_SRC emacs-lisp + (eval-after-load "ess-common" + (setq ess-R-mode-font-lock-keywords + (append + (list '("\\(\\sw\\|\\s_\\)+\\s-*\\(=\\|<-\\)\\s-*function" + 1 font-lock-function-name-face t) + '("\\s\"\\(\\S\"+\\)\\s\"\\s-*\\(=\\|<-\\)\\s-*function" + 1 font-lock-function-name-face t)) + ess-R-mode-font-lock-keywords))) +#+END_SRC +* Development + swankr's primary development repository is a git repository, + accessible through + and + git://common-lisp.net/crhodes/swankr/swankr.git; a web view of the + development history is [[http://common-lisp.net/gitweb?p=users/crhodes/swankr.git][available through gitweb]]. +* Acknowledgments + Thanks to my colleagues at [[http://www.gold.ac.uk/][Goldsmiths, University of London]], for + suggesting that I investigate R for numerical and graphical + investigations, and to my colleagues at [[http://www.teclo.net/][Teclo Networks AG]] for giving + me motivation to get around to it. Initial development was done at + the [[http://ismir2010.ismir.net/][International Symposium on Music Information Retrieval]], which I + attended (indirectly) thanks to the EPSRC-funded [[http://www.omras2.org/][OMRAS2]] research + project and the [[http://www.londoninternational.ac.uk][University of London External System]]; Helmut Eller's + partial implementation of swank for Ruby was an excellent blueprint + to get development started. +* Footnotes +[fn:1] part of SLIME, the Superior Lisp Interaction Mode for Emacs: +. + +[fn:2] a free software environment for statistical computing and +graphics: . + +[fn:3] also known as ESS, an emacs mode for interacting with a number +of statistical software packages, including R: +. +* COMMENT: +Local Variables: +mode: org; +End: -- 2.30.2