| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 4.6 References to historical commands.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
| 4.4.1 Manipulating the output from the last command | ||
| 4.4.2 Viewing older commands | ||
| 4.4.3 Re-submitting commands from the transcript | ||
| 4.4.4 Keeping a record of your S session |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 section `Shell History Copying' in The GNU Emacs Reference Manual.)
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 section `Syntax of Regular Expression' in The GNU Emacs Reference Manual), and then moves to the next (previous) command matching the pattern.
(comint-backward-matching-input regexp arg) (comint-forward-matching-input regexp arg) | [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 signaled). 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 signaled. 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 4.5 Command History.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 3.5 Changing the startup actions.
We recommend you save your transcripts with filenames that end in
`.St'. There is a special mode (ESS transcript mode ---
see section 5. Manipulating saved transcript files) 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!
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 section `Syntax of Regular Expression' in The GNU Emacs Reference Manual), 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 section `Shell History Ring' in The GNU Emacs Reference Manual, for a more detailed discussion of the history mechanism.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
ESS provides a number of commands for executing the commonly used
functions. These commands below are basically information-gaining
commands (such as objects() or search()) which tend to
clutter up your transcript and for this reason some of the hot keys
display their output in a temporary buffer instead of the process buffer
by default. This behavior is controlled by the variable
ess-execute-in-process-buffer which, if
non-nil, means that these commands will produce their output in
the process buffer instead. In any case, passing a prefix argument to
the commands (with C-u) will reverse the meaning of
ess-execute-in-process-buffer for that command, i.e. the output
will be displayed in the process buffer if it usually goes to a
temporary buffer, and vice-versa. These are the hot keys that behave in
this way:
ess-execute-objects) objects()
command to the ESS process. A prefix argument specifies the
position on the search list (use a negative argument to toggle
ess-execute-in-process-buffer as well). A quick way to see what
objects are in your working directory.
ess-execute-search) search()
command to the ESS process.
ess-execute)
ess-execute may seem pointless when you could just type the
command in anyway, but it proves useful for `spot' calculations which
would otherwise clutter your transcript, or for evaluating an expression
while partway through entering a command. You can also use this command
to generate new hot keys using the Emacs keyboard macro facilities;
see section `Keyboard Macros' in The GNU Emacs Reference Manual.
The following hot keys do not use ess-execute-in-process-buffer
to decide where to display the output -- they either always display in
the process buffer or in a separate buffer, as indicated:
ess-execute-attach) attach() command.
If a numeric prefix argument is given it is used as the position on the
search list to attach the directory; otherwise the S default of 2 is
used. The attach() command actually executed appears in the
process buffer.
ess-load-file) source(). If there is an error during loading, you can jump to
the error in the file with C-x ` (ess-parse-errors).
See section 7.3 Detecting errors in source files, for more details.
ess-display-help-on-object)
ess-quit) q()
command to the ESS process (or (exit)
to the XLS process), and cleans up any temporary buffers (such as
help buffers or edit buffers) you may have created along the way. Use
this command when you have finished your S session instead of simply
typing q() yourself, otherwise you will need to issue the command
M-x ess-cleanup
command explicitly to make sure that all the files that need to be saved
have been saved, and that all the temporary buffers have been killed.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
For the S languages (S, S-Plus, R) ESS sets an option in the current process that programs in the language can check to determine the environment in which they are currently running.
ESS sets
options(STERM="iESS") for S language processes running in an
inferior iESS[S] or iESS[R] buffer.
ESS sets
options(STERM="ddeESS") for independent S-Plus for Windows
processes running in the GUI and communicating with ESS via
the DDE (Microsoft Dynamic Data Exchange) protocol through a
ddeESS[S] buffer.
Other values of options()$STERM that we recommend are:
length: Fixed length xterm or telnet window.
scrollable: Unlimited length xterm or telnet window.
server: S-Plus Stat Server.
BATCH: BATCH.
Rgui: R GUI.
Commands: S-Plus GUI without DDE interface to ESS.
Additional values may be recommended in the future as new interaction
protocols are created. Unlike the values iESS and ddeESS,
ESS can't set these other values since the S language program is not
under the control of ESS.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
When starting R or S under Unix, ESS sets
options(editor="emacsclient"). (Under Microsoft Windows, it will
use gnuclient.exe rather than emacsclient, but the same principle
applies.) Within your R session, for example, if you have a function
called iterator, typing fix(iterator), will show that
function in a temporary Emacs buffer. You can then correct the
function. When you kill the buffer, the definition of the function is
updated. Using edit() rather than fix() means that the
function is not updated. Finally, the S function page(x) will
also show a text representation of the object x in a temporary
Emacs buffer.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The following commands are also provided in the process buffer:
comint-interrupt-subjob)
ess-abort) q() nor
.Last will be executed and device drivers will not finish
cleanly. This command is provided as a safety to
comint-stop-subjob, which is usually bound to C-c C-z. If
you want to quit from S, use C-c C-q (ess-quit) instead.
ess-dump-object-into-edit-buffer) Other commands available in Inferior S mode are discussed in section `Shell Mode' in The Gnu Emacs Reference Manual.
| [ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |