Built for Code

Ace is an embeddable code editor written in JavaScript.
It matches the features and performance of native
editors such as Sublime, Vim and TextMate. It can be easily embedded
in any web page and JavaScript application. Ace is maintained as the
primary editor for Cloud9 IDE
and is the successor of the Mozilla Skywriter (Bespin) project.

Features

Syntax highlighting for over 110 languages (TextMate/Sublime Text.tmlanguage files can be imported)

Over 20 themes (TextMate/Sublime Text .tmtheme files can be imported)

Automatic indent and outdent

An optional command line

Handles huge documents (four million lines seems to be the limit!)

Fully customizable key bindings including vim and Emacs modes

Search and replace with regular expressions

Highlight matching parentheses

Toggle between soft tabs and real tabs

Displays hidden characters

Drag and drop text using the mouse

Line wrapping

Code folding

Multiple cursors and selections

Live syntax checker (currently JavaScript/CoffeeScript/CSS/XQuery)

Cut, copy, and paste functionality

Get the Open-Source Code

Ace is a community project. We actively encourage and support
contributions! The Ace source code is hosted on GitHub
and released under the BSD license &dash;
very simple and friendly to all kinds of projects, whether open-source
or not. Take charge of your editor and add your favorite language
highlighting and keybindings!

git clone git://github.com/ajaxorg/ace.git

History

Skywriter/Bespin and Ace started
as two independent projects both aiming to build a no compromise
code editor component for the web. Bespin started as part of
Mozilla Labs and was based on the <canvas> tag, while Ace is
the editor component of Cloud9 IDE
and uses the DOM for rendering. After the release of Ace at
JSConf.eu 2010
in Berlin the Skywriter team decided to merge Ace with a simplified
version of Skywriter's plugin system and some of Skywriter's
extensibility points. All these changes have been merged back to Ace
now, which supersedes Skywriter. Both Cloud9 IDE
and Mozilla are actively developing and
maintaining Ace.

Now check out the How-To Guide for instructions on
common operations, such as setting a different language mode or
getting the contents from the editor.

Loading Ace from a Local URL

If you want to clone and host Ace locally you can
use one of the pre-packaged versions. Just copy
one of src* subdirectories somewhere into your project, or use RequireJS to load the
contents of lib/ace folder as ace:

The packaged version can also be loaded from CDN's such as jsDelivr or cdnjs.

Working with Ace

In all of these examples Ace has been invoked
as shown in the embedding guide.

Setting Themes

Themes are loaded on demand; all you have to do is pass the string name:

Creating a Syntax Highlighter for Ace

Creating a new syntax highlighter for Ace is extremely simple. You'll need to define two pieces of code: a new mode, and a new set of highlighting rules.

Where to Start

We recommend using the the Ace Mode Creator 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.

Defining a Mode

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.

What's going on here? First, you're defining the path to TextMode (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!

Regarding TextMode, you'll notice that it's only being used once: oop.inherits(Mode, TextMode);. 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 .html pages. You can either inherit from TextMode, or any other existing mode, if it already relates to your language.

All Ace modes can be found in the lib/ace/mode folder.

Defining Syntax Highlighting Rules

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 mynew_highlight_rules.js, which our mode above uses.

The token state machine operates on whatever is defined in this.$rules. The highlighter always begins at the start state, and progresses down the list, looking for a matching regex. When one is found, the resulting text is wrapped within a <span class="ace_<token>"> tag, where <token> is defined as the token property. Note that all tokens are preceded by the ace_ prefix when they're rendered on the page.

Once again, we're inheriting from TextHighlightRules 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 "extending Highlighters" below.

Defining Tokens

The Ace highlighting system is heavily inspired by the TextMate language grammar. Most tokens will follow the conventions of TextMate when naming grammars. A thorough (albeit incomplete) list of tokens can be found on the Ace Wiki.

For the complete list of tokens, see tool/tmtheme.js. It is possible to add new token names, but the scope of that knowledge is outside of this document.

Multiple tokens can be applied to the same text by adding dots in the token, e.g.token: support.function wraps the text in a <span class="ace_support ace_function"> tag.

Defining Regular Expressions

Regular expressions can either be a RegExp or String definition

If you're using a regular expression, remember to start and end the line with the / character, like this:

{
token : "constant.language.escape",
regex : /\$[\w\d]+/
}

A caveat of using stringed regular expressions is that any \ character must be escaped. That means that even an innocuous regular expression like this:

regex: "function\s*\(\w+\)"

Must actually be written like this:

regex: "function\\s*\(\\w+\)"

Groupings

You can also include flat regexps--(var)--or have matching groups--((a+)(b+)). There is a strict requirement whereby matching groups must cover the entire matched string; thus, (hel)lo is invalid. If you want to create a non-matching group, simply start the group with the ?: predicate; thus, (hel)(?:lo) is okay. You can, of course, create longer non-matching groups. For example:

{
token : "constant.language.boolean",
regex : /(?:true|false)\b/
},

For flat regular expression matches, token 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:

If token is a function,it should take the same number of arguments as there are groups, and return an array of tokens.

For grouped regular expressions, token can be a String, in which case all matched groups are given that same token, like this:

{
token: "identifier",
regex: "(\\w+\\s*:)(\\w*)"
}

More commonly, though, token 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:

Defining States

The syntax highlighting state machine stays in the start state, until you define a next state for it to advance to. At that point, the tokenizer stays in that new state, until it advances to another state. Afterwards, you should return to the original start state.

In this extremly short sample, we're defining some highlighting rules for when Ace detectes a <![CDATA tag. When one is encountered, the tokenizer moves from start into the cdata state. It remains there, applying the text token to any string it encounters. Finally, when it hits a closing ]> symbol, it returns to the start state and continues to tokenize anything else.

Using the TMLanguage Tool

There is a tool that
will take an existing tmlanguage file and do its best to convert it into Javascript for Ace to consume. Here's what you need to get started:

Two files are created and placed in lib/ace/mode: one for the language mode, and one for the set of highlight rules. You will still need to add the code into ace/ext/modelist.js, and add a sample file for testing.

A Note on Accuracy

Your .tmlanguage 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:

The use of regular expression lookbehindsThis is a concept that JavaScript simply does not have and needs to be faked

Deciding which state to transition toWhile the tool does create new states correctly, it labels them with generic terms like state_2, state_10, e.t.c.

Extending modesMany modes say something like include source.c, 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 extending existing highlighters).

Rule preference order

Gathering keywordsMost likely, you’ll need to take keywords from your language file and run them through createKeywordMapper()

However, the tool is an excellent way to get a quick start, if you already possess a tmlanguage file for you language.

Extending Highlighters

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 (<?lua, <?php, {%, for example). Ace allows you to easily extend a highlighter using a few helper functions.

Getting Existing Rules

To get the existing syntax highlighting rules for a particular language, use the getRules() function. For example:

Extending a Highlighter

The addRules 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:

Here, this.$rules starts off as a set of HTML highlighting rules. To this set, we add two new checks for <%= and <?lua=. We also delegate that if one of these rules are matched, we should move onto the lua-start state. Next, embedRules takes the already existing set of LuaHighlightRules and applies the lua- prefix to each state there. Finally, it adds two new checks for %> and ?>, allowing the state machine to return to start.

Code Folding

Adding new folding rules to your mode can be a little tricky. First, insert the following lines of code into your mode definition:

Just like with TextMode for syntax highlighting, BaseFoldMode contains the starting point for code folding logic. foldingStartMarker defines your opening folding point, while foldingStopMarker defines the stopping point. For example, for a C-style folding system, these values might look like this:

These regular expressions identify various symbols--{, [, //--to pay attention to. getFoldWidgetRange matches on these regular expressions, and when found, returns the range of relevant folding points. For more information on the Range object, see the Ace API documentation.

Again, for a C-style folding mechanism, a range to return for the starting fold might look like this:

Testing Your Highlighter

The best way to test your tokenizer is to see it live, right? To do that, you'll want to modify the live Ace demo to preview your changes. You can find this file in the root Ace directory with the name kitchen-sink.html.

Ace API Reference

Welcome to the Ace API Reference!

On the left, you'll find a list of all of our currently documented classes.
These is not a complete set of classes, but rather, the "core" set. For more
information on how to work with Ace, check out the embedding guide.

Below is an ERD diagram describing some fundamentals about how the internals of Ace works:

Projects Using Ace

Ace is used all over the web in all kinds of production applications. Here is
just a small sampling: