<li><ahref="http://pcwalton.blogspot.com/2010/11/syntax-highlighting-specification.html">Syntax highlighting</a> for over 110 languages (TextMate/Sublime Text<em>.tmlanguage</em> files can be imported)</li>
<li>Over 20 themes (TextMate/Sublime Text <em>.tmtheme</em> files can be imported)</li>
<li>Automatic indent and outdent</li>
<li>An optional command line</li>
<li>Handles huge documents (four million lines seems to be the limit!)</li>
<li>Fully customizable key bindings including vim and Emacs modes</li>
<li>Search and replace with regular expressions</li>
<p>Now check out the <ahref="#nav=howto">How-To Guide</a> for instructions on
common operations, such as setting a different language mode or
getting the contents from the editor.
</p>
<h2>Loading Ace from a Local URL</h2>
<p>If you want to clone and host Ace locally you can
use one of the <ahref="https://github.com/ajaxorg/ace-builds/">pre-packaged versions</a>. Just copy
one of <code>src*</code> subdirectories somewhere into your project, or use RequireJS to load the
contents of <ahref="https://github.com/ajaxorg/ace/tree/master/lib/ace">lib/ace</a> folder as <code>ace</code>:
</p>
<p>The packaged version can also be loaded from CDN's such as <ahref="http://www.jsdelivr.com/#!ace">jsDelivr</a> or <ahref="http://cdnjs.com/libraries/ace/">cdnjs</a>.
</p>
</div>
<divclass="tab-pane fade"id="howto">
<h1>Working with Ace</h1>
<p><em>In all of these examples Ace has been invoked
as shown in the <ahref="#nav=embedding">embedding guide</a>.</em>
</p>
<h2>Setting Themes</h2>
<p>Themes are loaded on demand; all you have to do is pass the string name:</p>
<p>The following options are available to you for your search parameters:</p>
<ul>
<li>
<code>needle</code>: The string or regular expression you're looking for
</li>
<li>
<code>backwards</code>: Whether to search backwards from where cursor currently is. Defaults to <code>false</code>.
</li>
<li>
<code>wrap</code>: Whether to wrap the search back to the beginning when it hits the end. Defaults to <code>false</code>.
</li>
<li>
<code>caseSensitive</code>: Whether the search ought to be case-sensitive. Defaults to <code>false</code>.
</li>
<li>
<code>wholeWord</code>: Whether the search matches only on whole words. Defaults to <code>false</code>.
</li>
<li>
<code>range</code>: The <aclass="internal absent"href="/ajaxorg/ace/wiki/Range">Range</a> to search within. Set this to <code>null</code> for the whole document
</li>
<li>
<code>regExp</code>: Whether the search is a regular expression or not. Defaults to <code>false</code>.
</li>
<li>
<code>start</code>: The starting <aclass="internal absent"href="/ajaxorg/ace/wiki/Range">Range</a> or cursor position to begin the search
</li>
<li>
<code>skipCurrent</code>: Whether or not to include the current line in the search. Default to <code>false</code>.
readOnly: true // false if this command should not apply in readOnly mode
});</code></pre>
</div>
<divclass="tab-pane fade"id="higlighter">
<h1>Creating a Syntax Highlighter for Ace</h1>
<p>Creating a new syntax highlighter for Ace is extremly simple. You'll need to define two pieces of code: a new mode, and a new set of highlighting rules.</p>
<h2id="where-to-start"><aclass="heading_anchor"href="#where-to-start"><iclass="headerLinkIcon"></i></a>Where to Start</h2>
<p>We recommend using the the <ahref="tool/mode_creator.html">Ace Mode Creator</a> when defining your highlighter. This allows you to inspect your code's tokens, as well as providing a live preview of the syntax highlighter in action.</p>
<h2id="defining-a-mode"><aclass="heading_anchor"href="#defining-a-mode"><iclass="headerLinkIcon"></i></a>Defining a Mode</h2>
<p>Every language needs a mode. A mode contains the paths to a language's syntax highlighting rules, indentation rules, and code folding rules. Without defining a mode, Ace won't know anything about the finer aspects of your language.</p>
<p>Here is the starter template we'll use to create a new mode:</p>
var worker = new WorkerClient(["ace"], "ace/mode/mynew_worker", "NewWorker");
worker.attachToDocument(session.getDocument());
worker.on("errors", function(e) {
session.setAnnotations(e.data);
});
return worker;
};
}).call(Mode.prototype);
exports.Mode = Mode;
});</code></pre>
<p>What's going on here? First, you're defining the path to <code>TextMode</code> (more on this later). Then you're pointing the mode to your definitions for the highlighting rules, as well as your rules for code folding. Finally, you're setting everything up to find those rules, and exporting the Mode so that it can be consumed. That's it!</p>
<p>Regarding <code>TextMode</code>, you'll notice that it's only being used once: <code>oop.inherits(Mode, TextMode);</code>. If your new language depends on the rules of another language, you can choose to inherit the same rules, while expanding on it with your language's own requirements. For example, PHP inherits from HTML, since it can be embedded directly inside <em>.html</em> pages. You can either inherit from <code>TextMode</code>, or any other existing mode, if it already relates to your language.</p>
<p>All Ace modes can be found in the <em>lib/ace/mode</em> folder.</p>
<p>The Ace highlighter can be considered to be a state machine. Regular expressions define the tokens for the current state, as well as the transitions into another state. Let's define <em>mynew_highlight_rules.js</em>, which our mode above uses.</p>
<p>All syntax highlighters start off looking something like this:</p>
<p>The token state machine operates on whatever is defined in <code>this.$rules</code>. The highlighter always begins at the <code>start</code> state, and progresses down the list, looking for a matching <code>regex</code>. When one is found, the resulting text is wrapped within a <code><span class="ace_<token>"></code> tag, where <code><token></code> is defined as the <code>token</code> property. Note that all tokens are preceded by the <code>ace_</code> prefix when they're rendered on the page.</p>
<p>Once again, we're inheriting from <code>TextHighlightRules</code> here. We could choose to make this any other language set we want, if our new language requires previously defined syntaxes. For more information on extending languages, see "<ahref="#extending-highlighters">extending Highlighters</a>" below.</p>
<p>The Ace highlighting system is heavily inspired by the <ahref="http://manual.macromates.com/en/language_grammars">TextMate language grammar</a>. Most tokens will follow the conventions of TextMate when naming grammars. A thorough (albeit incomplete) list of tokens can be found <ahref="https://github.com/ajaxorg/ace/wiki/Creating-or-Extending-an-Edit-Mode#wiki-commonTokens">on the Ace Wiki</a>.</p>
<p>For the complete list of tokens, see <em><ahref="https://github.com/ajaxorg/ace/blob/master/tool/tmtheme.js">tool/tmtheme.js</a></em>. It is possible to add new token names, but the scope of that knowledge is outside of this document.</p>
<p>Multiple tokens can be applied to the same text by adding dots in the token, <em>e.g.</em><code>token: support.function</code> wraps the text in a <code><span class="ace_support ace_function"></code> tag.</p>
<p>Regular expressions can either be a RegExp or String definition</p>
<p>If you're using a regular expression, remember to start and end the line with the <code>/</code> character, like this:</p>
<pre><codeclass="language-javascript">{
token : "constant.language.escape",
regex : /\$[\w\d]+/
}</code></pre>
<p>A caveat of using stringed regular expressions is that any <code>\</code> character must be escaped. That means that even an innocuous regular expression like this:</p>
<p>You can also include flat regexps--<code>(var)</code>--or have matching groups--<code>((a+)(b+))</code>. There is a strict requirement whereby matching groups <strong>must</strong> cover the entire matched string; thus, <code>(hel)lo</code> is invalid. If you want to create a non-matching group, simply start the group with the <code>?:</code> predicate; thus, <code>(hel)(?:lo)</code> is okay. You can, of course, create longer non-matching groups. For example:</p>
<pre><codeclass="language-javascript">{
token : "constant.language.boolean",
regex : /(?:true|false)\b/
},</code></pre>
<p>For flat regular expression matches, <code>token</code> can be a String, or a Function that takes a single argument (the match) and returns a string token. For example, using a function might look like this:</p>
else if (fonts.hasOwnProperty(value.toLowerCase())) {
return "support.constant.fonts";
}
else {
return "text";
}
},
regex: "\\-?[a-zA-Z_][a-zA-Z0-9_\\-]*"
}</code></pre>
<p>If <code>token</code> is a function,it should take the same number of arguments as there are groups, and return an array of tokens.</p>
<p>For grouped regular expressions, <code>token</code> can be a String, in which case all matched groups are given that same token, like this:</p>
<pre><codeclass="language-javascript">{
token: "identifier",
regex: "(\\w+\\s*:)(\\w*)"
}</code></pre>
<p>More commonly, though, <code>token</code> is an Array (of the same length as the number of groups), whereby matches are given the token of the same alignment as in the match. For a complicated regular expression, like defining a function, that might look something like this:</p>
<p>The syntax highlighting state machine stays in the <code>start</code> state, until you define a <code>next</code> state for it to advance to. At that point, the tokenizer stays in that new <code>state</code>, until it advances to another state. Afterwards, you should return to the original <code>start</code> state.</p>
<p>In this extremly short sample, we're defining some highlighting rules for when Ace detectes a <code><![CDATA</code> tag. When one is encountered, the tokenizer moves from <code>start</code> into the <code>cdata</code> state. It remains there, applying the <code>text</code> token to any string it encounters. Finally, when it hits a closing <code>]></code> symbol, it returns to the <code>start</code> state and continues to tokenize anything else.</p>
<h2>Using the TMLanguage Tool</h2>
<p>There is a tool that
will take an existing <em>tmlanguage</em> file and do its best to convert it into Javascript for Ace to consume. Here's what you need to get started:
</p>
<ol>
<li>In the Ace repository, navigate to the <em><ahref="https://github.com/ajaxorg/ace/tree/master/tool">tools</a></em> folder.</li>
<li>Run <code>npm install</code> to install required dependencies.</li>
<li>Run <code>node tmlanguage.js <path_to_tmlanguage_file></code>; for example, <code>node <path_to_tmlanguage_file> /Users/Elrond/elven.tmLanguage</code></li>
</ol>
<p>Two files are created and placed in <em>lib/ace/mode</em>: one for the language mode, and one for the set of highlight rules. You will still need to add the code into <em>ace/ext/modelist.js</em>, and add a sample file for testing.</p>
<h3id="a-note-on-accuracy"><aclass="heading_anchor"href="#a-note-on-accuracy"><iclass="headerLinkIcon"></i></a>A Note on Accuracy</h3>
<p>Your <em>.tmlanguage</em> file will then be converted to the best of the converter’s ability. It is an understatement to say that the tool is imperfect. Probably, language mode creation will never be able to be fully autogenerated. There's a list of non-determinable items; for example:</p>
<ul>
<li>The use of regular expression lookbehinds<br/>This is a concept that JavaScript simply does not have and needs to be faked</li>
<li>Deciding which state to transition to<br/>While the tool does create new states correctly, it labels them with generic terms like <code>state_2</code>, <code>state_10</code>, <em>e.t.c.</em></li>
<li>Extending modes<br/>Many modes say something like <code>include source.c</code>, to mean, “add all the rules in C highlighting.” That syntax does not make sense to Ace or this tool (though of course you can <ahref="/extension-development-resources/guides/extending_highlighters.html">extending existing highlighters</a>).</li>
<li>Rule preference order</li>
<li>Gathering keywords<br/>Most likely, you’ll need to take keywords from your language file and run them through <code>createKeywordMapper()</code></li>
</ul>
<p>However, the tool is an excellent way to get a quick start, if you already possess a <em>tmlanguage</em> file for you language.</p>
<h2>Extending Highlighters</h2>
<p>Suppose you're working on a LuaPage, PHP embedded in HTML, or a Django template. You'll need to create a syntax highlighter that takes all the rules from the original language (Lua, PHP, or Python) and extends it with some additional identifiers (<code><?lua</code>, <code><?php</code>, <code>{%</code>, for example). Ace allows you to easily extend a highlighter using a few helper functions.</p>
this.$rules = new HtmlHighlightRules().getRules();
/*
this.$rules == Same this.$rules as HTML highlighting
*/</code></pre>
<h3id="extending-a-highlighter"><aclass="heading_anchor"href="#extending-a-highlighter"><iclass="headerLinkIcon"></i></a>Extending a Highlighter</h3>
<p>The <code>addRules</code> method does one thing, and it does one thing well: it adds new rules to an existing rule set, and prefixes any state with a given tag. For example, let's say you've got two sets of rules, defined like this:</p>
<h3id="extending-two-highlighters"><aclass="heading_anchor"href="#extending-two-highlighters"><iclass="headerLinkIcon"></i></a>Extending Two Highlighters</h3>
<p>The last function available to you combines both of these concepts, and it's called <code>embedRules</code>. It takes three parameters:</p>
<ol>
<li>An existing rule set to embed with</li>
<li>A prefix to apply for each state in the existing rule set</li>
<li>A set of new states to add</li>
</ol>
<p>Like <code>addRules</code>, <code>embedRules</code> adds on to the existing <code>this.$rules</code> object. </p>
<p>To explain this visually, let's take a look at the syntax highlighter for Lua pages, which combines all of these concepts:</p>
var LuaHighlightRules = require("./lua_highlight_rules").LuaHighlightRules;
var LuaPageHighlightRules = function() {
this.$rules = new HtmlHighlightRules().getRules();
for (var i in this.$rules) {
this.$rules[i].unshift({
token: "keyword",
regex: "<\\%\\=?",
next: "lua-start"
}, {
token: "keyword",
regex: "<\\?lua\\=?",
next: "lua-start"
});
}
this.embedRules(LuaHighlightRules, "lua-", [
{
token: "keyword",
regex: "\\%>",
next: "start"
},
{
token: "keyword",
regex: "\\?>",
next: "start"
}
]);
};</code></pre>
<p>Here, <code>this.$rules</code> starts off as a set of HTML highlighting rules. To this set, we add two new checks for <code><%=</code> and <code><?lua=</code>. We also delegate that if one of these rules are matched, we should move onto the <code>lua-start</code> state. Next, <code>embedRules</code> takes the already existing set of <code>LuaHighlightRules</code> and applies the <code>lua-</code> prefix to each state there. Finally, it adds two new checks for <code>%></code> and <code>?></code>, allowing the state machine to return to <code>start</code>.</p>
<h3>Code Folding</h3>
<p>Adding new folding rules to your mode can be a little tricky. First, insert the following lines of code into your mode definition:</p>
<p>You'll be defining your code folding rules into the <em>lib/ace/mode/folding</em> folder. Here's a template that you can use to get started:</p>
// test each line, and return a range of segments to collapse
};
}).call(FoldMode.prototype);
});</code></pre>
<p>Just like with <code>TextMode</code> for syntax highlighting, <code>BaseFoldMode</code> contains the starting point for code folding logic. <code>foldingStartMarker</code> defines your opening folding point, while <code>foldingStopMarker</code> defines the stopping point. For example, for a C-style folding system, these values might look like this:</p>
<p>These regular expressions identify various symbols--<code>{</code>, <code>[</code>, <code>//</code>--to pay attention to. <code>getFoldWidgetRange</code> matches on these regular expressions, and when found, returns the range of relevant folding points. For more information on the <code>Range</code> object, see <ahref="#nav=api&api=range">the Ace API documentation</a>.</p>
<p>Again, for a C-style folding mechanism, a range to return for the starting fold might look like this:</p>
<pre><codeclass="language-javascript">var line = session.getLine(row);
var range = session.getCommentFoldRange(row, i + match[0].length);
range.end.column -= 2;
return range;
}</code></pre>
<p>Let's say we stumble across the code block <code>hello_world() {</code>. Our range object here becomes:</p>
<pre><codeclass="language-json">{
startRow: 0,
endRow: 0,
startColumn: 0,
endColumn: 13
}</code></pre>
<h2>Testing Your Highlighter</h2>
<p>The best way to test your tokenizer is to see it live, right? To do that, you'll want to modify the <ahref="build/kitchen-sink.html">live Ace demo</a> to preview your changes. You can find this file in the root Ace directory with the name <em>kitchen-sink.html</em>.</p>
<ol>
<li>
add an entry to <code>supportedModes</code> in <ahref="https://github.com/ajaxorg/ace/blob/master/lib/ace/ext/modelist.js#L53"><code>ace/ext/modelist.js</code></a>
</li>
<li>
<p>add a sample file to <code>demo/kitchen-sink/docs/</code> with same name as the mode file
</li>
</ol>
<p>Once you set this up, you should be able to witness a live demonstration of your new highlighter.</p>
<p>Adding automated tests for a highlighter is trivial so you are not required to do it, but it can help during development.</p>
<p>In <code>lib/ace/mode/_test</code> create a file named <code><pre>text_<spanstyle="color:#AA0D91"><modeName></span>.txt</pre></code> with some example code. (You can skip this if the document you have added in <code>demo/docs</code> both looks good and covers various edge cases in your language syntax).
</p>
<p> Run <code><spanstyle="color:#AA0D91">node</span><spanstyle="color:#008800">highlight_rules_test.js</span><spanstyle="color:#000088">-gen</span></code> to preserve current output of your tokenizer in <code>tokens_<spanstyle="color:#AA0D91"><modeName></span>.json</code>
</p>
<p>After this running <code><spanstyle="color:#008800">highlight_rules_test.js</span><spanstyle="color:#000088">optionalLanguageName</span></code> will compare output of your tokenizer with the correct output you've created.
</p>
<p>Any files ending with the <em>_test.js</em> suffix are automatically run by Ace's <ahref="http://travis-ci.org/#!/ajaxorg/ace">Travis CI</a> server.</p>