Sending Code from Emacs to Stata

Starting with version, ado-mode can send code from the emacs file you are editing directly to a running instance of Stata. As of the version, it works on Mac OS X and MS Windows, but the framework is built so that it should not be too hard to get it working for another Unixes. (see the innards section below). Of course this last statement is theoretical: in reality there are so many windows managers in Unix, that it would be hard to maintain a different set of scripts for each windows manager.

Starting with version, ado-mode can even send code to targeted instances (or all instances) of Stata under MS Windows. See the multiple instances section below).

What gets sent?

This is quite simple. If some code is selected within Emacs, that code is sent to Stata for consumption. If no code is selected within Emacs, whatever command the insertion point is sitting in (or just after) will be sent to Stata. By default, the key combination M-RET (meta-return) is bound to sending a region to Stata. Thus, it is possible to type commands into Emacs, using meta-return, and use the Emacs editor instead of Stata's command window.

There are a couple of choices that can be made about how code is sent to Stata. These can be changed most easily using Emacs' built-in customization routines: type M-x customize-group RET ado-stata-interaction RET to get to the proper place.

Modes of Work

There are four ways that ado-mode can get Stata to run code: via the Command window, via a temporary include file, via a temporary do-file, or via a menu-item running a temporary do-file. These four choices populate the Review window differently

Command window
If code is passed to the Command window, the commands are kept in the Review window. You may still use /// continuations, // and /* ... */ comments, because these will be stripped before the text is sent to Stata. Working this way is allows using Emacs as though it were the Command window, while allowing reuse of old commands from within Stata. This is the default behavior.
To mimic working out of the Do-file editor, you can tell ado-mode to send code to Stata via a temporary do-file. No individual commands appear in the Review window. Many do .../ commands appear, though (as when using the Do-file editor). To use this option, change the Ado Submit Default to dofile.
Include file
This is identical to working via do-files, with one major improvement: the command used to execute the file is include instead of do. This means that local macros retain their values. This mode is very useful When sending snippets of code from a larger do-file, because it allows working incrementally. Just as when working via do-files, no individual commands appear in the Review window. Many include .../ commands appear, though. To use this option, change the Ado Submit Default to include. Many thanks to David Lucca for suggesting this.
To mimic using the Do-file editor without putting any commands in the Review window at all, tell ado-mode to send code to Stata using a menu item. In return for not filling up the Review window, this gives somewhat odd-looking results in the results window, because there will be no command prompt (.) in front of any command. To use this option change the Ado submit default to menu. (Many thanks to Elliot Lowy and his presentation about passing code in jEdit for inspiring this way to work)

Dual Monitors vs. Little Laptop Screen

By default, ado-mode is set up for people running on a single small monitor. Hence, when code is sent over to Stata for consumption, Stata remains in the foreground after completing its meal.

If you have dual monitors, so that Emacs and Stata don't overlap, you can automatically come back to Emacs after submitting code. Simply change the Ado Comeback Flag to 't' for this to work. This can also be changed on a buffer-by-buffer basis from the Ado-mode menu which appears when in ado-mode.

Multiple Instances

As of version, ado-mode can work with multiple instances of Stata. This feature works in MS Windows only, because Mac OS X is not designed to distinguish between multiple instances of the same application. In any case, here is how it works.

How the code is sent is ruled by 5 options:

Some examples:

For each of the following, suppose that there are two instances of StataMP 11.1, one instance of StataSE 10.1 running, and one instance of StataMP 10.1 running.

This implementation was created in the vacuum of my mind, so if you have a better idea of how this should be set up, please let me know. For all you emacs-hackers out there, please treat this feature as a beta feature, and do not depend on its current implementation staying stable. Frankly, I'm always on a Mac, so I never use multiple instances of Stata, and I'm not sure what habits multiple-instance-users have.


The mechanism by which this works is fairly straightforward. I've done my best to separate things done easily within Emacs from those which are platform specific, in the hope that it will make porting to other platforms simpler. When you hit M-RET, this is what happens:

  1. ado-mode copies what is selected into a string. If nothing is selected, it copies whatever command the insertion point is sitting in or just after.
  2. ado-mode looks to see if the code will be sent to Stata's Command window. If it will be, ado-mode strips out all comments, and changes continuations to be single line commands. This keeps the Command window from getting indigestion and heaving red text all over the Results window.
  3. Whether destined for a do-file or the Command window, ado-mode makes sure there is exactly one trailing end-of-line. This ensures all the code gets executed while avoiding extra nothingness in the Results window.
  4. ado-mode then puts the resulting commands into the clipboard (and kill-ring) so it can be sent to Stata.
  5. An applescript is called at this time to take whatever is on the clipboard and send it to Stata. This is the one step that needs to be ported to other platforms.

This is all there is to it.

  • ado-mode can get confused when automatically sending without selecting if there are nested comments or comments in the middle of a command or other bizarre forms of commenting.
  • If you have questions or trouble, send me an email. Enjoy!

    Send Bill comments about this page or go to his main home page

    Last Updated Friday, June 17, 2011, 10:54