User manual

Chapter 7: Editing objects and functions 38
automatically if the buffer was generated with C-c C-e C-d). The file will then be loaded,
and if it loads successfully you will be returned to the ESS process.
7.3 Detecting errors in source files
If any errors occur when loading a file with 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-c ‘ (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-c ‘ 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-c ‘.
7.4 Indenting and formatting S code
ESS 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 of 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 begin-
ning 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.
ESS also supports Roxygen entries which is R documentation maintained in the source
code as comments See Section 10.2.2 [Roxygen], page 52.
The indentation commands provided by ESS are:
[Command]ess-indent-or-complete
TAB Indents the current line as S code.
Try to indent first, and if code is already properly indented, complete instead. In
ess-mode, only tries completion if ess-tab-complete-in-script is non-nil. See also
ess-first-tab-never-complete.
[User Option]ess-tab-complete-in-script
If non-nil, TAB in script buffers tries to complete if there is nothing to indent.