Jonathan Marc Bearak

R & Stata Plug-ins for BBEdit

Revisions

This page provides software extensions to add support for R and Stata to BBEdit on macOS. “Language modules” enable syntax highlighting and contextual awareness, e.g., to index subroutines. Scripts send entire files or single or multiple commands directly to R and Stata at the stroke of a key.

Language Modules

These language modules make possible syntax coloring, auto-completion, function browsing, and code folding. These recognize function declarations and bodies, so you always know where you are in a long file. The Stata module supports Mata and Stata functions and programs, respectively, within the same file, as well as recursive strings and macros (as of 16 February 2015). Name your R scripts or Stata do-files with the extension .r or .do, respectively, to activate these features.

Place the language modules in your Language Modules folder.

Do not rename the language modules; they must remain named R.plist and Stata.plist.

Scripts

These scripts allow you to control R and Stata from within BBEdit.

Place these files in your Scripts folder.

How do these scripts work?

Quick Paste to R or Stata: This script pastes and executes the active line or selected text in Stata or R.

Paste to R or Stata: For R, this does the same thing as Quick Paste. For Stata, this copies the active line or selected text into a temporary do-file, saved to the same folder in which the .do-file is saved. (The last line of the temporary file contains an instruction which tells Stata to delete the temporary file.) The script then tells Stata to do this file. While R accepts the same commands at its console as it accepts in .r files, Stata accepts commands in .do-files that it does not accept at its console. For example, if a line of code ends with a comment, you need to use the Paste script and not the Quick Paste script.

Do File in R or Stata: This script saves your .do or .r file. Then, it calls the script in R or Stata, respectively, by way of the source or do commands.

Run File in R or Stata: This script saves your .do or .r file. Then, it calls the script in R or Stata, respectively, by way of the source(..., echo=FALSE) or run commands.

How do I activate these scripts from within my text editor?

From within BBEdit, select Scripts from the Palettes submenu of the Window menu. Highlight each of the four scripts, and, for each in turn, click the Set Shortcut button, which is in the toolbar of the script palette window.

  1. Select Quick Paste to R or Stata. Click Set Shortcut. Type ⌘R. Press return.
  2. Select Paste to R or Stata. Click Set Shortcut. Type ⌘I. Press return.
  3. Select Do File in R or Stata. Click Set Shortcut. Type ⇧⌘R. Press return.
  4. Select Run File in R or Stata. Click Set Shortcut. Type ⇧⌘I. Press return.

Note that you need assign filenames – and that these filenames must end with .do or .r – for these scripts to work. If these scripts do not cause anything to happen, or if you receive an error message, this is the reason.

Finish Configuring BBEdit

Three issues remain. Two pertain only to Stata. The third pertains to both Stata and R.

1. In Stata, the carriage return indicates the end of a sentence. It seems like Stata reads each line as its own statement, but, this is not true, and this has critical consequences. Suppose your do-file contains 3 lines, each of which contains a statement. Stata will only execute the first and second statements; unless your file contains a fourth line (an empty line), Stata will not execute the third statement. (Stata will not print an error. It will simply ignore your last line of code.) You may never notice this if you only work in Stata's built-in do-file editor. This is because Stata's built-in editor always includes an extra, blank line, to files it saves. It does not show you this line, but, it includes it. You can configure BBEdit to do the same.

2. Stata will recognize tabs as whitespace only when you execute code as part of a do-file. If a line contains tabs, you cannot use the Quick Paste script – you have to use the Paste script instead. Better to tell BBEdit to insert a some spaces (by default, four spaces) whenever you press the tab key. You still cannot use Quick Paste if your line contains a comment – unless you select the portion of the line before the comment begins, and then run Quick Paste.

3. Although the language modules tell BBEdit how to recognize comments – and BBEdit will colorize them – they will not pick up on this, to allow you to automatically comment/uncomment lines/selections. Note the Un/Comment Selection item in the Text menu. You can assign a keyboard shortcut for this – see Menus & Shortcuts in the Preferences window. I suggest ⌘. (command + period).

To resolve these issues, follow these steps

  1. Select Preferences from the BBEdit menu.
  2. Select Languages from the left-hand panel of the Preferences window that you opened in step 1.
  3. Press the + sign in the upper half of the right-hand panel, and choose Stata from the drop-down menu.
  4. The general tab appears. Under Line comment, type //
  5. Under Block comment start, type /*
  6. Under Block comment end, type */
  7. Under Reference URL Template, type www.stata.com/help.cgi?__SYMBOLNAME__
  8. Choose the Editor tab.
  9. Check Auto-expand tabs.
  10. Choose the Files tab.
  11. Below When saving, check Ensure file ends with line break
  12. Press OK
  13. Press the + sign in the upper half of the right-hand panel, and choose R from the drop-down menu.
  14. The general tab appears. Under Line comment, type #
  15. Press OK
  16. You may now close the Preferences window.

Allocating Window Space to Your Statistical Software and Text Editor

After you set up these scripts, you can quickly and easily send commands, a series of commands, or an entire file to your statistical software from within your text editor. Your text editor will remain active, so that you can continue working within it. Your commands will execute in a Stata or R window. If this window is hidden, it will remain hidden. Regardless, your commands will execute.

You will want to allocate window space to your text editor and statistical software. For example, you may wish your text editor to consume the left half of your screen, and your statistical software to consume the right half of your screen. To accomplish this quickly and easily, use “window snapping”. For this end, you will need to download, install and open Better Touch Tool

Acknowledgements

I wrote the R language module in 2009, by extending a 2005 module by Gene Cutler. I updated the keyword lists, and programmed regular expressions so that BBEdit could identify comments, subroutine names, and subroutine bodies. Please see the comments at the top of the .plist file for additional details.

I wrote expressions for Stata and Mata in 2014/15, building atop John Gardner's simpler language module, which offered syntax highlighting, so that BBEdit would understand Stata programs, Mata functions, block and line comments, and Stata strings and macros. My module follows recursive strings and macros, including recursive combinations of these, except -- for performance reasons -- those that span multiple lines.

I wrote scripts to accompany my R language module around the same time. Years later, I found Steve Samuels' scripts, based on a script by Ben Hulley, for sending files or selections to Stata. I merged these scripts with my R scripts, so that one could send a selection, file, or line – without having to highlight any text – directly to R or Stata. Also unlike these scripts, my scripts run in your current working directory (I do not reassign your working directory to the location of these scripts), and, in addition, your text editor remains the active application. (I also perform error-checking, so that weird error messages do not pop up that may confuse beginners -- e.g., if you try to run a script on an unnamed file, or a file without a Stata or R extension.)