This is ess.info, produced by makeinfo version 4.0 from ess.texi. START-INFO-DIR-ENTRY * ESS: (ess). Emacs Speaks Statistics (S/R, SAS, XLisp-Stat, etc). END-INFO-DIR-ENTRY ESS -- Emacs Speaks Statistics ****************************** Originally known as S-mode, written by Doug Bates, Ed Kademan, Frank Ritter, and David Smith. Currently maintained by A.J. (Tony) Rossini, Richard M. Heiberger, Kurt Hornik, Martin Maechler, and Rodney 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.19 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: Top, Next: Introduction, Prev: (dir), Up: (dir) ESS: Emacs Speaks Statistics **************************** ESS version 5.1.20 (Documentation $Revision: 1.19 $ $Date: 2002/02/13 20:47:35 $). A.J. Rossini, R.M. Heiberger, K. Hornik, M. Maechler, and R. Sparapani (Formerly: Doug Bates, Ed Kademan, Frank Ritter and David Smith). A programming and inferior mode package for (X)Emacs intended for interacting with statistical software packages (primarily S(plus), R, XLisp-Stat, and SAS), for data analysis and statistical software development. * Menu: * Introduction:: Overview of features provided by this package * Starting Up:: Starting the ESS process * Entering commands:: Interacting with the process buffer * Editing:: How to create or edit S objects or functions * Help:: Reading help files in ESS * Transcript Mode:: Manipulating saved transcript files * Miscellaneous:: Other features of ESS * Bugs Etc:: * Help Statistics:: * Help OS:: * Installation:: Installing ESS on your system * Unix installation:: Installing ESS on your Unix system * Microsoft Windows installation:: Installing ESS on your MS Windows system * Customization:: Customizing ESS * Key Index:: * Command Index:: * Concept Index:: * Variable and command index:: --- The Detailed Node Listing --- Introduction to ESS * Features:: Why should I use ESS? * New features:: * Credits:: Authors of and contributors to ESS * Latest version:: Getting the latest version of ESS * Manual:: How to read this manual Starting the ESS process * Multiple ESS processes:: * Customizing startup:: Changing the startup actions Interacting with the ESS process * Command-line editing:: Entering commands and fixing mistakes * Completion:: Completion of object names * Completion details:: Advanced completion concepts * Transcript:: Manipulating the transcript * Command History:: Command History * History expansion:: References to historical commands * Is the Statistical Process running under ESS?:: S language options()$STERM * Hot keys:: Hot keys for common commands * Other:: Other commands provided by inferior-ESS Manipulating the transcript * Last command:: Manipulating the output from the last command * Process buffer motion:: Viewing more historic commands * Transcript resubmit:: Re-submitting commands from the transcript * Saving transcripts:: Keeping a record of your S session Editing S functions * Edit buffer:: Edit objects in a specialized buffer * Loading:: Loading source files into the ESS process * Error Checking:: Detecting errors in source files * Evaluating code:: Sending code to the ESS process * Indenting:: Indenting and formatting S code * Other edit buffer commands:: Commands for motion, completion and more * Source Files:: Maintaining S source files * Source Directories:: Names and locations of dump files Manipulating saved transcript files * Resubmit:: Resubmitting commands from the transcript file * Clean:: Cleaning transcript files Other features of ESS * Highlighting:: Syntactic highlighting of buffers * Graphics:: Using graphics with ESS * Object Completion:: Using graphics with ESS * printer:: The printer() graphics driver * X11:: The X11() (and other X-windows based) driver Bugs and Bug Reporting, Mailing Lists * Bugs:: * Reporting Bugs:: * Mailing Lists:: Help, arranged by Statistical Package * Help on Unix Splus :: * Help on Microsoft Splus:: * Help on R:: * Help on SAS:: * Help on XLispStat:: * Help on Stata:: Help, arranged by Operating System * Help Unix:: * Help Microsoft:: Installing ESS on your system * System dependent:: Other variables you may need to change Customizing ESS * Variables:: Variables for customization * Hooks:: Customizing ESS with hooks * Keybindings:: Changing the default ESS keybindings Variables for customization * 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: Introduction, Next: Starting Up, Prev: Top, Up: Top Introduction to ESS ******************* The S and Splus packages provide sophisticated statistical and graphical routines for manipulating data. S-mode, the package on which ESS was based, provided a programming environment for data analysis and statistical programming, as well as an intelligent interface to the S process. The _ESS (:= Emacs Speaks Statistics)_ package is an extension of S-mode to provide a common, generic, and useful interface, through Emacs, to many statistical packages. It has currently been extended for R, XLisp-Stat, and SAS, with other statistical languages such as Stata, SPSS, and Fiasco slated for implementations in the future. A bit of notation before we begin. _Emacs_ refers to both _Emacs_ as distributed by the Free Software Foundation, as well as _XEmacs_, which is a second GNU version of Emacs. The Emacs major mode `ESS[language]' which is used for editing source for dialect `language', can take values `S', `SAS', or `XLS', for instance. The inferior process interface (the connection between Emacs and the running process) referred to as interactive ESS (`iESS'), is denoted in the modeline by `ESS[dialect]', where `dialect' can take values `S3', `S4', `S+3', `R', `XLS', `VST', `SAS', as well as others. Currently, the documentation contains many references to ``S'' where actually any supported (statistics) language is meant, i.e., `S' could also mean `XLisp-Stat' or `SAS'. For exclusively interactive users of S, ESS provides a number of features to make life easier. There is an easy to use command history mechanism, including a quick prefix-search history. To reduce typing, command-line completion is provided for all S objects and "hot keys" are provided for common S function calls. Help files are easily accessible, and a paging mechanism is provided to view them. Finally, an incidental (but very useful) side-effect of ESS is that a transcript of your session is kept for later saving or editing. No special knowledge of Emacs is necessary when using S interactively under ESS. For those that use S in the typical edit-test-revise cycle when programming S functions, ESS provides for editing of S functions in Emacs edit buffers. Unlike the typical use of S where the editor is restarted every time an object is edited, ESS uses the current Emacs session for editing. In practical terms, this means that you can edit more than one function at once, and that the ESS process is still available for use while editing. Error checking is performed on functions loaded back into S, and a mechanism to jump directly to the error is provided. ESS also provides for maintaining text versions of your S functions in specified source directories. * Menu: * Features:: Why should I use ESS? * New features:: * Credits:: Authors of and contributors to ESS * Latest version:: Getting the latest version of ESS * Manual:: How to read this manual  File: ess.info, Node: Features, Next: New features, Prev: Introduction, Up: Introduction Why should I use ESS? ===================== S is a powerful system for manipulating and analyzing data, but its user interface -- particularly on Unix platforms -- leaves something to be desired. ESS is a package which is designed to make S easier to use. ESS provides several features which make it easier to interact with the ESS process (i.e. enter commands and view the output). These include: * Command-line editing for fixing mistakes in commands before they are entered. The `-e' flag for S-plus provides something similar to this, but here you have the full range of Emacs commands rather than a limited subset. However, other packages such as XLisp-Stat and S3 do not necessarily have features like this built-in. *Note Command-line editing::. * Searchable command history for recalling previously-submitted commands. This provides all the features of the `Splus -e' history mechanism, plus added features such as history searching. *Note Command History::. * Command-line completion of both object and file names for quick entry. This is similar to `tcsh''s facility for filenames; here it also applies to object names and list components. *Note Completion::. * Hot-keys for quick entry of commonly-used commands in `S' such as `objects()' and `search()'. *Note Hot keys::. * Transcript recording for a complete record of all the actions in an S session. *Note Transcript::. * Interface to the help system, with a specialized mode for viewing S help files. *Note Help::. If you commonly create or modify S functions, you will have found the standard facilities for this (the `fix()' function, for example) severely limiting. Using S's standard features, one can only edit one function at a time, and you can't continue to use S while editing. ESS corrects these problems by introducing the following features: * Object editing. ESS allows you to edit more than one function simultaneously in dedicated Emacs buffers. The ESS process may continue to be used while functions are being edited. *Note Edit buffer::. * A specialized editing mode for S code, which provides syntactic indentation and highlighting. *Note Indenting::. * Facilities for loading and error-checking source files, including a keystroke to jump straight to the position of an error in a source file. *Note Error Checking::. * Source code revision maintenance, which allows you to keep historic versions of S source files. *Note Source Files::. * Facilities for evaluating S code such as portions of source files, or line-by-line evaluation of files (useful for debugging). *Note Evaluating code::. Finally, ESS provides features for re-submitting commands from saved transcript files, including: * Evaluation of previously entered commands, stripping away unnecessary prompts. *Note Transcript resubmit::.  File: ess.info, Node: New features, Next: Credits, Prev: Features, Up: Introduction New features in ESS =================== Changes/New Features in 5.1.20: * New `options()$STERM' in the S dialects (S, S-Plus, R). The S program can determine the environment in which it is currently running. ESS sets the option to `iESS' or `ddeESS' when it starts an S language process. We recommend other specific values for S language processes that ESS does not start. * New `ess-mouse-me' function, assigned to S-mouse-3 by default. User may click on a word or region and then choose from the menu to display the item, or a summary, or a plot, etc. This feature is still under development. * GNU Emacs 21.1 is now supported (fixed for S dialects, SAS & BUGS), (some from Stephen Eglen). * XEmacs 21.x is now supported (fixed w32-using-nt bug) * XEmacs on Win (NT) is better supported. * Workaround for bug in Sqpe+6 (S-PLUS 6 for Win). * should now work even when imenu is not available (for old Xemacsen). * for SAS : XEmacs-Imenu fix; C-TAB is globalized along with your function-key definitions, if specified; you can specify your SAS library definitions outside of autoexec.sas for ess-sas-data-view with SAS code placed in the variable ess-sas-data-view-libname, also the dataset name is defaulted to the nearest permanent dataset to point; Speedbar support now works for permanent datasets, please ignore first./last.; new font-locking is now the default with more improvements for font-locking PROCs, macro statements, * ; and %* ; comments; you can toggle sas-log-mode with F10 which will font-lock your .log (if it isn't too big); submit remote .sas files accessed with ange-ftp, EFS or Tramp (Kermit is experimental) by setting ess-sas-submit-method to 'sh; ess-sas-submit-command and ess-sas-submit-command-options are buffer-local so you can have local file variable sections at the end of your .sas files to request different executables or specify special options and the local file variables are re-read at submit instead of only at file open so that if you make a change it is picked up immediately; * for BUGS: font-lock with `in' fixed. * for STATA: font-lock bug fixed. * for Rd mode: C-c C-v and `switch-process' in menu. further, C-c C-f prefix (Rd-font) for inserting or surrounding a word by things such as \code{.}, \code{\link{.}}, \emph{.} etc. * new functions (ess-directory-function) and (ess-narrow-to-defun) ess-directory <-> default-directory logic (Jeff Mincy). * Re-organized Makefile and fixed a few bugs. Changes/New Features in 5.1.19: * S+6 now supported (Tony Rossini (Unix) and Rich Heiberger (Windows)) * New BUGS support through ESS[BUGS] mode (Rodney Sparapani) Templates assist you in writing .bug and .cmd code (.cmd and .log are replaced by .bmd and .bog to avoid emacs extension collisions). "Substitution" parameters facilitate "automagic" generation of "data...in" and "init...in" filenames, "const N=" from your data file and "monitor()/stats()" commands. Activated by pressing F12. * Fixes for `ess-smart-underscore' SAS breakage (Rich Heiberger) * You can change between PC and Unix, local and global SAS function-key definitions interactively (Rich Heiberger) * C-Submit a highlighted region to SAS batch (Rodney Sparapani) * New and improved SAS syntax highlighting (Rodney Sparapani) To get the new functionality, set ess-sas-run-make-regexp to nil. Also available in .log files via F10. * Open a permanent SAS dataset for viewing via F9 (Rodney Sparapani) You must have the library defined in autoexec.sas for it to work. * User-friendly defaults for `sas-program', `ess-sas-batch-pre-command' and `ess-sas-batch-post-command' as well Customize support for these and other ESS[SAS] variables (Rodney Sparapani) * `ess-sas-suffix-2' now defaults to .dat via F11 (Rodney Sparapani) * Emacs/XEmacs, Unix/Windows issues collectively handled in ess-emcs.el * defadvice solves problem of missing *ESS* (thanks to Jeff Mincy) * Improved manual a bit by including things that were only in `README'. Changes/New Features in 5.1.18: * New `ess-smart-underscore' function, now assigned to "_" by default. Inserts `ess-S-assign' (customizable " <- "), unless inside string and comments where plain "_" is used instead. (MM) * Fixes for longstanding interactive SAS breakage (RMH) Changes/New Features in 5.1.17: * Documentation for Windows Installation (Rich Heiberger ()) * removal of ess-vars, finalization of customize support (in the sense that there is no more use of ess-vars, but that we need to fix ess-cust) (AJ Rossini ()) * Many small (and large) fixes/contributions (MMaechler, ()). * addition of the "S-equal" variable and provide M-x ess-add-MM-keys a way to remap "_" to `ess-S-assign', typically " <- ", but customizable. (MMaechler, ()). Changes/New Features in 5.1.16: * BUG FIXES * Better SAS support Changes/New Features in 5.1.15: * BUG FIXES Changes/New Features in 5.1.14: * Yet more fixes to SAS mode, (Rich Heiberger () and Rodney Sparapani )). * Customize support (for most Emacsen which support it) (AJRossini, () * ARC and ViSta support out of the box, and fixes for XLispStat (AJRossini, ) Changes/New Features in 5.1.13: * Version numbering finally all depending on the ./VERSION file, thanks to Martin Maechler. * Yet more fixes to SAS mode, thanks to Rich Heiberger (). Changes/New Features in 5.1.12: * Splus 5.1 stabilized, thanks to Martin Maechler, Bill Venables, Chuck Taylor, and others. * More fixes to SAS mode, thanks to Rodney Sparapani () and Rich Heiberger (). Changes/New Features in 5.1.11: * More fixes to Stata mode, thanks to Brendan Halpin () * fixed bugs in ESS-elsewhere, thanks to many testers * README.SPLUS4WIN has DETAILED instructions for S-PLUS 2000, thanks to David Brahm (). * Fixes to SAS mode, thanks to Rodney Sparapani () Changes/New Features in 5.1.10: * More fixes to Stata mode * primitive generic version of ESS-elsewhere * Small fixes to SAS/Stata. Changes/New Features in 5.1.9: * Stata mode works * Literate Data Analysis using Noweb works Changes/New Features in 5.1.8: * Bug fixes * R documentation mode defaults changed Changes/New Features in 5.1.2: * able to use inferior iESS mode to communicate directly with a running S-Plus 4.x process using the Microsoft DDE protocol. We use the familiar (from Unix ESS) C-c C-n and related key sequences to send lines from the S-mode file to the inferior S process. We continue to edit S input files in ESS[S] mode and transcripts of previous S sessions in ESS Transcript mode. All three modes know the S language, syntax, and indentation patterns and provide the syntactic highlighting that eases the programming tasks.  File: ess.info, Node: Credits, Next: Latest version, Prev: New features, Up: Introduction Authors of and contributors to ESS ================================== ESS is based on Olin Shivers' excellent comint package (which is supplied with version 19 of GNU Emacs). The original version of ESS (then known as `S-mode') was written by Doug Bates () and Ed Kademan (). Frank Ritter () then merged this version with his own S-mode mode to form `S.el' version 2.1. Version 2.1 of `S.el' was then updated and expanded by David Smith to form version 3.4. This was then updated for Emacs 19 to create version 4. Most bugs have now been fixed (and several new ones introduced) and many new features have been added. Thanks must go to the many people who have helped with the development of the present version of ESS: * The multiple process code, and the idea for `ess-eval-line-and-next-line' are by Rod Ball. * Thanks to Doug Bates for many useful suggestions. * Thanks to Martin Maechler for reporting and fixing bugs, providing many useful comments and suggestions, and for maintaining the S-mode mailing list. * Thanks to Frank Ritter for updates from the previous version, the menu code, and invaluable comments on the manual. * Thanks to Ken'ichi Shibayama for his excellent indenting code, and many comments and suggestions. * Last but definitely not least, thanks to the many beta testers of the S-mode and ESS mailing lists. The new version, _ESS_ version 5, is being developed and currently maintained by * A.J. Rossini (http://www.biostat.washington.edu/~rossini/) * Richard M. Heiberger (http://www.sbm.temple.edu/departments/statistics/) * Kurt Hornik (http://www.ci.tuwien.ac.at/~hornik) * Martin Maechler (http://stat.ethz.ch/~maechler/) * Rodney Sparapani (http://www.mcw.edu/pcor/rsparapa)  File: ess.info, Node: Latest version, Next: Manual, Prev: Credits, Up: Introduction Getting the latest version of ESS ================================= The latest versions of ESS are always available by WWW from: `http://ess.stat.wisc.edu/' and `ftp://ess.stat.wisc.edu/pub/ESS/' The HTML version of the documentation can be found at: `http://stat.ethz.ch/ESS/' The latest (no more than 24 hours behind the developers) version of ESS can also be retrieved using anonymous cvs: You need a cvs client (that works with your firewall, if any) the repository name is `:pserver:anoncvs@software.biostat.washington.edu:/var/anoncvs' using a command-line cvs client (i.e. on Unix or DOS), first type: `cvs -d :pserver:anoncvs@software.biostat.washington.edu:/var/anoncvs login' password is anoncvs then type: `cvs -d :pserver:anoncvs@software.biostat.washington.edu:/var/anoncvs co ess' Check the `README' file first to see which files you need. Look at `ANNOUNCE' to learn about new user-visible features; also, many changes are listed in the `ChangeLog' file.  File: ess.info, Node: Manual, Prev: Latest version, Up: Introduction How to read this manual ======================= If ESS has already been installed on your system, the next chapter has details on how to get started using S under ESS. If you need to install ESS, read *Note Installation:: for details on what needs to be done before proceeding to the next chapter. *Note Customization:: provides details of user variables you can change to customize ESS to your taste, but it is recommended that you defer this section until you are more familiar with ESS. Don't forget that this manual is not the only source of information about ESS. In particular, the mode-based online help (obtained by pressing `C-h m' when in the process buffer, edit buffer or help buffer) is quite useful. However the best source of information is, as always, experience -- try it out!  File: ess.info, Node: Starting Up, Next: Entering commands, Prev: Introduction, Up: Top Starting the ESS process ************************ To start an S session, simply type `M-x S RET', i.e. press , then , then capital and then the key. S will then (by default) ask the question S starting data directory? Enter the name of the directory you wish to start S from (that is, the directory you would have `cd''d to before starting S from the shell). This directory should have a `.Data' subdirectory. You will then be popped into a buffer with name `*S*' which will be used for interacting with the ESS process, and you can start entering commands. * Menu: * Multiple ESS processes:: * Customizing startup:: Changing the startup actions  File: ess.info, Node: Multiple ESS processes, Next: Customizing startup, Prev: Starting Up, Up: Starting Up Running more than one ESS process ================================= ESS allows you to run more than one ESS process simultaneously in the same session. Each process has a name and a number; the initial process (process 1) is simply named (using S-PLUS as an example) `S+3:1'. The name of the process is shown in the mode line in square brackets (for example, `[S+3:2]'); this is useful if the process buffer is renamed. Without a prefix argument, `M-x S' starts a new ESS process, using the first available process number. With a prefix argument (for R), `C-u M-x R' allows for the specification of command line options for the size of memory allocated to the R process, for example. You can switch to any active ESS process with the command `C-c C-k' (`ess-request-a-process'). Just enter the name of the process you require; completion is provided over the names of all running S processes. This is a good command to consider binding to a global key. For the predecessor to ESS (S-mode 4.8), the initial process was not visibly numbered, i.e. S instead of S1 was used in the mode-line. To obtain this behavior, set the variable `ess-plain-first-buffername' to `t'. See `ess-site' for how to set this for all users.  File: ess.info, Node: Customizing startup, Prev: Multiple ESS processes, Up: Starting Up Changing the startup actions ============================ If you do not wish ESS to prompt for a starting directory when starting a new process, set the variable `ess-ask-for-ess-directory' to `nil'. In this case, the value of the variable `ess-directory' is used as the starting directory. The default value for this variable is your home directory. If `ess-ask-for-ess-directory' has a non-`nil' value (as it does by default) then the value of `ess-directory' provides the default when prompting for the starting directory. Incidentally, `ess-directory' is an ideal variable to set in `ess-pre-run-hook'. If you like to keep a records of your S sessions, set the variable `ess-ask-about-transfile' to `t', and you will be asked for a filename for the transcript before the ESS process starts. - User Option: ess-ask-about-transfile If non-`nil', as for a file name in which to save the session transcript. Enter the name of a file in which to save the transcript at the prompt. If the file doesn't exist it will be created (and you should give it a file name ending in `.St'; if the file already exists the transcript will be appended to the file. (Note: if you don't set this variable but you still want to save the transcript, you can still do it later -- *note Saving transcripts::.) Once these questions are answered (if they are asked at all) the S process itself is started by calling the program name specified in the variable `inferior-ess-program'. If you need to pass any arguments to this program, they may be specified in the variable `inferior-S_PROGRAM_NAME-args' (e.g. if `inferior-ess-program' is `"S+"' then the variable to set is `inferior-S+-args'. It is not normally necessary to pass arguments to the S program; in particular do not pass the `-e' option to `Splus', since ESS provides its own command history mechanism.  File: ess.info, Node: Entering commands, Next: Editing, Prev: Starting Up, Up: Top Interacting with the ESS process ******************************** The primary function of the ESS package is to provide an easy-to-use front end to the S interpreter. This is achieved by running the S process from within an Emacs buffer, so that the Emacs editing commands are available to correct mistakes in commands, etc. The features of Inferior S mode are similar to those provided by the standard Emacs shell mode (*note Shell Mode: (emacs)Shell Mode.). Command-line completion of S objects and a number of `hot keys' for commonly-used S commands are also provided for ease of typing. * Menu: * Command-line editing:: Entering commands and fixing mistakes * Completion:: Completion of object names * Completion details:: Advanced completion concepts * Transcript:: Manipulating the transcript * Command History:: Command History * History expansion:: References to historical commands * Is the Statistical Process running under ESS?:: S language options()$STERM * Hot keys:: Hot keys for common commands * Other:: Other commands provided by inferior-ESS  File: ess.info, Node: Command-line editing, Next: Completion, Prev: Entering commands, Up: Entering commands Entering commands and fixing mistakes ===================================== Sending a command to the ESS process is as simple as typing it in and pressing the key: * `RET' (`inferior-ess-send-input') Send the command on the current line to the ESS process. If you make a typing error before pressing `RET' all the usual Emacs editing commands are available to correct it (*note Basic: (emacs)Basic.). Once the command has been corrected you can press (even if the cursor is not at the end of the line) to send the corrected command to the ESS process. ESS provides some other commands which are useful for fixing mistakes: * `C-c C-w' (`backward-kill-word') Deletes the previous word (such as an object name) on the command line. * `C-c C-u' (`comint-kill-input') Deletes everything from the prompt to point. Use this to abandon a command you have not yet sent to the ESS process. * `C-c C-a' (`comint-bol') Move to the beginning of the line, and then skip forwards past the prompt, if any. *Note Shell Mode: (emacs)Shell Mode, for other commands relevant to entering input.  File: ess.info, Node: Completion, Next: Completion details, Prev: Command-line editing, Up: Entering commands Completion of object names ========================== In the process buffer, the key is for completion, similar to that provided by Shell Mode for filenames. In Inferior S mode, pressing the key when the cursor is following the first few characters of an object name _completes_ the object name; if the cursor is following a file name `TAB' completes the file name. * `TAB' (`comint-dynamic-complete') Complete the S object name or filename before point. When the cursor is just after a partially-completed object name, pressing provides completion in a similar fashion to `tcsh' except that completion is performed over all known S object names instead of file names. ESS maintains a list of all objects known to S at any given time, which basically consists of all objects (functions and datasets) in every attached directory listed by the `search()' command along with the component objects of attached data frames (if your version of S supports them). For example, consider the three functions (available in Splus version 3.0) called `binomplot()', `binom.test()' and `binomial()'. Typing `bin TAB' after the S prompt will insert the characters `om', completing the longest prefix (`binom') which distinguishes these three commands. Pressing `TAB' once more provides a list of the three commands which have this prefix, allowing you to add more characters (say, `.') which specify the function you desire. After entering more characters pressing `TAB' yet again will complete the object name up to uniqueness, etc. If you just wish to see what completions exist without adding any extra characters, type `M-?'. * `M-?' (`ess-list-object-name-completions') List all possible completions of the object name at point. ESS also provides completion over the components of named lists accessed using the `$' notation, to any level of nested lists. This feature is particularly useful for checking what components of a list object exist while partway through entering a command: simply type the object name and `$' and press `TAB' to see the names of existing list components for that object. Completion is also provided over file names, which is particularly useful when using S functions such as `get()' or `scan()' which require fully expanded file names. Whenever the cursor is within an S string, pressing `TAB' completes the file name before point, and also expands any `~' or environment variable references. If the cursor is not in a string and does not follow a (partial) object name, the key has a third use: it expands history references. *Note History expansion::.  File: ess.info, Node: Completion details, Next: Transcript, Prev: Completion, Up: Entering commands Completion details ================== ESS automatically keeps track of any objects added or deleted to the system (such as new objects created, or directories added to the search list) to make completion as accurate as possible. Whenever ESS notices that search list has changed (1) when you attach a directory or data frame, the objects associated with it immediately become available for a completion; when it is detached completion is no longer available on those objects. To maintain a list of accessible objects for completion, ESS needs to determine which objects are contained in each directory or data frame on the search list. This is done at the start of each S session, by running the `objects()' command on every element of the search list. On some systems, however, this can be rather slow; it's doubly frustrating when you consider that most of the directories on the search list are the standard S libraries, which never change anyway! When ESS was installed, a database of the standard object names should have been created which should speed up this process at the start of an S session; if it has not been created you will get a warning like `S-namedb.el does not exist'. *Note Installation::, for information on how to create this database. Efficiency in completion is gained by maintaining a cache of objects currently known to S; when a new object becomes available or is deleted, only one component of the cache corresponding to the associated directory needs to be refreshed. If ESS ever becomes confused about what objects are available for completion (such as when if refuses to complete an object you *know* is there), the command `M-x ess-resynch' forces the _entire_ cache to be refreshed, which should fix the problem. ---------- Footnotes ---------- (1) The variable `ess-change-sp-regex' is a regular expression matching commands which change the search list. You will need to modify this variable if you have defined custom commands (other than `attach', `detach', `collection' or `library') which modify the search list.  File: ess.info, Node: Transcript, Next: Command History, Prev: Completion details, Up: Entering commands Manipulating the transcript =========================== Most of the time, the cursor spends most of its time at the bottom of the ESS process buffer, entering commands. However all the input and output from the current (and previous) ESS sessions is stored in the process buffer (we call this the transcript) and often we want to move back up through the buffer, to look at the output from previous commands for example. Within the process buffer, a paragraph is defined as the prompt, the command after the prompt, and the output from the command. Thus `M-{' and `M-}' move you backwards and forwards, respectively, through commands in the transcript. A particularly useful command is `M-h' (`mark-paragraph') which will allow you to mark a command and its entire output (for deletion, perhaps). For more information about paragraph commands, *note Paragraphs: (emacs)Paragraphs.. If an ESS process finishes and you restart it in the same process buffer, the output from the new ESS process appears after the output from the first ESS process separated by a form-feed (`^L') character. Thus pages in the ESS process buffer correspond to ESS sessions. Thus, for example, you may use `C-x [' and `C-x ]' to move backward and forwards through ESS sessions in a single ESS process buffer. For more information about page commands, *note Pages: (emacs)Pages.. * Menu: * Last command:: Manipulating the output from the last command * Process buffer motion:: Viewing more historic commands * Transcript resubmit:: Re-submitting commands from the transcript * Saving transcripts:: Keeping a record of your S session  File: ess.info, Node: Last command, Next: Process buffer motion, Prev: Transcript, Up: Transcript Manipulating the output from the last command --------------------------------------------- Viewing the output of the command you have just entered is a common occurrence and ESS provides a number of facilities for doing this. Whenever a command produces a longish output, it is possible that the window will scroll, leaving the next prompt near the middle of the window. The first part of the command output may have scrolled off the top of the window, even though the entire output would fit in the window if the prompt were near the bottom of the window. If this happens, you can use the command * `C-c C-e' (`comint-show-maximum-output') Move to the end of the buffer, and place cursor on bottom line of window. to make more of the last output visible. (To make this happen automatically for all inputs, set the variable `comint-scroll-to-bottom-on-input' to `t'; for information on this and other options for handling process input and output *note Shell Mode Options: (emacs)Shell Options..) If the first part of the output is still obscured, use * `C-c C-r' (`comint-show-output') Moves cursor to the previous command line and and places it at the top of the window. to view it. Finally, if you want to discard the last command output altogether, use * `C-c C-o' (`comint-kill-output') Deletes everything from the last command to the current prompt. to delete it. Use this command judiciously to keep your transcript to a more manageable size.  File: ess.info, Node: Process buffer motion, Next: Transcript resubmit, Prev: Last command, Up: Transcript Viewing more historic commands ------------------------------ If you want to view the output from more historic commands than the previous command, commands are also provided to move backwards and forwards through previously entered commands in the process buffer: * `C-c C-p' (`comint-previous-input') Moves point to the preceding command in the process buffer. * `C-c C-n' (`comint-next-input') Moves point to the next command in the process buffer. Note that these two commands are analogous to `C-p' and `C-n' but apply to command lines rather than text lines. And just like `C-p' and `C-n', passing a prefix argument to these commands means to move to the ARG'th next (or previous) command. (These commands are also discussed in *Note Shell History Copying: (emacs)Shell History Copying.) There are also two similar commands (not bound to any keys by default) which move to preceding or succeeding commands, but which first prompt for a regular expression (*note Syntax of Regular Expression: (emacs)Regexps.), and then moves to the next (previous) command matching the pattern. - Command: comint-backward-matching-input regexp arg - Command: comint-forward-matching-input regexp arg Search backward (forward) through the transcript buffer for the ARG'th previous (next) command matching REGEXP. ARG is the prefix argument; REGEXP is prompted for in the minibuffer.  File: ess.info, Node: Transcript resubmit, Next: Saving transcripts, Prev: Process buffer motion, Up: Transcript Re-submitting commands from the transcript ------------------------------------------ When moving through the transcript, you may wish to re-execute some of the commands you find there. ESS provides three commands to do this; these commands may be used whenever the cursor is within a command line in the transcript (if the cursor is within some command _output_, an error is signaled). Note all three commands involve the key. * `RET' (`inferior-ess-send-input') Copy the command under the cursor to the current command line, and execute it. * `C-c RET' (`comint-copy-old-input') Copy the command under the cursor to the current command line, but don't execute it. Leaves the cursor on the command line so that the copied command may be edited. * `M-RET' (`ess-transcript-send-command-and-move') Copy the command under the cursor to the current command line, and execute it. Moves the cursor to the following command. When the cursor is not after the current prompt, the key has a slightly different behavior than usual. Pressing `RET' on any line containing a command that you entered (i.e. a line beginning with a prompt) sends that command to the ESS process once again. If you wish to edit the command before executing it, use `C-c RET' instead; it copies the command to the current prompt but does not execute it, allowing you to edit it before submitting it. These two commands leave the cursor at the new command line, allowing you to continue with interactive use of S. If you wish to resubmit a series of commands from the transcript, consider using `M-RET' instead, which leaves the cursor at the command line following the one you re-submitted. Thus by using `M-RET' repeatedly, you can re-submit a whole series of commands. These commands work even if if the current line is a continuation line (i.e. the prompt is `+' instead of `>') -- in this case all the lines that form the multi-line command are concatenated together and the resulting command is sent to the ESS process (currently this is the only way to resubmit a multi-line command to the ESS process in one go). If the current line does not begin with a prompt, an error is signaled. This feature, coupled with the command-based motion commands described above, could be used as a primitive history mechanism. ESS provides a more sophisticated mechanism, however, which is described in *Note Command History::.  File: ess.info, Node: Saving transcripts, Prev: Transcript resubmit, Up: Transcript Keeping a record of your S session ---------------------------------- To keep a record of your S session in a disk file, use the Emacs command `C-x C-w' (`write-file') to attach a file to the ESS process buffer. The name of the process buffer will (probably) change to the name of the file, but this is not a problem. You can still use S as usual; just remember to save the file before you quit Emacs with `C-x C-s'. You can make ESS prompt you for a filename in which to save the transcript every time you start S by setting the variable `ess-ask-about-transfile' to `t'; see *Note Customizing startup::. We recommend you save your transcripts with filenames that end in `.St'. There is a special mode (ESS transcript mode -- *note Transcript Mode::) for editing transcript files which is automatically selected for files with this suffix. S transcripts can get very large, so some judicious editing is appropriate if you are saving it in a file. Use `C-c C-o' whenever a command produces excessively long output (printing large arrays, for example). Delete erroneous commands (and the resulting error messages or other output) by moving to the command (or its output) and typing `M-h C-w'. Also, remember that `C-c C-e' (and other hot keys) may be used for commands whose output you do not wish to appear in the transcript. These suggestions are appropriate even if you are not saving your transcript to disk, since the larger the transcript, the more memory your Emacs process will use on the host machine. Finally, if it is your intention to produce S source code (suitable for using with `source()' or inclusion in an S function) from a transcript, then the command `M-x ess-clean-region' may be of use. This command works in any Emacs buffer, and removes all prompts and command output from an ESS transcript within the current region, leaving only the commands. Don't forget to remove any erroneous commands first!  File: ess.info, Node: Command History, Next: History expansion, Prev: Transcript, Up: Entering commands Command History =============== ESS provides easy-to-use facilities for re-executing or editing previous commands. An input history of the last few commands is maintained (by default the last 50 commands are stored, although this can be changed by setting the variable `comint-input-ring-size' in `inferior-ess-mode-hook'.) The simplest history commands simply select the next and previous commands in the input history: * `M-p' (`comint-previous-input') Select the previous command in the input history. * `M-n' (`comint-next-input') Select the next command in the input history. For example, pressing `M-p' once will re-enter the last command into the process buffer after the prompt but does not send it to the ESS process, thus allowing editing or correction of the command before the ESS process sees it. Once corrections have been made, press `RET' to send the edited command to the ESS process. If you want to select a particular command from the history by matching it against a regular expression (*note Syntax of Regular Expression: (emacs)Regexps.), to search for a particular variable name for example, these commands are also available: * `M-r' (`comint-previous-matching-input') Prompt for a regular expression, and search backwards through the input history for a command matching the expression. * `M-s' (`comint-next-matching-input') Prompt for a regular expression, and search backwards through the input history for a command matching the expression. A common type of search is to find the last command that began with a particular sequence of characters; the following two commands provide an easy way to do this: * `A-M-r' (`comint-previous-matching-input-from-input') Select the previous command in the history which matches the string typed so far. * `A-M-s' (`comint-next-matching-input-from-input') Select the next command in the history which matches the string typed so far. Instead of prompting for a regular expression to match against, as they instead select commands starting with those characters already entered. For instance, if you wanted to re-execute the last `attach()' command, you may only need to type `att' and then `A-M-r' and `RET'. (Note: you may not have an key on your keyboard, in which case it may be a good idea to bind these commands to some other keys.) *Note Shell History Ring: (emacs)Shell Ring, for a more detailed discussion of the history mechanism.  File: ess.info, Node: History expansion, Next: Hot keys, Prev: Command History, Up: Entering commands References to historical commands ================================= Instead of searching through the command history using the command described in the previous section, you can alternatively refer to a historical command directly using a notation very similar to that used in `csh'. History references are introduced by a `!' or `^' character and have meanings as follows: `!!' The immediately previous command `!-N' The Nth previous command `!text' The last command beginning with the string `text' `!?text' The last command containing the string `text' In addition, you may follow the reference with a "word designator" to select particular "words" of the input. A word is defined as a sequence of characters separated by whitespace. (You can modify this definition by setting the value of `comint-delimiter-argument-list' to a list of characters that are allowed to separate words and themselves form words.) Words are numbered beginning with zero. The word designator usually begins with a `:' (colon) character; however it may be omitted if the word reference begins with a `^', `$', `*' or `-'. If the word is to be selected from the previous command, the second `!' character can be omitted from the event specification. For instance, `!!:1' and `!:1' both refer to the first word of the previous command, while `!!$' and `!$' both refer to the last word in the previous command. The format of word designators is as follows: `0' The zeroth word (i.e. the first one on the command line) `N' The Nth word, where N is a number `^' The first word (i.e. the second one on the command line) `$' The last word `X-Y' A range of words; `-Y' abbreviates `0-Y' `*' All the words except the zeroth word, or nothing if the command had just one word (the zeroth) `X*' Abbreviates X-$ `X-' Like `X*', but omitting the last word In addition, you may surround the entire reference except for the first `!' by braces to allow it to be followed by other (non-whitespace) characters (which will be appended to the expanded reference). Finally, ESS also provides quick substitution; a reference like `^old^new^' means "the last command, but with the first occurrence of the string `old' replaced with the string `new'" (the last `^' is optional). Similarly, `^old^' means "the last command, with the first occurrence of the string `old' deleted" (again, the last `^' is optional). To convert a history reference as described above to an input suitable for S, you need to "expand" the history reference, using the key. For this to work, the cursor must be preceded by a space (otherwise it would try to complete an object name) and not be within a string (otherwise it would try to complete a filename). So to expand the history reference, type `SPC TAB'. This will convert the history reference into an S command from the history, which you can then edit or press to execute. For example, to execute the last command that referenced the variable `data', type `!?data SPC TAB RET'.