Volume Number: 24 (2008)
Issue Number: 06
Column Tag: Programming

Textmate: Take Your (Text) Editing to the Next Level

Or: How to make friends with robot ninjas from Denmark

by Ryan Wilcox

Why read this article? "There's heavy duty text editing lifting to do, and only TextEdit (or XCode's editor) to help me!" you say, "No time to waste!" But using TextEdit for serious text editing is like moving a house with a crowbar – hard work. Why do all that hard work when there's a better way? Read this article and start learning how to really Work Smarter, Not Harder. You'll be amazed at all the typing you're not doing!

"No thanks, I use BBEdit!" And I must say, what a fine text editor choice – still the preferred tool of this author for certain tasks. BBEdit stays out of your way and lets you work, giving you tools to perform fine and sterile surgery on your text. But text editing isn't necessarily hospital surgery: it's rough and tumble M*A*S*H style just-get-it-done meatball surgery. That doesn't mean things are done sloppily: quickness, efficiency, and (above all) correctness are the name of this game. But imagine being able to hit F1 and have a dated comment happen. Type "objc" and have an entire Objective-C class structure created for you, just waiting for you to fill in the class name... but only when you're editing Objective-C code. At first glance, BBEdit's Clippings feature provides this, but no. TextMate takes "automatically filling in chunks of repetitive text" beyond anything in your Clippings-brain.

This article is the gonzo-journalist guide to MacroMate's TextMate (http://www.macromates.com). The wild and crazy is out there, and you'll see a bit of it in this guided tour: the fundamental keys of TextMate (and a glimpse into their power); dealing with repetitive text with TextMate's Snippets feature; getting Bundles for your language or task; customizing TextMate; and more. I suggest reading it once on the bus or the sofa, or wherever you read MacTech, then run to the computer, download the trial to TextMate, and follow along – it's best it see this power in action, experience it for yourself.

So why TextMate? TextMate lets you create tools quickly: tools that you use once to do a specific operation on a lot of text, or tools that you'll use forever. These tools can be written from scratch in your favorite shell scripting language, or sent through the ancient tools of your Unix forefathers. Maybe the resulting tool is so useful you want to publish it to the world! Many have gone before you: TextMate is used (and has tools, or in TextMate parlance, bundles) for almost every editing task under the sun. If you're doing something with text, there's a good chance that there's a bundle out there to make your life easier. What if the bundle just makes things more annoying? Just edit the bundle to work like you want: bundles are just written in shell scripting languages (primarily Ruby, but with some Python, Perl, or bash), nothing special. TextMate's motto might as well be "Yes, you can feed the animals! They're not dangerous: feed them, pet them, change how they behave!"

Allan Odgaard, a Mac programmer from Denmark, created TextMate itself. He moved to Mac OS X from Windows, looked around and wasn't pleased with what he saw in the text editor environment. TextMate, being born in the OS X generation, can (and does) integrate very well with the Unix command line, putting 30 years of text-dicing knowledge in your hands. But, if we wanted Unix Text Editing we'd all be on IRC involved in the latest vi vs emacs debate. No, a text editor for the Mac must be very Mac like. TextMate, at least in this author's mind, does extremely well in balancing what Must Be Done In The Core App vs What Can Be Done By Others. The Unix philosophy of "Write Programs That Work Together" is absolutely TextMatian... but in a way that, like the Mac, makes it easy to do something amazingly complex.

TextMate's most fundamental command is also the easiest to see. Fire up TextMate, open a new document, and type "MacTech". Now: space, "Mac", and press the escape key. See how your "Mac" turned into MacTech? The Escape key completes the current word with matching words from your document. Try to complete "Ap". It doesn't work: there's no "Ap" word in the document. Type "Apple", space, and "Ap" again (it completes!). Now add the word "Applefritter" to the end of your document, type space, and "Ap". TextMate completes it as "Applefritter" – that was the match closest to your insertion point. But we don't want "Applefritter", we want "Apple". Press escape again: "Applefritter" goes away and "Apple" replaces it. Shift-Escape goes back to "Applefritter". If both of those matches are wrong (AppleSauce, perhaps?), Undo will take you back to your plain "Ap".

But wait, there's more to the escape key. Bundles can influence the completion list too, adding words to the mix (even if they aren't already in the document!) via the completions preference key. To see this in action, use the language popup (the second item at the bottom of the TextMate window) and change from Plain Text to Objective-C. Type "re" and escape – boom, it is autocompleted to "retain". Some bundles implement magic via option-escape too, bundles like Objective-C, HTML, CSS. Sometimes a bundle documents this in its Help command, sometimes you have to look through a bundle's menu, looking for a menu item that contains "CodeCompletion". We're skipping ahead here, and will return to bundles a bit later. For now, just remember the escape key.

Not to be outdone by the lowly escape key, the tab key begs for attention in TextMate. TextMate uses abbreviations and the tab key as one way of triggering snippets of text. Watch this: type "isoD" in TextMate (case is important) and press tab. Your isoD expanded to today's date in ISO date format (year-month-day format). (if there's no snippet that matches your abbreviation, a regular tab goes into the document. Try it with "isod".

Now TextMate is really going to blow your mind. Use the language popup at the bottom of the TextMate window to switch to HTML. Snippets can be set up to only happen when a certain language is activated... or even when the user is in a certain syntax construction in the file. HTML mode all set? Type "h1" and tab. <h1 id=""></h1> is generated... but notice your cursor is between the > and < ? Now type your headline text. Robot Ninjas Attack! As you type your headline, the id part of the tag is filled out, with spaces translated to underscores.

Later in this article we'll examine this magic further, but the curious can open the bundle editor now, expand the HTML group, use the popup above the bundle list to show only Snippets (not required, but now it's easier to see what we want – and to identify the Snippet's icon, for future reference). Click on the Heading item, and see the code that generates the h1 code. The code is rather complex, but the important part is the ${1:$TM_SELECTED_TEXT}. This says, "the first tab stop is here, and our default value is the selection." If you don't want to use a tab trigger, you can select this item from the Bundles->HTML->Insert Tag->Heading. Magic happens when you choose this menu item when you have a selection. $TM_SELECTED_TEXT is an environmental variable: TextMate has a slew of these that reflect the user's state. You can use any environmental variable in a snippet. Readers fond of experiments can replace $TM_SELECTED_TEXT with $HOME or $USER, or any other Unix Environmental variable and see what "h1" expands to now. (If you're wondering how to make your own variables, skip ahead to the conclusion of this article, where it's mentioned briefly, then come back)

Say you have two snippets with the same abbreviation (and scope, which we'll cover later), don't worry: TextMate will display a popup menu with your choices. In your HTML document Type "input", and tab. A popup appears with two options: "input" and "input with label", now select "input" with your mouse (or type "1"). TextMate expands the trigger to <input type="text/submit/hidden/button" name="some_name" value="" id="some_name">, with the type block selected. Ok, it's a text input, so type "text". Type tab again and the name value is selected. Fill it in, tab to the next field: huge chunks of syntax dealt with, no effort at all.

Automation on call is nice. Automatic automation is even nicer. Type "<". Woh! TextMate completed the tag pair with the ">". Try with {, [, ", - the appropriate ending delimiter is added in all cases! This is a feature called Smart Typing Pairs (and customizable at the bundle level, or you can turn the feature off all together in the Text Editing pane in TextMate's application preferences). Why type ")" ever again?

Snippets are a big part of the timesaving power of TextMate, and they deserve some attention. Snippets at their heart are simple: fill in this text when I tell you to. If you want, that's all they have to be. But snippets are almost a programming language: with the ability to guide users through a "form", mirror text, apply transformations to a mirror, and call shell script commands.

Say we're programming and it's company policy to have every comment be on its own line, start off every comment with the filename, colon, our name, timestamp, the comment itself, "updated: " the timestamp again and our name in Last Name, First Name order. Too much typing if we had to do it manually, but watch your coworkers look on in awe as you finish your comments while they're still typing the date! We're going to create a bundle that creates most of this – including comment syntax – automatically!

TextMate recommends that you create your own bundle for your own, personal, snippets and macros and things. Open the bundle editor, down to the Plus menu item, and down at the bottom of the menu is "New Bundle". Name your bundle as you wish. In your bundle, go down to the Plus menu again and select New Snippet.

The Snippet's code is (all on one line):

$TM_COMMENT_START$TM_FILENAME: ${1:$TM_FULLNAME} ¬
${2:`date+%m-%d-%Y`} ${3:TextMate's not scary!!} ¬
updated: $2 by ${1/(\w+)\W(\w+)/$2, $1/}  $TM_COMMENT_END

Taking this one thing at a time, and starting at the first tab (or, in TextMate parlance, the first tab stop) the $TM_COMMENT_START environmental variable holds the comment syntax for the language you're working in. A language can define as many comment styles as it likes, and can specify if the comment style comments to the end of the line, or from the start of the comment syntax to the end of the comment syntax (in TextMate terms, the former is a line style comment and the latter is a block style comment). $TM_COMMENT variables are stored in a bundle's preferences. For example, the C bundle has a preference item named "Comments" that specifies both the // style comment syntax (comments go from // to the end of the line) and the /* syntax (comments extend until a */ is found). The $TM_COMMENT variables are used in lots of other places in TextMate. The best place for information is to look at the Source bundle's Comment Line/Selection command. Our snippet uses $TM_COMMENT_END at the end of the snippet out of paranoia: needed if our current language only supports block style comments (or if $TM_COMMENT_START is actually a block comment). The Bundle Development -> Show TM_* Variables command shows all the environmental variables provided for TextMate, including $TM_FILENAME.

The next chunk of code, ${1:$TM_FULLNAME}, is where your insertion point will start when you trigger the snippet (aka: tab stop #1, or field #1, for those of you used to tabbing from field to field in Mac applications), and filled in with your full name. The {$#: } syntax specifies that the snippet has a default value. Again we see this in the ${2:`date +%m-%d-%Y`} chunk, which executes a shell command to generate a default value at tab stop #2. (Shell commands can be executed anywhere in a snippet, with just the `cmd` syntax.) Tab Stop #3 defaults in normal text, our actual comment.

The first time a tab stop appears in a snippet, the user is prompted to add or replace text. Every other time in appears it simply mirrors the value filled in the first time. In this case, the "updated: $2" chunk echoes the second tab stop (which has a default value filled in by the date unix command).

Echoes can also have transformations applied to them with the ${#/find regex/replace regex} syntax, similar to Perl's regular expression operators. (As a sidenote, TextMate uses the Oniguruma regular expression engine, instead of the PCRE Perl Compatible Regular Expression engine). Our regular expression query captures the first two words (first name and last name, in this case) and reverses them.

With this snippet, a long (mostly boring) line is generated with 3 tabs and the actual comment text itself. Robot ninjas cut through red tape! TextMate's bundle mechanism can contain so much more than just snippets.

TextMate is like your body. Specifically, like your naked body. Clothes make the man, while bundles make TextMate. You put on certain clothes for certain tasks (work, lounging, the gym), and TextMate has bundles for specific tasks (tracking TODOs, doing HTML, hacking Cocoa, writing LaTeX). Like clothes, if you don't have the right bundle for the right situation, chances are that someone has already created the right bundle for you already – just run into the store and pick up the appropriate outfit. But, unlike clothes, bundles are free!

TextMate bundles are just OS X bundles, an Info.plist describing the bundle, and folders for commands, snippets, preferences,

Bundles reside, at least for now, in a central subversion repository at the MacroMates Subversion repository at http://macromates.com/svn/Bundles/trunk/Bundles/ (yup, Bundles twice). You can download these via Subversion (installed by default on Mac OS X 10.5!), or by a TextMate bundle called GetBundle, available at http://projects.validcode.net/getbundle. Because they are checked out with source control, and everything (except supporting .nibs etc) in a bundle is stored as a plain text file, Subversion should be able to merge updates from the repository with any changes you've made locally. (The bundles that come with TextMate, or are installed by the user double-clicking a .tmbundle file – aka: a bundle – also have a system for keeping your personal changes in the face of a changed bundle.)

Subversion is (as of this writing) the most reliable way to get bundles. TextMate invites users to put their bundles in ~/Library/Application Support/TextMate/Bundles/. So, to check out a bundle (say the Haskell bundle) using Subversion, just open up Terminal and:

$ cd ~/Library/"Application Support"/TextMate/Bundles/
$ svn co http://macromates.com/svn/Bundles/trunk/Bundles/Haskell.tmbundle/

(Notice the quotes around Application Support in the first command. This makes sure the space gets to through the cd command, and not interpreted by the shell as a delimiter for a new parameter).

Bundles can also be found on the Internet, available as a .zip or .dmg archive. Simply double-clicking these bundles will trigger TextMate to install the bundle. The GetBundle bundle is distributed like this.

The GetBundle bundle is less geeky, although it uses the same source for bundles. Install GetBundle by following the instructions on the website, then Bundles -> GetBundle -> Install Bundle, or Bundles -> GetBundle -> Show Bundles on Repository. However, as of this writing neither of these commands seem to download a bundle, but development happens very fast in the TextMate community, so it may be working by the time you read this.

Another promising source for bundles is http://bundleforge.com/. BundleForge provides subversion hosting for bundle authors, a prettier way to view the official TextMate subversion repository, and a way to download a tarball of a bundle, for easy double-click installation. BundleForge is probably the simplest way to get double-clickable bundles, for those not familiar with subversion.

Remember: when you get and install a bundle, look and see if it has a Help command. At the very least go through the menus and familiarize yourself with the snippets and macros on the menus!

But don't forget the bundles included in TextMate! My favorite built-in bundles are the Math bundle (including commands to perform math on the selection and translate bases); the Source bundle (including commenting commands and the Move To EOL commands.) and the TODO bundle (makes a list of TODO lines found in every source file of a project). Or explore these with the bundle editor and find out how these commands work!

TextMate is highly customizable with its collection of Themes. There are two main collections of themes online: the TextMate wiki at: http://wiki.macromates.com (then click on Themes Gallery in the sidebar on the left), and http://www.tmthemes.com/. A word of warning here: very often themes will work best with one language or another, this is an unfortunate side effect of how themes are created. Take a moment to page through these themes, and see if you find one you like better than you current TextMate theme. There are themes for everyone's tastes, even themes to ease eyes accustomed to BBEdit's default color scheme. Once you've downloaded a theme, simply double-click on it and it will open TextMate and install itself. Themes are keyed to language scopes, applying specified colors to chunks of code. Opening the Fonts And Colors pane in TextMate's Preferences shows a list of elements. Clicking on an element will show the scope (in the Scope Selector field) where that color will be applied.

Scopes are actually defined in a bundle's language grammar. A simple example of this is TextMate's own Release Notes. TextMate's release notes (available from the Help menu) is simply a text file... but a text file that is stylized into something useful by TextMate.

TextMate picks a language to use based on a file's extension, specified by the language grammar. If you open up the Bundle Editor, go into the TextMate bundle, and select the Release Notes language, you'll see these lines:

{   scopeName = 'text.plain.release-notes';
   fileTypes = ( 'tmReleaseNotes' );
   patterns = (

If we examine these two lines in detail we see that the scope name is text.plain.release-notes, meaning it inherits from the text.plain language grammar (check it out: that grammar lives in the Text bundle). We also see that the fileType is tmReleaseNotes. That is your extension: if you saved a document with that extension it would open up as TextMate's release notes (Of course, selecting Release Notes from the language popup will activate the Release Notes language grammar too!)

Each rule (that is, pattern) in the language grammar has at least two parts: a scope name and a regular expression. If a chunk of code matches the regular expression, that chunk of code is said to have that scope, and any theme elements for that scope selector are applied.

Examining this in action, click one of the [UPDATED] or [NEW] or [FIXED] lines, specifically in the middle of the []s. From the Bundles menu's Bundle Development the Show Scope command will display the current scope in a tooltip. In this case we find the scope is keyword.other.release-notes. Go into the Fonts and Colors Application preference, and click the plus button at the bottom. Name your element (this part is irrelevant), give it the scope selector of keyword.other.release-notes and pick a color or style (notice how changes are reflected in the document in real time!).

Element styles are not "stackable". For example, if we added an element with a Scope Selector of keyword, and gave it complimentary style to the element we created above (say keyword is underlined where keyword.other.release-notes is just colored red) then our [(FIXED/CHANGED/NEW)] lines will not be red with underlines –they will just be red. You could think of this in terms of overriding in the object oriented sense – if you override a method from a superclass, your method is used instead of the base class's. In our case, keyword.other.release-notes beats keyword. If keyword.other.release-notes element is missing or misspelled, the default implementation (our keyword element) is used. In simpler words: TextMate picks the most specific style if it can and if one's not found it works its way to more general and still more general, until it can't anymore.

Moving beyond Fonts And Colors, bundle preferences are applied to scopes. For example, if you wanted to change the colors of the [DATE: Revision ####] lines in the Release Notes, you'd find there is no element in Fonts And Colors to tweak this. But you can force color settings for scopes in the bundle's preferences: look in the Style: Separator bundle preference. Want to make separators have black text instead? Change the foreground key value to #000000.

Want to add spell checking to comments for any programming language you work in? In the Source bundle (because every other code language "derives" from this bundle) add a preference with the value {spellChecking = 1;} and the scope of comment.block, comment.line (so, any of those two scopes).

Scopes also control what commands, snippets, and macros are available – this is how the h1 snippet, for example, only expands when editing a HTML document.

For those interested in creating your own language grammars, the Bundle Development submenu's Help: Scope Conventions, which covers some of the information above and naming conventions for your language grammar and rules. For those of you wanting to create your own themes: usually a look through a language grammar sparks some ideas, even without taking the time to understand what the regular expressions are doing.

The awesome power of TextMate, like the awesome power of robot ninjas, can't be described in a single article. We didn't even get into projects, TextMate's Find/Replace (with grep power!), touch any of the standard bundles, take a good look at TextMate's macro powers, or even take a look of the advanced powers of snippets! The Project Drawer is great part of the workflow, even integrated with the Navigation->Go to Header/Source menu item. (A peek of power of a project file: Go To Header/Source will search for files with the same name, but different extension, all over the project file. Without a project file Go To Header/Source only looks in the same folder as the current file). Creating your own language grammar (or modifying an existing one) is one way to really learn the concepts touched on in the previous section.

Another mostly unexplored area is the Bundle Editor. The bundle editor is where all the customization magic happens. From Snippets, to Commands, to Macros, to languages and preferences acting on language scopes, you'll find it all in here. A TextMate bundle can have any number of preference settings, in (the old, ASCII style) plist format – this is where the smartTypingPairs and the completions preference keys live. Remember to use the popup above the bundle list to zoom in on just what you want. The bundle scheme in and of itself smacks of object orientation: Languages can inherit from other languages, and override functionality provided in the parent languages. For example, the CSS bundle inherits from the Source bundle.

Bundles can have Commands in addition to Snippets – commands can take input from the frontmost document and return text for the document, or HTML for a separate window. Commands are written by default in bash shell script, but a simple #! line can change that (just like in script you write on the console). So #!/usr/bin/env python as the first line of the Command signals that it is written in Python.

But say you need to run something just once on the selection, and you don't need to keep the command in a bundle (say like sorting some lines). Select the lines and select Text->"Filter Through Command". This gives you space to type out a Unix command (like sort –f, to sort lines regardless of their capitalization). Leverage the power of your Unix forefathers!

TextMate's application preferences are tiny, compared to say BBEdit's, We know this is because most of the power lays in bundles, but I want to show you something quickly: Advanced pane, Shell Variables group box. Here you can define Unix Environmental Variables. Did you explore the Heading snippet when we first played with Snippets and the tab key? Well, any variable can be used there: including one you define here, in TextMate's Shell Variables preferences. Environmental Variables can also be defined at the project level!

TextMate's awesome power is quick to surface, and easy to take advantage of. With a bit more work, like finding and learning a bundle for the task you most often do (Web programming, Cocoa, shell scripting, Apache config file editing), you can direct armies of robot ninjas, leaving onlookers to wonder "Who was that unmasked man, and how did he do that?"

For more information on TextMate, The Pragmatic Programmer's book TextMate: Power Editing For The Mac, is available at fine bookstores near you, or at http://www.pragprog.com/titles/textmate. (And yes, I've stolen the Robot Ninja theme of this article from that book's back cover). There's also a review of TextMate by Joe Zobiw in the April 2006 edition of MacTech (Volume 22, Issue 4). There's a strong community at http://www.macromates.com, consisting of a wiki and mailing lists – lots of places to learn.

Ryan Wilcox has more than a decade of experience making text editors sing. Ryan would have given his first born to Barebones, the makers of BBEdit... until he found TextMate. Now Ryan loves the robot ninjas inside TextMate. He can be found at: http://www.wilcoxd.com