Digging in to TextMate

The first time I opened TextMate was about a year ago. I opened it, edited a couple of files, looked through the options, was overwhelmed and deleted the trial. It wasn’t until about 4 months ago that I decided to give it another try. I’m now a die-hard fan (as readers of this blog already know). But I know full well that the first impression of TextMate can be intimidating, especially for self-professed non-programmers like myself. Combine a huge library of commands, shortcuts and language specific tools with an almost completely barren user interface and a first-timer can be a little overwhelmed. This article is not necessarily intended for full-on geeks or converts from BBEdit or Emacs, it’s written for people who are checking out the buzz, picked up a copy through MacHeist, or just stumbled upon it and decided to check it out. The former may find some solace here, but this is going to be a “dummy’s” guide to teaching yourself the interface and exploring the available tools, not an in-depth reference. For that, see resources like TextMate: Power Editing for the Mac by James Edward Gray II. It’s available in PDF and is a great compendium of TextMate knowledge. See below for a list of other resources that should follow this initial tutorial if you haven’t already checked them out…

I’m going to touch on, but not rewrite, some basic resources that are already available. These include:

• The online manual
• The TextMate Wiki
• The mailing list(s): See the Community page on the TM site.
• The IRC Channel at freenode.org
• David Powers’ TextMate Cheat Sheet
• Soryu’s Tutorials (far more in-depth than mine and a great resource)
• Allan’s Screencasts

I watched a few screencasts which were quit the tease, but left me no less confused. I’m a tactile learner, according to my school shrink… I’m starting this tutorial after the point where I stopped reading the online manual (chapters three and four) and decided to just dive in. Of course, after my own exploration I headed back to the manual and finished reading. I eventually used all of the above resources and continue to use the IRC channel and mailing list. This article is for people like me who just want to figure it out and get going but fully realize that their initial questions are only going to annoy veteran users. If you haven’t at least gotten TextMate set up, check out this tutorial and check back when you’re done… Having said that, here’s a look at how to survive your first look at TextMate.

First Step: Kill Unnecessary Bundles

The most overwhelming thing about your first look at TextMate is the sheer number of commands. This can be remedied: All you have to do is hide the bundles you don’t need. Go into the Bundle Editor (Bundles->Bundle Editor->Show Bundle Editor) and at the bottom click on “Filter List…”. Uncheck all of the bundles that are not of immediate interest to you. You can add them back if you need them, don’t worry. This is going to clear up your menus and help you find the commands that are actually relevant. Make sure you keep Source, Text and TextMate, as noted in the dialog. Trust the dialog.

Adding More Bundles

It seems antithetical to the previous paragraph, but if you’re looking for specific functionality, you may need a bundle that’s not included in TextMate by default. There’s a section in the manual about getting more bundles, and a link on the TextMate blog about the GetBundle bundle. There are a couple of methods for getting more bundles. The simplest is to download the GetBundle bundle and use it. However, I prefer Subversion checkout to keep things under control. Don’t combine the two. Which you choose is up to you, but stick with one or the other. Add any bundles that you need, there are quite a few available.

Let The Exploration Commence

Bundle commands are only available when you have a file open in TextMate. So open one or create a new one, either with File->New or File->New From Template.

Language Check!

Your current language will largely determine what commands are available. You need to make sure that you’ve set your file to the proper language. If you opened a pre-existing file, TextMate will generally do a good job of figuring out what it is, but it doesn’t hurt to double check. If you opened a Template, you should be fine. If you’re creating a brand new file, you definitely need to set a language. To check the document type look at the bottom status bar, to the right of the line/column number indicators and notice a grey L in a circle followed by a language name. You can click on this to pull up a menu of available languages based on your installed (and unfiltered) bundles. Select an appropriate language for your exploration. If you’re looking for Ruby commands, select one of the appropriate Ruby languages. If you’re editing HTML, choose HTML… etc. Note that php files are edited within the HTML language syntax. For the purposes of this exploration, make sure you have a window open and that you know what language it’s set to.

Quick Search for a Command

Now you want to know whether TextMate can do what you want… type ⌃-⌘-t or go to Bundles->Select Bundle Item and type part of a search term into the dialog. It will search the available bundles for related commands, snippets and macros. If, for example, you were editing an HTML file and wanted to know what options you had for quickly creating unordered lists, you would open up the Select Bundle Item dialog and type “unordered” or “list”.

Manual Digging

Sometimes you don’t know what to call a command, though, or you just want to find out more about a bundle. Before you go posting newbie questions to the list, open up the bundle editor and dig.

Clicking on a bundle in the left pane will show the menu items for the bundle. This is the menu that the bundle’s developer has thoughtfully arranged for you. It usually categorizes all of the commands, snippets, macros and templates into an easily navigated structure and is great for a quick overview of the bundle. The title of a command is listed on the left of the middle pane of the editor. To the right of it, in standard UI fashion, is the shortcut for it. Shortcuts in grey followed by a ⇥ are tab triggers and will execute when the preceding string is typed immediately followed by the tab key. Usually these are used to insert snippets which often have a structure that allows you to tab through and set variable options in the resulting code. Items that all have the same trigger or shortcut will present a menu when triggered that can be navigated by the keyboard or mouse to select the intended item.

If you want to dig deeper and see more of what a particular item does, expand the arrow next to the bundle in the left pane and select any item from the bundle. Each type of bundle item is coded with a colored icon. Green C for commands, Purple S for Snippets, Red D for drop commands, Grey P for Preferences, Grey L for Language definitions, Orange M for Macros, Blue T for Templates. You can filter the list by pulling down the menu at the top of the list and choosing a particular type of bundle item that you’d like to explore. Click a Snippet (purple S) and take a look at it. Snippets are the easiest Bundle Item to understand.

Anatomy of a Snippet

In the main window is the text that will be inserted when the snippet is triggered. Text surrounded by a ${} or any $ followed by a number is tab-stopped and will provide a means for replacing text in the Snippet after it’s inserted. If there’s a lot of regular expression code in the Snippet you’re looking at, it’s probably using transformation, which I’m not going to cover in this article. If you’re curious, go to your edit window and trigger the Snippet to see what it does.

Activation

At the bottom of the Bundle Editor window there’s a drop down that determines the trigger type. Most snippets are tab triggered, but some have shortcuts. One confusing part of the interface is that any item can have both types of triggers simultaneously. In the tab trigger, whatever text appears in the box will trigger the command or snippet when followed immediately (no space) by a ⇥ (tab). To set or change a tab trigger, just edit that text. To set a shortcut, change the pulldown to Key Equivalent, click in the text area and press the desired shortcut combination. To clear a shortcut, press the “x” in the text area. If you don’t clear out a tab trigger or shortcut before setting the other, both will be in effect.

Scope

Below the trigger (Activation) is the Scope Selector. The scope is defined in a cascade of language definitions and works like CSS selectors. A very specific scope will keep an item from triggering in the wrong place and will also give it precedence over less specific items. You can get a general idea where a command will trigger from the existing scope selector without having to delve into the language files, with a little common sense.

Templates

You’ll also find the available Templates for a bundle in the Bundle Editor. Open one up and you’ll be able to modify it to suit your needs. The actual text that’s inserted is found inside the file that’s revealed when you drop down the arrow next to the template name.

Other Bundle Items

Commands in the Bundle Editor can use a variety of languages, including shell scripting and Ruby to accomplish just about any task (when it comes to editing code). Peek through the commands to get an idea how they work and you’ll get a feel for how extensible TextMate is. Keep in mind that a good portion of the items in the Bundle Editor came from the user community, and let that give you a warm, fuzzy feeling. Macros are just what they sound like. Language Grammars and Preference Items are a little overwhelming for the purposes of this article, but feel free to look at them in awe.

Google is Your Friend

There is an ever-growing number of people like me who write about TextMate. And if you need a specific combination, such as TextMate and ActionScript, or TextMate and Ruby on Rails, head for Google. There’s a plethora of user-contributed resources available.

Wrapping Up

Well, that’s it for a quick overview. I have no intention of delving in to the creation of bundles or advanced editing in this article. There are quite a few articles out there for such pursuits, just do a little googling! Hopefully this will serve as a reference for TextMate virgins and a jumping point for people to become long time lovers with a spectacular piece of software.

bundle» development» Geekery» osx» software» textmate» tutorial»