Starting with version 1.10.1.1, ado-mode can send code from the emacs file you are editing directly to a running instance of Stata. As of the version 1.11.0.0, 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 1.11.1.2, ado-mode can even send code to targeted instances (or all instances) of Stata under MS Windows. See the multiple instances section below).
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.
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
/// 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.
ado-mode to send code to Stata via a temporary do-file. No individual commands appear in the Review window. Many do .../feedStata.do commands appear, though (as when using the Do-file editor). To use this option, change the Ado Submit Default to dofile.
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 .../feedStata.do commands appear, though. To use this option, change the Ado Submit Default to include. Many thanks to David Lucca for suggesting this.
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)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.
As of version 1.11.1.2, 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:
ado-send-to-all-flag: if this is t, then all instances get the sent
code.ado-stata-version, ado-stata-flavor, and ado-stata-instance:
When these filters are specified, emacs will look at all running instances and count the number of these that are matched (note that the default values will match any Stata). If ado-strict-match-flag is nil (the default), *all* Statas which tie for most matches are considered candidates for the code. (This is done so that when all are at their default values, they will always match any running Stata.) If ado-strict-match-flag is t, then only those instances which match all 3 filters are candidates.
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.
ado-strict-match-flag is nil, there will be 4 matching Statas. If the ado-send-to-all-flag is nil, you will get an error, if the ado-send-to-all flag is true, all 4 instances will get the same command. If ado-strict-match-flag is t, there will also be 4 matching Statas, so there will be no difference in behavior.ado-stata-flavor is "SE", and the other filters are unset, there will be 1 matching instance of Stata, regardless of the state of the
ado-strict-match-flag: StataSE 10.1, so it alone will get the code.ado-stata-version is 12, and ado-stata-flavor is "MP", there will be 0 matching Statas if the ado-strict-match-flag is t (because no Stata is Stata 12), but there will be 3 matching Statas if ado-strict-matching is nil, because the 3 StataMP instances will all match 2 out of 3 filters (the "MP" filter and the unset filter).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:
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.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.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.ado-mode then puts the resulting commands into the clipboard (and kill-ring) so it can be sent to Stata.This is all there is to it.
ado-stata-home. Setting it to an existing directory will make Emacs happy, but is not necessary if you have just one flavor installed.)
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!