User manual

Chapter 7: Editing objects and functions 37
7 Editing objects and functions
ESS provides facilities for editing S objects within your Emacs session. Most editing is
performed on S functions, although in theory you may edit datasets as well. Edit buffers
are always associated with files, although you may choose to make these files temporary
if you wish. Alternatively, you may make use of a simple yet powerful mechanism for
maintaining backups of text representations of S functions. Error-checking is performed
when S code is loaded into the ESS process.
7.1 Creating or modifying S objects
To edit an S object, type
[Command]ess-dump-object-into-edit-buffer object
C-c C-e C-d Edit an S object in its own edit buffer.
from within the ESS process buffer (*S*). You will then be prompted for an object
to edit: you may either type in the name of an existing object (for which completion is
available using the TAB key), or you may enter the name of a new object. A buffer will
be created containing the text representation of the requested object or, if you entered the
name of a non-existent object at the prompt and the variable ess-function-template is
non-nil, you will be presented with a template defined by that variable, which defaults to
a skeleton function construct.
You may then edit the function as required. The edit buffer generated by ess-dump-
object-into-edit-buffer is placed in the ESS major mode which provides a number of
commands to facilitate editing S source code. Commands are provided to intelligently
indent S code, evaluate portions of S code and to move around S code constructs.
Note: when you dump a file with C-c C-e C-d, ESS first checks to see whether there
already exists an edit buffer containing that object and, if so, pops you directly to that
buffer. If not, ESS next checks whether there is a file in the appropriate place with the
appropriate name (see Section 7.6 [Source Files], page 40) and if so, reads in that file. You
can use this facility to return to an object you were editing in a previous session (and which
possibly was never loaded to the S session). Finally, if both these tests fail, the ESS process
is consulted and a dump() command issued. If you want to force ESS to ask the ESS process
for the object’s definition (say, to reformat an unmodified buffer or to revert back to S’s idea
of the object’s definition) pass a prefix argument to ess-dump-object-into-edit-buffer
by typing C-u C-c C-e C-d.
7.2 Loading source files into the ESS process
The best way to get information — particularly function definitions — into S is to load
them in as source file, using S’s source function. You have already seen how to create
source files using C-c C-e C-d; ESS provides a complementary command for loading source
files (even files not created with ESS!) into the ESS process, namely ess-load-file (C-c
C-l). see Section 4.5 [Hot keys], page 30.
After typing C-c C-l you will prompt for the name of the file to load into S; usually this is
the current buffer’s file which is the default value (selected by simply pressing RET at the
prompt). You will be asked to save the buffer first if it has been modified (this happens