ESS version 5.3.8
by A.J. Rossini,
R.M. Heiberger,
K. Hornik,
M. Maechler,
R.A. Sparapani
and S.J. Eglen.
Emacs Speaks Statistics (ESS) provides an intelligent, consistent interface between the user and the software. ESS interfaces with SAS, S-PLUS, R, BUGS/JAGS and other statistical analysis packages under the Unix, Microsoft Windows, and Apple Mac operating systems. ESS is itself a package within the emacs text editor and uses emacs features to streamline the creation and use of statistical software. ESS knows the syntax and grammar of statistical analysis packages and provides consistent display and editing features based on that knowledge. ESS assists in interactive and batch execution of statements written in these statistical analysis languages.
The S family (S, Splus and R) and SAS statistical analysis packages provide sophisticated statistical and graphical routines for manipulating data. Emacs Speaks Statistics (ESS) is based on the merger of two pre-cursors, S-mode and SAS-mode, which provided support for the S family and SAS respectively. Later on, Stata-mode was also incorporated.
ESS provides a common, generic, and useful interface, through emacs, to many statistical packages. It currently supports the S family, SAS, BUGS/JAGS, Stata and XLisp-Stat with the level of support roughly in that order.
A bit of notation before we begin. emacs refers to both
GNU Emacs by the Free Software Foundation, as well as
XEmacs by the XEmacs Project. The emacs major
mode ESS[language], where language can take values such as
S, SAS, or XLS. The inferior process interface
(the connection between emacs and the running process) referred to as inferior ESS
(iESS), is denoted in the modeline by ESS[dialect], where
dialect can take values such as S3, S4, S+3,
S+4, S+5, S+6, S+7, R, XLS, VST, SAS.
Currently, the documentation contains many references to `S' where actually any supported (statistics) language is meant, i.e., `S' could also mean `XLisp-Stat' or `SAS'.
For exclusively interactive users of S, ESS provides a number of features to make life easier. There is an easy to use command history mechanism, including a quick prefix-search history. To reduce typing, command-line completion is provided for all S objects and “hot keys” are provided for common S function calls. Help files are easily accessible, and a paging mechanism is provided to view them. Finally, an incidental (but very useful) side-effect of ESS is that a transcript of your session is kept for later saving or editing.
No special knowledge of Emacs is necessary when using S interactively under ESS.
For those that use S in the typical edit–test–revise cycle when programming S functions, ESS provides for editing of S functions in Emacs edit buffers. Unlike the typical use of S where the editor is restarted every time an object is edited, ESS uses the current Emacs session for editing. In practical terms, this means that you can edit more than one function at once, and that the ESS process is still available for use while editing. Error checking is performed on functions loaded back into S, and a mechanism to jump directly to the error is provided. ESS also provides for maintaining text versions of your S functions in specified source directories.
Statistical packages are powerful software systems for manipulating and analyzing data, but their user interfaces often leave something something to be desired: they offer weak editor functionality and they differ among themselves so markedly that you have to re-learn how to do those things for each package. ESS is a package which is designed to make editing and interacting with statistical packages more uniform, user-friendly and give you the power of emacs as well.
ESS provides several features which make it easier to interact with the ESS process (a connection between your buffer and the statistical package which is waiting for you to input commands). These include:
tcsh's facility for filenames; here it
also applies to object names and list components.
See Completion.
objects() and search().
See Hot keys.
If you commonly create or modify S functions, you will have found the standard facilities for this (the `fix()' function, for example) severely limiting. Using S's standard features, one can only edit one function at a time, and you can't continue to use S while editing. ESS corrects these problems by introducing the following features:
Finally, ESS provides features for re-submitting commands from saved transcript files, including:
Changes/New Features in 5.3.8:
Changes/New Features in 5.3.7:
ess-default-style now *is* customizable, i.e.,
changing its value in ~/.emacs now does have the desired effect.
ess-font-lock-mode is a new variable (default: t)
which controls whether font-locking is enabled in ESS buffers.
ess-sas-submit-command-options which is buffer-local; portable
snooze for MS Windows via customize-able ess-sleep-for (floats welcome);
Xpdf now supported as a PDF viewer
ess-continued-statement-p for R and S.
Rgui
on MS Windows to send lines directly from emacs
to Rgui is available in file lisp/essd-rgui.el.
Preliminary documentation is in file doc/rgui-doc.txt.
Changes/New Features in 5.3.6:
Changes/New Features in 5.3.5:
R-mode
which is active by default and can be customized via
ess-r-args-electric-paren; i.e., use (setq
ess-r-args-electric-paren nil) to turn it off. Further,
ess-r-args-show-as allows to switch to the “tooltip” mode.
ess-get-pdf-viewer and *-ps-viewer; built on new
customizable variables ess-pdf-viewer-pref and
ess-ps-viewer-pref; currently used in ess-swv-PDF and
*-PS.
ess-swv-PDF to run pdf viewer only if
pdflatex was ok
ess-swv-weave to start R automatically if
none is running.
Changes/New Features in 5.3.4:
Changes/New Features in 5.3.3:
ess-display-buffer-reuse-frames
set to true (which changes default behavior) such that execution or
help *frames* are reused.
Changes/New Features in 5.3.2:
(require 'essd-bugs) with ESS[BUGS]
and JAGS by (require 'essd-jags) with ESS[JAGS]. But, only one
of them can be used at a time since they don't play nice together. Also,
C-c C-c is now bound to the function ess-bugs-next-action
(F12 has been retired). And finally, note that essl-bug.el
is deprecated and the replacement is essl-bugs.el.
Changes/New Features in 5.3.1:
make install
ess-assign-key is now C-x =.
RSiteSearch(..) but with the advantage of
using Emacs' preferred browser, see browse-url-browser-function
Changes/New Features in 5.3.0:
ess-use-inferior-program-name-in-buffer-name,
which enables using the executable name instead of the dialect name for
R. Feature request.
ess-eval-paragraph-and-step and
ess-eval-function-or-paragraph-and-step are bound to keys
C-c C-p and C-c C-c respectively and to the menu in
ESS-mode; also bound in the help mode (for evaluating examples).
ess-toggle-S-assign-key allows to
assign the “ <- ” insertion to an arbitrary key.
Changes/New Features in 5.2.12:
comment-dwim
may be broken, if so, use M-x comment-region and M-x
uncomment-region instead; only valid PROCs are fontified which is very
helpful finding syntax errors (currently supported: BASE, ETS, FSP, GRAPH,
IML, INSIGHT and STAT); the “feature” where F-keys take you to an
empty buffer when the requested destination is a file that does not exist
has been fixed, now the request results in a no-op.
Further, sas-mode now also works in simple terminals.
Changes/New Features in 5.2.11:
ess-sas-file-root
for details; all lag and dif functions now fontified correctly
ess-s-versions and
ess-s-versions-list, are used to tell ESS what other versions of
Splus you would like to run.
Changes/New Features in 5.2.10:
make install
Changes/New Features in 5.2.9:
ess-beginning-of-function) etc now work for many more
cases, including S4 method definitions.
options("help.try.all.packages" =
TRUE) then ?rlm will list which packages rlm is defined in. This help
buffer is not bogus, but instead is now relabelled “*help[R](rlm in
packages)*”.
Changes/New Features in 5.2.8:
Changes/New Features in 5.2.7:
Changes/New Features in 5.2.6:
Changes/New Features in 5.2.5:
(ess-cleanup), called from
ess-quit, now depends on the new customizable variable
ess-S-quit-kill-buffers-p which defaults to nil.
Consequently, the question “Delete all buffers associated
with ..?” will not be asked anymore by default.
recode application as well which is available on many platforms
Changes/New Features in 5.2.4:
dd command (only available on unix or unix-like platforms).
ess-create-object-name-db) since modern computers seem fast
enough for dynamic completion. (We expect few users, if any, have
been using the pre-computed database method.)
Changes/New Features in 5.2.3:
Changes/New Features in 5.2.2:
Changes/New Features in 5.2.1:
Changes/New Features in 5.2.0:
Changes/New Features in 5.1.24:
Changes/New Features in 5.1.23:
Changes/New Features in 5.1.22:
Changes/New Features in 5.1.21:
Changes/New Features in 5.1.20:
Changes/New Features in 5.1.19:
Changes/New Features in 5.1.18:
Changes/New Features in 5.1.17:
Changes/New Features in 5.1.16:
Changes/New Features in 5.1.15:
Changes/New Features in 5.1.14:
Changes/New Features in 5.1.13:
Changes/New Features in 5.1.12:
Changes/New Features in 5.1.11:
Changes/New Features in 5.1.10:
Changes/New Features in 5.1.9:
Changes/New Features in 5.1.8:
Changes/New Features in 5.1.2:
The ESS environment is built on the open-source projects of many contributors, dating back to 1989 where Doug Bates and Ed Kademan wrote S-mode to edit S and Splus files in GNU Emacs. Frank Ritter and Mike Meyer added features, creating version 2. Meyer and David Smith made further contributions, creating version 3. For version 4, David Smith provided significant enhancements to allow for powerful process interaction.
John Sall wrote GNU Emacs macros for SAS source code around 1990. Tom Cook added functions to submit jobs, review listing and log files, and produce basic views of a dataset, thus creating a SAS-mode which was distributed in 1994.
In 1994, A.J. Rossini extended S-mode to support XEmacs. Together with extensions written by Martin Maechler, this became version 4.7 and supported S, Splus, and R. In 1995, Rossini extended SAS-mode to work with XEmacs.
In 1997, Rossini merged S-mode and SAS-mode into a single Emacs package for statistical programming; the product of this marriage was called ESS version 5. Richard M. Heiberger designed the inferior mode for interactive SAS and SAS-mode was further integrated into ESS. Thomas Lumley's Stata mode, written around 1996, was also folded into ESS. More changes were made to support additional statistical languages, particularly XLispStat.
ESS initially worked only with Unix statistics packages that used standard-input and standard-output for both the command-line interface and batch processing. ESS could not communicate with statistical packages that did not use this protocol. This changed in 1998 when Brian Ripley demonstrated use of the Windows Dynamic Data Exchange (DDE) protocol with ESS. Heiberger then used DDE to provide interactive interfaces for Windows versions of Splus. In 1999, Rodney A. Sparapani and Heiberger implemented SAS batch for ESS relying on files, rather than standard-input/standard-output, for Unix, Windows and Mac. In 2001, Sparapani added BUGS batch file processing to ESS for Unix and Windows.
ess-eval-line-and-next-line are by Rod Ball.
ESS version 5 is being developed and currently maintained by
The latest released version of ESS is always available on the web at: ESS web page or StatLib
The latest development version of ESS is available via https://svn.R-project.org/ESS/, the ESS Subversion repository. If you have a Subversion client (see http://subversion.tigris.org/), you can download the sources using:
% svn checkout https://svn.r-project.org/ESS/trunk path
which will put the ESS files into directory path. Later, within that directory, `svn update' will bring that directory up to date. Windows-based tools such as TortoiseSVN are also available for downloading the files. Alternatively, you can browse the sources with a web browser at: ESS SVN site. However, please use a subversion client instead to minimize the load when retrieving.
If you remove other versions of ESS from your emacs load-path, you can then use the development version by adding the following to .emacs:
(load "/path/to/ess-svn/lisp/ess-site.el")
Note that https is required, and that the SSL certificate for the Subversion server of the R project is
Certificate information:
- Hostname: svn.r-project.org
- Valid: from Jul 16 08:10:01 2004 GMT until Jul 14 08:10:01 2014 GMT
- Issuer: Department of Mathematics, ETH Zurich, Zurich, Switzerland, CH
- Fingerprint: c9:5d:eb:f9:f2:56:d1:04:ba:44:61:f8:64:6b:d9:33:3f:93:6e:ad
(currently, there is no “trusted certificate”). You can accept this certificate permanently and will not be asked about it anymore.
If you need to install ESS, read Installation for details on what needs to be done before proceeding to the next chapter.
In this manual we use the standard notation for describing the keystrokes used to invoke certain commands. C-<chr> means hold the CONTROL key while typing the character <chr>. M-<chr> means hold the META or EDIT or ALT key down while typing <chr>. If there is no META, EDIT or ALT key, instead press and release the ESC key and then type <chr>.
All ESS commands can be invoked by typing M-x command. Most of the useful commands are bound to keystrokes for ease of use. Also, the most popular commands are also available through the emacs menubar, and finally, if available, a small subset are provided on the toolbar. Where possible, keybindings are similar to other modes in emacs to strive for a consistent user interface within emacs, regardless of the details of which programming language is being edited, or process being run.
Some commands, such as M-x R can accept an optional `prefix' argument. To specify the prefix argument, you would type C-u before giving the command. e.g. If you type C-u M-x R, you will be asked for command line options that you wish to invoke the R process with.
Emacs is often referred to as a `self-documenting' text editor. This applies to ESS in two ways. First, limited documentation about each ESS command can be obtained by typing C-h f. For example, if you type C-h f ess-eval-region, documentation for that command will appear in a separate *Help* buffer. Second, a complete list of keybindings that are available in each ESS mode and brief description of that mode is available by typing C-h m within an ESS buffer.
Emacs is a versatile editor written in both C and lisp; ESS is written in the Emacs lisp dialect (termed `elisp') and thus benefits from the flexible nature of lisp. In particular, many aspects of ESS behaviour can be changed by suitable customization of lisp variables. This manual mentions some of the most frequent variables. A full list of them however is available by using the Custom facility within emacs. (Type M-x customize-group RET ess RET to get started.) Customization provides details of common user variables you can change to customize ESS to your taste, but it is recommended that you defer this section until you are more familiar with ESS.
The following section details those steps necessary to get ESS running on your system.
cd to a directory where you keep emacs lisp files, or create a
new directory (for example, $HOME/emacs) to hold the distribution.
This directory will be referred to below as "the ESS distribution
directory".
Note for XEmacs packages: ESS is no longer available as an XEmacs package. But, you can still install ESS into the XEmacs package system by choosing ESSDIR=PREFIX/lib/xemacs/site-packages. ESS requires that the XEmacs sumo tarball (all XEmacs packages combined) also be installed. For information on installing XEmacs packages, follow this link: Quickstart Package Guide.
If you are using GNU tar,tar zxf ess-VERSION.tgz. Otherwise,gunzip < ess-VERSION.tgz | tar xf -,
The tar command will create the subdirectory ess-VERSION and install
the files there.
(load "ESSDIR/ess-VERSION/lisp/ess-site")
to $HOME/.emacs. For XEmacs, if you followed the XEmacs package system installation advice, add the line
(require 'ess-site)
to $HOME/.xemacs/init.el. Otherwise, for XEmacs, add the line
(load "ESSDIR/ess-VERSION/lisp/ess-site")
to $HOME/.xemacs/init.el.
M-x R.
If you want to place the compiled files in other locations edit the
LISPDIR, INFODIR and ETCDIR entries in Section 1 of
Makeconf in the ESSDIR/ess-VERSION directory (if you are
using XEmacs, then uncomment the XEmacs subsection in Section 1).
You can compile those files by:
make all
When that completes successfully, install the compiled files:
make install
For Microsoft Windows installation, please follow the next steps.
cd to a directory where you keep emacs lisp files, or create a
new directory (for example, c:\emacs\) to hold the distribution.
This directory will be referred to below as "the ESS distribution
directory".
Note for XEmacs packages: ESS is no longer available as an XEmacs package. But, you can still install ESS into the XEmacs package system by choosing ESSDIR=PREFIX\XEmacs\site-packages. ESS requires that the XEmacs sumo tarball (all XEmacs packages combined) also be installed. For information on installing XEmacs packages, follow this link: Quickstart Package Guide.
(load "ESSDIR/ess-VERSION/lisp/ess-site")
to %HOME%/.emacs. For XEmacs, if you followed the XEmacs package system installation advice, add the line
(require 'ess-site)
to %HOME%/.xemacs/init.el. Otherwise, for XEmacs, add the line
(load "ESSDIR/ess-VERSION/lisp/ess-site")
to %HOME%/.xemacs/init.el. Note: Both GNU Emacs and XEmacs require that the HOME environment variable be set on your system, otherwise, your initialization file will not be utilized, and therefore, ESS will not work.
After saving your initialization file, ESS is now installed. Start a new emacs and you should be ready to use ESS. For example, to edit statistical programs, load the files with the requisite extensions (".sas" for SAS, ".S" or "s" or "q" or "Q" for S-PLUS, ".r" or ".R" for R, and ".lsp" for XLispStat). One further step is needed if you wish to run statistical processes, see below.
path=%PATH%;c:\progra~1\insightful\splus70\cmd
On Windows NT/2000/XP, add the directories to the PATH using the
My Computer/Control Panel/System/Advanced/Environment Variables menu.
Note that the directory containing the program is
added to the PATH, not the program itself. One such line is needed
for each software program. Be sure to use the abbreviation
progra~1 and not the long version with embedded blanks. Use
backslashes "\".
An alternative, for R users, is that rather than adjusting the PATH variable, you can add the following to your emacs initialization file (and restart emacs):
(setq inferior-R-program-name "C:/progra~1/R/R-2.2.1/bin/Rterm.exe")
This assumes that you have installed R-2.2.1 in the default location. Change the path otherwise to point to other locations.
Windows users who place S-PLUS anywhere other than the default location will also need to add the following three lines (properly adjusted for their location) to their %HOME%/.emacs or %HOME%/.xemacs/init.el file:
(setq-default inferior-S+6-program-name
"c:/progra~1/Insightful/SPLUS70/cmd/Splus")
(setq-default inferior-Sqpe+6-SHOME-name
"c:/progra~1/Insightful/SPLUS70")
(setq-default inferior-Sqpe+6-program-name
"c:/progra~1/Insightful/SPLUS70/cmd/Sqpe.exe")
The above example uses the default location of S-PLUS in
c:/progra~1/Insightful. Please note that ESS
considers S-PLUS 6, 7, and 8 to be variants of S+6.
These users may also need to modify the emacs variable ess-SHOME-versions
to match their installation in order to get the full set of S-PLUS versions
on their machine into the ESS menu.
To start the S-PLUS [678].x GUI from ESS under emacs:
M-x S
(or M-x S+6).
M-x S+6-msdos
C-c C-n or C-c C-r keys.
(If you are still using S-PLUS 4.x or 2000,\
then use M-x S+4 or M-x S+4-msdos.)
To start an S-PLUS [678].x session inside an emacs buffer—and without the S-PLUS GUI:
M-x Sqpe
(or M-x Sqpe+6).
This works with both the bash and msdos shells.
You will then be asked for a pathname ("S starting data
directory?"), from which to start the process. The prompt will
propose your current directory as the default.
You get Unix-like behavior, in particular the entire
transcript is available for emacs-style search commands.
Send lines or regions from the emacs buffer containing your S
program (for example, myfile.s) to the *S+6* buffer with the
C-c C-n or C-c C-r keys.
Interactive graphics are available with Sqpe by using the java
library supplied with S-PLUS 6.1 and newer releases.
Enter the commands:
library(winjava)
java.graph()
Graphs can be saved from the java.graph device
in several formats, but not PostScript. If you
need a PostScript file you will need to open a separate
postscript device.
(If you are still using S-PLUS 4.x or 2000, then use M-x Sqpe+4.)
To connect to an already running S-PLUS GUI (started, for example, from the S-PLUS icon):
M-x S+6-existing
or
M-x S+6-msdos-existing
You will then be
asked for a pathname ("S starting data directory?"), from which to
start the process. The prompt will propose your current directory
as the default. ESS will arrange for
communication with the already running S-PLUS GUI using the DDE protocol.
Send lines or regions
from the emacs buffer containing your S program (for example,
myfile.s) to the S-PLUS Commands Window with the
C-c C-n or C-c C-r keys.
(If you are still using S-PLUS 4.x or 2000,
then use M-x S+4-existing or M-x S+4-msdos-existing.)
If you wish to run R, you can start it with:
M-x R
XLispStat can not currently be run with
M-x XLS
Hopefully, this will change. However, you can still edit with emacs, and cut and paste the results into the XLispStat *Listener* Window under Microsoft Windows.
ESS has been tested with
on the following platforms
with the following versions of emacs
As well as using ESS to edit your source files for statistical programs, you can use ESS to run these statistical programs. In this chapter, we mostly will refer by example to running S from within emacs. The emacs convention is to name such processes running under its control as `inferior processes'. This term can be slightly misleading, in which case these processes can be thought of `interactive processes'. Either way, we use the term `iESS' to refer to the Emacs mode used to interact with statistical programs.
To start an S session on Unix or on Windows when you use the Cygwin bash shell, simply type M-x S RET.
To start an S session on Windows when you use the MSDOS prompt shell, simply type M-x S+6-msdos RET.
S will then (by default) ask the question
S starting data directory?
Enter the name of the directory you wish to start S from (that is,
the directory you would have cd'd to before starting S from
the shell). This directory should have a .Data subdirectory.
You will then be popped into a buffer with name `*S*' which will be used for interacting with the ESS process, and you can start entering commands.
ESS allows you to run more than one ESS process simultaneously in the same session. Each process has a name and a number; the initial process (process 1) is simply named (using S-PLUS as an example) `S+3:1'. The name of the process is shown in the mode line in square brackets (for example, `[S+3:2]'); this is useful if the process buffer is renamed. Without a prefix argument, M-x S starts a new ESS process, using the first available process number. With a prefix argument (for R), C-u M-x R allows for the specification of command line options.
You can switch to any active ESS process with the command `M-x ess-request-a-process'. Just enter the name of the process you require; completion is provided over the names of all running S processes. This is a good command to consider binding to a global key.
ESS works with processes on remote computers as easily as with processes on the local machine. The recommended way to access a statistical program on remote computer is to start it from a telnet or ssh buffer and then connect ESS to that buffer.
Should you or a colleague inadvertently start a statistical process in an ordinary `*shell*' buffer, the `ess-remote' command can be used to convert it to an ESS buffer and allow you to use the ESS commands with it.
We have two older commands, now deprecated, for accessing ESS processes on remote computers. See S+elsewhere and ESS-elsewhere.
These commands are now deprecated. We recommend `ess-remote'. We have two versions of the elsewhere function. `S+elsewhere' is specific for the S-Plus program. The more general function `ESS-elsewhere' is not as stable.
Or enter `M-x ESS-elsewhere'. You will be prompted for an ESS program and for a starting directory. I usually give it my project directory on the local machine, say `~myname/myproject/'
If you do not wish ESS to prompt for a starting directory when starting
a new process, set the variable ess-ask-for-ess-directory to
nil. In this case, the starting directory will be set using
one of the following methods:
ess-directory-function stores the name of a
function, the value returned by this function is used. The default for
this variable is nil.
ess-directory stores the name of a
directory (ending in a slash), this value is used. The default for this
variable is nil.
If ess-ask-for-ess-directory has a non-nil value (as it
does by default) then the value determined by the above rules provides
the default when prompting for the starting directory. Incidentally,
ess-directory is an ideal variable to set in
ess-pre-run-hook.
If you like to keep a record of your S sessions, set the variable
ess-ask-about-transfile to t, and you will be asked for a
filename for the transcript before the ESS process starts.
If non-
nil, as for a file name in which to save the session transcript.
Enter the name of a file in which to save the transcript at the prompt. If the file doesn't exist it will be created (and you should give it a file name ending in `.St'); if the file already exists the transcript will be appended to the file. (Note: if you don't set this variable but you still want to save the transcript, you can still do it later — see Saving transcripts.)
Once these questions are answered (if they are asked at all) the S
process itself is started by calling the program name specified in the
variable inferior-ess-program.
If you need to pass any arguments to this program, they may be specified
in the variable inferior-S_program_name-args (e.g. if
inferior-ess-program is "S+" then the variable to set is
inferior-S+-args.
It is not normally necessary to pass arguments to the S program; in
particular do not pass the `-e' option to Splus, since ESS
provides its own command history mechanism.
By default, the new process will be displayed in the same window in the
current frame. If you wish your S process to appear in a separate
variable, customize the variable inferior-ess-own-frame.
Alternatively, change inferior-ess-same-window if you wish the
process to appear within another window of the current frame.
The primary function of the ESS package is to provide an easy-to-use front end to the S interpreter. This is achieved by running the S process from within an Emacs buffer, so that the Emacs editing commands are available to correct mistakes in commands, etc. The features of Inferior S mode are similar to those provided by the standard Emacs shell mode (see Shell Mode). Command-line completion of S objects and a number of `hot keys' for commonly-used S commands are also provided for ease of typing.
Sending a command to the ESS process is as simple as typing it in and pressing the <RETURN> key:
If you make a typing error before pressing RET all the usual Emacs editing commands are available to correct it (see Basic). Once the command has been corrected you can press <RETURN> (even if the cursor is not at the end of the line) to send the corrected command to the ESS process.
ESS provides some other commands which are useful for fixing mistakes:
backward-kill-word) comint-kill-input) comint-bol) See Shell Mode, for other commands relevant to entering input.
In the process buffer, the <TAB> key is for completion, similar to that provided by Shell Mode for filenames. In Inferior S mode, pressing the <TAB> key when the cursor is following the first few characters of an object name completes the object name; if the cursor is following a file name TAB completes the file name.
When the cursor is just after a partially-completed object name,
pressing <TAB> provides completion in a similar fashion to
tcsh
except that completion is performed over all known S object names
instead of file names. ESS maintains a list of all objects known to S
at any given time, which basically consists of all objects (functions
and datasets) in every attached directory listed by the search()
command
along with the component objects of attached data frames
(if your version of S supports them).
For example, consider the three functions (available in Splus version
3.0) called binomplot(), binom.test() and
binomial(). Typing bin TAB after the S prompt will
insert the characters `om', completing the longest prefix
(`binom') which distinguishes these three commands. Pressing
TAB once more provides a list of the three commands which have
this prefix, allowing you to add more characters (say, `.') which
specify the function you desire. After entering more characters
pressing TAB yet again will complete the object name up to
uniqueness, etc. If you just wish to see what completions exist without
adding any extra characters, type M-?.
ESS also provides completion over the components of named lists accessed
using the `$' notation, to any level of nested lists. This feature
is particularly useful for checking what components of a list object
exist while partway through entering a command: simply type the object
name and `$' and press TAB to see the names of existing list
components for that object.
Completion is also provided over file names, which is particularly
useful when using S functions such as get() or scan()
which require fully expanded file names. Whenever the cursor is within
an S string, pressing TAB completes the file name before
point, and also expands any `~' or environment variable references.
If the cursor is not in a string and does not follow a (partial) object name, the <TAB> key has a third use: it expands history references. See History expansion.
ESS automatically keeps track of any objects added or deleted to the system (such as new objects created, or directories added to the search list) to make completion as accurate as possible. Whenever ESS notices that search list has changed 2 when you attach a directory or data frame, the objects associated with it immediately become available for a completion; when it is detached completion is no longer available on those objects.
To maintain a list of accessible objects for completion, ESS needs to
determine which objects are contained in each directory or data frame on
the search list. This is done at the start of each S session, by
running the objects() command on every element of the search
list.
Efficiency in completion is gained by maintaining a cache of objects currently known to S; when a new object becomes available or is deleted, only one component of the cache corresponding to the associated directory needs to be refreshed. If ESS ever becomes confused about what objects are available for completion (such as when if refuses to complete an object you know is there), the command M-x ess-resynch forces the entire cache to be refreshed, which should fix the problem.
Most of the time, the cursor spends most of its time at the bottom of the ESS process buffer, entering commands. However all the input and output from the current (and previous) ESS sessions is stored in the process buffer (we call this the transcript) and often we want to move back up through the buffer, to look at the output from previous commands for example.
Within the process buffer, a paragraph
is defined as the prompt, the command after the prompt, and the output
from the command. Thus M-{ and M-} move you backwards and
forwards, respectively, through commands in the transcript. A
particularly useful command is M-h (mark-paragraph) which
will allow you to mark a command and its entire output (for deletion,
perhaps). For more information about paragraph commands,
see Paragraphs.
If an ESS process finishes and you restart it in the same process buffer, the output from the new ESS process appears after the output from the first ESS process separated by a form-feed (`^L') character. Thus pages in the ESS process buffer correspond to ESS sessions. Thus, for example, you may use C-x [ and C-x ] to move backward and forwards through ESS sessions in a single ESS process buffer. For more information about page commands, see Pages.
Viewing the output of the command you have just entered is a common occurrence and ESS provides a number of facilities for doing this. Whenever a command produces a longish output, it is possible that the window will scroll, leaving the next prompt near the middle of the window. The first part of the command output may have scrolled off the top of the window, even though the entire output would fit in the window if the prompt were near the bottom of the window. If this happens, you can use the command
comint-show-maximum-output) to make more of the last output visible. (To make this happen
automatically for all inputs, set the variable
comint-scroll-to-bottom-on-input to t.)
If the first part of the output is still obscured, use
comint-show-output) to view it. Finally, if you want to discard the last command output altogether, use
to delete it. Use this command judiciously to keep your transcript to a more manageable size.
If you want to view the output from more historic commands than the previous command, commands are also provided to move backwards and forwards through previously entered commands in the process buffer:
comint-previous-input) comint-next-input) Note that these two commands are analogous to C-p and C-n but apply to command lines rather than text lines. And just like C-p and C-n, passing a prefix argument to these commands means to move to the ARG'th next (or previous) command. (These commands are also discussed in Shell History Copying.)
There are also two similar commands (not bound to any keys by default) which move to preceding or succeeding commands, but which first prompt for a regular expression (see Syntax of Regular Expression), and then moves to the next (previous) command matching the pattern.
(comint-backward-matching-input regexp arg) (comint-forward-matching-input regexp arg) When moving through the transcript, you may wish to re-execute some of the commands you find there. ESS provides three commands to do this; these commands may be used whenever the cursor is within a command line in the transcript (if the cursor is within some command output, an error is signalled). Note all three commands involve the <RETURN> key.
inferior-ess-send-input) comint-copy-old-input) ess-transcript-send-command-and-move) When the cursor is not after the current prompt, the <RETURN> key has a slightly different behavior than usual. Pressing RET on any line containing a command that you entered (i.e. a line beginning with a prompt) sends that command to the ESS process once again. If you wish to edit the command before executing it, use C-c RET instead; it copies the command to the current prompt but does not execute it, allowing you to edit it before submitting it.
These two commands leave the cursor at the new command line, allowing you to continue with interactive use of S. If you wish to resubmit a series of commands from the transcript, consider using M-RET instead, which leaves the cursor at the command line following the one you re-submitted. Thus by using M-RET repeatedly, you can re-submit a whole series of commands.
These commands work even if if the current line is a continuation line (i.e. the prompt is `+' instead of `>') — in this case all the lines that form the multi-line command are concatenated together and the resulting command is sent to the ESS process (currently this is the only way to resubmit a multi-line command to the ESS process in one go). If the current line does not begin with a prompt, an error is signalled. This feature, coupled with the command-based motion commands described above, could be used as a primitive history mechanism. ESS provides a more sophisticated mechanism, however, which is described in Command History.
To keep a record of your S session in a disk file, use the Emacs
command C-x C-w (write-file) to attach a file to the
ESS process buffer. The name of the process buffer will (probably)
change to the name of the file, but this is not a problem. You can
still use S as usual; just remember to save the file before you quit
Emacs with C-x C-s. You can make ESS prompt you for a filename in
which to save the transcript every time you start S by setting the
variable
ess-ask-about-transfile to t; see Customizing startup.
We recommend you save your transcripts with filenames that end in
`.St'. There is a special mode (ESS transcript mode —
see Transcript Mode) for editing transcript files which is
automatically selected for files with this suffix.
S transcripts can get very large, so some judicious editing is appropriate if you are saving it in a file. Use C-c C-o whenever a command produces excessively long output (printing large arrays, for example). Delete erroneous commands (and the resulting error messages or other output) by moving to the command (or its output) and typing M-h C-w. Also, remember that C-c C-e (and other hot keys) may be used for commands whose output you do not wish to appear in the transcript. These suggestions are appropriate even if you are not saving your transcript to disk, since the larger the transcript, the more memory your Emacs process will use on the host machine.
Finally, if you intend to produce S source code (suitable for using
with source() or inclusion in an S function) from a
transcript, then the command M-x ess-transcript-clean-region may
be of use.
This command works in any Emacs buffer, and removes all prompts and
command output from an ESS transcript within the current region, leaving
only the commands. Don't forget to remove any erroneous commands first!
ESS provides easy-to-use facilities for re-executing or editing previous
commands. An input history of the last few commands is maintained (by
default the last 50 commands are stored, although this can be changed by
setting the variable comint-input-ring-size in
inferior-ess-mode-hook.) The simplest history commands simply
select the next and previous commands in the input history:
comint-previous-input) comint-next-input) For example, pressing M-p once will re-enter the last command into the process buffer after the prompt but does not send it to the ESS process, thus allowing editing or correction of the command before the ESS process sees it. Once corrections have been made, press RET to send the edited command to the ESS process.
If you want to select a particular command from the history by matching it against a regular expression (see Syntax of Regular Expression), to search for a particular variable name for example, these commands are also available:
comint-previous-matching-input) comint-next-matching-input) A common type of search is to find the last command that began with a particular sequence of characters; the following two commands provide an easy way to do this:
comint-previous-matching-input-from-input) comint-next-matching-input-from-input) Instead of prompting for a regular expression to match against, as they
instead select commands starting with those characters already entered.
For instance, if you wanted to re-execute the last attach()
command, you may only need to type att and then A-M-r and
RET. (Note: you may not have an <ALT> key on your keyboard,
in which case it may be a good idea to bind these commands to some other
keys.)
See Shell History Ring, for a more detailed discussion of the history mechanism.
Instead of searching through the command history using the command
described in the previous section, you can alternatively refer to a
historical command directly using a notation very similar to that used
in csh. History references are introduced by a `!' or
`^' character and have meanings as follows:
In addition, you may follow the reference with a word designator
to select particular words of the input. A word is defined as a
sequence of characters separated by whitespace. (You can modify this
definition by setting the value of comint-delimiter-argument-list
to a list of characters that are allowed to separate words and
themselves form words.) Words are numbered beginning with zero. The
word designator usually begins with a `:' (colon) character;
however it may be omitted if the word reference begins with a `^',
`$', `*' or `-'. If the word is to be selected from the
previous command, the second `!' character can be omitted from the
event specification. For instance, `!!:1' and `!:1' both
refer to the first word of the previous command, while `!!$' and
`!$' both refer to the last word in the previous command. The
format of word designators is as follows:
In addition, you may surround the entire reference except for the first `!' by braces to allow it to be followed by other (non-whitespace) characters (which will be appended to the expanded reference).
Finally, ESS also provides quick substitution; a reference like `^old^new^' means “the last command, but with the first occurrence of the string `old' replaced with the string `new'” (the last `^' is optional). Similarly, `^old^' means “the last command, with the first occurrence of the string `old' deleted” (again, the last `^' is optional).
To convert a history reference as described above to an input suitable for S, you need to expand the history reference, using the <TAB> key. For this to work, the cursor must be preceded by a space (otherwise it would try to complete an object name) and not be within a string (otherwise it would try to complete a filename). So to expand the history reference, type SPC TAB. This will convert the history reference into an S command from the history, which you can then edit or press <RET> to execute.
For example, to execute the last command that referenced the variable
data, type !?data SPC TAB RET.