# orion.edit.highlighter

The `orion.edit.highlighter` service contributes syntax highlighting rules to the editor. A highlighter service may provide highlighting in one of two ways:

- By passing a grammar, which is a declarative description of a language's syntax. The grammar tells the Orion editor how to recognize and style language constructs in a file.
- By writing a highlighter, which allows highlighting information to be calculated asynchronously by the provider itself and sent to the Orion editor for display.

The service also provides a list of content types. When the editor opens a file of a registered content type, the provider is invoked (using one of the two methods described above) to obtain the styling.

NOTE: The "highlighter" API is experimental and subject to change in future versions.

## Service methods

Implementations of `orion.edit.highlighter` whose type attribute is "highlighter", must define the following method:

setContentType(contentTypeId)
  Orion invokes this method to inform the provider what kind of file it must provide highlighting for. This allows the provider that to register itself with several content types, but implement different logic for each type.

When this provider's type is "grammar", no service methods are defined. In other words, the provider is purely declarative.

## Service attributes

Implementations of `orion.edit.highlighter` must define the following attributes:

type
  `String` What kind of highlight provider is being registered. Allowed values are `"grammar"` and `"highlighter"`. Future versions may support more.
contentType
  `Array` An array of Content Type IDs that this provider will be used for.
grammar
  `Object` Optional. When the type of this provider is "grammar", this attribute holds an object giving the grammar to be used to assign style classes. This object is a JavaScript equivalent of the format described here.

## Service events

When the type of the provider is "highlighter", the provider must independently listen to changes in the Orion text editor by registering with the `orion.edit.model` service, and calculate the necessary highlighting information in response to the changes. Whenever highlighting information is available, the provider must dispatch an event of type `"orion.edit.highlighter.styleReady"` containing the styles. The event will be used by the Orion editor to apply styles to the file being displayed.

orion.edit.highlighter.styleReady
  This event is documented in the Orion Client API reference as `orion.editor.StyleReadyEvent`. Consult its entry there for detailed information.

When the type of the provider is "grammar", the provider dispatches no service events.

## Example of a 'grammar' provider

    var provider = new eclipse.PluginProvider();
    provider.registerServiceProvider("orion.edit.highlighter",
      {
        // "grammar" provider is purely declarative. No service methods.
      }, {
        type : "grammar",
        contentType: "text/html",
        grammar: {
          patterns: [
              {  begin: "<!--",
                 end: "-->",
                 captures: { "0": "punctuation.definition.comment.html" },
                 contentName: "comment.block.html"
              }
          ]
        }
      });
    provider.connect();

The above example provides a grammar to be used for HTML files. It will assign the CSS class `punctuation-definition-comment-html` to the `<!--` and `-->` delimiters, and assign the CSS class `comment-block-html` to the text inside the delimiters. Consult this reference for a full description of the grammar format.

(Note that some aspects of the grammar format are not supported. See `orion.editor.TextMateStyler` in the Client API reference for a detailed explanation.)

## Example of a 'highlighter' provider

See the source code of the orion-codemirror plugin, particularly these lines.