The underlining imposed by markup. There are some other settings here, but they affect things like soft wrapping also something to watch out for. Themes bundle: These settings affect both the font and size of these scopes.
In my opinion, they are among the most horrible side effects of using TextMate 2. To avoid having your text affected by these settings, avoid these scopes. TextMate bundle: If you use or enable other bundles, keep your eyes peeled for settings that may perform scope styling. For example: Diff bundle: Standard Scopes The official list of scopes that are considered standard or conventional is not quite the same as the list of scopes that are commonly styled by themes.
The list as given in the documentation is as follows. I have starred once the entries that are present also in the list of commonly styled scopes though note that for some reason there are commonly styled scopes that are not present in this list ; I have double-starred the entries that are styled by settings: Note that although the documentation claims that meta scope is not styled, nevertheless some meta subscopes are in the list of scopes styled by themes and settings above.
Regular Expressions Grammar match rules are written as Ruby regular expressions. You need to be conversant with these! Download a copy of the Oniguruma regular expression syntax used by Ruby and keep it handy. Things to note: It allows you to test regular expressions, indicating matched groups. Bear in mind, however, that because of the way the TextMate parser surveys your document, all regular expressions used in grammar match rules must apply to a single line at a time.
A single expression cannot embrace multiple lines. Another pitfall is that TextMate will not complain if you write a bad regular expression; the expression will just fail silently. This is another reason why Rubular is useful; it will show a descriptive error message if the expression itself is syntactically faulty. Regular expressions will be surrounded by single quotes in the grammar.
To express a single quote within a regular expression in a grammar, use two single quotes in succession. Grammar Structure We now come to the actual apparent structure of a language grammar.
The documentation is shockingly uninformative about this. There is no formal complete definitive specification, so far as I have discovered, of the structure of a grammar. Moreover, many aspects of a grammar are described in separate and scattered documents that can be difficult to discover.
But I will attempt to do a better job here of assembling and summarizing the facts. Property List Syntax The grammar is portrayed by the bundle editor as an old-style property list. Under the hood, however, it is a new-style property list, i.
The grammar contents may not look the same when you return to it as when you left it; for example, things whose order does not matter dictionary elements may appear in a different order.
This is more of a problem than you might expect, because the bundle editor window is responsive to clicks when it is not frontmost. I know this from experience, obviously! My solution is: An old style property list has two kinds of collection: An array, bounded by parentheses , is an ordered list of elements separated by comma.
It does no harm to follow the last element with a comma as well, and I recommend that you do so. A name—value pair is joined by an equal sign. The name does not have to be quoted, and usually will not be, unless it contains spaces or numbers. String values will be single quoted. In the grammar structure, any dictionary can contain a comment entry.
This can be extremely useful and I recommend liberal use of this feature. Top Level Structure Before I can describe the top level of a language grammar, I need to tell you that a match rule also called a pattern is a dictionary. Some of the entries in the real underlying dictionary are now edited through fields in the bundle editor drawer.
This is the main scope that will be assigned to the entire document. It is typically a specialization of some existing scope, in order to acquire related bundle-based features, though not usually in such a way that an existing grammar will be injected automatically on top of yours.
For example, text. But because it is a specialization of text. On the other hand, in the Bundle Development bundle, the Language Grammar grammar is scoped as source.
A patterns array is an array of match rules. Matches are performed in the order listed. TextMate considers lines of a document one at a time, looking within each one for matches. Thus, you can effectively make conditional rules by judicious ordering of a patterns array.
A repository is a dictionary, and it may contain two kinds of thing: A repository may contain named match rules. The fact that the rules are named is important, because this means that a match rule can refer to another match rule by name, provided the latter is in a repository.
A repository may contain named top levels. That is, a repository entry might be a name paired with a dictionary containing a patterns array and optionally a repository dictionary. The patterns array inside a named dictionary inside a repository provides a way of naming and thus referring to a whole bunch of match rules simultaneously. The repository inside a named dictionary inside a repository has no structural significance — it is not special merely because it is at a deeper level — but it is certainly an organizational convenience, especially because the bundle editor gives you structural code folding.
The blockquote match rule, despite its depth a repository within a repository , can be referred to from anywhere. Match Rules A match rule, also known as a pattern, is where the power lies in a language grammar. A match rule can be one entry in a patterns array. A match rule can be a named dictionary in a repository. I have not, however, said anything yet about what is inside a match rule dictionary.
There are actually three possible structures for the contents of a match rule: An include. A match pattern. We will consider each in turn. A comment. This is a name—value pair named comment. An off switch. This is a name—value pair named disabled, with value 1.
This is a convenient way to experiment or develop, leaving a rule in place while effectively commenting it out.
An Include Match Rule An include match rule is a way of saying: The name of that pair is include. The value is usually the name of something in the repository at any level, preceded by a hash-sign. But it cannot, I believe, be repository, even though that might be the name of something in the repository.
There is only one top-level match rule — the include rule specifying block. This rule effectively substitutes for itself the entire array of patterns listed under block in the repository. These patterns are themselves all include rules. The result is exactly as if the top level patterns array were the include rule for separator, then the include rule for heading, then the include rule for blockquote, and so on.
Those include rules, in turn, are virtually replaced by the rules that their values name — the actual separator rule from the repository, the actual heading rule from the respository, the actual blockquote rule from the repository, and so forth. Those actual rules are all defined in the second-level repository. Note that the order of the include rules in the patterns array is significant; an array is ordered. The value of an include rule can alternatively be a scope name. This is a good way to inject an entire grammar inside yours.
For example, in my AsciiDoc bundle, I assume that the contents of a passthrough block never mind what that is will be XML. Therefore, inside my match rule for a passthrough block, I have an include rule specifying text. This causes the whole grammar from the XML bundle to come into play in this region of my document.
In addition, TextMate 2 permits a single named item to be plucked from a foreign repository using the syntax scopeName itemName.
As I mentioned at the outset, as far as I can tell, if a match rule contains an include key, that is its only key except possibly for comment and disabled. A One-Pattern Rule A one-pattern rule must contain at least this key—value pair: The match key. Its value is a regular expression that the TextMate parser is to look for.
This is, I am at pains to stress, a single-line regular expression. A one-pattern rule may also contain this key—value pair: The name key. Its value is a scope, or an expression that evaluates to a scope. This is the scope that will be applied to the matched text.
A theme or setting may then come along and style any constant. What do I mean by that? Well, the scope name is actually what TextMate calls a format string. For more about these, see this article. For example: This is because Git reuses the temporary file used for the commit message and TextMate stores per-file caret position via extended attributes. To avoid this problem you can set the Git editor to mate -wl1.
This instructs TextMate to open with the caret at line 1 rather than where it last was. TeX Editor When TeX gives an error message relating to a file, you can enter e to edit the file and correct the error. These can refer to local files which can be useful when: If you are generating a set of web-pages from simpler text files you can have these link to the original text files, so that when you are inspecting the generated result in a browser you can quickly edit the source of each page by following the txmt: The URL scheme is txmt: This command takes up to three arguments: So a full example of a txmt: URL could be click here to test:
This manual covers TextMate 1. It can also perform an Open With… operation by use of the -a argument, e. This standard command has a few shortcomings: For this reason TextMate comes with its own mate shell command, which supersedes the open command. For usage instructions you can run mate -h from Terminal. After having created this link, you may want to setup a few shell variables to make other applications use TextMate as an external editor.