codemirror-atom-modes

codemirror-atom-modes

Syntax highlighting in CodeMirror using Atom grammar files

This module allows any Atom grammar file to be used for syntax highlighting in a CodeMirror editor, a popular text editor that works in the browser. This module works by adapting first-mate, the source code tokenizing library used by Atom, to work with CodeMirror as a custom CodeMirror mode.

Disclaimer: In the browser, the first-mate module will use onigurumajs, a JavaScript implementation of the oniguruma Regular Expression library. The oniguruma library used by Atom has bindings to native C++ binaries that won't work in the browser (which may not be the case with WebAssembly in the future). onigurumajs depends on XRegExp and may not be perfect substitution in all situations. As a result, there may be edge cases that prevent this module from working correctly for all Atom grammars. If you find any issues, please open a Github issue.

Why?

Atom, Sublime Text, WebStorm and TextMate all support the TextMate approach to defining language grammars. CodeMirror and highlight.js, however, adopted their own unique approach to doing syntax highlighting. As a language author, it requires a lot of work to also support proper syntax highlighting and this is not work that you would want to repeat for every editor and syntax highlighting library. After creating a TextMate grammar file for the Marko templating language I did not want to have to create a new grammar file for CodeMirror. After looking at the CodeMirror API I found that CodeMirror works by tokenizing each line at a time. Fortunately, this was very similar to the approach used by first-mate (the tokenizer used by Atom). With a few tricks I was able to get the two to play nicely together.

This project is being successfully used on markojs.com (see: Try Marko Online!). On markojs.com we are using the Atom: language-marko grammar file to apply syntax highlighting in a CodeMirror editor.

Usage

The following code illustrates how to register multiple Atom grammar files for use with CodeMirror:

var CodeMirror = require('codemirror');

require('codemirror-atom-modes').registerGrammars([
        require('./atom-grammars/css.cson'),
        require('./atom-grammars/javascript.cson'),
        {
            grammar: require('./atom-grammars/marko.cson'),
            options: {
                scopeTranslations: {
                    'meta.section.marko-placeholder': 'strong',
                    'meta.section.marko-attribute': 'strong',
                    'support.function.marko-tag': 'strong tag',
                    'support.function.marko-attribute': 'strong attribute'
                }
            }
        }
    ], CodeMirror);

API

registerGrammar(grammar, options, CodeMirror)

• grammar: The Atom grammar object (required)
• options: An options object (optional, see below)
• CodeMirror: A reference to the CodeMirror module (optional, defaults to window.CodeMirror)

The grammar argument should be an Atom grammar object (not a string). Typically, Atom grammar files are stored on disk as a CSON file (CoffeeScript Object Notation). For example: github.com/marko-js/atom-language-marko/grammars/marko.cson

You will need to pass the parsed grammar file as the first argument.

Supported options:

• scopeTranslations: A mapping of Atom/TextMate scopes to corresponding CodeMirror token names (object)

registerGrammars(grammars[, CodeMirror])

The grammars argument should be an array where each element is one of the following:

• An Atom grammar object
• Or, a { grammar: <grammar_object>, options: <options> } object

The CodeMirror argument is optional and defaults to window.CodeMirror. See registerGrammar(grammar, options, CodeMirror) for more details.

Maintainers

• Patrick Steele-Idem (Twitter: @psteeleidem)

Contribute

Pull Requests welcome.

Please submit Github issues for any feature enhancements, bugs or documentation problems.

License

ISC