K. Customizing ESS
ESS can be easily customized to your taste simply by including the
appropriate lines in your `.emacs' file. There are numerous
variables which affect the behavior of ESS in certain situations which
can be modified to your liking. Keybindings may be set or changed to
your preferences, and for per-buffer customizations hooks are also
available.
K.1 Variables for customization
ESS is easily customizable by means of setting variables in your
`.emacs' file.
In most cases, you can change defaults by including lines of the form
| (setq variable-name value)
|
in your `.emacs'.
In what follows, variable names will be listed along with their
descriptions and default values. Just substitute the variable name and
the new value into the template above.
K.1.1 Variables for starting ESS
- User Option: ess-ask-for-ess-directory
- Default:
t
If this variable has a non-nil
value, then every time ESS is
run with M-x S
you will be prompted for a directory to use as the working directory for
your S session; this directory should have a `.Data'
subdirectory.
If the value of ess-ask-for-ess-directory
is nil
, the
value of S-directory
is used as the working directory.
- User Option: S-directory
- Default: Your home directory
The working directory for your S
session if ess-ask-for-ess-directory
is nil
, and the
default when prompting for a directory if it is not. For example, you
may wish to set this to the value of the current buffer's working
directory before starting S by adding the following line to your
`.emacs' file (see section K.2 Customizing ESS with hooks)
| (setq ess-pre-run-hook
'((lambda () (setq S-directory default-directory))))
|
- User Option: ess-ask-about-display
- Default:
nil
If this variable has a non-nil
value, then every time ESS is
run with M-x S
you will be asked for a value for the DISPLAY
environment
variable
to be used in the current S session. If this variable is not set
correctly, S will not be able to create any windows under the X
windowing environment.
Completion is provided over the X-displays-list
variable; the
default is the current value of DISPLAY
. This feature is useful
is you often run S on a different display than that of the machine you
are running S from. If
ess-ask-about-display
is nil
, the current value of
DISPLAY
is used.
- User Option: X-displays-list
- Default:
'(":0.0")
List of possible values for the DISPLAY
environment variable,
provided for completion when prompting for such a value.
K.1.2 Variables for dump files
- User Option: ess-insert-function-templates
- Default:
t
If this variable has a non-nil
value, then
dumping a non-existent object will result in the edit buffer containing
a skeleton function definition, ready for editing.
- User Option: ess-source-directory
- Default:
"/tmp/"
Directory name (ending in `/') in which dump files are placed. This
should always be a writable directory.
- User Option: ess-source-directory-generator
- Default:
nil
Alternative, dynamic method of specifying the directory for dump files.
- User Option: ess-dump-filename-template
- Default: user_name
.
object_name.S
Naming system to use for dumped object files. See section F.8 Names and locations of dump files,
for details of this and the previous two variables.
- User Option: ess-keep-dump-files
- Default:
nil
Boolean flag signifying whether to keep dump files or to delete them
after each use. See section F.7 Maintaining S source files, for more details.
K.1.3 Variables controlling indentation
- User Option: ess-tab-always-indent
- Default:
t
If non-nil
, then TAB in the edit buffer always indents the
current line, regardless of the position of point in the line.
Otherwise, indentation is only performed if point is in the lines
indentation, and a tab character is inserted is point is after the first
nonblank character.
- User Option: ess-auto-newline
- Default:
nil
Non-nil
means automatically newline before and after braces
inserted in S code.
The following variables control amounts of indentation. These variables
automatically become buffer-local in any ESS buffer, and so setting
any of these variables has effect in the current buffer only.
- User Option: ess-indent-level
- Default: 2
Extra indentation of S statement sub-block with respect to enclosing
braces.
- User Option: ess-brace-imaginary-offset
- Default: 0
Extra indentation (over sub-block indentation) for block following an
open brace which follows on the same line as a statement.
- User Option: ess-brace-offset
- Default: 0
Extra indentation for braces, compared with other text in same context.
- User Option: ess-continued-statement-offset
- Default: 0
Extra indent for lines not starting new statements.
- User Option: ess-continued-brace-offset
- Default: 0
Extra indent for substatements that start with open-braces.
This is in addition to ess-continued-statement-offset
.
- User Option: ess-arg-function-offset
- Default: 2
Extra indent for arguments of function foo
when it is called as
the value of an argument to another function in
arg=foo(...)
form. If not number, the statements are indented at
open-parenthesis following foo
.
- User Option: ess-expression-offset
- Default: 4
Extra indent for internal substatements of the call to
expression()
specified in
form. If not a number, the statements are indented at open-parenthesis
following `expression'.
- User Option: ess-else-offset
- Default: 2
Extra indentation of the else
clause with respect to the
corresponding if
.
In addition, a number of default styles are defined for you (in
ess-style-alist
):
- User Option: ess-default-style
- Default:
DEFAULT
The default formatting style to use in edit buffers. The DEFAULT style
uses the values of the above indentation variables at load-time, so that
changing these variables in your `.emacs' file will affect your
buffer defaults. Other styles are:
GNU
, BSD
, K&R
, CLB
, and C++
.
See `ess-cust.el' for the complete definitions of the styles.
See section F.1 Creating or modifying S objects, for more details.
K.1.4 Variables controlling interaction with the ESS process
- User Option: comint-input-ring-size
- Default: 50
Number of commands to store in the command history.
- User Option: ess-execute-in-process-buffer
- Default:
nil
If this is nil
, then the ess-execute-
commands (see section E.9 Other commands provided by inferior-ESS)
output to a temporary buffer. Otherwise, the
output goes to the ESS process.
- User Option: ess-eval-visibly-p
- Default:
nil
If non-nil
, then the ess-eval-
commands (see section F.1 Creating or modifying S objects) echo the S commands in the process buffer by default. In any
case, passing a prefix argument to the eval command reverses the meaning
of this variable.
K.2 Customizing ESS with hooks
ESS provides the following hooks:
- Hook: ess-mode-hook
- Called every time
ESS
is run.
- Hook: ess-mode-load-hook
- Called just after the file `ess.el' is loaded. Useful for setting
up your keybindings, etc.
- Hook: ess-pre-run-hook
- Called before the ESS process is started (e.g., with M-x S).
Good for setting up your directory.
- Hook: ess-post-run-hook
- Called just after the ESS process starts up. This can be used to
evaluate ESS code at the start of a session, with
ess-eval-visibly
, say.
- Hook: inferior-ess-mode-hook
- For customizing inferior ess mode. Called after inferior-ess-mode is
entered and variables have been initialized.
- Hook: ess-help-mode-hook
- Called every time when entering ess-help-mode (i.e., an ESS help
buffer is generated).
- Hook: ess-send-input-hook
- Called just before line input is sent to the process.
- Hook: ess-transcript-mode-hook
- For customizing ESS transcript mode.
K.3 Changing the default ESS keybindings
ESS provides a separate keymaps (keymap variables) for ESS process
buffers, edit buffers and for help buffers. The key bindings in the
edit buffers further depend on the language and dialect in use.
- Keymap: inferior-ess-mode-map
-
Keymap used in the ESS process buffer. The bindings from
comint-mode-map
are automatically inherited.
- Keymap: ess-mode-map
- Keymap used within edit (ess-mode) buffers.
- Keymap: ess-eval-map
- Keymap used within edit buffers for sending ESS code to the running
process.
- Keymap: ess-help-mode-map
- Keymap used within help buffers. In addition,
ess-help-sec-map
is the keymap for the `s' prefix key. Keys defined in
ess-help-sec-keys-alist
are automatically inserted into this
keymap
when ESS is loaded.
- Keymap: ess-transcript-mode-map
- Keymap used within ESS transcript buffers.
This document was generated
by on July, 28 2004
using texi2html