# orion.edit.highlighter

Note that this section has been rewritten for the new syntax styling service in the Orion 5.0 release. The implementation of the older syntax styling service is also in Orion 5.0 in order to preserve backwards-compatibility, but is considered deprecated. Documentation for this old service can be found here. All new syntax styling declaration should be implemented in terms of the new styling service that is described below.

The `orion.edit.highlighter` service contributes syntax styling patterns to the editor. This is done 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. The service also provides a list of content types. When the editor opens a file of a registered content type, the provider is invoked to obtain the styling.

## Service methods

None. This service is purely declarative.

## Service attributes

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

id
  `String` A name that uniquely identifies this grammar.
contentTypes
  `String[]` An array of Content Type IDs that this grammar will be used for.
patterns
  `Object[]` An array of pattern objects to be used to assign style classes. Pattern objects are described below.
repository
  `Object` Optional. A set of named pattern objects that can be referenced by this grammar and others.

## Pattern objects

Patterns are defined in a similar way to TextMate language rules, with some minor variation to adapt to the context of Orion:

- Patterns are defined using valid Javascript syntax, and remember that every '\' character requires an extra '\' to escape it in the Javascript string (for example, to define a regular expression that matches a tab character would require string "\\t").
- Regular expressions are bound by the abilities/constraints of Javascript's RegExp (for example, no look-behinds).
- Sub-patterns can be defined for both match: and begin:/end: patterns.
- A pattern that references another grammar does so by its id attribute (for example: "include: 'orion.lib'").
- If a capture group is used to style part of a match then all parts of the match MUST belong to capture groups, to help the styler correctly compute the capture group range (this is due to a limitation in Javascript's RegExp). For example, to style the escaped character sequences in match result "newline is \n, tab is \t", the capture groups could look like "(newline is )(\n)(, tab is )(\t)", with the escaped character styling applied to capture groups 2 and 4.

## Style names

The TextMate naming conventions are followed by the text styler. In addition to visual styling, the following styles can be used to provide semantic info about matches:

- punctuation.section.(begin|end): pairs of matches with these styles are used by the editor to compute section matches (for example, showing bracket matching)
- meta.annotation.task.todo: a match within a comment that has this style may be handled specially by the editor's container (for example, Orion will show a corresponding TODO annotation in the editor's gutter)

## orion.lib and orion.c-like

Many of the patterns that were defined for Orion's core language stylings are applicable across many languages (for example, strings, numbers, etc.). In order to make these patterns easily re-usable, two generic grammars are defined that contain them and can be inherited by other language grammars either in whole or in part. These grammars are:

- orion.lib: provides stylings for:
  - matching of (), [] and {} brackets
  - base-10 and base-16 numbers (for example, -1.02, 3e10, 0x8ab3, etc.)
  - single- and double-quoted strings
- orion.c-like: provides stylings for everything in orion.lib, and additionally for // and /* */ comments

A grammar can include the full set of patterns from orion.lib with "include: 'orion.lib'". That grammar could then override any of the included patterns, including an override to no-op, by specifying a pattern with the same name in its repository section.

For an example of including most patterns from orion.c-like see Orion's Java syntax styling. The orion.lib and orion.c-like grammars are defined here.

## Example

     provider.registerServiceProvider("orion.edit.highlighter",
       {
         // no service methods
       }, {
         id: "orion.json",
         contentTypes: ["application/json"],
         patterns: [
           {
               include: "orion.lib"
           }, {
               match: "\\b(?:false|true)\\b",
               name: "keyword.json"
           }
         ]
       });

The above example shows Orion's grammar for styling of .json files. Since .json has many language constructs that are found in other languages it is able to inherit most of its styling from Orion's provided orion.lib grammar. The .json grammar supplements this by defining a pattern for styling false and true as keywords (an alternate styling name for these could have been constant.language).