Go to the first, previous, next, last section, table of contents.
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 section `Shell Mode' in The Gnu Emacs Reference Manual). 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 section `Basic editing commands' in The GNU Emacs Reference Manual). 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 section `Shell Mode' in The Gnu Emacs Reference Manual, 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 section References to historical commands.
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 (1) 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. On some systems, however, this can be rather slow; it's doubly
frustrating when you consider that most of the directories on the search
list are the standard S libraries, which never change anyway! When
ESS was installed, a database of the standard object names should have
been created which should speed up this process at the start of an S
session; if it has not been created you will get a warning like
`S-namedb.el does not exist'. See section Installing ESS on your system, for information on
how to create this database.
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 section `Paragraphs' in The GNU Emacs Reference Manual.
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 section `Pages' in The GNU Emacs Reference Manual.
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 for the size of memory allocated to the R process, for example.
You can switch to any active ESS process with the command C-c
C-k (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.
For the predecessor to ESS (S-mode 4.8), the initial process was not
visibly numbered, i.e. S instead of S1 was used in the mode-line. To
obtain this behavior, set the variable ess-plain-first-buffername
to t. See `ess-site' for how to set this for all users.
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 value of the variable ess-directory
is used as the starting directory. The default value for this variable
is your home directory. If ess-ask-for-ess-directory has a
non-nil value (as it does by default) then the value of
ess-directory 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 records 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.
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 section Keeping a record of your S session.)
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.
Go to the first, previous, next, last section, table of contents.