This is ess.info, produced by makeinfo version 4.0 from ess.texi. START-INFO-DIR-ENTRY * ESS: (ess). Emacs Speaks Statistics (S/S+/R, SAS, BUGS, Stata, XLisp-Stat). END-INFO-DIR-ENTRY ESS -- Emacs Speaks Statistics ****************************** Currently maintained by A.J. (Tony) Rossini, Richard M. Heiberger, Kurt Hornik, Martin Maechler, and Rodney A. Sparapani. This file documents `ESS', a GNU Emacs package for running `S(plus)', `R', `XLisp-Stat', `SAS' and potentially any other interactive `statistical' languages in an `inferior' buffer, editing source code in these languages and interacting with the running program. This documentation relates to Version 5.1.21 of `ESS'. Original Info Author: David M. Smith (), Department of Mathematics and Statistics, Lancaster University, UK. Current Info Author: A.J. Rossini (), Department of Biostatistics, University of Washington, Seattle, WA 98185, USA  File: ess.info, Node: System dependent, Prev: Installation, Up: Installation Other variables you may need to change ====================================== If you run the S program (from the shell) with a command other than `Splus' you will need to set the variable `inferior-ess-program' to the name of the appropriate program by including a line such as (setq inferior-ess-program "S+") in your `.emacs' file (substituting `S+' for the name of your S program.) If you need to call this program with any arguments, the variable you need to set is dependent on the value of `inferior-ess-program'; for example if it is `"Splus"', set the variable `inferior-Splus-args' to a string of arguments to the `Splus' program. If `inferior-ess-program' has some other value, substitute the `Splus' part of `inferior-Splus-args' with the appropriate program name. There aren't many instances where you need to call S with arguments, however: in particular do not call the S program with the `-e' command-line editor argument since ESS provides this feature for you. If you are running Splus (the enhanced version of S from Statsci) you may also need to set the variable `S-plus' to `t'. If your value of `inferior-ess-program' is `"S+"' or `Splus' this will not be necessary, however; `S-plus' defaults to `t' in this case. Finally, if you use a non-standard prompt within S, you will need to set the variable `inferior-ess-prompt' to a regular expression which will match both the primary prompt (`"> "' by default) and the continuing prompt (default of `"+ "'.) The default value of this variable matches S's default prompts. For example, if you use (`"$ "') as your primary prompt (you have `options(prompt="$ ")' in your `.First' function), add the following line to your `.emacs': (setq inferior-ess-prompt "^\\(\\+\\|[^\\$]*\\$\\) *") You will also need to set the variable `inferior-ess-primary-prompt' to a regular expression which matches the primary prompt only. Do not anchor the regexp to the beginning of the line with `^'. Once again, the default value matches S's default prompt; in the example above the appropriate value would be `"[^\\$]*\\$ *"'. Once these variables are set appropriately, ESS should work on any system.  File: ess.info, Node: Customization, Next: Key Index, Prev: Installation, Up: Top 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. * Menu: * Variables:: Variables for customization * Hooks:: Customizing ESS with hooks * Keybindings:: Changing the default ESS keybindings  File: ess.info, Node: Variables, Next: Hooks, Prev: Customization, Up: Customization 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. * Menu: * Variables for starting ESS:: Variables for starting ESS * Dump file variables:: Variables for dump files * Indentation variables:: Variables controlling indentation * Variables controlling interaction:: Variables controlling interaction with the ESS process  File: ess.info, Node: Variables for starting ESS, Next: Dump file variables, Prev: Variables, Up: Variables 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 (*note 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.  File: ess.info, Node: Dump file variables, Next: Indentation variables, Prev: Variables for starting ESS, Up: Variables 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. *Note Source Directories::, 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. *Note Source Files::, for more details.  File: ess.info, Node: Indentation variables, Next: Variables controlling interaction, Prev: Dump file variables, Up: Variables 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. Other styles are: `GNU', `BSD', `K&R', `CLB', and `C++'. See `ess-cust.el' for the complete definitions of the styles. *Note Edit buffer::, for more details.  File: ess.info, Node: Variables controlling interaction, Prev: Indentation variables, Up: Variables 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 (*note Other::) 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 (*note Edit buffer::) 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.  File: ess.info, Node: Hooks, Next: Keybindings, Prev: Variables, Up: Customization 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.  File: ess.info, Node: Keybindings, Prev: Hooks, Up: Customization 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.  File: ess.info, Node: Key Index, Next: Command Index, Prev: Customization, Up: Top Key (Character) Index ********************* * Menu:  File: ess.info, Node: Command Index, Next: Concept Index, Prev: Key Index, Up: Top Command and Function Index ************************** * Menu: * comint-backward-matching-input: Process buffer motion. * comint-forward-matching-input: Process buffer motion.  File: ess.info, Node: Concept Index, Next: Variable and command index, Prev: Command Index, Up: Top Concept Index ************* * Menu: * .Data directory: Variables for starting ESS. * .emacs file <1>: Indenting. * .emacs file <2>: System dependent. * .emacs file <3>: Variables for starting ESS. * .emacs file <4>: Variables. * .emacs file: Source Directories. * .First function: System dependent. * aborting S commands: Other. * aborting the ESS process: Other. * arguments to S program <1>: System dependent. * arguments to S program: Customizing startup. * authors: Credits. * autosaving: Source Files. * Bug reports: Reporting Bugs. * bugs: Bugs. * cleaning up: Hot keys. * comint: Credits. * command history: Command History. * command to run S program: System dependent. * command-line completion: Completion. * command-line editing: Command-line editing. * commands: Entering commands. * comments: Source Files. * comments in S: Indenting. * completion in edit buffer: Other edit buffer commands. * completion of object names: Completion. * completion on file names: Completion. * completion on lists: Completion. * completion, when prompted for object names: Edit buffer. * continuing prompt: System dependent. * creating new objects: Edit buffer. * credits: Credits. * customization: Customization. * data frames: Completion. * debugging S functions: Evaluating code. * defaults: Variables. * deleting output: Last command. * directories <1>: Variables for starting ESS. * directories: Starting Up. * DISPLAY environment variable: Variables for starting ESS. * dump file directories: Source Directories. * dump file names: Source Directories. * dump files <1>: Edit buffer. * dump files <2>: Dump file variables. * dump files: Source Files. * echoing commands when evaluating: Evaluating code. * edit buffer: Edit buffer. * editing commands: Command History. * editing functions: Editing. * editing transcripts: Saving transcripts. * entering commands: Entering commands. * environment variables: Variables for starting ESS. * errors: Error Checking. * ESS process buffer: Starting Up. * ESS process directory: Starting Up. * evaluating code with echoed commands: Evaluating code. * evaluating S expressions: Evaluating code. * Font-lock mode: Highlighting. * formatting source code <1>: Indentation variables. * formatting source code: Indenting. * graphics: Graphics. * help files: Help. * highlighting: Highlighting. * historic backups: Source Files. * hooks: Hooks. * hot keys: Hot keys. * indentation: Indentation variables. * indenting: Indenting. * installation: Installation. * interactive use of S: Introduction. * interrupting S commands: Other. * introduction: Introduction. * keyboard short cuts: Hot keys. * killing temporary buffers: Hot keys. * killing the ESS process: Hot keys. * lists, completion on: Completion. * motion in transcript mode: Transcript Mode. * multi-line commands, resubmitting: Transcript resubmit. * Multiple ESS processes: Multiple ESS processes. * name of S program: System dependent. * new objects, creating: Edit buffer. * objects: Hot keys. * pages in the process buffer: Transcript. * paging commands in help buffers: Help. * paragraphs in the process buffer: Transcript. * parsing errors: Error Checking. * primary prompt: System dependent. * process buffer: Starting Up. * process names: Multiple ESS processes. * programming in S: Introduction. * project work in S: Source Files. * prompts in S: System dependent. * quitting from ESS: Hot keys. * re-executing commands: Command History. * reading long command outputs: Last command. * Remote Computers: ESS processes on Remote Computers. * reverting function definitions: Edit buffer. * running S: Starting Up. * S program name: System dependent. * search list <1>: Source Directories. * search list: Hot keys. * sending input: Entering commands. * Splus: System dependent. * starting directory <1>: Starting Up. * starting directory: Variables for starting ESS. * starting ESS: Starting Up. * stepping through code: Evaluating code. * STERM: Statistical Process running in ESS?. * tcsh: Completion. * temporary buffers: Help. * temporary buffers, killing: Hot keys. * transcript: Transcript. * transcript file: Customizing startup. * transcript file names: Saving transcripts. * transcript mode motion: Transcript Mode. * transcripts of S sessions: Introduction. * using S interactively: Introduction. * variables: Variables. * working directory <1>: Source Directories. * working directory: Starting Up. * X windows <1>: Variables for starting ESS. * X windows: X11.  File: ess.info, Node: Variable and command index, Prev: Concept Index, Up: Top Variable and command index ************************** * Menu: * (exit): Hot keys. * attach(): Hot keys. * backward-kill-word: Command-line editing. * comint-bol: Command-line editing. * comint-copy-old-input: Transcript resubmit. * comint-delimiter-argument-list: History expansion. * comint-dynamic-complete: Completion. * comint-input-ring-size <1>: Command History. * comint-input-ring-size: Variables controlling interaction. * comint-interrupt-subjob: Other. * comint-kill-input: Command-line editing. * comint-kill-output: Last command. * comint-mode-map: Keybindings. * comint-next-input <1>: Command History. * comint-next-input: Process buffer motion. * comint-next-matching-input: Command History. * comint-next-matching-input-from-input: Command History. * comint-previous-input <1>: Process buffer motion. * comint-previous-input: Command History. * comint-previous-matching-input: Command History. * comint-previous-matching-input-from-input: Command History. * comint-show-maximum-output: Last command. * comint-show-output: Last command. * comint-stop-subjob: Other. * comment-column: Indenting. * dump(): Edit buffer. * ess-abort: Other. * ess-arg-function-offset: Indentation variables. * ess-ask-about-display <1>: Variables for starting ESS. * ess-ask-about-display: X11. * ess-ask-about-transfile <1>: Customizing startup. * ess-ask-about-transfile: Saving transcripts. * ess-ask-for-ess-directory <1>: Variables for starting ESS. * ess-ask-for-ess-directory: Customizing startup. * ess-auto-newline: Indentation variables. * ess-beginning-of-function: Other edit buffer commands. * ess-brace-imaginary-offset: Indentation variables. * ess-brace-offset: Indentation variables. * ess-change-sp-regex: Completion details. * ess-clean-region: Saving transcripts. * ess-cleanup <1>: Hot keys. * ess-cleanup: Help. * ess-continued-brace-offset: Indentation variables. * ess-continued-statement-offset: Indentation variables. * ess-default-style: Indentation variables. * ess-delete-dump-files: Source Files. * ess-describe-help-mode: Help. * ess-directory <1>: Source Directories. * ess-directory: Customizing startup. * ess-display-help-on-object: Help. * ess-dump-filename-template <1>: Source Directories. * ess-dump-filename-template: Dump file variables. * ess-dump-object-into-edit-buffer <1>: Other. * ess-dump-object-into-edit-buffer: Edit buffer. * ess-else-offset: Indentation variables. * ess-elsewhere: ESS processes on Remote Computers. * ess-end-of-function: Other edit buffer commands. * ess-eval-buffer: Evaluating code. * ess-eval-function: Evaluating code. * ess-eval-function-and-go: Evaluating code. * ess-eval-line: Evaluating code. * ess-eval-line-and-go: Evaluating code. * ess-eval-line-and-next-line: Evaluating code. * ess-eval-map: Keybindings. * ess-eval-region <1>: Evaluating code. * ess-eval-region: Help. * ess-eval-region-and-go: Evaluating code. * ess-eval-visibly-p <1>: Evaluating code. * ess-eval-visibly-p: Variables controlling interaction. * ess-execute: Hot keys. * ess-execute-attach: Hot keys. * ess-execute-in-process-buffer <1>: Variables controlling interaction. * ess-execute-in-process-buffer: Hot keys. * ess-execute-in-tb: Evaluating code. * ess-execute-objects: Hot keys. * ess-execute-search: Hot keys. * ess-expression-offset: Indentation variables. * ess-fancy-comments: Indenting. * ESS-font-lock-keywords: Highlighting. * ess-function-template: Edit buffer. * ess-help-mode-hook: Hooks. * ess-help-mode-map: Keybindings. * ess-help-sec-keys-alist: Keybindings. * ess-indent-level: Indentation variables. * ess-inf-font-lock-keywords: Highlighting. * ess-insert-function-templates <1>: Dump file variables. * ess-insert-function-templates: Edit buffer. * ess-keep-dump-files <1>: Dump file variables. * ess-keep-dump-files: Source Files. * ess-list-object-name-completions: Completion. * ess-load-file <1>: Loading. * ess-load-file: Hot keys. * ess-mode-hook: Hooks. * ess-mode-load-hook: Hooks. * ess-mode-map: Keybindings. * ess-parse-errors <1>: Hot keys. * ess-parse-errors: Error Checking. * ess-plain-first-buffername: Multiple ESS processes. * ess-post-run-hook: Hooks. * ess-pre-run-hook: Hooks. * ess-quit <1>: Other. * ess-quit: Help. * ess-remote: ESS processes on Remote Computers. * ess-request-a-process: Multiple ESS processes. * ess-resynch: Completion details. * ess-search-list: Source Directories. * ess-send-input-hook: Hooks. * ess-skip-to-help-section: Help. * ess-skip-to-next-section: Help. * ess-skip-to-previous-section: Help. * ess-source-directory <1>: Dump file variables. * ess-source-directory: Source Directories. * ess-source-directory-generator: Dump file variables. * ess-style-alist: Indentation variables. * ess-submit-bug-report: Reporting Bugs. * ess-switch-to-end-of-ESS <1>: Help. * ess-switch-to-end-of-ESS: Other edit buffer commands. * ess-switch-to-ESS: Other edit buffer commands. * ess-tab-always-indent: Indentation variables. * ess-trans-font-lock-keywords: Highlighting. * ess-transcript-copy-command: Resubmit. * ess-transcript-mode-hook: Hooks. * ess-transcript-mode-map: Keybindings. * ess-transcript-send-command: Resubmit. * ess-transcript-send-command-and-move: Transcript resubmit. * expression(): Indentation variables. * inferior-ess-mode-hook: Hooks. * inferior-ess-mode-map: Keybindings. * inferior-ess-primary-prompt: System dependent. * inferior-ess-program <1>: System dependent. * inferior-ess-program: Customizing startup. * inferior-ess-prompt: System dependent. * inferior-ess-send-input <1>: Transcript resubmit. * inferior-ess-send-input: Command-line editing. * inferior-Splus-args: System dependent. * objects(): Hot keys. * options(): System dependent. * printer(): printer. * q(): Hot keys. * S <1>: Variables for starting ESS. * S <2>: Starting Up. * S: Variables for starting ESS. * S+elsewhere: ESS processes on Remote Computers. * S-directory: Variables for starting ESS. * S-plus: System dependent. * search() <1>: Completion. * search(): Hot keys. * source() <1>: Loading. * source(): Evaluating code. * STERM: Statistical Process running in ESS?. * X-displays-list: Variables for starting ESS.