Dies ist ess.info, hergestellt von Makeinfo Version 4.0 aus ess.texi. ESS -- Emacs Speaks Statistics ****************************** START-INFO-DIR-ENTRY * ESS: (ess). Emacs Speaks Statistics (S/S+/R, SAS, BUGS, Stata, XLisp-Stat). END-INFO-DIR-ENTRY  File: ess.info, Node: Philosophies for using ESS(S), Next: Scenarios for use (possibilities--based on actual usage), Prev: ESS-help--assistance with viewing help, Up: Help for the S family Philosophies for using ESS[S] ============================= The first is preferred, and configured for. The second one can be retrieved again, by changing emacs variables. 1: (preferred by the current group of developers): The source code is real. The objects are realizations of the source code. Source for EVERY user modified object is placed in a particular directory or directories, for later editing and retrieval. 2: (older version): S objects are real. Source code is a temporary realization of the objects. Dumped buffers should not be saved. _We_strongly_discourage_this_approach_. However, if you insist, add the following lines to your .emacs file (GNU emacs uses the filename `~/.emacs' and Xemacs uses the filename `~/.xemacs/init.el' for the initialization file): (setq ess-keep-dump-files 'nil) (setq ess-delete-dump-files t) (setq ess-mode-silently-save nil) The second saves a small amount of disk space. The first allows for better portability as well as external version control for code.  File: ess.info, Node: Scenarios for use (possibilities--based on actual usage), Next: Customization Examples and Solutions to Problems, Prev: Philosophies for using ESS(S), Up: Help for the S family Scenarios for use (possibilities-based on actual usage) ======================================================= We present some basic suggestions for using ESS to interact with S. These are just a subset of approaches, many better approaches are possible. Contributions of examples of how you work with ESS are appreciated (especially since it helps us determine priorities on future enhancements)! (comments as to what should be happening are prefixed by "##"). 1: ## Data Analysis Example (source code is real) ## Load the file you want to work with C-x C-f myfile.s ## Edit as appropriate, and then start up S-PLUS 3.x M-x S+3 ## A new buffer *S+3:1* will appear. Splus will have been started ## in this buffer. The buffer is in iESS [S+3:1] mode. ## Split the screen and go back to the file editing buffer. C-x 2 C-x b myfile.s ## Send regions, lines, or the entire file contents to S-PLUS. For regions, ## highlight a region with keystrokes or mouse and then send with: C-c C-r ## Re-edit myfile.s as necessary to correct any difficulties. Add ## new commands here. Send them to S by region with C-c C-r, or ## one line at a time with C-c C-n. ## Save the revised myfile.s with C-x C-s. ## Save the entire *S+3:1* interaction buffer with C-c C-s. You ## will be prompted for a file name. The recommended name is ## myfile.St. With the *.St suffix, the file will come up in ESS ## Transcript mode the next time it is accessed from Emacs. 2: ## Program revision example (source code is real) ## Start up S-PLUS 3.x in a process buffer (this will be *S+3:1*) M-x S+3 ## Load the file you want to work with C-x C-f myfile.s ## edit program, functions, and code in myfile.s, and send revised ## functions to S when ready with C-c C-f ## or highlighted regions with C-c C-r ## or individual lines with C-c C-n ## or load the entire buffer with C-c C-l ## save the revised myfile.s when you have finished C-c C-s 3: ## Program revision example (S object is real) ## Start up S-PLUS 3.x in a process buffer (this will be *S+3:1*) M-x S+3 ## Dump an existing S object my.function into a buffer to work with C-c C-d my.function ## a new buffer named yourloginname.my.function.S will be created with ## an editable copy of the object. The buffer is associated with the ## pathname /tmp/yourloginname.my.function.S and will amlost certainly not ## exist after you log off. ## enter program, functions, and code into work buffer, and send ## entire contents to S-PLUS when ready C-c C-b ## Go to *S+3:1* buffer, which is the process buffer, and examine ## the results. C-c C-y ## The sequence C-c C-y is a shortcut for: C-x b *S+3:1* ## Return to the work buffer (may/may not be prefixed) C-x C-b yourloginname.my.function.S ## Fix the function that didn't work, and resubmit by placing the ## cursor somewhere in the function and C-c C-f ## Or you could've selected a region (using the mouse, or keyboard ## via setting point/mark) and C-c C-r ## Or you could step through, line by line, using C-c C-n ## Or just send a single line (without moving to the next) using C-c C-j ## To fix that error in syntax for the "rchisq" command, get help ## by C-c C-v rchisq 4: Data Analysis (S object is real) ## Start up S-PLUS 3.x, in a process buffer (this will be *S+3:1*) M-x S+3 ## Work in the process buffer. When you find an object that needs ## to be changed (this could be a data frame, or a variable, or a ## function), dump it to a buffer: C-c C-d my.cool.function ## Edit the function as appropriate, and dump back in to the ## process buffer C-c C-b ## Return to the S-PLUS process buffer C-c C-y ## Continue working. ## When you need help, use C-c C-v rchisq ## instead of entering: help("rchisq")  File: ess.info, Node: Customization Examples and Solutions to Problems, Prev: Scenarios for use (possibilities--based on actual usage), Up: Help for the S family Customization Examples and Solutions to Problems ================================================ 1. Suppose that you are primarily an SPLUS 3.4 user, occasionally using S version 4, and sick and tired of the buffer-name *S+3* we've stuck you with. Simply edit the "ess-dialect" alist entry in the essd-s+3.el and essd-s4.el files to be "S" instead of "S4" and "S+3". This will insure that all the inferior process buffer names are "*S*". 2. Suppose that you WANT to have the first buffer name indexed by ":1", in the same manner as your S-PLUS processes 2,3,4, and 5 (for you heavy simulation people). Then uncomment the line in ess-site (or add after your (require 'ess-site) or (load "ess-site") command in your .emacs file, the line: (setq ess-plain-first-buffername nil) ) 3. Fontlocking sometimes fails to behave nicely upon errors. When Splus dumps, a mis-matched " (double-quote) can result in the wrong font-lock face being used for the remainder of the buffer. Solution: add a " at the end of the "Dumped..." statement, to revert the font-lock face back to normal.  File: ess.info, Node: Help for SAS, Next: Entering commands, Prev: Help for the S family, Up: Top Help for SAS ************ * Menu: * ESS(SAS)--Design philosophy:: * ESS(SAS)--Editing files:: * iESS(SAS)--Interactive SAS processes:: * ESS(SAS)--Batch SAS processes:: * ESS(SAS)--Function keys for batch processing:: * ESS(SAS)--TAB key:: * ESS(SAS)--Usage scenarios:: * iESS(SAS)--Common problems:: * ESS(SAS)--MS Windows:: ESS[SAS] was designed for use with SAS. It is descended from emacs macros developed by John Sall for editing SAS programs and SAS-mode by Tom Cook. Those editing features and new advanced features are part of ESS[SAS]. The user interface of ESS[SAS] has similarities with ESS[S] and the SAS Display Manager. By emacs, we mean either GNU Emacs from the Free Software Foundation or XEmacs from the XEmacs Project.  File: ess.info, Node: ESS(SAS)--Design philosophy, Next: ESS(SAS)--Editing files, Prev: Help for SAS, Up: Help for SAS ESS[SAS]-Design philosophy ========================== ESS[SAS] was designed to aid the user in writing and maintaining SAS programs, such as myfile.sas. Both interactive and batch submission of SAS programs is supported. ESS[SAS] was written with two primary goals. 1. Using the emacs environment is desirable for users accessing a remote computer via a network or dial-up who can not use the SAS Display Manager. 2. Using the emacs environment is desirable for local users as well due to the inherent efficiency of using the same, superior interface all of the time.  File: ess.info, Node: ESS(SAS)--Editing files, Next: iESS(SAS)--Interactive SAS processes, Prev: ESS(SAS)--Design philosophy, Up: Help for SAS ESS[SAS]-Editing files ====================== ESS[SAS] is the mode for editing SAS language files. This mode handles: - proper indenting, generated by both [Tab] and [Return]. - color and font choices based on syntax. - ability to send the contents of an entire buffer, a highlighted region, or a single line to an interactive SAS process. - ability to switch between processes which would be the target of the buffer (for the above). - ability to save and submit the file you are working on as a batch SAS process with a single keypress and to continue editing while it is runs in the background. - capability of killing the batch SAS process through the shell buffer or allow the SAS process to keep on running after you exit emacs. - single keypress navigation of .sas, .log and .lst files (.log and .lst files are automatically refreshed with each keypress). ESS[SAS] is automatically turned on when editing a file with a ".sas" suffix (or other, if specified in ess-site via auto-mode-alist). The batch processing keypress commands can be enabled to use the same function keys that the SAS Display Manager does. The interactive capabilities of ESS require you to start an inferior SAS process with M-x SAS (*Note iESS(SAS)--Interactive SAS processes::.) At this writing, the indenting and syntax highlighting are generally correct. Known issues: for multiple line * or %* comments, only the first line is highlighted; for .log files, only the first line of a NOTE:, WARNING: or ERROR: message is highlighted; unmatched single/double quotes in CARDS data lines are NOT ignored.  File: ess.info, Node: iESS(SAS)--Interactive SAS processes, Next: ESS(SAS)--Batch SAS processes, Prev: ESS(SAS)--Editing files, Up: Help for SAS iESS[SAS]-Interactive SAS processes =================================== iESS (inferior ESS) is the method for interfacing with interactive statistical processes (programs). iESS[SAS] is what is needed for interactive SAS programming. iESS[SAS] works best with the following settings for SAS command-line options (the default of inferior-SAS-args): -stdio -linesize 80 -noovp -nosyntaxcheck -stdio required to make the redirection of stdio work -linesize 80 keeps output lines from folding on standard terminals -noovp prevents error messages from printing 3 times -nosyntaxcheck permits recovery after syntax errors To start up iESS[SAS] mode, use: M-x SAS The *SAS:1.log* buffer in ESStr mode corresponds to the file myfile.log in SAS batch usage and to the "SAS: LOG" window in the SAS Display Manager. All commands submitted to SAS, informative messages, warnings, and errors appear here. The *SAS:1.lst* buffer in ESSlst mode corresponds to the file myfile.lst in SAS batch usage and to the "SAS: OUTPUT" window in the SAS Display Manager. All data related printed output from the PROCs appear in this window. The iESS [SAS:1] buffer exists solely as a communications buffer. Files are edited in the myfile.sas buffer. The C-c C-r key in ESS[SAS] is the functional equivalent of bringing a file into the "SAS: PROGRAM EDITOR" window followed by the 'Local' 'Submit' menu commands. The user should never use this buffer directly. Troubleshooting: *Note iESS(SAS)--Common problems::.  File: ess.info, Node: ESS(SAS)--Batch SAS processes, Next: ESS(SAS)--Function keys for batch processing, Prev: iESS(SAS)--Interactive SAS processes, Up: Help for SAS ESS[SAS]-Batch SAS processes ============================ Submission of a SAS batch job is dependent on your environment. ess-sas-submit-method is determined by your operating system and your shell. It defaults to 'sh unless you are running Windows or Mac Classic. Under Windows, it will default to 'sh if you are using bash for your shell rather than MS-DOS ('ms-dos). On Mac OS X, it will default to 'sh, but under Mac Classic AppleScript is used ('apple-script). You will also set this to 'sh if the SAS batch job needs to run on a remote machine rather than your local machine. This works transparently if you are editing the remote file via ange-ftp/EFS or tramp. However, if you are editing the file locally and transferring it back and forth with Kermit, you need some additional steps. First of all, start Kermit locally before remotely logging in. Open a local copy of the file with the ess-kermit-prefix character prepended (the default is "#"). Execute the command ess-kermit-get which brings the contents of the remote file into your local copy. Also, note that the remote Kermit command is defined by ess-kermit-command. The command used by the SUBMIT function key (F3 or F8) to submit a batch SAS job, whether local or remote, is ess-sas-submit-command which defaults to sas-program. sas-program is "invoke SAS using program file" for Mac Classic and "sas" otherwise. However, you may have to alter ess-sas-submit-command for a particular program, so it is defined as buffer-local (conveniently, you can set it in Local Variables: at the end of your program). The command line is also made of ess-sas-submit-pre-command, ess-sas-submit-post-command and ess-sas-submit-command-options (the last of which is also buffer-local). Here are some examples for your .emacs file (you may also use M-x customize-variable with): (setq ess-sas-submit-pre-command "nohup") ;'sh default (setq ess-sas-submit-post-command "-rsasuser &") ;'sh default (setq ess-sas-submit-command "/usr/local/sas/sas") ;'sh example (setq ess-sas-submit-pre-command "start") ;'ms-dos default (setq ess-sas-submit-post-command "-rsasuser -icon") ;'ms-dos default (setq ess-sas-submit-command "c:/progra~1/sas/sas.exe") ;Windows example (setq ess-sas-submit-command "c:\\progra~1\\sas\\sas.exe");Windows example There is a built-in delay before a batch SAS job is submitted when using a Unix shell under Windows. This is necessary in many cases since the shell might not be ready to receive a command. This delay is currently set high enough so as not to be a problem. But, there may be cases when it needs to be set higher, or could be set much lower to speed things up. You can over-ride the default in your .emacs file by: (setq ess-sleep-for 0.2)  File: ess.info, Node: ESS(SAS)--Function keys for batch processing, Next: ESS(SAS)--TAB key, Prev: ESS(SAS)--Batch SAS processes, Up: Help for SAS ESS[SAS]-Function keys for batch processing =========================================== The setup of function keys for SAS batch processing is unavoidably complex, but the usage of function keys is simple. There are five distinct options: Option 1 (default). Function keys in ESS[SAS] are not bound to elisp commands. This is in accordance with the GNU Elisp Coding Standards (GECS) which do not allow function keys to be bound so that they are available to the user. Options 2-5. Since GECS does not allow function keys to be bound by modes, these keys are often unused. So, ESS[SAS] provides users with the option of binding elisp commands to these keys. Users who are familiar with SAS will, most likely, want to duplicate the function key capabilities of the SAS Display Manager. There are four options (noted in parentheses below). a. SAS provides different function key definitions with its Unix (2, 4) and Windows (3, 5) products; ESS can use either. b. The ESS[SAS] function key definitions can be active in all buffers (global: 4, 5) or limited (local: 2, 3) only to buffers with files that are associated with ESS[SAS] as defined in your auto-mode-alist. The distinction between local and global is subtle. If you want the ESS[SAS] definitions to work when you are in the *shell* buffer or when editing files other than the file extensions that ESS[SAS] recognizes, you will most likely want to use the global definitions. If you want your function keys to understand SAS batch commands when you are editing SAS files, and to behave normally when editing other files, then you will choose the local definitions. The option can be chosen by the person installing ESS for a site or by an individual. a. For a site installation or an individual, uncomment ONLY ONE of the following lines in your ess-site.el! ESS[SAS] Function keys are available in ESS[SAS] if you uncomment either 2 or 3 and in all modes if you uncomment 4 or 5: ;;2; (setq ess-sas-local-unix-keys t) ;;3; (setq ess-sas-local-pc-keys t) ;;4; (setq ess-sas-global-unix-keys t) ;;5; (setq ess-sas-global-pc-keys t) The names -unix- and -pc- have nothing to do with the operating system that you are running. Rather, they mimic the definitions that the SAS Display Manager uses by default on those platforms. b. If your site installation has configured the keys contrary to your liking, say 2, you must turn it off before selecting a different option, say 3. (load "ess-site") (setq ess-sas-local-unix-keys nil) ;;2 (setq ess-sas-local-pc-keys t) ;;3 Finally, we get to what the function keys actually do. You may recognize some of the Short Names as SAS Display Manager commands (they are in all capitals). Unix PC Short Name Long Description F2 F2 refresh revert the current buffer with the file of the same name if the file is newer than the buffer F3 F8 SUBMIT save the current .sas file (which is either the .sas file in the current buffer or the .sas file associated with the .lst or .log file in the current buffer) and submit the file as a batch SAS job F4 F5 PROGRAM switch buffer to .sas file F5 F6 LOG switch buffer to .log file, `refresh' and goto next error message, if any F6 F7 OUTPUT switch buffer to .lst file and `refresh' F7 F4 filetype-1 switch buffer to filetype-1 (defaults to .txt) file and `refresh' F8 F3 shell switch buffer to shell F9 F9 VIEWTABLE open an interactive FSEDIT/FSBROWSE session on the SAS dataset near point F10 F10 toggle-log toggle ESS[SAS] for .log files; may be useful for certain debugging situations F11 F11 filetype-2 switch buffer to filetype-2 (defaults to .dat) file and `refresh' F12 F12 viewgraph open a GSASFILE near point for viewing either in emacs or with an external viewer C-F3 C-F8 submit-region write region to ess-temp.sas and submit C-F5 C-F6 append-to-log append ess-temp.log to the current .log file C-F6 C-F7 append-to-output append ess-temp.lst to the current .lst file SUBMIT, PROGRAM, LOG and OUTPUT need no further explanation since they mimic the SAS Display Manager function key definitions. However, six other keys have been provided for convenience and are described below. `shell' switches you to the *shell* buffer where you can interact with your operating system. This is especially helpful if you would like to kill a SAS batch job. You can specify a different buffer name to associate with a SAS batch job (besides *shell*) with the buffer-local variable ess-sas-shell-buffer. This allows you to have multiple buffers running SAS batch jobs on multiple local/remote computers that may rely on different methods specified by the buffer-local variable ess-sas-submit-method. F2 performs the `refresh' operation on the current buffer. `refresh' compares the buffer's last modified date/time with the file's last modified date/time and replaces the buffer with the file if the file is newer. This is the same operation that is automatically performed when LOG, OUTPUT, `filetype-1' or `filetype-2' are pressed. `filetype-1' switches you to a file with the same file name as your .sas file, but with a different extension (.txt by default) and performs `refresh'. You can over-ride the default extension; for example in your .emacs file: (setq ess-sas-suffix-1 "csv") ; for example F9 will prompt you for the name of a permanent SAS dataset near point to be opened for viewing by PROC FSEDIT. You can control the SAS batch command-line with ess-sas-data-view-submit-options. For controlling the SAS batch commands, you have the global variables ess-sas-data-view-libname and ess-sas-data-view-fsview-command as well as the buffer-local variable ess-sas-data-view-fsview-statement. If you have your SAS LIBNAMEs defined in autoexec.sas, then the defaults for these variables should be sufficient. F10 toggles ESS[SAS] mode for .log files which is off by default (technically, it is SAS-log-mode, but it looks the same). The syntax highlighting can be helpful in certain debugging situations, but large .log files may take a long time to highlight. F11 is the same as `filetype-1' except it is .dat by default. F12 will prompt you for the name of a GSASFILE near point to be opened for viewing either with emacs or with an external viewer. Depending on your version of emacs and the operating system you are using, emacs may support .gif and .jpg files internally. You may need to change the following two variables for your own situation: (setq ess-sas-graph-suffix-regexp "[.]\\(e?ps\\|gif\\|jpe?g\\|tiff?\\)") (setq ess-sas-image-viewer "kodakimg") ;; Windows external viewer  File: ess.info, Node: ESS(SAS)--TAB key, Next: ESS(SAS)--Usage scenarios, Prev: ESS(SAS)--Function keys for batch processing, Up: Help for SAS ESS[SAS]-TAB key ================ Two options. The TAB key is bound by default to sas-indent-line. This function is used to syntactically indent SAS code so PROC and RUN are in the left margin, other statements are indented 4 spaces from the margin, continuation lines are indented 4 spaces in from the beginning column of that statement. This is the type of functionality that emacs provides in most programming language modes. This functionality is equivalent to uncommenting the following line in ess-site.el: (setq ess-sas-edit-keys-toggle 0) ESS provides an alternate behavior for the TAB key that makes it behave as it does in other editors, i.e. move the cursor to the next tab stop. The alternate behavior also provides a backwards TAB, C-TAB, that moves the cursor to the tab stop to the left and deletes any characters between them. This functionality is obtained by uncommenting the following line in ess-site.el: (setq ess-sas-edit-keys-toggle 1) Under the alternate behavior, the TAB key is bound to tab-to-tab-stop and the tab stops are set at multiples of sas-indent-width.  File: ess.info, Node: ESS(SAS)--Usage scenarios, Next: iESS(SAS)--Common problems, Prev: ESS(SAS)--TAB key, Up: Help for SAS ESS[SAS]-Usage scenarios ======================== We present one scenario for using ESS to interact with SAS (comments are prefixed by "##"). SAS Batch (ess-sas-global-unix-keys shown with ess-sas-global-pc-keys denoted by -pc- comments) ## Find the file you want to work with C-x C-f myfile.sas ## myfile.sas will be in ESS[SAS] mode ## Edit as appropriate, then save and submit the batch SAS job. ## -pc- F8 F3 ## The job runs in the shell buffer while you continue to edit ## myfile.sas. If ess-sas-submit-method is 'sh, then the ## message buffer will display the shell notification when the ## job is complete. The 'sh setting also allows you to ## terminate the SAS batch job before it is finished. ## -pc- F3 F8 ## Terminating a SAS batch job; typing in the *shell* buffer. kill %1 ## You may want to visit the .log (whether the job is still running ## or it is finished) and check for error messages. The .log will be ## refreshed and you will be placed in it's buffer. You will be ## taken to the 1st error message after the cursor, if any. ## -pc- F6 F5 ## Goto the next error message, if any. ## -pc- F6 F5 ## Now, refresh the .lst and go to it's buffer. ## -pc- F7 F6 ## If you wish to make changes, go to the .sas file with ## -pc- F5 F4 ## Make your editing changes and submit again. ## -pc- F8 F3 Interactive SAS ## Find the file you want to work with C-x C-f myfile.sas ## myfile.sas will be in ESS[SAS] mode ## Edit as appropriate, and then start up SAS with the cursor in ## the myfile.sas buffer M-x SAS ## Four buffers will appear on screen: ## myfile.sas in ESS[SAS] mode # your source file ## *SAS:1* in iESS [SAS:1] mode # ESS communication buffer ## *SAS:1.log* in Shell [] ESStr mode # SAS log information ## *SAS:1.lst* in Shell [] ESSlst mode # SAS listing information ## If you would prefer each of the four buffers to appear in its ## own individual frame, you can arrange for that. Place the ## cursor in the buffer displaying myfile.sas. Enter the ## sequence: C-c C-w ## The cursor will normally be in buffer myfile.sas. ## If not, put it there: C-x b myfile.sas ## Send regions, lines, or the entire file contents to SAS ## (regions are most useful). A highlighted region will normally ## begin with the keywords 'DATA' or 'PROC' and end with the ## keyword 'RUN;' C-c C-r ## Information appears in the log buffer, analysis results in the ## listing buffer. In case of errors, make the corrections in the ## myfile.sas buffer and resubmit with another C-c C-r ## PROC GPLOT graphs will normally be produced in a postscript ## file and be viewed later. Include the lines /* required gsoptions for batch files */ /* comment out these lines for interactive use on X-terminals*/ filename grafout 'temp.ps'; goptions device=ps gsfname=grafout gsfmode=append gaccess=sasgastd; ## in myfile.sas. ## PROC PLOT graphs can be viewed in the listing buffer. You may ## wish to control the vertical spacing to allow the entire plot ## to be visible on screen, for example, by proc plot; plot a*b / vpos=25; ## At the end of the session you may save the log and listing ## buffers with the usual C-x C-s commands. You will be prompted ## for a file name. Typically, the names myfile.log and mfile.lst ## will be used. You will almost certainly want to edit the saved ## files before including them in a report. The files are ## read-only by default. You can make them writable by the emacs ## command C-x C-q. ## At the end of the session, the input file myfile.sas will ## typically have been revised. You can save it. It can be used ## later as the beginning of another iESS[SAS] session. It can ## also be used as a batch input file to SAS. ## The *SAS:1* buffer is strictly for ESS use. The user should ## never need to read it or write to it. Refer to the .lst and ## .log buffers for monitoring output!  File: ess.info, Node: iESS(SAS)--Common problems, Next: ESS(SAS)--MS Windows, Prev: ESS(SAS)--Usage scenarios, Up: Help for SAS iESS[SAS]-Common problems ========================= 1. iESS[SAS] does not work on Windows. In order to run SAS inside an emacs buffer, it is necessary to start SAS with the -stdio option. SAS does not support the -stdio option on Windows. 2. If M-x SAS gives errors upon startup, check the following: - you are running Windows: see 1. - ess-sas-sh-command (in the ESS source directory) needs to be executable (solution: "chmod ugo+rx ess-sas-sh-command"). - sas isn't in your executable path (verify using "which sas" from a shell command-line) 3. M-x SAS starts SAS Display Manager. Probably, the command "sas" on your system calls a shell script. Change the line in ess-sas-sh-command file from: sas $stdout 2>$stderr $ to the correct path name of the sas executable, for example: /usr/local/sas612/sas $stdout 2>$stderr $ To find the sas exectuable, you can execute the unix command: find / -name sas -print and expect a response similar to the following /usr/local/sas612/sas  File: ess.info, Node: ESS(SAS)--MS Windows, Prev: iESS(SAS)--Common problems, Up: Help for SAS ESS[SAS]-MS Windows =================== * iESS[SAS] does not work on Windows. *Note iESS(SAS)--Common problems::. * ESS[SAS] mode for editing SAS language files works very well. *Note ESS(SAS)--Editing files::. * There are two execution options for SAS on Windows. You can use batch. *Note ESS(SAS)--Batch SAS processes::. Or you can mark regions with the mouse and submit the code with `submit-region' or paste them into SAS Display Manager.  File: ess.info, Node: Entering commands, Next: Editing, Prev: Help for SAS, 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 * Hot keys:: Hot keys for common commands * Statistical Process running in ESS?:: * 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!