Go to the first, previous, next, last section, table of contents.


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.

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.

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 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.

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 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 Maintaining S source files for more details.

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
obj <- expression(...)

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. See section Creating or modifying S objects for more details.

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 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 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.

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.

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.


Go to the first, previous, next, last section, table of contents.