| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
To edit an S object, type
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-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.7 Maintaining S source files) 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-d.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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-d; ESS provides a complementary command for
loading source files (even files not created with ESS!) into the ESS
process:
After typing C-c C-l you will prompted 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 automatically if the buffer was generated with C-c C-d). The file will then be loaded, and if it loads successfully you will be returned to the ESS process.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
C-c C-l, ESS will
inform you of this fact. In this case, you can jump directly to the
line in the source file which caused the error by typing C-x `
(ess-parse-errors).
You will be returned to the offending file (loading it into a buffer if
necessary) with point at the line S reported as containing the
error. You may then correct the error, and reload the file. Note that
none of the commands in an S source file will take effect if any
part of the file contains errors.
Sometimes the error is not caused by a syntax error (loading a
non-existent file for example). In this case typing C-x ` will
simply display a buffer containing S's error message. You can force
this behavior (and avoid jumping to the file when there is a
syntax error) by passing a prefix argument to ess-parse-errors
with C-u C-x `.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Other commands are also available for evaluating portions of code in the
S process. These commands cause the selected code to be evaluated
directly by the ESS process as if you had typed them in at the
command line; the source() function is not used. You may choose
whether both the commands and their output appear in the process buffer
(as if you had typed in the commands yourself) or if the output alone is
echoed. The behavior is controlled by the variable
ess-eval-visibly-p whose default is nil
(display output only). Passing a prefix argument (C-u) to any of
the following commands, however, reverses the meaning of
ess-eval-visibly-p for that command only -- for example C-u
C-c C-j echoes the current line of S (or other) code in the ESS
process buffer, followed by its output. This method of evaluation is an
alternative to S's source() function
when you want the input as well as the output to be displayed. (You can
sort of do this with source() when the option echo=T is
set, except that prompts do not get displayed. ESS puts prompts in the
right places.) The commands for evaluating code are:
ess-eval-line)
ess-eval-line-and-go)
ess-eval-function)
ess-eval-function-and-go)
ess-eval-region)
ess-eval-region-and-go)
ess-eval-buffer)
ess-eval-buffer-and-go)
ess-eval-line-and-step)
It should be stressed once again that these ess-eval- commands
should only be used for evaluating small portions of code for debugging
purposes, or for generating transcripts from source files. When editing
S functions, C-c C-l is the command to use to update the
function's value. In particular, ess-eval-buffer is now largely
obsolete.
One final command is provided for spot-evaluations of S code:
ess-execute-in-tb) This is useful for quick calculations, etc.
All the above commands are useful for evaluating small amounts of code
and observing the results in the process buffer. A useful way to work
is to divide the frame into two windows; one containing the source code
and the other containing the process buffer. If you wish to make the
process buffer scroll automatically when the output reaches the bottom
of the window, you will need to set the variable
comint-scroll-to-bottom-on-output to 'others or t.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
ESS now provides a sophisticated mechanism for indenting S source
code (thanks to Ken'ichi Shibayama). Compound statements (delimited by
`{' and `}') are indented relative to their enclosing block.
In addition, the braces have been electrified to automatically indent to
the correct position when inserted, and optionally insert a newline at
the appropriate place as well. Lines which continue an incomplete
expression are indented relative to the first line of the expression.
Function definitions, if statements, calls to expression()
and loop constructs are all recognized and indented appropriately. User
variables are provided to control the amount if indentation in each
case, and there are also a number of predefined indentation styles to
choose from.
Comments are also handled specially by ESS, using an idea borrowed from
the Emacs-Lisp indentation style. By default,
comments beginning with `###'
are aligned to the beginning of the line. Comments beginning with
`##' are aligned to the current level of indentation for the block
containing the comment. Finally, comments beginning with `#' are
aligned to a column on the right (the 40th column by default, but this
value is controlled by the variable comment-column,)
or just after the expression on the line containing the comment if it
extends beyond the indentation column. You turn off the default
behavior by adding the line
(setq ess-fancy-comments nil) to your `.emacs' file.
The indentation commands provided by ESS are:
ess-indent-command)
newline-and-indent)
ess-indent-exp)
ess-electric-brace)
indent-for-comment)
GNU, BSD, K&R, CLB, and C++.
The DEFAULT style uses the default values for the indenting
variables (unless they have been modified in your `.emacs' file.)
This command causes all of the formatting variables to be buffer-local.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
A number of commands are provided to move across function definitions in the edit buffer:
ess-beginning-of-function)
ess-end-of-function)
ess-mark-function) Completion is provided in the edit buffer in a similar fashion to the process buffer: M-TAB completes file names and M-? lists file completions. Since TAB is used for indentation in the edit buffer, object completion is now performed with C-c TAB. Note however that completion is only provided over globally known S objects (such as system functions) -- it will not work for arguments to functions or other variables local to the function you are editing.
Finally, two commands are provided for returning to the ESS process buffer:
ess-switch-to-end-of-ESS)
ess-switch-to-ESS) In addition some commands available in the process buffer are also available in the edit buffer. You can still read help files with C-c C-v, edit another function with C-c C-d and of course C-c C-l can be used to load a source file into S. See section 4.10 Other commands provided by inferior-ESS, for more details on these commands.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Every edit buffer in ESS is associated with a dump file on disk.
Dump files are created whenever you type C-c C-d
(ess-dump-object-into-edit-buffer), and may either be deleted
after use, or kept as a backup file or as a means of keeping several
versions of an S function.
nil, dump files created with C-c C-d are deleted
immediately after they are created by the ess-process.
Since immediately after S dumps an object's definition to a disk
file the source code on disk corresponds exactly to S's idea of the
object's definition, the disk file isn't needed; deleting it now has the
advantage that if you don't modify the file (say, because you
just wanted to look at the definition of one of the standard S
functions) the source dump file won't be left around when you kill the
buffer. Note that this variable only applies to files generated with
S's dump function; it doesn't apply to source files which already
exist. The default value is t.
nil (always
delete), ask (always ask whether to delete), check (delete
files generated with C-c C-d in this Emacs session, otherwise ask
--- this is the default) and t (never delete). This variable is
buffer-local.
After an object has been successfully (i.e. without error) loaded back into S with C-c C-l, the disk file again corresponds exactly (well, almost -- see below) to S's record of the object's definition, and so some people prefer to delete the disk file rather than unnecessarily use up space. This option allows you to do just that.
If the value of ess-keep-dump-files is t, dump files are
never deleted after they are loaded. Thus you can maintain a complete
text record of the functions you have edited within ESS. Backup files
are kept as usual, and so by using the Emacs numbered backup facility ---
see section `Single or Numbered Backups' in The Gnu Emacs Reference Manual, you can keep a historic
record of function definitions. Another possibility is to maintain the
files with a version-control system such as RCS See section `Version Control' in The Gnu Emacs Reference Manual. As long as a dump file exists in the appropriate place for a
particular object, editing that object with C-c C-d finds that
file for editing (unless a prefix argument is given) -- the ESS
process is not consulted. Thus you can keep comments outside the
function definition as a means of documentation that does not clutter
the S object itself. Another useful feature is that you may format
the code in any fashion you please without S re-indenting the code
every time you edit it. These features are particularly useful for
project-based work.
If the value of ess-keep-dump-files is nil, the dump file is always
silently deleted after a successful load with C-c C-l. While this
is useful for files that were created with C-c C-d it also applies
to any other file you load (say, a source file of function
definitions), and so can be dangerous to use unless you are careful.
Note that since ess-keep-dump-files is buffer-local, you can make
sure particular files are not deleted by setting it to t in the
Local Variables section of the file See section `Local Variables in Files' in The Gnu Emacs Reference Manual.
A safer option is to set ess-keep-dump-files to ask; this
means that ESS will always ask for confirmation before deleting the
file. Since this can get annoying if you always want to delete dump
files created with C-c C-d, but not any other files, setting
ess-keep-dump-files to check (the default value) will
silently delete dump files created with C-c C-d in the current
Emacs session, but query for any other file. Note that in any case you
will only be asked for confirmation once per file, and your answer is
remembered for the rest of the Emacs session.
Note that in all cases, if an error (such as a syntax error) is detected while loading the file with C-c C-l, the dump file is never deleted. This is so that you can edit the file in a new Emacs session if you happen to quit Emacs before correcting the error.
Dump buffers are always autosaved, regardless of the value of
ess-keep-dump-files.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Every dump file should be given a unique file name, usually the dumped object name with some additions.
%s is replaced by the
object name.
By default, dump file names are the user name, followed by `.' and
the object and ending with `.S'. Thus if user joe dumps the
object myfun the dump file will have name `joe.myfun.S'.
The username part is included to avoid clashes when dumping into a
publicly-writable directory, such as `/tmp'; you may wish to remove
this part if you are dumping into a directory owned by you.
You may also specify the directory in which dump files are written:
By default, dump files are always written to `/tmp', which is fine
when ess-keep-dump-files is nil. If you are keeping dump
files, then you will probably want to keep them somewhere in your home
directory, say `~/S-source'. This could be achieved by including
the following line in your `.emacs' file:
(setq ess-source-directory (expand-file-name "~/S-source/")) |
If you would prefer to keep your dump files in separate directories
depending on the value of some variable, ESS provides a facility for
this also. By setting ess-source-directory to a lambda
expression which evaluates to a directory name, you have a great deal of
flexibility in selecting the directory for a particular source file to
appear in. The lambda expression is evaluated with the process buffer
as the current buffer and so you can use the variables local to that
buffer to make your choice. For example, the following expression
causes source files to be saved in the subdirectory `Src' of the
directory the ESS process was run in.
(setq ess-source-directory
(lambda ()
(concat ess-directory "Src/")))
|
(ess-directory is a buffer-local variable in process buffers
which records the directory the ESS process was run from.) This is
useful if you keep your dump files and you often edit objects with the
same name in different ESS processes. Alternatively, if you often
change your S working directory during an S session, you may
like to keep dump files in some subdirectory of the directory pointed to
by the first element of the current search list. This way you can edit
objects of the same name in different directories during the one S
session:
(setq ess-source-directory
(lambda ()
(file-name-as-directory
(expand-file-name (concat
(car ess-search-list)
"/.Src")))))
|
If the directory generated by the lambda function does not exist but can be created, you will be asked whether you wish to create the directory. If you choose not to, or the directory cannot be created, you will not be able to edit functions.
| [ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |