| 1 |
<!doctype html> |
| 2 |
|
| 3 |
<title>CodeMirror: Simple Mode Demo</title> |
| 4 |
<meta charset="utf-8"/> |
| 5 |
<link rel=stylesheet href="../doc/docs.css"> |
| 6 |
|
| 7 |
<link rel="stylesheet" href="../lib/codemirror.css"> |
| 8 |
<script src="../lib/codemirror.js"></script> |
| 9 |
<script src="../addon/mode/simple.js"></script> |
| 10 |
<script src="../mode/xml/xml.js"></script> |
| 11 |
<style> |
| 12 |
.CodeMirror {border: 1px solid silver; margin-bottom: 1em; } |
| 13 |
dt { text-indent: -2em; padding-left: 2em; margin-top: 1em; } |
| 14 |
dd { margin-left: 1.5em; margin-bottom: 1em; } |
| 15 |
dt {margin-top: 1em;} |
| 16 |
</style> |
| 17 |
|
| 18 |
<div id=nav> |
| 19 |
<a href="https://codemirror.net"><h1>CodeMirror</h1><img id=logo src="../doc/logo.png"></a> |
| 20 |
|
| 21 |
<ul> |
| 22 |
<li><a href="../index.html">Home</a> |
| 23 |
<li><a href="../doc/manual.html">Manual</a> |
| 24 |
<li><a href="https://github.com/codemirror/codemirror">Code</a> |
| 25 |
</ul> |
| 26 |
<ul> |
| 27 |
<li><a class=active href="#">Simple Mode</a> |
| 28 |
</ul> |
| 29 |
</div> |
| 30 |
|
| 31 |
<article> |
| 32 |
<h2>Simple Mode Demo</h2> |
| 33 |
|
| 34 |
<p>The <a href="../addon/mode/simple.js"><code>mode/simple</code></a> |
| 35 |
addon allows CodeMirror modes to be specified using a relatively simple |
| 36 |
declarative format. This format is not as powerful as writing code |
| 37 |
directly against the <a href="../doc/manual.html#modeapi">mode |
| 38 |
interface</a>, but is a lot easier to get started with, and |
| 39 |
sufficiently expressive for many simple language modes.</p> |
| 40 |
|
| 41 |
<p>This interface is still in flux. It is unlikely to be scrapped or |
| 42 |
overhauled completely, so do start writing code against it, but |
| 43 |
details might change as it stabilizes, and you might have to tweak |
| 44 |
your code when upgrading.</p> |
| 45 |
|
| 46 |
<p>Simple modes (loosely based on |
| 47 |
the <a href="https://github.com/mozilla/skywriter/wiki/Common-JavaScript-Syntax-Highlighting-Specification">Common |
| 48 |
JavaScript Syntax Highlighting Specification</a>, which never took |
| 49 |
off), are state machines, where each state has a number of rules that |
| 50 |
match tokens. A rule describes a type of token that may occur in the |
| 51 |
current state, and possibly a transition to another state caused by |
| 52 |
that token.</p> |
| 53 |
|
| 54 |
<p>The <code>CodeMirror.defineSimpleMode(name, states)</code> method |
| 55 |
takes a mode name and an object that describes the mode's states. The |
| 56 |
editor below shows an example of such a mode (and is itself |
| 57 |
highlighted by the mode shown in it).</p> |
| 58 |
|
| 59 |
<div id="code"></div> |
| 60 |
|
| 61 |
<p>Each state is an array of rules. A rule may have the following properties:</p> |
| 62 |
|
| 63 |
<dl> |
| 64 |
<dt><code><strong>regex</strong>: string | RegExp</code></dt> |
| 65 |
<dd>The regular expression that matches the token. May be a string |
| 66 |
or a regex object. When a regex, the <code>ignoreCase</code> flag |
| 67 |
will be taken into account when matching the token. This regex |
| 68 |
has to capture groups when the <code>token</code> property is |
| 69 |
an array. If it captures groups, it must capture <em>all</em> of the string |
| 70 |
(since JS provides no way to find out where a group matched).</dd> |
| 71 |
<dt><code><strong>token</strong></code>: string | array<string> | null</dt> |
| 72 |
<dd>An optional token style. Multiple styles can be specified by |
| 73 |
separating them with dots or spaces. When this property holds an array of token styles, |
| 74 |
the <code>regex</code> for this rule must capture a group for each array item. |
| 75 |
</dd> |
| 76 |
<dt><code><strong>sol</strong></code>: boolean</dt> |
| 77 |
<dd>When true, this token will only match at the start of the line. |
| 78 |
(The <code>^</code> regexp marker doesn't work as you'd expect in |
| 79 |
this context because of limitations in JavaScript's RegExp |
| 80 |
API.)</dd> |
| 81 |
<dt><code><strong>next</strong>: string</code></dt> |
| 82 |
<dd>When a <code>next</code> property is present, the mode will |
| 83 |
transfer to the state named by the property when the token is |
| 84 |
encountered.</dd> |
| 85 |
<dt><code><strong>push</strong>: string</code></dt> |
| 86 |
<dd>Like <code>next</code>, but instead replacing the current state |
| 87 |
by the new state, the current state is kept on a stack, and can be |
| 88 |
returned to with the <code>pop</code> directive.</dd> |
| 89 |
<dt><code><strong>pop</strong>: bool</code></dt> |
| 90 |
<dd>When true, and there is another state on the state stack, will |
| 91 |
cause the mode to pop that state off the stack and transition to |
| 92 |
it.</dd> |
| 93 |
<dt><code><strong>mode</strong>: {spec, end, persistent}</code></dt> |
| 94 |
<dd>Can be used to embed another mode inside a mode. When present, |
| 95 |
must hold an object with a <code>spec</code> property that describes |
| 96 |
the embedded mode, and an optional <code>end</code> end property |
| 97 |
that specifies the regexp that will end the extent of the mode. When |
| 98 |
a <code>persistent</code> property is set (and true), the nested |
| 99 |
mode's state will be preserved between occurrences of the mode.</dd> |
| 100 |
<dt><code><strong>indent</strong>: bool</code></dt> |
| 101 |
<dd>When true, this token changes the indentation to be one unit |
| 102 |
more than the current line's indentation.</dd> |
| 103 |
<dt><code><strong>dedent</strong>: bool</code></dt> |
| 104 |
<dd>When true, this token will pop one scope off the indentation |
| 105 |
stack.</dd> |
| 106 |
<dt><code><strong>dedentIfLineStart</strong>: bool</code></dt> |
| 107 |
<dd>If a token has its <code>dedent</code> property set, it will, by |
| 108 |
default, cause lines where it appears at the start to be dedented. |
| 109 |
Set this property to false to prevent that behavior.</dd> |
| 110 |
</dl> |
| 111 |
|
| 112 |
<p>The <code>meta</code> property of the states object is special, and |
| 113 |
will not be interpreted as a state. Instead, properties set on it will |
| 114 |
be set on the mode, which is useful for properties |
| 115 |
like <a href="../doc/manual.html#addon_comment"><code>lineComment</code></a>, |
| 116 |
which sets the comment style for a mode. The simple mode addon also |
| 117 |
recognizes a few such properties:</p> |
| 118 |
|
| 119 |
<dl> |
| 120 |
<dt><code><strong>dontIndentStates</strong>: array<string></code></dt> |
| 121 |
<dd>An array of states in which the mode's auto-indentation should |
| 122 |
not take effect. Usually used for multi-line comment and string |
| 123 |
states.</dd> |
| 124 |
</dl> |
| 125 |
|
| 126 |
<script id="modecode">/* Example definition of a simple mode that understands a subset of |
| 127 |
* JavaScript: |
| 128 |
*/ |
| 129 |
|
| 130 |
CodeMirror.defineSimpleMode("simplemode", { |
| 131 |
// The start state contains the rules that are intially used |
| 132 |
start: [ |
| 133 |
// The regex matches the token, the token property contains the type |
| 134 |
{regex: /"(?:[^\\]|\\.)*?(?:"|$)/, token: "string"}, |
| 135 |
// You can match multiple tokens at once. Note that the captured |
| 136 |
// groups must span the whole string in this case |
| 137 |
{regex: /(function)(\s+)([a-z$][\w$]*)/, |
| 138 |
token: ["keyword", null, "variable-2"]}, |
| 139 |
// Rules are matched in the order in which they appear, so there is |
| 140 |
// no ambiguity between this one and the one above |
| 141 |
{regex: /(?:function|var|return|if|for|while|else|do|this)\b/, |
| 142 |
token: "keyword"}, |
| 143 |
{regex: /true|false|null|undefined/, token: "atom"}, |
| 144 |
{regex: /0x[a-f\d]+|[-+]?(?:\.\d+|\d+\.?\d*)(?:e[-+]?\d+)?/i, |
| 145 |
token: "number"}, |
| 146 |
{regex: /\/\/.*/, token: "comment"}, |
| 147 |
{regex: /\/(?:[^\\]|\\.)*?\//, token: "variable-3"}, |
| 148 |
// A next property will cause the mode to move to a different state |
| 149 |
{regex: /\/\*/, token: "comment", next: "comment"}, |
| 150 |
{regex: /[-+\/*=<>!]+/, token: "operator"}, |
| 151 |
// indent and dedent properties guide autoindentation |
| 152 |
{regex: /[\{\[\(]/, indent: true}, |
| 153 |
{regex: /[\}\]\)]/, dedent: true}, |
| 154 |
{regex: /[a-z$][\w$]*/, token: "variable"}, |
| 155 |
// You can embed other modes with the mode property. This rule |
| 156 |
// causes all code between << and >> to be highlighted with the XML |
| 157 |
// mode. |
| 158 |
{regex: /<</, token: "meta", mode: {spec: "xml", end: />>/}} |
| 159 |
], |
| 160 |
// The multi-line comment state. |
| 161 |
comment: [ |
| 162 |
{regex: /.*?\*\//, token: "comment", next: "start"}, |
| 163 |
{regex: /.*/, token: "comment"} |
| 164 |
], |
| 165 |
// The meta property contains global information about the mode. It |
| 166 |
// can contain properties like lineComment, which are supported by |
| 167 |
// all modes, and also directives like dontIndentStates, which are |
| 168 |
// specific to simple modes. |
| 169 |
meta: { |
| 170 |
dontIndentStates: ["comment"], |
| 171 |
lineComment: "//" |
| 172 |
} |
| 173 |
}); |
| 174 |
</script> |
| 175 |
|
| 176 |
<script> |
| 177 |
var sc = document.getElementById("modecode"); |
| 178 |
var code = document.getElementById("code"); |
| 179 |
var editor = CodeMirror(code, { |
| 180 |
value: (sc.textContent || sc.innerText || sc.innerHTML), |
| 181 |
mode: "simplemode" |
| 182 |
}); |
| 183 |
</script> |
| 184 |
|
| 185 |
</article> |