R and S+ Mode Help
Name:S+/R Mode
Version:2.7
Last update:2021-05-18 15:43:55



This document describes the S+/R statistical mode for the text editor Alpha.

Introduction

This mode serves primarily to make it easier to write statistical syntax files for the R or S+ languages.
It is triggered automatically for files with a .s, .R or .r extension. Note that the .r extension is also claimed by the language C mode: use the menu item Alpha ↣ Global Setup ↣ Preferred Mapping in case of conflict.
The S mode includes its own menu called S+/R in the menu bar, allowing Alpha to act as a front end for the Mac OS X version of the R application. This means that R commands can be sent directly from Alpha to R for execution. The menu includes Options, Help, and Keywords submenus that contain items for obtaining command information, setting mode specific preferences, and adding or removing keywords.
Since version 2.6 of S mode, Alpha is able to communicate either with the R Gui application (R.app) or with RStudio. You can select which interpreter you want to use in the Options submenu (the current one is marked by a diamond symbol ◇).

Editing features

The S mode has the following capacities:
  1. Syntax coloring, syntax completion, commenting preferences.
  2. The mode contains a full set of electric completions, as well as a Completions Tutorial via the Alpha ↣ S+/R Mode Setup menu item.
  3. The mode lets you execute R code from Alpha either by sending the selected commands or an entire file to the R or RStudio gui applications, or by typing commands in an interactive R console within Alpha. See the Executing R code from Alpha section.
  4. An example syntax file is available. If you open the example syntax file through the provided hyperlink, it will open in a shell window. After you close the window, clicking on the hyperlink will return the unblemished original.
  5. The mode automatically indents the new line created by the Return key. Adjust the mode's Indent On Return preference if you want to turn off this feature. The mode recognizes both the continuation and the end of commands, indenting appropriately. The indentation amount can be set in the preferences panel Alpha ↣ Preferences ↣ Global Preferences ↣ Electrics. Click here to open the Electrics panel.
    One could also take advantage of Alpha's indent on return override key binding. Pressing Control-return will place the cursor on the next line without any indentation.
  6. The mode has navigation menu items, bound to the ⌃⇧N and ⌃⇧P key combos. These items are also bound to Control-Shift Arrrow keys, and to 1 and 3 on the keypad when the Num-Lock is turned off.
    Control-Shift up and down will find the prev/next command. The right and left Arrrow keys not only find prev/next commands, but will also place the cursor at the top of the window.
  7. The mode has its own indentation scheme, based upon unbalanced braces. Entire commands can also be highlighted with ⌃⇧S, or reformatted (aligning indentation) with ⌃⇧I.
    The Full Indent mode preference determines if continued commands are indented to the full Indentation Amount (which can be set using Alpha ↣ Preferences ↣ Global Preferences ↣ Electrics panel), or just half of this value. Click here to open the Electrics panel.
  8. The mode has Mark Window and Parse Function capabilities. Each marking routine can recognize either source or output files.
  9. Finally, on-line help is available for each mode through Shift-Command-Double-Clicking. If you double-click on a keyword while pressing the Shift-Command keys (⇧⌘), the corresponding help page is opened in the R application.

Executing R code from Alpha

The S+/R menu provides commands to execute R instructions from the currently edited window. The following commands are available:
Process Current File
This command sends the current window to R or RStudio for evaluation. If the window does not correspond to a file on disk, the entire text is executed line by line. Otherwise, the file itself is executed in the R application via a source command.
Process Selection
Similar to the previous command but Alpha sends only the current selection. You may select any set of R commands and send them for processing. If there is no selection, the entire text of the current window is processed line by line.
Process A Script
This command lets you select an R script file and sends it to R for processing via a source command.
Launch Console
This command displays an R console within Alpha. The console establishes a connection with the R command line (not the GUI application) and you can type any instructions. The result is displayed directly in the console so that you do not have to quit Alpha at all. Graphic commands need the AquaTerm program to be available on your machine.
Note that the R console is also directly available from the Console Launcher package. If this package is activated, you do not need to be in S+/R mode to lanch the console. See the documentation of the Console Launcher package.

Sweave support

Alpha supports the editing of sweave files (with a .Snw or .Rnw extension). For more information, see the Sweave support section of the LaTeX Mode User's Guide.

S mode preferences

S mode preferences include items for indentation, help keys, etc. Click here to open the S mode preferences.

Keywords completion

S-Plus is remarkably elegant in structure. Commands have arguments, and rarely does the language use the same names for both. Keywords are primarily based on release number 3.3, taken from the 'common commands' as listed in Venable and Ripley's Modern Applied Statistics with S-PLUS, second edition.
The Venable and Ripley MASS library can also be included in keyword lists for completions by checking the Use Mass Library preference.
Keywords can be reviewed in "sMode.tcl" .
Each of the S+/R commands has an electric completion available, and the mode comes with a Completions Tutorial, available via the Alpha ↣ Mode Setup ↣ Edit Tutorial menu item. Using the completion key, which can be defined with the menu item Alpha ↣ Global Setup ↣ Keyboard Shortcuts ↣ Special Keys, the user can type 
    glm<complete>
and Alpha will automatically insert the following text: 
    glm(| ~ •)•
    •
The template stops will allow the user to use the tab key to jump ahead to insert the needed variable names, and the last stop will position the cursor for the next command.
Additional keywords can be added or removed in two ways, through the Keywords submenu, and in an SPrefs.tcl file. Extra keywords defined (using either method) will be included in the electric completion routines. The Keywords ↣ Add Keywords menu item will let you specify your own keywords. These user defined keywords are recorded between sessions.
Completions Tutorial: "S Tutorial.s"

S mode Carriage Returns

S mode has its own indentation scheme, based upon unbalanced braces, and uses the Indent On Return preference for automatic indentation of new lines. Each time that you start a new line with the Return key, the previous non-commented line is evaluated for unmatched ( and ) -- ignoring any braces that appear within double quotes or after valid comment characters.
Lines that begin with ) will have their indentation reduced by one level to match the line with the matching (, as in 
    for (i in 1:length(data03.1$year)){
    	data03.1$year <- as.vector(data03.1$year)
    	if(data03.1$year[i] == "1965-70") (
    		data03.1$year[i] <- c("1965-69")
    	)
    }
In some cases, as when you are continuing a command, you might want to over-ride this behavior. For example, if you type 
    qqno|
and press the completion key, the command completes to 
    qqnorm(|)••
Typing resid and pressing the completion key again turns the line into 
    qqnorm(resid(|)••)••
If you type some more text and then press Return, the next line will automatically indent to 
    qqnorm(resid(out3.11), ylab = "deviance residuals",
    |)••
which is properly indented. This would be fine if this line actually terminated the command, but you might want to continue the command. To over-ride this behavior, which in this case would increase the level of indentation for the next line to 1, press Shift-Return instead: 
    qqnorm(resid(out3.11), ylab = "deviance residuals",
    	|)••
and then some more text and a regular carriage return will make the command look like 
    qqnorm(resid(out3.11), ylab = "deviance residuals",
    	xlab = "extremities"
    )
Entire commands can also be reformatted (aligning indentation) with ⌃⇧I.
To enter a carriage return with no indentation whatsoever, press ⌃-Return.

S File Marking

For S mode, Mark Window will return the first 35 characters of each command that begins a new line. Therefore it should not include any indented or continued commands. Headings will be marked, defined by three (and only three) comment characters and a space at the start of a line. Subheadings are indicated by four comment characters.
The FileThe Mark
### Section Heading• Section Heading
#### Subsection Heading* Subsection Heading
command varlist (options)command varlist (options)
Function parsing (available in the Parse popup menu of document windows) will return only the command names, in alphabetical order.

Adding an S Prefs file

To declare additional keywords in an SPrefs.tcl file, select the menu item Alpha ↣ Mode Setup ↣ Edit Prefs File and add these lines: 
    set SUserKeywords {
    	blah bladdity
    }

	S::buildCompletionList
Include as many keywords as desired within the braces, separating each keyword by at least one space or carriage return. Alpha will automatically load this preferences file the first time that the S mode is invoked.
Any keywords contained in these categories will not only be colorized, but will also be included as electric completions.

License and Disclaimer

Copyright (c) 2000-2021, Craig Barton Upright.
All rights reserved.
The S+/R Mode package is free software and distributed under the terms of the new BSD license:
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL CRAIG BARTON UPRIGHT BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.