Quick Tip: Configuring TextMate for Dart Coding

Dart is a pretty cool new language that could mean a change in the way you write web applications. Google provides an Eclipse-based Dart Editor that provides a handy means to get started. But TextMate users usually find a way to bend TextMate to their will, and this Quick Tip will get you started a-bending to use Dart with TextMate.

Prerequisites

I assume you are familiar with TextMate bundles to at least the degree of what they are and that they add functionality (usually language-specific) to TextMate. I also assume you are familiar with and are capable of checking code out of a Subversion repository. Lastly, I assume you have a little Dart experience. You don’t need much, but having some Dart files around to open in TextMate will make this go much smoother.

Install Dart Editor

We won’t really be using the Dart Editor (the point of this tutorial is to use TextMate for Dart development), but the download includes the Dart SDK, which is really what we’re after. Even if you’re a hardcore TextMate fanatic (like I am), it’s still not a terrible idea to have the “official” Dart Editor installed and handy.

If you’re on Windows or Linux, yet are reading this tutorial despite its Mac-centric nature, you can download the Dart Editor for those platforms from the Dart Editor for Windows and Linux pages.

Under “Step 1” of that page, you’ll find a link to a ZIP file containing the Dart Editors. It’s around 40 MB, so it’s not a terribly heavy download.

The Dart Editor is based on Eclipse, so if you’ve used that you’ll be right at home with the Dart Editor. I won’t be getting into details on using it in this tutorial, but feel free to play around with it. The current Activetuts+ Facebook Fan Bonus takes you through the basic usage of the Dart Editor.

Install frogc

frogc is the Dart-to-JavaScript compiler. It’s a command line tool, but it’s thankfully easy to use. We’ll be using it in a TextMate command later to turn our Dart file(s) into JavaScript so we can actually use our Dart code today.

Open up Terminal (found in your /Applications/Utilities/ folder). Type the following:

nano ~/.bash-profile

If you already have some PATH customizations going on, place your cursor after these lines.

Type:

export PATH=$PATH:

And then drag the bin folder, which should be located at /Applications/dart/dart-sdk/bin, into the Terminal window. If it’s not in that location, look for a dart-sdk folder in something that you downloaded (if you downloaded the SDK by itself, this should be that download, unzipped). You should end up with something like this:

export PATH=$PATH:/Applications/dart/dart-sdk/bin

To save this file, press Control-O (that’s Control, not Command), press Return to confirm the file to save, and then press Control-X to exit nano.

Almost ready; I’ve found a problem with frogc if you happen to have spaces in your file or folder names. This can be easily fixed, though. Open up frogc. It’s an executable shell script, so don’t double-click it. Instead, drag it to your TextMate icon, and you may be presented with a warning dialog but you should be able to see the short script. You don’t need to understand what this does, just change the last line from this:

Install Google’s Dart TMBundle

You can either check out the entire Dart source, which might be interesting to poke through, or you can simply check out the .tmbundle. Using the Terminal, navigate to the location in which you’d like to have the code (type cd then drag the destination folder into the Terminal window again — note that there’s a space after cd). Once Terminal is in your desired location, type this is in for a full checkout:

If you’ve checked out the entire project, you can navigate to the .tmbundle by following this path from the project root: [dart-read-only]/dart/tools/utils/textmate/Dart.tmbundle. Either way, double-click on the .tmbundle to have TextMate install it.

A lot of TextMate users like to simply check .tmbundles out directly to their bundle directory. To do this, navigate to that directory in Terminal (this should do it: cd "~/Library/Application Support/TextMate/Pristine Copy/Bundles") and then run the second svn checkout line above (the one that checks out just the .tmbundle). This way you can easily update the bundle in-place with svn up "~/Library/Application Support/TextMate/Pristine Copy/Bundles".

Write a Command to Compile Dart to JavaScript

The Google Dart Bundle is great for adding syntax support for Dart, so when you create a file ending in .dart you get colored syntax and code folding and that sort of thing. But it doesn’t include any snippets or commands. The most useful command (indeed, the first thing I thought of) is a command to compile your current Dart script with frogc for you. We’ll add one in this step.

In TextMate, open the Bundle Editor (press Command-Option-Control-B, or go to Bundles > Bundle Editor > Show Bundle Editor)

Click on the Dart entry in the left-hand list.

With the “+” button at the bottom left, choose “New Command”.

You should see a new “untitled” command appear under the Dart bundle. Rename it to “Compile with frogc”

In the large text area on the right (labeled “Command(s)”), enter the following:

frogc "$TM_FILEPATH"

Above the text area, you have the option of having the command save the file before running. This might appeal to you (it does to me; one less keystroke!). If it does, then change the “Save” option from “Nothing” to either “Current File” or “All Files in Project”.

Underneath the text area, where it says “Input,” set it to "None".

Below that, where it says “Output,” set it to "Show as Tooltip". This lets any output from the command show up in a tooltip near the cursor, which means if you have errors while running frogc you can see them. They’re not terribly pretty but it’s better than nothing.

Below that, where it says “Activation,”, make sure it’s set to "Key Equivalent" then put your cursor in the text field to the right. Type Command-B; this sets this command to trigger when you type that keyboard shortcut. Command-B is the TextMate idiom for a Build command if bundles have one.

Below that, where it says “Scope Selector,” type “source.dart#8221;.

Your command window should look something like this:

Close the Bundle editor window.

Step 1: Tell TextMate Where frogc is

We’ve set up Terminal so that it knows where frogc is, but unfortunately TextMate does not share that information. The easiest solution is to add the path that we added to the .bash_profile file to your Textmate preferences.

Open up TextMate’s Preferences (press Command-, or go to TextMate > Preferences…).

Click on the Advanced button at the top, then click on the Shell Variables tab.

If you don’t already have a PATH variable, click the “+” button and, in the first column, type PATH.

In the second column of the row that begins PATH, type the path you added to the .bash_profile (just the path, not the part that says EXPORT PATH=@PATH:). Be sure to leave the existing value intact — add a colon at the end of what’s there already, and then copy in the new path.

Close the Preferences window, and you’re ready to try it out. If you need a Dart file, you can either create a Hello World file by creating a new project with Dart Editor, or you can dig up the examples from the Dart Editor download, in the “samples” folder. Open up a Dart file in TextMate and hit Command-B; if all goes well you should have a JavaScript file next to the Dart file after a few seconds.

Step 2: Get Feedback From frogc

If you’d like to get a little fancier, you can change the code of your compile command to this:

This will give you a “Compile completed” tooltip once frogc is done running, if it runs successfully. If you have errors, they’ll still show up as they did before.

One other option: if you liked the idea of automatically saving files when running the command, you might like the idea of replacing the Save command with a Save-and-Compile command. This is as simple as changing Command-B to Command-S, and making sure you’re saving the “Current File” in the command. This overrides the regular Command-S, which simply saves the current document, with the execution of this command, which saves and then compiles.

For completeness, you can create a duplicate command that saves “All Files” and has an activation key of Command-Option-S. This shortcut will override the regular Command-Option-S in TextMate, which normally saves all files in a project. Note that because you’ve set a Scope Selector, this override will only happen in Dart files, notevery time you save any file.

Start Building Snippets

There are potentially many useful snippets to be added to a Dart bundle. Generally I find myself incrementally adding them as I get to know a language and discover that the existing .tmbundle doesn’t already include one. Let me get you started by adding a snippet that creates a new method.

In the Bundle Editor, make sure the Dart bundle (or an item in the Dart bundle) is selected, then choose “New Snippet” from the “+” button. Name it “method”.

In the large text area, select all the existing text and delete it. Now enter (or paste) the following:

Under “Activation,” set the pop-up to “Tab Trigger” and enter method in the text field (feel free to change this).

Under “Scope Selector,” type in source.dart.

Your snippet should look like this:

Close the Bundle Editor.

Try it out. In a Dart file, type “method” (or whatever you specified, if you forged your own tab trigger), press Tab, and watch it expand. You can tab through the various stops, starting at the return type, then to the method name, and finally in between the parentheses if you want to add arguments. The last tab will drop you at the first line of the method.

The cool part is that if you change the return type from void, you get an automatic return null statement at the end of your method body. Naturally you’ll want to adapt this to your needs, but hopefully it’s a feature that saves a little typing. The magic happens in the unwieldy second line of the snippet; if you’ve never seen this before, then it’s somewhat difficult to explain concisely, but it looks at the contents of the first tab stop (the return type) and if it’s anything other than “void”, it adds the return null. It might make sense if you’ve ever used Regular Expressions, particularly with the substitution syntax of /pattern/substitute/ found in Perl.

Given that Google provides no snippets with their .tmbundle, the field’s wide open for the creation of time-saving Dart snippets. Feel free to post your snippets in the comments. We’ll compile them and see if we can get Google to incorporate them into their official bundle.

That is All

Thanks for reading! I hope you are as excited about Dart as I am. And the Dart Editor is neat and everything, but I’m a fool for TextMate. Combining Dart with my text editor of choice is something that just had to be shared.

Dru Kepple works at Summit Projects as an ActionScripter, and teaches Flash at the Art Institute of Portland. He writes about Flash-ish things at the Summit Projects Flash Blog. He's always thinking about ActionScript. He's thinking about it right now, in fact.