Sublime Text and Stata Integration
StataEditor is a Sublime Text 3 plugin that integrates closely with Stata. It allows you to use Sublime Text's main features (syntax highlighting, autocompletion, snippets, build systems, goto symbols, etc.) interactively with Stata, so you can fully take advantage of the Sublime Text workflow in Stata.
Installation
Requirements
- Stata 13 (should work up to Stata 11)
- Sublime Text 3
- Windows (it should be straightforward to add this for OSX using Andrew Heiss's work; not sure about Linux)
Installation
- Install Package Control if not installed.
- Install the Pywin32 package. Note: to install a package, go to the Command Palette in Sublime Text (ctrl+shift+p), type "install", type the package name, and select it.
- Add this Github repository. Press ctrl+shift+p, type "add repo", and enter https://github.com/sergiocorreia/StataEditor
- Install the StataEditor package.
- (Optional) Set the Stata Path: ctrl+shift+p, type "stata path" (or use the Tools - Stata menu) and enter the path as seen in the image at the end. If this step is skipped, StataEditor will just try to find it, and ask if it fails.
- (Optional) Register the Stata Automation type library: ctrl+shift+p, "stata register", and accept the Windows Prompt. In case of an error, see the manual instructions. If this step is skipped, StataEditor will try to run it when required.
Using Stata
Quick Overview
- Create a new file, and save it with a .do extension. This will activate the Stata syntax highlighting.
- To run the do-file in Stata, press ctrl+b or go to Tools - Build
- To use snippets, press Tab or Enter when it starts autocompleting. To see all snippets, type "snip:" in the Command Palette (ctrl+shift+p)
- To set up autocompletion, type "auto" and then Tab. Then fill the dtapaths line with e.g. "C:/MyData/"
- To insert a dataset name, press ctrl+space when in the correct line (e.g. in a use/merge/append/etc)
- To insert a variable name, press ctrl+shift+space
- To insert a header, type "head" and then tab. You can quickly jump to a header or program with the ctrl+r key ("goto symbol")
Syntax Highlighting
To use the Stata package and syntax highlighting, you can either i) save the file as a Stata type (.do .ado .mata), ii) click on the lower right corner, or iii) type "syntax: stata" in the Command Palette
Executing Code
To do or run the file, press ctrl+b (do) or ctrl+shift+b (run), or go to the Build menu. Note that building a file is the Sublime Text equivalent of do and run in Stata.
A do-file can be run in its entirety, as seen below, but also partially when part of the code is selected.
Snippets
To use a snippet, just start writing it and then press Tab:
To see all available snippets, press "snip" in the Command Palette or go to Tools - Snippets.
Snippets are "intelligent" and allow to be completed in order, indicating variables, options, etc. Within a snippet, press Tab to go to the next value:
Go To Symbol
You can jump to different sections of the do-file with the ctrl+g shortcut. Currently, it recognizes program declarations and "header comments". To insert a header comment, use the "header" snippet (type "head", then Tab).
Technical note: a header comment is just a line that starts with "// " (nothing before the slashes, and a space after them).
Help
Pressing the F1 key will search for the help file of any selected word and try to open it in Sublime Text. Pressing shift+F1 will do the same but opening it in the Stata Viewer.
Autocompletion
Using the Autocomplete Snippet
- Save the file if it is still Untitled.
- Use the "autocomplete" snippet ("auto", Tab) to insert the required comments.
- Change the dtapaths line. Just type one or more folders followed by commas.
The dtapaths line can be customizable:
- Paths can be absolute or relative to the do-file.
- Multiple paths must be separated by commas.
- Quotes are optional.
- If the line is too long, you can use multiple lines; just start each line with "*! dtapaths: "
- Nicknames: If in the code you have set something like global TEST=C:/MyData/TestData, which you then use in strings like "$TEST/SomeDataset" you can use a nickname to refer to a folder. For instance, $TEST=C:/MyData/Final instead of just C:/MyData/Final
Dataset Autocompletion
Just press ctrl+space if you are in a line that has a "use" or "using" strings. If the Stata window was still closed, you may need to press it again.
Variable Autocompletion
Press ctrl+shift+space anywhere in the do file:
Select all the variables that you want and press Esc to exit the menu.
The first option allows you to filter by dataset:
Notice the "(current)" dataset. It has all the variables generated with gen and egen, as well as the ones in the dataset currently open in Stata.
When filtering by a saved dataset, the variables that sort the dataset will be shown first and a * will be next to them:
Example: Autocompletion + Snippets = Fun
Select the uselong snippet
It will move the caret exactly where you want.
Now press ctrl+space, and select the dataset from the list of avaiable datasets
Now press Tab to move the caret to the varlist, and press ctrl+shift+space. Notice that the using dataset will be automatically selected!
Add as many variables as you want. Remember that the ones prefixed by a * are sorting the data.
Available Commands
To see all available commands, you can either use the menu (Tools - Stata) or the Command Palette (ctrl+shift+p, then type "stata:"):
Menu Bar
Command Palette
Known issues (taken from Mattias' Readme.md)
Orphan Stata Window After Closing
The development of this package is still in beta and may contain bugs, so use at your own risk and make sure you backup your data. When running code from ST3, a new instance of Stata is opened. If you close ST3, then that instance will also close, though it may take around five minutes before that happens. Note that Stata will not ask you whether you want to save the data but will close without warning. Therefore, do not use an instance of Stata that has been launched from ST3 after ST3 has been closed, as you would risk loosing your unsaved work. This is true even if you re-launch ST3 as the connection to the old instance of Stata will have been permanently broken. Please let me know if you detect any other bugs or if you have requests for additional featuers. You can contact me at mnordin [at] gmx [dot] com.
Encoding
If you write Stata code containing non-ASCII characters in ST3, you may notice that these characters have been replaced with nonsense when you open the file in Stata's native do-file editor. This is because Stata and ST3 use different encodings. To avoid this issue, you can save your file with a different encoding in ST3. To do so, open File -> Save with encoding, and choose the appropriate encoding. Which encoding is right for you I would imagine depends on your Stata distribution. For most users in Europe and the U.S. you would probably get the correct result by choosing Western (Windows 1252). If that doesn't work, try saving with other encodings.
Missing Features
- OSX Support (easy/medium)
- Linux Support (hard?)
- Allow variable autocompletion based on what has been currently typed (medium)
- Fix "build when selecting". Currently every build expands the selected lines by one (hard)
- Display message in red when sublime closes to warn anyone using the Stata window that it will be closed (very hard)
- Interact with a remote Stata session via either Remote Desktop or an SSH Terminal (very hard)
Acknowledgements
This is a fork by Sergio Correia of the StataEditor project created by Mattias Nordin.
It is heavily influenced by several other projects:
- SublimeStataEnhanced by Andrew Heiss
- The original TextMate plugin by Timothy Beatty, currently maintained by Dan Byler
Thanks to Adrian Adermon and Daniel Forchheimer for helpful suggestions.
Suggestions, code contributions, and pull requests are greatly appreciated!