CodeMirror

Simple Mode Demo

The mode/simple addon allows CodeMirror modes to be specified using a relatively simple declarative format. This format is not as powerful as writing code directly against the mode interface, but is a lot easier to get started with, and sufficiently expressive for many simple language modes.

This interface is still in flux. It is unlikely to be scrapped or overhauled completely, so do start writing code against it, but details might change as it stabilizes, and you might have to tweak your code when upgrading.

Simple modes (loosely based on the Common JavaScript Syntax Highlighting Specification, which never took off), are state machines, where each state has a number of rules that match tokens. A rule describes a type of token that may occur in the current state, and possibly a transition to another state caused by that token.

The CodeMirror.defineSimpleMode(name, states) method takes a mode name and an object that describes the mode's states. The editor below shows an example of such a mode (and is itself highlighted by the mode shown in it).

Each state is an array of rules. A rule may have the following properties:

regex: string | RegExp

The regular expression that matches the token. May be a string or a regex object. When a regex, the ignoreCase flag will be taken into account when matching the token. This regex has to capture groups when the token property is an array. If it captures groups, it must capture all of the string (since JS provides no way to find out where a group matched). Currently negative lookbehind assertion for regex is not supported, regardless of browser support.

token: string | array<string> | null

An optional token style. Multiple styles can be specified by separating them with dots or spaces. When this property holds an array of token styles, the regex for this rule must capture a group for each array item.

sol: boolean

When true, this token will only match at the start of the line. (The ^ regexp marker doesn't work as you'd expect in this context because of limitations in JavaScript's RegExp API.)

next: string

When a next property is present, the mode will transfer to the state named by the property when the token is encountered.

push: string

Like next, but instead replacing the current state by the new state, the current state is kept on a stack, and can be returned to with the pop directive.

pop: bool

When true, and there is another state on the state stack, will cause the mode to pop that state off the stack and transition to it.

mode: {spec, end, persistent}

Can be used to embed another mode inside a mode. When present, must hold an object with a spec property that describes the embedded mode, and an optional end end property that specifies the regexp that will end the extent of the mode. When a persistent property is set (and true), the nested mode's state will be preserved between occurrences of the mode.

indent: bool

When true, this token changes the indentation to be one unit more than the current line's indentation.

dedent: bool

When true, this token will pop one scope off the indentation stack.

dedentIfLineStart: bool

If a token has its dedent property set, it will, by default, cause lines where it appears at the start to be dedented. Set this property to false to prevent that behavior.

The meta property of the states object is special, and will not be interpreted as a state. Instead, properties set on it will be set on the mode, which is useful for properties like lineComment, which sets the comment style for a mode. The simple mode addon also recognizes a few such properties:

dontIndentStates: array<string>

An array of states in which the mode's auto-indentation should not take effect. Usually used for multi-line comment and string states.