Below you find some topics for which the subtle details are unlikely to be extracted through trial and error alone.
As a supplement to this documentation you should also check the various “Tip of the Day”, as these contain some nice features not currently explicitly documented.
If you think some vital information is missing from the topics above please write to feedback@macromates.com.
TextMate has its own regular expression library with a syntax inspired by Perl. You can use regular expressions in searches (and format strings in replaces), but there are also many other places in TextMate where you can enter a regular expression. Generally though, the user interface abbreviates it “Pattern”. So when a text field has the label “Pattern” or the suffix of said label is “Pattern”, then you can enter a regular expression.
\t Tab \v Vertical tab \n Newline \r Return \f Form feed \a Alarm (bell) \e Escape \nnn Octal char (e.g. \033) \xnn Hex char (e.g. \x1B) \x{nnnn} Wide hex char (e.g. \x{001B})
\ Quote the next metacharacter ^ Match the beginning of the line . Match any character (except newline) $ Match the end of the line | Alternation () Grouping [] Character class Supports negation ([^Q]), ranges ([a-z]), the "general escape codes", and mixing of these -- currently no character classes (although these are parsed)
\w Word char (includes underscore) \W Non-word char \d Digit \D Non-digit \s Space \S Non-space \u Uppercase char \U Non-uppercase char \l Lowercase char \L Non-lowercase char
\A Begin of buffer \z End of buffer \< Begin of word \> End of word \b Word boundary \B Non-word boundary
\Q Quote (disable) pattern metacharacters till \E \E Enable pattern metacharacters \n Match the n'th capture. n can be > 9 when that many captures exist.
* Match 0 or more times + Match 1 or more times ? Match 1 or 0 times {n} Match exactly n times {n,} Match at least n times {n,m} Match at least n but not more than m times
*? Match 0 or more times +? Match 1 or more times ?? Match 0 or 1 time {n}? Match exactly n times {n,}? Match at least n times {n,m}? Match at least n but not more than m times
(?=...) Look ahead assertion (?!...) Negative look ahead assertion (?>...) Non-backtracking match (?R) Recursive match (placeholder for the entire pattern) (?(n)...:...) Condition: if the n'th capture exists, match lhs, otherwise match rhs (?is-is:...) i = case insensitive, s = single line (. matches newline), - = disables option
Captures are enumerated syntactically, i.e.
((a)|(b)|(c)) $1 = a|b|c $2 = a $3 = b $4 = c
Only plain parenthesis constitutes a capture, that is everything of the form (?...) will not count as a capture.
Captures in look-ahead assertions can be used outside the assertion. Negative look-ahead on the other hand are not available (since the pattern shouldn't match)
On repetition, the last string captured is reported. i.e. (<(\w+)>)+.*?</\2>
will match <foo><bar>...</bar>
On recursion, each recursion has unique captures, i.e. <(\w+)>(?R)?</\1>
will match: <foo><bar></bar></foo>
Captures are generally greedy, starting with the left-most as the most greedy, i.e. "a*(.*)"
on "aaaXYZ"
will have $1
= "aaaXYZ"
, whereas "(a*)(.*)"
on the same string will have $1
= "aaa"
and $2
= "XYZ"
.
A capture holding zero characters will test true when used in a condition. So use "(\s+)?"
instead of "(\s*)"
if you need to test for the presence of whitespace.
The format string supports the general escape codes and grouping using ()
, so you must escape parenthesis if you want them inserted.
Use $n
for the nth capture. If non-existent then nothing will be inserted. To insert a $
use \$
.
Use "?n{true}:{false}"
to test for the presence of an nth capture, and insert {true}
if it exists, otherwise insert {false}
. Use parenthesis around the expression if you want something to follow {false}. You also need to use parenthesis around {true} if it has leading digits, e.g. "?1(21):42"
instead of the ambiguous "?121:42"
.
A string (generally a capture) can be uppercased or lowercased by putting \U…\E
or \L…\E
around it. For example by using \U$0\E
as the format/replacement string, we will get the entire match in uppercase.
When you execute a shell command in TextMate by picking “Execute Line [...]” / “Filter Through Command…” from the “Text” menu, choosing a custom command from the “Command” menu, or running the command of a template, TextMate will setup some standard shell environment variables which lets you extract information from the current document or project.
The encoding of these variables are utf-8, which is the same as used by the file system, so for file paths the variables can be used as-is, but in other situations it may be necessary either to use iconv to convert to another encoding or to explicitly specify the encoding. For an example of this, see the encoding examples under commands.
The “Wrap Column” as set in the “View” menu.
The “Tab Size” as set in the “View” menu.
Caret column position (counting from 1).
Caret line position (counting from 1).
Textual content of the line which the caret is on.
The word at the caret.
Full content of the selection, if any.
The mode of the current document (or where the caret is in the current document). The mode is set by the syntax file used, and if not set, is the name of the bundle from which the current syntax is loaded. If syntax highlight is unset, the mode will have the value “Defaults”.
Path (including file name) for the current document (if it is not untitled).
The folder of the current document (if it is not untitled).
If the current document is part of a project, this variable contains the folder of that project (if it is not untitled). Scratch projects always have a folder, even though they are untitled.
If the current document is part of a project, and this project is not untitled, this variable contains the full path of that project file including its name.
If the current document is part of a project, this variable contains the full path of the first selected file or folder reference in the project drawer.
If the current document is part of a project, this variable contains a space separated list of each of the selected files and folder references in the project drawer, using full paths and in single quotes.
By default this variable is set to __MyOrganizationName__, see below for how you can change it, and how to add your own variables.
As a supplement to the dynamic variables mentioned above, TextMate also has a list of static variables. This is primarily useful in the context of templates but may also be useful for commands.
The list of static variables can be seen in the preferences window under advanced.
If you drag multiple files and/or one or more folders to the TextMate application icon then a new project will open containing these files (folders are added as folder references).
This project is called a scratch project mainly because if you quit TextMate, it will not warn about the (untitled) project not being saved.
Another peculiarity about scratch projects is that if you execute a shell command in the context of a scratch project, the TM_PROJECT_DIRECTORY shell variable will contain the nearest common parent folder of the contained files (TM_PROJECT_FILEPATH will be blank).
If you manually save a scratch project, it loses the special property of being a scratch project, but then if the project is not untitled, you would not get a warning when quitting about the project being untitled.
TextMate can record your editing operations and play them back at a later time. You activate recording by selecting “Start Macro Recording” from the “Automation” menu, and when you have performed the editing operations, you select it again (the title has changed to “Stop Macro Recording”, and while it is recording, a camera icon will fade up and down in the status bar).
The editing operations recorded are:
After having recorded a macro you can replay it with “Replay Scratch Macro” from the “Automation” menu.
You can also save a scratch macro for later use. Select “Save Scratch Macro…” from the “Automation” menu and give it a name and an optional key equivalent. This key equivalent does not need to include a modifier key.
Names and key equivalents for saved macros can be changed by opening the “Replay Macro” submenu and selecting “Edit Menu…”.
You can insert a snippet either by selecting it in the “Insert Snippet” submenu found under “Automation”, or by typing its trigger in a document and pressing tab.
In the most simple case, a snippet is just a sequence of text, for example you can let it be “© 2004 MacroMates.” and set the trigger to “cmm”. If you then type “cmm” in your document (either at the beginning of a line or preceded by a non-word character) and press tab (⇥) then it will expand to “© 2004 MacroMates.” (the trigger typed will be removed/replaced).
It would be nice to make this useful even in a year from now, so hard coding 2004 obviously does not work. We can instead insert a placeholder using “$1”. This is done by changing the snippet to “© $1 MacroMates.”. When we insert this snippet, it will place the caret where “$1” is written (“$1” will not be inserted in the document), and then we can type the current year.
Since the year will be 2004 for at least some months to come, we can make this the default value by writing “${1:2004}”, so the snippet becomes “© ${1:2004} MacroMates.”. What happens when we insert this snippet is that it will insert “© 2004 MacroMates.”, just like the first version, but “2004” will be selected, so we can either overtype it, or leave it alone.
Since a snippet may contain several pieces which must be typed when inserted, we can embed several placeholders and cycle between them with tab and shift tab, for example we could let it be “© ${1:2004} ${2:MacroMates}.$3”. When we insert this snippet, it will once again insert “© 2004 MacroMates.” with the year selected. Now we can either decide to overtype the year, or leave it as is. After this we press tab to move to the next placeholder, which causes MacroMates to be selected. Again we can decide either to overtype it, or let it be. After this, we can go back to the year with shift tab, or we can move forward to the last placeholder (“$3”) with tab.
When we reach the last placeholder, we leave the cycle-chain, and can no longer use shift tab to go backwards.
If the same word or phrase needs to appear at different positions in the snippet, you can re-use the placeholder number to activate “mirror typing” when the snippet is inserted. An example follows.
<html> <head> <title>${1:MyPage}</title> </head> <body> <h1>${1:MyPage}</h1> <p>$2</p> </body> </html>
When this snippet is inserted, “MyPage” in the title will be selected. Overtyping it will cause “MyPage” in the <h1>...</h1> section to reflect the changes made to the title. When done, press tab, and the caret will move inside the <p></p> section.
Note that mirror typing will not work for the last placeholder, since it would not be possible to dismiss it, as there are no defined placement of the caret when pressing tab after having moved to the last placeholder (here tab inserts a tab, rather than advance to the next placeholder).
Also note that currently if you provide a placeholder with a default value, you must add this same default value to all of the “mirrors”.
If you need dynamic content in the snippet, like the current date, you can have normal shell commands executed. Simply surround these with backticks (`). All the normal shell variables are available.
For example to insert the copyright with the proper year and the users name, we can do:
© Copyright `date +%Y` ${1:`niutil -readprop / /users/$USER realname`}. $0
Here the name of the user is a placeholder, so it can be changed, but the year is not.
Commands are executed before the snippet is parsed for placeholders, so if the command outputs a $, it should be escaped.
TextMate builds on Cocoa's key binding mechanism, which is completely re-mappable by the user.
The standard bindings can be found in /System/Library/Frameworks/AppKit.framework/Resources/StandardKeyBinding.dict. These bindings are customizable by the user (for every application which uses the Cocoa text system). You can create a file in ~/Library/KeyBindings/DefaultKeyBinding.dict to augment or replace the standard bindings (again, for every application using the Cocoa text system).
TextMate further augments the key bindings with its own dictionary in path_to_textmate/TextMate.app/Contents/Resources/KeyBindings.dict. This file is a normal property list and it follows the same format as the standard key binding files, that is, to make a key binding with a modifier you use “$” for ⇧ (shift), “^” for ⌃ (control), “~” for ⌥ (option), “@” for ⌘ (command), and “#” for the numeric keypad.
If you would like to change TextMate's default bindings, you should copy this file to ~/Library/Application Support/TextMate/KeyBindings.dict and make your changes.
If TextMate finds that you have a local key bindings file in the aforementioned location, it will not use its own defaults. The reason for this is that TextMate is rather greedy, for example it binds ⌥L to selectLine:, which is used on the German keyboard layout to insert an at sign (@). If TextMate were to merge its own defaults with the users custom file, there would be no way for the user to “unbind” a key.
Currently TextMate does not support multi-stroke key bindings nor the “quoted keystroke binding”.
Note: even after you change the key bindings dictionary you may still see the old key equivalents in the menus, since TextMate currently does not set menu key equivalents based on the bindings it gets from the key binding dictionaries. One option is to go to the Keyboard & Mouse preferences pane, switch to the Keyboard Shortcuts tab and add TextMate under All Applications. Then you should be able to change the key bindings you desire — an easier way is to get Menu Master from Unsanity.
Templates are used when creating new files (currently only from a project window).
TextMate scans all installed bundles for a “Templates” folder. This folder must have one folder per template, which must contain an Info.plist property list. All other files in this folder are ignored.
An example of the anatomy of a bundle with a Template folder that contains two templates follow.
MyLanguage.tmbundle/ Templates/ Source File/ Info.plist Default Source.in Header File/ Info.plist Default Header.in
The Info.plist describes the template and its keys are described below. The property list must at least have a name and a command key. The rest of the keys are optional.
This is the name of the template, as it will appear in the user interface.
The extension of the file type. If this key is left out, TextMate will use whatever extensions it thinks make sense, i.e. the last extension used, or the extension of the current file. So if the filetype has no extension, you should set this key to an empty string.
This is a boolean (set it to 0 or 1 if you use the ASCII format) which tells TextMate that this is the default template. This should only be set for a single template and by default the “untitled” template has it set (it means that the template will appear as the first choice in the list of selectable templates, and thus, selected by default).
This is a shell command line to execute in order to have the template(s) generated. When executing the command all the normal shell variables will be available, and additionally the following three variables are setup:
In the most simple case the command could be “touch "$TM_NEW_FILE"”, which would generate an empty file at the desired location.
The current working folder of the command executed will be the one in which the Info.plist file is contained. If we look at the example anatomy of the template folder above then the command for the “Source File” template could be “cp "Default Source.in" "$TM_NEW_FILE"”, which would create a copy of Default Source.in as the name entered in the GUI.
Often though, you would let the .in files be piped through a macro preprocessor of some sort like m4, cpp, php, erb, or a small perl script. You could also create a program and place in the folder and run that program as the command, either directing its output to $TM_NEW_FILE or pass it on as an argument.
By default TextMate will expect the command to generate the $TM_NEW_FILE file, but if you generate other files (and want these added to the current project) this key should be a command that returns a list of generated files.
For example if we generate an additional header file with a .h extension, then we could set files to “printf "$TM_NEW_FILE\n$TM_NEW_FILE_DIRECTORY/$TM_NEW_FILE_BASENAME.h"”.
Note: when quoting property list values in the above, quotes are not escaped. If you use the ASCII property list format then you need to escape quotes. An example property list follows.
{ name = "HTML document"; extension = "html"; command = "perl -pe 's/\\$\\{([^}]*)\\}/$ENV{$1}/g' < index.html >\"$TM_NEW_FILE\""; }
This template expects to find index.html in the template folder and it will pipe this file through perl which will substitute all variables of the form ${variable} with the actual environment variable.
TextMate uses property lists for most external files.
Since some of these currently do not have a graphical “in-app” editor, you'll need to edit these by hand.
Generally the files bundled with TextMate (which you would probably want to copy and edit) is in the Old Style ASCII Property List.
You can edit the files with Apple's Property List Editor, or you can edit them by hand. If you do the latter, you may find the pl command line utility useful. It reads a property list from standard in, and outputs it to standard out, after having verified that it is valid (so use it to verify the integrity of the files you create yourself).
The pl utility can also be used to convert the XML format into the ASCII format, making it easier to edit by hand.
Another command is plutil which can also verify the property list and do conversion to XML.
See also: shell variables
Commands allow you to execute external commands from within TextMate. There are several options for the input to the commands and what to do with the output from the commands. This makes them very versatile and suitable for as different tasks as sorting the selection, activating Safari and reloading its current page, looking up the word at your caret in the documentation and show the result as a tooltip, or even run a compiler on your source code, and have errors shown in TextMate with the ability to jump to the reported lines.
Like with shell variables the encoding used to exchange data with the shell environment is utf-8.
If you want to dump the text as numeric HTML entities, you can use iconv to convert it to ucs-2 (16 bit unicode) and have hexdump write out the entities:
iconv -f utf-8 -t ucs-2 | hexdump -ve '/2 "&#%d;"'
If you only want “special” characters to be written as entities, you can let PHP work on the text and explicitly state the encoding:
php -r 'echo htmlentities(stripslashes($_ENV["TM_SELECTED_TEXT"]), ENT_QUOTES, "UTF-8");'
The first thing to do is to create a new command. This is done by clicking the ✚ button in the lower left corner. Clicking it will add a new “untitled” entry in the list of commands. You can rename the entry by double clicking it to activate the normal edit in place. The right column of this list contains the key equivalents for the commands, you can also change these with edit in place.
You can tell TextMate to save either the current document or all modified documents in the current project, before executing the command. This makes sense if the command is something that works on the actual files. If the command is set to save modified files in the project, but is executed from a normal document window, it will just look at the current document.
You set the command to execute in the text field with the “Command(s)” label. You can execute several commands by putting each new command on its own line.
For example, if we want to activate Safari and reload its current page, we can execute two AppleScript commands using the osascript command.
osascript -e 'tell application "Safari" to activate' osascript -e 'tell application "Safari" to do JavaScript "window.location.reload();" in first document'
When executing the command(s) all the normal shell variables are available. For example, if we wish to run GCC on the current source, we could do:
g++ -o /tmp/a.out -Wmost -pipe -fmessage-length=0 "$TM_FILEPATH"
Additionally there is a TM_BUNDLE_PATH variable available which gives the full path of the bundle from which the command has been loaded. This excludes the Command sub folder. This variable allows the command to access other resources from the bundle in which it is contained (mainly for distribution purposes).
If the command to be executed reads data from its standard input, then you can specify what input TextMate should feed the command. For example if we want to create a command to sort selected text, we wouldd set the command to sort and the input to Selection.
If the command generates output, you can specify how it should be treated here. If we continue with the “Sort Selection” command from above, we would set the output to Replace selected text
Another output option is to have it shown as a tooltip. This is a lightweight presentation of the output, and is especially useful for commands which provide statistics (like wc) or lookup information based on the current word/selection or similar.
The output can also be inserted as a snippet, which means it can contain placeholders.
The most powerful output option is Show in separate window. Basically it shows the output in a window containing a list and a text view. The text view will show the raw output from the command, but the list will only show lines matching the pattern you can set below the popup gadget.
This pattern is a regular expression and it is going to be applied to every line of the output. For the lines matching the pattern, it will use the format string to format the match and show it in the list.
Additionally you can tell TextMate if one of the capture registers of the regular expression contains a filename, line- or column number. If it does, selecting the match in the list will jump to that file/line/column.
A simple example is to configure a command like this:
Before running command: Do nothing Command(s): grep -n $TM_CURRENT_WORD Standard input: Entire document Standard output: Seperate window Pattern: ^(\d+):(.*)$ Format string: $2 File register: Line: 1 Column:
The actual command (grep) searches its standard input and it outputs matching lines. We provide it with $TM_CURRENT_WORD for it to search for the current word, and we set the -n switch in order to make it prefix all lines with the line number and a colon.
The pattern we specify matches lines starting with one or more digits, a colon, and then arbitrary characters. Furthermore it will assign the digits matched to capture register 1 and the characters after the colon to capture register 2 (captures are marked with parenthesis).
We make TextMate aware of the line numbers in the output by setting the line capture register to 1. We set the format string to $2 to show only the text after the colon.
If you execute this command, it will search your entire text for the word at the caret and show the results in a list where you can select a line in the list to jump to the match in the document.
TextMate can be specialized to different programming languages by writing language specific
A bundle is just a folder which groups these things. The folder should have a tmbundle extension and contain one or more folders. An example of a HTML bundle follows.
HTML.tmbundle/ Commands/ Reload in Safari.plist DragCommands/ Anchor Tag.plist CSS Link.plist Image Tag.plist Macros/ Make Tag From Word.plist Make Anchor From Selection.plist Escape Chars in Selection.plist Snippets/ HTML Img Tag.plist CSS Include.plist Syntaxes/ HTML.plist PHP.plist Templates/ HTML document/ Info.plist page.in
When TextMate is launched it will search the locations below for bundles. If it finds a bundle with the same name in two different locations, it will, per folder, use the first one it finds. For example if we have a HTML bundle in our users local application support folder which only contains macros, and there is another HTML bundle in /System/Library/... then it will use the macros from the first bundle, but it will also use commands, snippets, syntaxes, and templates from the latter bundle.
~/Library/Application Support/TextMate/Bundles/ /Library/Application Support/TextMate/Bundles/ /System/Library/Application Support/TextMate/Bundles/ /Network/Library/Application Support/TextMate/Bundles/ TextMate.app/Contents/SharedSupport/Bundles/
If you create a command, macro, or snippet from within TextMate, it will be saved as a single file in ~/Library/Application Support/TextMate/Bundles/Custom.tmbundle/ (in the appropriate folder). So if you want to distribute your commands, macros, or snippets, this is the where to find them.
If you want to distribute commands, macros, snippets, syntaxes, or templates, it is recommended that you create a new bundle named after the purpose of your “distribution” (i.e. if it is for a programming language, name it the same as the language). Then move the appropriate items to this bundle (in the proper sub folders). The filename of each item is only used when sorting the items for presentation in the GUI, which is why they have a numeric prefix when created from within TextMate.
A user which receives your bundle will see it with a special “plugin” icon and the user will be able to double click it or drag it onto the TextMate icon, to have it installed. He can also manually move it to the Application Support folder (either locally or for all users).
If a bundle is found in the non-local application support folder, and the user makes changes (or deletes) some of the items in this bundle, TextMate will create a user-local copy of the bundle, and make the changes in this copy. It does this only for the required folders. E.g. if we have a system-wide HTML bundle with macros and snippets, and the user deletes one of the macros, only the macros are then copied to his local application support folder i.e. if the snippets in the system-wide HTML bundle is updated at a later time, the user will still see these new snippets (but any changes made to the system-wide macros will not be seen, unless he removes his local copy).
You can add normal files to the project drawer and these can be grouped using the “Group Selected Files” from the action menu which opens when you click the gear icon (or you can control-click/right click the outline view). You can later reorder your groups and files using drag'n'drop, remove items from the project, rename them, a.s.o.
You can also add folders to your project. These are referred to as Folder References since they are a mirror of what is on your disk with one exception: You can set a regular expression pattern as a filter to what should be shown in the project. The default filter will exclude files which start with a period (hidden files) and it will also exclude some common folders, like CVS. You can access the pattern by selecting the folder reference and pressing the I button (“Information”). There is a separate file and folder pattern, and the pattern is applied to the full path. In addition to the normal regular expression syntax, you can prefix the pattern with an exclamation mark (!) to negate the result. For example, if you do not want to show txt and utf8 files, you can use a file pattern like: “!\.(txt|utf8)$”.
As mentioned above, a folder reference mirrors the structure on disk. This means that if you add or remove files from a folder referenced by TextMate, e.g. using Finder, then when you come back to TextMate, the new files will appear, or the removed files will disappear.
If you drag files from one folder reference to another, or drag between sub-folders of a folder reference, TextMate will move the files on disk.
For TextMate to syntax highlight your text it needs to know the structure of the text, i.e. which keywords it contains, how a string is defined etc. This can be edited by selecting View -> Edit Languages… from the menus.
Currently a language grammar is defined in the property list format, and it's probably best to start by duplicating a language which resemble the new one that you want to create.
The job of the grammar is only to assign a name to subsets of the text, associating actual style and color to these subsets are done using general style sheets (configured in the Theme Editor).
The root element of the property list is a dictionary which can contain the following keys:
The scope name used for this language, should start with source or text. Example: "source.ruby".
An array of filetype extensions for which this syntax is intended. This is only a hint since the user can choose to use the syntax for any extension he wishes, and TextMate will remember his choice, but for "new" extensions, this key is consulted. Example: ( rb, Rakefile, rake ).
A regular expression pattern which is matched against the first line of all files loaded. If it matches, the grammar is used for the file (unless there's a user override). Example: "^#!/.*\\bruby\\b".
A regular expression pattern which each line is matched against. If a line matches, that line will mark the start of a potential folding. Example: "\\{\\s*$)".
A regular expression pattern which each line is matched against. If a line matches and there already is a folding start marker with the same indent level as the candidate, then the matching line will mark the stop of a potential folding. Example: "^\\s*\\}".
A dictionary of rules which can be included from other places in the grammar. The key is the name of the rule as used when included (see the info for the include key for an example) and value is the actual rule. Repository rules can also include other repository rules.
This is an array of rules that the document should be matched against. Each rule is a dictionary and has keys to "describe" the text to be matched using regular expressions.
There are two types of matches. Those which match a small unit of the text, like a keyword, numeric constant, function name, or similar, and then there are those which potentially span multiple lines like strings or comments. The latter type of match can provide its own patterns dictionary to be used in the block of text matched by the rule (and for these nested rules, the same applies).
When two rules match at the same location in the text, TextMate will choose the rule which matches the longest sequence. If both matches are of the same length, it uses the order in the patterns array, and selects the first match.
What follows is a list of keys that can be used in each rule dictionary.
The name of the construct matched. This is used for styling and scope specific settings/actions, which means it should generally be derived from one of the standard names.
A regular expression which is used to identify the portion of text to be styled. Example: "\\b(true|false)\\b".
These keys allow matches which span several lines, and are mutually exclusive with the match key. Each is a regular expression pattern. begin is the pattern that starts the block and end is the pattern which ends the block. Captures from the begin pattern can be referenced in the end pattern by using normal regular expression back-references.
A begin/end rule can have nested patterns using the patterns key. For example we can do:
{ begin = "<%"; end = "%>"; patterns = ( { match = "\\b(def|end)\\b"; … }, … ); };
And that will match def and end keywords only inside a <% … %> block.
This key assigns a name to the text between the begin/end patterns (but not the text actually matched by these patterns). For example to get the text between #if 0 and #endif marked up as a comment, we'd do:
{ begin = "#if 0(\\s.*)?$"; end = "#endif"; contentName = "comment.block.preprocessor"; };
These keys allows you to assign attributes to the captures of the match, begin, or end patterns. Using the captures key for a begin/end rule is short-hand for giving both beginCaptures and endCaptures with same values.
The value of these keys is a dictionary with the key being the capture number and the value being a dictionary of attributes to assign to the captured text, currently name is the only attribute which can be used. Here's an example:
{ match = "(@selector\\()(.*?)(\\))"; captures = { 1 = { name = "storage.type.objc"; }; 2 = { name = "constant.other.selector.objc"; }; 3 = { name = "storage.type.objc"; }; }; };
This allows you to reference a different language, recursively reference the grammar itself, or a rule declared in this files repository.
To reference another language, use the scope name of that language:
{ begin = "<\\?(php|=)?"; end = "\\?>"; patterns = ( { include = "source.php"; } ); }
To reference the grammar itself, use $self:
{ begin = "\\("; end = "\\)"; patterns = ( { include = "$self"; } ); }
To reference a rule from the grammars repository, prefix the name with a pound sign (#):
patterns = ( { begin = '"'; end = '"'; patterns = ( { include = "#escaped-char"; }, { include = "#variable"; } ); }, … }; // end of patterns repository = { escaped-char = { match = "\\\\."; }; variable = { match = "\\$[a-zA-Z0-9_]+"; }; };
Note: the examples above are as they would appear in an ASCII property list. In particular this means that the value is surrounded with quotes and that the " and \ characters are escaped.
Documentation forthcoming (until then, check the release notes)
You can select Print… from the File menu to print the text in the current window. If you use the command while a web preview has focus, it will print the formatted HTML.
In the print dialog (sheet) for printing normal text files there is a popup menu (default showing: Copies & Pages) where you can select TextMate. This gives you 6 text fields to customize the header and footer of the printout.
In these text fields you can write normal text, use any of the normal shell variables or have a shell command executed by placing it in back quotes (similar to command substitution in snippets). There are two additional shell variables defined:
The current page being printed (this is the actual page number as if all pages in the document are printed, so even if you print only page 3, this variable will be 3 and not 1).
Total number of pages in the document.
End print version