/* User manual and reference guide */
/* User manual and reference guide */
CodeMirror is a code-editor component that can be embedded in Web pages. The core library provides only the editor component, no accompanying buttons, auto-completion, or other IDE functionality. It does provide a rich API on top of which such functionality can be straightforwardly implemented. See the addons included in the distribution, and the list of externally hosted addons, for reusable implementations of extra features.
CodeMirror works with language-specific modes. Modes are
JavaScript programs that help color (and optionally indent) text
written in a given language. The distribution comes with a number
of modes (see the mode/
directory), and it isn't hard to write new
ones for other languages.
The easiest way to use CodeMirror is to simply load the script
and style sheet found under lib/ in the distribution,
plus a mode script from one of the mode/ directories.
(See the compression helper for an
easy way to combine scripts.) For example:
<script src="lib/codemirror.js"></script> <link rel="stylesheet" href="../lib/codemirror.css"> <script src="mode/javascript/javascript.js"></script>
Having done this, an editor instance can be created like this:
var myCodeMirror = CodeMirror(document.body);
The editor will be appended to the document body, will start
empty, and will use the mode that we loaded. To have more control
over the new editor, a configuration object can be passed
to CodeMirror as a second
argument:
var myCodeMirror = CodeMirror(document.body, {
value: "function myScript(){return 100;}\n",
mode: "javascript"
});
This will initialize the editor with a piece of code already in it, and explicitly tell it to use the JavaScript mode (which is useful when multiple modes are loaded). See below for a full discussion of the configuration options that CodeMirror accepts.
In cases where you don't want to append the editor to an
element, and need more control over the way it is inserted, the
first argument to the CodeMirror function can also
be a function that, when given a DOM element, inserts it into the
document somewhere. This could be used to, for example, replace a
textarea with a real editor:
var myCodeMirror = CodeMirror(function(elt) {
myTextArea.parentNode.replaceChild(elt, myTextArea);
}, {value: myTextArea.value});
However, for this use case, which is a common way to use CodeMirror, the library provides a much more powerful shortcut:
var myCodeMirror = CodeMirror.fromTextArea(myTextArea);
This will, among other things, ensure that the textarea's value is updated with the editor's contents when the form (if it is part of a form) is submitted. See the API reference for a full description of this method.
Both the CodeMirror
function and its fromTextArea method take as second
(optional) argument an object containing configuration options.
Any option not supplied like this will be taken
from CodeMirror.defaults, an
object containing the default options. You can update this object
to change the defaults on your page.
Options are not checked in any way, so setting bogus option values is bound to lead to odd errors.
These are the supported options:
value: string|CodeMirror.Docmode: string|objectname property that names the mode (for
example {name: "javascript", json: true}). The demo
pages for each mode contain information about what configuration
parameters the mode supports. You can ask CodeMirror which modes
and MIME types have been defined by inspecting
the CodeMirror.modes
and CodeMirror.mimeModes objects. The first maps
mode names to their constructors, and the second maps MIME types
to mode specs.theme: string.cm-s-[name]
styles is loaded (see
the theme directory in the
distribution). The default is "default", for which
colors are included in codemirror.css. It is
possible to use multiple theming classes at once—for
example "foo bar" will assign both
the cm-s-foo and the cm-s-bar classes
to the editor.indentUnit: integersmartIndent: booleantabSize: integerindentWithTabs: booleantabSize
spaces should be replaced by N tabs. Default is false.electricChars: booleanrtlMoveVisually: booleanfalse
on Windows, and true on other platforms.keyMap: string"default", which is the only keymap defined
in codemirror.js itself. Extra keymaps are found in
the keymap directory. See
the section on keymaps for more
information.extraKeys: objectkeyMap. Should be
either null, or a valid keymap value.lineWrapping: booleanfalse (scroll).lineNumbers: booleanfirstLineNumber: integerlineNumberFormatter: function(line: integer) → stringgutters: array<string>width (and optionally a
background), and which will be used to draw the background of
the gutters. May include
the CodeMirror-linenumbers class, in order to
explicitly set the position of the line number gutter (it will
default to be to the right of all other gutters). These class
names are the keys passed
to setGutterMarker.fixedGutter: booleancoverGutterNextToScrollbar: booleanfixedGutter
is on, and there is a horizontal scrollbar, by default the
gutter will be visible to the left of this scrollbar. If this
option is set to true, it will be covered by an element with
class CodeMirror-gutter-filler.readOnly: boolean|string"nocursor" is given (instead of
simply true), focusing of the editor is also
disallowed.showCursorWhenSelecting: booleanundoDepth: integerhistoryEventDelay: integertabindex: integerautofocus: booleanfromTextArea is
used, and no explicit value is given for this option, it will be
set to true when either the source textarea is focused, or it
has an autofocus attribute and no other element is
focused.Below this a few more specialized, low-level options are listed. These are only useful in very specific situations, you might want to skip them the first time you read this manual.
dragDrop: booleanonDragEvent: function(instance: CodeMirror, event: Event) → booleandragenter, dragover,
or drop event. It will be passed the editor
instance and the event object as arguments. The callback can
choose to handle the event itself, in which case it should
return true to indicate that CodeMirror should not
do anything further.onKeyEvent: function(instance: CodeMirror, event: Event) → booleankeydown, keyup,
and keypress event that CodeMirror captures. It
will be passed two arguments, the editor instance and the key
event. This key event is pretty much the raw key event, except
that a stop() method is always added to it. You
could feed it to, for example, jQuery.Event to
further normalize it.keydown does not stop
the keypress from firing, whereas on others it
does. If you respond to an event, you should probably inspect
its type property and only do something when it
is keydown (or keypress for actions
that need character data).cursorBlinkRate: numbercursorScrollMargin: numbercursorHeight: number0.85),
which causes the cursor to not reach all the way to the bottom
of the line, looks betterworkTime, workDelay: numberworkTime milliseconds, and then use
timeout to sleep for workDelay milliseconds. The
defaults are 200 and 300, you can change these options to make
the highlighting more or less aggressive.workDelay: numberworkTime.pollInterval: numberflattenSpans: booleanmaxHighlightLength: numberInfinity to turn off
this behavior.viewportMargin: integerInfinity to make sure the whole document is
always rendered, and thus the browser's text search works on it.
This will have bad effects on performance of big
documents.Various CodeMirror-related objects emit events, which allow
client code to react to various situations. Handlers for such
events can be registed with the on
and off methods on the objects
that the event fires on. To fire your own events,
use CodeMirror.signal(target, name, args...),
where target is a non-DOM-node object.
An editor instance fires the following events.
The instance argument always refers to the editor
itself.
"change" (instance: CodeMirror, changeObj: object)changeObj is a {from, to, text, removed,
next} object containing information about the changes
that occurred as second argument. from
and to are the positions (in the pre-change
coordinate system) where the change started and ended (for
example, it might be {ch:0, line:18} if the
position is at the beginning of line #19). text is
an array of strings representing the text that replaced the
changed range (split by line). removed is the text
that used to be between from and to,
which is overwritten by this change. If multiple changes
happened during a single operation, the object will have
a next property pointing to another change object
(which may point to another, etc)."beforeChange" (instance: CodeMirror, changeObj: object)changeObj object
has from, to, and text
properties, as with
the "change" event, but
never a next property, since this is fired for each
individual change, and not batched per operation. It also has
a cancel() method, which can be called to cancel
the change, and, if the change isn't coming
from an undo or redo event, an update(from, to,
text) method, which may be used to modify the change.
Undo or redo changes can't be modified, because they hold some
metainformation for restoring old marked ranges that is only
valid for that specific change. All three arguments
to update are optional, and can be left off to
leave the existing value for that field
intact. Note: you may not do anything from
a "beforeChange" handler that would cause changes
to the document or its visualization. Doing so will, since this
handler is called directly from the bowels of the CodeMirror
implementation, probably cause the editor to become
corrupted."cursorActivity" (instance: CodeMirror)"keyHandled" (instance: CodeMirror, name: string, event: Event)name is the name of the handled key (for
example "Ctrl-X" or "'q'"),
and event is the DOM keydown
or keypress event."inputRead" (instance: CodeMirror, changeObj: object)"beforeSelectionChange" (instance: CodeMirror, selection: {head, anchor})selection parameter is an object
with head and anchor properties
holding {line, ch} objects, which the handler can
read and update. Handlers for this event have the same
restriction
as "beforeChange"
handlers — they should not do anything to directly update the
state of the editor."viewportChange" (instance: CodeMirror, from: number, to: number)from and to arguments
give the new start and end of the viewport."gutterClick" (instance: CodeMirror, line: integer, gutter: string, clickEvent: Event)mousedown event object as
fourth argument."focus" (instance: CodeMirror)"blur" (instance: CodeMirror)"scroll" (instance: CodeMirror)"update" (instance: CodeMirror)"renderLine" (instance: CodeMirror, line: LineHandle, element: Element)"mousedown",
"dblclick", "contextmenu", "keydown", "keypress",
"keyup", "dragstart", "dragenter",
"dragover", "drop"
(instance: CodeMirror, event: Event)preventDefault the event, or give it a
truthy codemirrorIgnore property, to signal that
CodeMirror should do no further handling.Document objects (instances
of CodeMirror.Doc) emit the
following events:
"change" (doc: CodeMirror.Doc, changeObj: object)changeObj has a similar type as the
object passed to the
editor's "change"
event, but it never has a next property, because
document change events are not batched (whereas editor change
events are)."beforeChange" (doc: CodeMirror.Doc, change: object)"cursorActivity" (doc: CodeMirror.Doc)"beforeSelectionChange" (doc: CodeMirror.Doc, selection: {head, anchor})Line handles (as returned by, for
example, getLineHandle)
support these events:
"delete" ()"change" (line: LineHandle, changeObj: object)change
object is similar to the one passed
to change event on the editor
object.Marked range handles (CodeMirror.TextMarker), as returned
by markText
and setBookmark, emit the
following events:
"beforeCursorEnter" ()"clear" (from: {line, ch}, to: {line, ch})clearOnEnter
or through a call to its clear() method. Will only
be fired once per handle. Note that deleting the range through
text editing does not fire this event, because an undo action
might bring the range back into existence. from
and to give the part of the document that the range
spanned when it was cleared."hide" ()"unhide" ()Line widgets (CodeMirror.LineWidget), returned
by addLineWidget, fire
these events:
"redraw" ()Keymaps are ways to associate keys with functionality. A keymap is an object mapping strings that identify the keys to functions that implement their functionality.
Keys are identified either by name or by character.
The CodeMirror.keyNames object defines names for
common keys and associates them with their key codes. Examples of
names defined here are Enter, F5,
and Q. These can be prefixed
with Shift-, Cmd-, Ctrl-,
and Alt- (in that order!) to specify a modifier. So
for example, Shift-Ctrl-Space would be a valid key
identifier.
Common example: map the Tab key to insert spaces instead of a tab character.
{
Tab: function(cm) {
var spaces = Array(cm.getOption("indentUnit") + 1).join(" ");
cm.replaceSelection(spaces, "end", "+input");
}
}
Alternatively, a character can be specified directly by
surrounding it in single quotes, for example '$'
or 'q'. Due to limitations in the way browsers fire
key events, these may not be prefixed with modifiers.
The CodeMirror.keyMap object associates keymaps
with names. User code and keymap definitions can assign extra
properties to this object. Anywhere where a keymap is expected, a
string can be given, which will be looked up in this object. It
also contains the "default" keymap holding the
default bindings.
The values of properties in keymaps can be either functions of
a single argument (the CodeMirror instance), strings, or
false. Such strings refer to properties of the
CodeMirror.commands object, which defines a number of
common commands that are used by the default keybindings, and maps
them to functions. If the property is set to false,
CodeMirror leaves handling of the key up to the browser. A key
handler function may return CodeMirror.Pass to indicate
that it has decided not to handle the key, and other handlers (or
the default behavior) should be given a turn.
Keys mapped to command names that start with the
characters "go" (which should be used for
cursor-movement actions) will be fired even when an
extra Shift modifier is present (i.e. "Up":
"goLineUp" matches both up and shift-up). This is used to
easily implement shift-selection.
Keymaps can defer to each other by defining
a fallthrough property. This indicates that when a
key is not found in the map itself, one or more other maps should
be searched. It can hold either a single keymap or an array of
keymaps.
When a keymap contains a nofallthrough property
set to true, keys matched against that map will be
ignored if they don't match any of the bindings in the map (no
further child maps will be tried). When
the disableInput property is set
to true, the default effect of inserting a character
will be suppressed when the keymap is active as the top-level
map.
Up to a certain extent, CodeMirror's look can be changed by
modifying style sheet files. The style sheets supplied by modes
simply provide the colors for that mode, and can be adapted in a
very straightforward way. To style the editor itself, it is
possible to alter or override the styles defined
in codemirror.css.
Some care must be taken there, since a lot of the rules in this file are necessary to have CodeMirror function properly. Adjusting colors should be safe, of course, and with some care a lot of other things can be changed as well. The CSS classes defined in this file serve the following roles:
CodeMirrorCodeMirror-scrolloverflow: auto +
fixed height). By default, it does. Setting
the CodeMirror class to have height:
auto and giving this class overflow-x: auto;
overflow-y: hidden; will cause the editor
to resize to fit its
content.CodeMirror-focusedCodeMirror-guttersCodeMirror-linenumbersCodeMirror-linenumberCodeMirror-linenumbers
(plural) element, but rather will be absolutely positioned to
overlay it. Use this to set alignment and text properties for
the line numbers.CodeMirror-linesCodeMirror-cursorCodeMirror-selectedspan elements
with this class.CodeMirror-matchingbracket,
CodeMirror-nonmatchingbracketIf your page's style sheets do funky things to
all div or pre elements (you probably
shouldn't do that), you'll have to define rules to cancel these
effects out again for elements under the CodeMirror
class.
Themes are also simply CSS files, which define colors for
various syntactic elements. See the files in
the theme directory.
A lot of CodeMirror features are only available through its API. Thus, you need to write code (or use addons) if you want to expose them to your users.
Whenever points in the document are represented, the API uses
objects with line and ch properties.
Both are zero-based. CodeMirror makes sure to 'clip' any positions
passed by client code so that they fit inside the document, so you
shouldn't worry too much about sanitizing your coordinates. If you
give ch a value of null, or don't
specify it, it will be replaced with the length of the specified
line.
Methods prefixed with doc. can, unless otherwise
specified, be called both on CodeMirror (editor)
instances and CodeMirror.Doc instances. Methods
prefixed with cm. are only available
on CodeMirror instances.
Constructing an editor instance is done with
the CodeMirror(place: Element|fn(Element),
?option: object) constructor. If the place
argument is a DOM element, the editor will be appended to it. If
it is a function, it will be called, and is expected to place the
editor into the document. options may be an element
mapping option names to values. The options
that it doesn't explicitly specify (or all options, if it is not
passed) will be taken
from CodeMirror.defaults.
Note that the options object passed to the constructor will be mutated when the instance's options are changed, so you shouldn't share such objects between instances.
See CodeMirror.fromTextArea
for another way to construct an editor instance.
doc.getValue(?separator: string) → string"\n").doc.setValue(content: string)doc.getRange(from: {line, ch}, to: {line, ch}, ?separator: string) → string{line, ch} objects. An optional third
argument can be given to indicate the line separator string to
use (defaults to "\n").doc.replaceRange(replacement: string, from: {line, ch}, to: {line, ch})from
and to with the given string. from
and to must be {line, ch}
objects. to can be left off to simply insert the
string at position from.doc.getLine(n: integer) → stringn.doc.setLine(n: integer, text: string)n.doc.removeLine(n: integer)doc.lineCount() → integerdoc.firstLine() → integerdoc.lastLine() → integerdoc.lineCount() - 1,
but for linked sub-views,
it might return other values.doc.getLineHandle(num: integer) → LineHandledoc.getLineNumber(handle: LineHandle) → integernull when it is no longer in the
document).doc.eachLine(f: (line: LineHandle))doc.eachLine(start: integer, end: integer, f: (line: LineHandle))start
and end line numbers are given, the range
from start up to (not including) end,
and call f for each line, passing the line handle.
This is a faster way to visit a range of line handlers than
calling getLineHandle
for each of them. Note that line handles have
a text property containing the line's content (as a
string).doc.markClean()changeGeneration,
which allows multiple subsystems to track different notions of
cleanness without interfering.doc.changeGeneration() → integerisClean to test whether
any edits were made (and not undone) in the meantime.doc.isClean(?generation: integer) → booleanmarkClean if no
argument is passed, or since the matching call
to changeGeneration
if a generation value is given.doc.getSelection() → stringdoc.replaceSelection(replacement: string, ?collapse: string)collapse argument can be used to change
this—passing "start" or "end" will
collapse the selection to the start or end of the inserted
text.doc.getCursor(?start: string) → {line, ch}start is a an optional string indicating which
end of the selection to return. It may
be "start", "end", "head"
(the side of the selection that moves when you press
shift+arrow), or "anchor" (the fixed side of the
selection). Omitting the argument is the same as
passing "head". A {line, ch} object
will be returned.doc.somethingSelected() → booleandoc.setCursor(pos: {line, ch}){line, ch} object, or the line and the
character as two separate parameters.doc.setSelection(anchor: {line, ch}, head: {line, ch})anchor
and head should be {line, ch}
objects. head defaults to anchor when
not given.doc.extendSelection(from: {line, ch}, ?to: {line, ch})setSelection, but
will, if shift is held or
the extending flag is set, move the
head of the selection while leaving the anchor at its current
place. pos2 is optional, and can be passed to
ensure a region (for example a word or paragraph) will end up
selected (in addition to whatever lies between that region and
the current anchor).doc.setExtending(value: boolean)extendSelection
to leave the selection anchor in place.cm.hasFocus() → booleancm.findPosH(start: {line, ch}, amount: integer, unit: string, visually: boolean) → {line, ch, ?hitSide: boolean}start is a {line, ch}
object, amount an integer (may be negative),
and unit one of the
string "char", "column",
or "word". Will return a position that is produced
by moving amount times the distance specified
by unit. When visually is true, motion
in right-to-left text will be visual rather than logical. When
the motion was clipped by hitting the end or start of the
document, the returned value will have a hitSide
property set to true.cm.findPosV(start: {line, ch}, amount: integer, unit: string) → {line, ch, ?hitSide: boolean}findPosH,
but used for vertical motion. unit may
be "line" or "page". The other
arguments and the returned value have the same interpretation as
they have in findPosH.cm.setOption(option: string, value: any)option
should the name of an option,
and value should be a valid value for that
option.cm.getOption(option: string) → anycm.addKeyMap(map: object, bottom: boolean)extraKeys
option. Maps added in this way have a higher precedence than
the extraKeys
and keyMap options,
and between them, the maps added earlier have a lower precedence
than those added later, unless the bottom argument
was passed, in which case they end up below other keymaps added
with this method.cm.removeKeyMap(map: object)addKeyMap. Either
pass in the keymap object itself, or a string, which will be
compared against the name property of the active
keymaps.cm.addOverlay(mode: string|object, ?options: object)mode can be a mode
spec or a mode object (an object with
a token method).
The options parameter is optional. If given, it
should be an object. Currently, only the opaque
option is recognized. This defaults to off, but can be given to
allow the overlay styling, when not null, to
override the styling of the base mode entirely, instead of the
two being applied together.cm.removeOverlay(mode: string|object)mode
parameter to addOverlay,
or a string that corresponds to the name propery of
that value, to remove an overlay again.cm.on(type: string, func: (...args))CodeMirror.on(object, type, func) version
that allows registering of events on any object.cm.off(type: string, func: (...args))CodeMirror.off(object, type,
func) also exists.Each editor is associated with an instance
of CodeMirror.Doc, its document. A document
represents the editor content, plus a selection, an undo history,
and a mode. A document can only be
associated with a single editor at a time. You can create new
documents by calling the CodeMirror.Doc(text, mode,
firstLineNumber) constructor. The last two arguments are
optional and can be used to set a mode for the document and make
it start at a line number other than 0, respectively.
cm.getDoc() → Docdoc.getEditor() → CodeMirrornull.cm.swapDoc(doc: CodeMirror.Doc) → Docdoc.copy(copyHistory: boolean) → DoccopyHistory is true, the history will also be
copied. Can not be called directly on an editor.doc.linkedDoc(options: object) → Docfrom: integerto: integermode: string|objectdoc.unlinkDoc(doc: CodeMirror.Doc)doc.iterLinkedDocs(function: (doc: CodeMirror.Doc, sharedHist: boolean))doc.undo()doc.redo()doc.historySize() → {undo: integer, redo: integer}{undo, redo} properties,
both of which hold integers, indicating the amount of stored
undo and redo operations.doc.clearHistory()doc.getHistory() → objectdoc.setHistory(history: object)getHistory. Note that
this will have entirely undefined results if the editor content
isn't also the same as it was when getHistory was
called.doc.markText(from: {line, ch}, to: {line, ch}, ?options: object) → TextMarkerfrom and to should
be {line, ch} objects. The options
parameter is optional. When given, it should be an object that
may contain the following configuration options:
className: stringinclusiveLeft: booleaninclusiveRight: booleaninclusiveLeft,
but for the right side.atomic: booleaninclusiveLeft
and inclusiveRight have a different meaning—they
will prevent the cursor from being placed respectively
directly before and directly after the range.collapsed: booleanclearOnEnter: boolean"clear" event
fired on the range handle can be used to be notified when this
happens.replacedWith: ElementhandleMouseEvents: booleanreplacedWith is given, this determines
whether the editor will capture mouse and drag events
occurring in this widget. Default is false—the events will be
left alone for the default browser handler, or specific
handlers on the widget, to capture.readOnly: booleansetValue to reset
the whole document. Note: adding a read-only span
currently clears the undo history of the editor, because
existing undo events being partially nullified by read-only
spans would corrupt the history (in the current
implementation).addToHistory: booleanstartStyle: stringendStyle: stringstartStyle, but for the rightmost span.title:
stringtitle attribute with the
given value.shared to true to make the
marker appear in all documents. By default, a marker appears
only in its target document.CodeMirror.TextMarker), which
exposes three methods:
clear(), to remove the mark,
find(), which returns
a {from, to} object (both holding document
positions), indicating the current position of the marked range,
or undefined if the marker is no longer in the
document, and finally changed(),
which you can call if you've done something that might change
the size of the marker (for example changing the content of
a replacedWith
node), and want to cheaply update the display.doc.setBookmark(pos: {line, ch}, ?options: object) → TextMarkerfind() and clear(). The first
returns the current position of the bookmark, if it is still in
the document, and the second explicitly removes the bookmark.
The options argument is optional. If given, the following
properties are recognized:
widget: ElementreplacedWith
option to markText).insertLeft: booleandoc.findMarksAt(pos: {line, ch}) → array<TextMarker>doc.getAllMarks() → array<TextMarker>cm.setGutterMarker(line: integer|LineHandle, gutterID: string, value: Element) → LineHandlegutters option)
to the given value. Value can be either null, to
clear the marker, or a DOM element, to set it. The DOM element
will be shown in the specified gutter next to the specified
line.cm.clearGutter(gutterID: string)cm.addLineClass(line: integer|LineHandle, where: string, class: string) → LineHandleline
can be a number or a line handle. where determines
to which element this class should be applied, can can be one
of "text" (the text element, which lies in front of
the selection), "background" (a background element
that will be behind the selection), or "wrap" (the
wrapper node that wraps all of the line's elements, including
gutter elements). class should be the name of the
class to apply.cm.removeLineClass(line: integer|LineHandle, where: string, class: string) → LineHandleline can be a
line handle or number. where should be one
of "text", "background",
or "wrap"
(see addLineClass). class
can be left off to remove all classes for the specified node, or
be a string to remove only a specific class.cm.lineInfo(line: integer|LineHandle) → object{line, handle, text,
gutterMarkers, textClass, bgClass, wrapClass, widgets},
where gutterMarkers is an object mapping gutter IDs
to marker elements, and widgets is an array
of line widgets attached to this
line, and the various class properties refer to classes added
with addLineClass.cm.addWidget(pos: {line, ch}, node: Element, scrollIntoView: boolean)node, which should be an absolutely
positioned DOM node, into the editor, positioned right below the
given {line, ch} position.
When scrollIntoView is true, the editor will ensure
that the entire node is visible (if possible). To remove the
widget again, simply use DOM methods (move it somewhere else, or
call removeChild on its parent).cm.addLineWidget(line: integer|LineHandle, node: Element, ?options: object) → LineWidgetline should be either an integer or a
line handle, and node should be a DOM node, which
will be displayed below the given line. options,
when given, should be an object that configures the behavior of
the widget. The following options are supported (all default to
false):
coverGutter: booleannoHScroll: booleanabove: booleanshowIfHidden: booleanhandleMouseEvents: booleaninsertAt: integerline property
pointing at the line handle that it is associated with, and the following methods:
clear()changed()cm.setSize(width: number|string, height: number|string)width and height height
can be either numbers (interpreted as pixels) or CSS units
("100%", for example). You can
pass null for either of them to indicate that that
dimension should not be changed.cm.scrollTo(x: number, y: number)null
or undefined to have no effect.cm.getScrollInfo() → {left, top, width, height, clientWidth, clientHeight}{left, top, width, height, clientWidth,
clientHeight} object that represents the current scroll
position, the size of the scrollable area, and the size of the
visible area (minus scrollbars).cm.scrollIntoView(pos: {line, ch}|{left, top, right, bottom}, ?margin: number)pos may be
either a {line, ch} position, referring to a given
character, null, to refer to the cursor, or
a {left, top, right, bottom} object, in
editor-local coordinates. The margin parameter is
optional. When given, it indicates the amount of pixels around
the given area that should be made visible as well.cm.cursorCoords(where: boolean|{line, ch}, mode: string) → {left, top, bottom}{left, top, bottom} object
containing the coordinates of the cursor position.
If mode is "local", they will be
relative to the top-left corner of the editable document. If it
is "page" or not given, they are relative to the
top-left corner of the page. where can be a boolean
indicating whether you want the start (true) or the
end (false) of the selection, or, if a {line,
ch} object is given, it specifies the precise position at
which you want to measure.cm.charCoords(pos: {line, ch}, ?mode: string) → {left, right, top, bottom}pos should be a {line, ch}
object. This differs from cursorCoords in that
it'll give the size of the whole character, rather than just the
position that the cursor would have when it would sit at that
position.cm.coordsChar(object: {left, top}, ?mode: string) → {line, ch}{left, top} object, returns
the {line, ch} position that corresponds to it. The
optional mode parameter determines relative to what
the coordinates are interpreted. It may
be "window", "page" (the default),
or "local".cm.lineAtHeight(height: number, ?mode: string) → numbermode can be one of the same strings
that coordsChar
accepts.cm.heightAtLine(line: number, ?mode: string) → numbermode
(see coordsChar), which
defaults to "page". When a line below the bottom of
the document is specified, the returned value is the bottom of
the last line in the document.cm.defaultTextHeight() → numbercm.defaultCharWidth() → numbercm.getViewport() → {from: number, to: number}{from, to} object indicating the
start (inclusive) and end (exclusive) of the currently rendered
part of the document. In big documents, when most content is
scrolled out of view, CodeMirror will only render the visible
part, and a margin around it. See also
the viewportChange
event.cm.refresh()When writing language-aware functionality, it can often be useful to hook into the knowledge that the CodeMirror language mode has. See the section on modes for a more detailed description of how these work.
doc.getMode() → objectgetOption("mode"), which gives you
the mode specification, rather than the resolved, instantiated
mode object.doc.getModeAt(pos: {line, ch}) → objectgetMode for
simple modes, but will return an inner mode for nesting modes
(such as htmlmixed).cm.getTokenAt(pos: {line, ch}, ?precise: boolean) → object{line, ch} object). The
returned object has the following properties:
startendstringtype"keyword"
or "comment" (may also be null).stateprecise is true, the token will be guaranteed to be accurate based on recent edits. If false or
not specified, the token will use cached state information, which will be faster but might not be accurate if
edits were recently made and highlighting has not yet completed.
cm.getTokenTypeAt(pos: {line, ch}) → stringgetTokenAt useful for
when you just need the type of the token at a given position,
and no other information. Will return null for
unstyled tokens, and a string, potentially containing multiple
space-separated style names, otherwise.cm.getHelper(pos: {line, ch}, type: string) → helpertype argument provides the helper namespace
(see
also registerHelper),
in which the value will be looked up. The key that is used
depends on the mode active at the given
position. If the mode object contains a property with the same
name as the type argument, that is tried first.
Next, the mode's helperType, if any, is tried. And
finally, the mode's name.cm.getStateAfter(?line: integer, ?precise: boolean) → objectprecise is defined
as in getTokenAt().cm.operation(func: () → any) → anycm.indentLine(line: integer, ?dir: string|integer)"smart") may be one of:
"prev""smart""prev" otherwise."add""subtract"<integer>cm.toggleOverwrite(?value: bool)doc.posFromIndex(index: integer) → {line, ch}{line, ch} object for a
zero-based index who's value is relative to the start of the
editor's text. If the index is out of range of the text then
the returned object is clipped to start or end of the text
respectively.doc.indexFromPos(object: {line, ch}) → integerposFromIndex.cm.focus()cm.getInputField() → TextAreaElementcm.getWrapperElement() → Elementcm.getScrollerElement() → Elementcm.getGutterElement() → ElementThe CodeMirror object itself provides
several useful properties.
CodeMirror.version: string"major.minor.patch",
where patch is zero for releases, and something
else (usually one) for dev snapshots.CodeMirror.fromTextArea(textArea: TextAreaElement, ?config: object)cm.save()cm.toTextArea()cm.getTextArea() → TextAreaElementCodeMirror.defaults: objectCodeMirror.defineExtension(name: string, value: any)defineExtension. This will cause the given
value (usually a method) to be added to all CodeMirror instances
created from then on.CodeMirror.defineDocExtension(name: string, value: any)defineExtension,
but the method will be added to the interface
for Doc objects instead.CodeMirror.defineOption(name: string,
default: any, updateFunc: function)defineOption can be used to define new options for
CodeMirror. The updateFunc will be called with the
editor instance and the new value when an editor is initialized,
and whenever the option is modified
through setOption.CodeMirror.defineInitHook(func: function)CodeMirror.defineInitHook. Give it a function as
its only argument, and from then on, that function will be called
(with the instance as argument) whenever a new CodeMirror instance
is initialized.CodeMirror.registerHelper(type: string, name: string, value: helper)name in
the given namespace (type). This is used to define
functionality that may be looked up by mode. Will create (if it
doesn't already exist) a property on the CodeMirror
object for the given type, pointing to an object
that maps names to values. I.e. after
doing CodeMirror.registerHelper("hint", "foo",
myFoo), the value CodeMirror.hint.foo will
point to myFoo.CodeMirror.Pos(line: integer, ?ch: integer){line, ch} objects that
are used to represent positions in editor documents.CodeMirror.changeEnd(change: object) → {line, ch}from, to,
and text properties, as passed to
various event handlers). The
returned position will be the end of the changed
range, after the change is applied.The addon directory in the distribution contains a
number of reusable components that implement extra editor
functionality. In brief, they are:
dialog/dialog.jsopenDialog method to CodeMirror instances,
which can be called with an HTML fragment that provides the
prompt (should include an input tag), and a
callback function that is called when text has been entered.
Depends on addon/dialog/dialog.css.search/searchcursor.jsgetSearchCursor(query, start, caseFold) →
cursor method to CodeMirror instances, which can be used
to implement search/replace functionality. query
can be a regular expression or a string (only strings will match
across lines—if they contain newlines). start
provides the starting position of the search. It can be
a {line, ch} object, or can be left off to default
to the start of the document. caseFold is only
relevant when matching a string. It will cause the search to be
case-insensitive. A search cursor has the following methods:
findNext() → booleanfindPrevious() → booleanmatch method, in case you
want to extract matched groups.from() → {line, ch}to() → {line, ch}findNext or findPrevious did
not return false. They will return {line, ch}
objects pointing at the start and end of the match.replace(text: string)search/search.jssearchcursor.js, and will make use
of openDialog when
available to make prompting for search queries less ugly.edit/matchbrackets.jsmatchBrackets which, when set
to true, causes matching brackets to be highlighted whenever the
cursor is next to them. It also adds a
method matchBrackets that forces this to happen
once, and a method findMatchingBracket that can be
used to run the bracket-finding algorithm that this uses
internally.edit/closebrackets.jsautoCloseBrackets that will
auto-close brackets and quotes when typed. By default, it'll
auto-close ()[]{}''"", but you can pass it a string
similar to that (containing pairs of matching characters), or an
object with pairs and
optionally explode properties to customize
it. explode should be a similar string that gives
the pairs of characters that, when enter is pressed between
them, should have the second character also moved to its own
line. Demo here.matchTags that, when enabled,
will cause the tags around the cursor to be highlighted (using
the CodeMirror-matchingbrackets class). Also
defines
a command toMatchingTag,
which you can bind a key to in order to jump to the tag mathing
the one under the cursor. Depends on
the addon/fold/xml-fold.js
addon. Demo here.edit/trailingspace.jsshowTrailingSpace which, when
enabled, adds the CSS class cm-trailingspace to
stretches of whitespace at the end of lines.
The demo has a nice
squiggly underline style for this class.comment/comment.jslineComment(from: {line, ch}, to: {line, ch}, ?options: object)blockComment when no line comment
style is defined for the mode.blockComment(from: {line, ch}, to: {line, ch}, ?options: object)lineComment when no block comment
style is defined for the mode.uncomment(from: {line, ch}, to: {line, ch}, ?options: object) → booleantrue if a comment range was found and
removed, false otherwise.options object accepted by these methods may
have the following properties:
blockCommentStart, blockCommentEnd, blockCommentLead, lineComment: stringpadding: stringcommentBlankLines: booleanindent: booleanfullLines: booleantrue.toggleComment command,
which will try to uncomment the current selection, and if that
fails, line-comments it.fold/foldcode.jsfoldCode method
to editor instances, which will try to do a code fold starting
at the given line, or unfold the fold that is already present.
The method takes as first argument the position that should be
folded (may be a line number or
a Pos), and as second optional
argument either a range-finder function, or an options object,
supporting the following properties:
rangeFinder: fn(CodeMirror, Pos)getHelper with
a "fold" type to find one that's appropriate for
the mode. There are files in
the addon/fold/
directory providing CodeMirror.fold.brace, which
finds blocks in brace languages (JavaScript, C, Java,
etc), CodeMirror.fold.indent, for languages where
indentation determines block structure (Python, Haskell),
and CodeMirror.fold.xml, for XML-style
languages.widget: string|ElementCodeMirror-foldmarker, or a DOM node.scanUp: booleanminFoldSize: integerfold/foldgutter.jsfoldGutter, which can be
used to create a gutter with markers indicating the blocks that
can be folded. Create a gutter using
the gutters option,
giving it the class CodeMirror-foldgutter or
something else if you configure the addon to use a different
class, and this addon will show markers next to folded and
foldable blocks, and handle clicks in this gutter. The option
can be either set to true, or an object containing
the following optional option fields:
gutter: string"CodeMirror-foldgutter". You will have to
style this yourself to give it a width (and possibly a
background).indicatorOpen: string | Element"CodeMirror-foldgutter-open".indicatorFolded: string | Element"CodeMirror-foldgutter-folded".rangeFinder: fn(CodeMirror, Pos)getHelper will be
used to determine a default.runmode/runmode.jsmode/overlay.jsCodeMirror.overlayMode, which is used to
create such a mode. See this
demo for a detailed example.mode/multiplex.jsCodeMirror.multiplexingMode which, when
given as first argument a mode object, and as other arguments
any number of {open, close, mode [, delimStyle, innerStyle]}
objects, will return a mode object that starts parsing using the
mode passed as first argument, but will switch to another mode
as soon as it encounters a string that occurs in one of
the open fields of the passed objects. When in a
sub-mode, it will go back to the top mode again when
the close string is encountered.
Pass "\n" for open or close
if you want to switch on a blank line.
delimStyle is specified, it will be the token
style returned for the delimiter tokens.innerStyle is specified, it will be the token
style added for each inner mode token.hint/show-hint.jsCodeMirror.showHint, which takes a
CodeMirror instance, a hinting function, and optionally an
options object, and pops up a widget that allows the user to
select a completion. Hinting functions are function that take an
editor instance and an optional options object, and return
a {list, from, to} object, where list
is an array of strings or objects (the completions),
and from and to give the start and end
of the token that is being completed as {line, ch}
objects. If no hinting function is given, the addon will try to
use getHelper with
the "hint" type to find one. When completions
aren't simple strings, they should be objects with the folowing
properties:
text: stringdisplayText: stringclassName: stringrender: fn(Element, self, data)hint: fn(CodeMirror, self, data)async: boolean(cm, callback, ?options), and the completion
interface will only be popped up when the hinting function
calls the callback, passing it the object holding the
completions.completeSingle: booleanalignWithWord: booleancloseOnUnfocus: booleancustomKeys: keymapmoveFocus(n), setFocus(n), pick(),
and close() methods (see the source for details),
that can be used to change the focused element, pick the
current element or close the menu.extraKeys: keymapcustomKeys above, but the bindings will
be added to the set of default bindings, instead of replacing
them."shown" ()"select" (completion, Element)"close" ()addon/hint/show-hint.css. Check
out the demo for an
example.hint/javascript-hint.jsCodeMirror.hint.javascript) and CoffeeScript
(CodeMirror.hint.coffeescript) code. This will
simply use the JavaScript environment that the editor runs in as
a source of information about objects and their properties.hint/xml-hint.jsCodeMirror.hint.xml, which produces
hints for XML tagnames, attribute names, and attribute values,
guided by a schemaInfo option (a property of the
second argument passed to the hinting function, or the third
argument passed to CodeMirror.showHint)."!top" property
containing a list of the names of valid top-level tags. The
values of the properties should be objects with optional
properties children (an array of valid child
element names, omit to simply allow all tags to appear)
and attrs (an object mapping attribute names
to null for free-form attributes, and an array of
valid values for restricted
attributes). Demo
here.hint/html-hint.jsCodeMirror.htmlSchema that you can pass to
as a schemaInfo option, and
a CodeMirror.hint.html hinting function that
automatically calls CodeMirror.hint.xml with this
schema data. See
the demo.hint/python-hint.jsCodeMirror.hint.python.hint/anyword-hint.jsCodeMirror.hint.anyword) that simply looks for
words in the nearby code and completes to those. Takes two
optional options, word, a regular expression that
matches words (sequences of one or more character),
and range, which defines how many lines the addon
should scan when completing (defaults to 500).match-highlighter.jshighlightSelectionMatches option that
can be enabled to highlight all instances of a currently
selected word. Can be set either to true or to an object
containing the following options: minChars, for the
minimum amount of selected characters that triggers a highlight
(default 2), style, for the style to be used to
highlight the matches (default "matchhighlight",
which will correspond to CSS
class cm-matchhighlight),
and showToken which can be set to true
or to a regexp matching the characters that make up a word. When
enabled, it causes the current word to be highlighted when
nothing is selected (defaults to off).
Demo here.lint/lint.jsjson-lint.js
and javascript-lint.js
in the same directory). Defines a lint option that
can be set to a warning source (for
example CodeMirror.lint.javascript), or
to true, in which
case getHelper with
type "lint" is used to determined a validator
function. Depends on addon/lint/lint.css. A demo
can be found here.selection/mark-selection.jsCodeMirror-selectedtext when the styleSelectedText option
is enabled. Useful to change the colour of the selection (in addition to the background),
like in this demo.selection/active-line.jsstyleActiveLine option that, when enabled,
gives the wrapper of the active line the class CodeMirror-activeline,
and adds a background with the class CodeMirror-activeline-background.
is enabled. See the demo.edit/closetag.jsmode/loadmode.jsCodeMirror.requireMode(modename,
callback) function that will try to load a given mode and
call the callback when it succeeded. You'll have to
set CodeMirror.modeURL to a string that mode paths
can be constructed from, for
example "mode/%N/%N.js"—the %N's will
be replaced with the mode name. Also
defines CodeMirror.autoLoadMode(instance, mode),
which will ensure the given mode is loaded and cause the given
editor instance to refresh its mode when the loading
succeeded. See the demo.edit/continuecomment.jscontinueComments option, which can be
set to true to have the editor prefix new lines inside C-like
block comments with an asterisk when Enter is pressed. It can
also be set to a string in order to bind this functionality to a
specific key..display/placeholder.jsplaceholder option that can be used to
make text appear in the editor when it is empty and not focused.
Also gives the editor a CodeMirror-empty CSS class
whenever it doesn't contain any text.
See the demo.merge/merge.jsCodeMirror.MergeView
constructor takes arguments similar to
the CodeMirror
constructor, first a node to append the interface to, and then
an options object. Two extra optional options are
recognized, origLeft and origRight,
which may be strings that provide original versions of the
document, which will be shown to the left and right of the
editor in non-editable CodeMirror instances. The merge interface
will highlight changes between the editable document and the
original(s) (demo).Modes typically consist of a single JavaScript file. This file defines, in the simplest case, a lexer (tokenizer) for your language—a function that takes a character stream as input, advances it past a token, and returns a style for that token. More advanced modes can also handle indentation for the language.
The mode script should
call CodeMirror.defineMode to register itself with
CodeMirror. This function takes two arguments. The first should be
the name of the mode, for which you should use a lowercase string,
preferably one that is also the name of the files that define the
mode (i.e. "xml" is defined in xml.js). The
second argument should be a function that, given a CodeMirror
configuration object (the thing passed to
the CodeMirror function) and an optional mode
configuration object (as in
the mode option), returns
a mode object.
Typically, you should use this second argument
to defineMode as your module scope function (modes
should not leak anything into the global scope!), i.e. write your
whole mode inside this function.
The main responsibility of a mode script is parsing the content of the editor. Depending on the language and the amount of functionality desired, this can be done in really easy or extremely complicated ways. Some parsers can be stateless, meaning that they look at one element (token) of the code at a time, with no memory of what came before. Most, however, will need to remember something. This is done by using a state object, which is an object that is always passed when reading a token, and which can be mutated by the tokenizer.
Modes that use a state must define
a startState method on their mode object. This is a
function of no arguments that produces a state object to be used
at the start of a document.
The most important part of a mode object is
its token(stream, state) method. All modes must
define this method. It should read one token from the stream it is
given as an argument, optionally update its state, and return a
style string, or null for tokens that do not have to
be styled. For your styles, you are encouraged to use the
'standard' names defined in the themes (without
the cm- prefix). If that fails, it is also possible
to come up with your own and write your own CSS theme file.
The stream object that's passed
to token encapsulates a line of code (tokens may
never span lines) and our current position in that line. It has
the following API:
eol() → booleansol() → booleanpeek() → stringnull at the end of the
line.next() → stringnull when no more characters are
available.eat(match: string|regexp|function(char: string) → boolean) → stringmatch can be a character, a regular expression,
or a function that takes a character and returns a boolean. If
the next character in the stream 'matches' the given argument,
it is consumed and returned. Otherwise, undefined
is returned.eatWhile(match: string|regexp|function(char: string) → boolean) → booleaneat with the given argument,
until it fails. Returns true if any characters were eaten.eatSpace() → booleaneatWhile when matching
white-space.skipToEnd()skipTo(ch: string) → booleanmatch(pattern: string, ?consume: boolean, ?caseFold: boolean) → booleanmatch(pattern: regexp, ?consume: boolean) → array<string>eat—if consume is true
or not given—or a look-ahead that doesn't update the stream
position—if it is false. pattern can be either a
string or a regular expression starting with ^.
When it is a string, caseFold can be set to true to
make the match case-insensitive. When successfully matching a
regular expression, the returned value will be the array
returned by match, in case you need to extract
matched groups.backUp(n: integer)n characters. Backing it up
further than the start of the current token will cause things to
break, so be careful.column() → integerindentation() → integercurrent() → stringBy default, blank lines are simply skipped when
tokenizing a document. For languages that have significant blank
lines, you can define a blankLine(state) method on
your mode that will get called whenever a blank line is passed
over, so that it can update the parser state.
Because state object are mutated, and CodeMirror
needs to keep valid versions of a state around so that it can
restart a parse at any line, copies must be made of state objects.
The default algorithm used is that a new state object is created,
which gets all the properties of the old object. Any properties
which hold arrays get a copy of these arrays (since arrays tend to
be used as mutable stacks). When this is not correct, for example
because a mode mutates non-array properties of its state object, a
mode object should define a copyState method,
which is given a state and should return a safe copy of that
state.
If you want your mode to provide smart indentation
(through the indentLine
method and the indentAuto
and newlineAndIndent commands, to which keys can be
bound), you must define
an indent(state, textAfter) method on your mode
object.
The indentation method should inspect the given state object,
and optionally the textAfter string, which contains
the text on the line that is being indented, and return an
integer, the amount of spaces to indent. It should usually take
the indentUnit
option into account. An indentation method may
return CodeMirror.Pass to indicate that it
could not come up with a precise indentation.
To work well with
the commenting addon, a mode may
define lineComment (string that starts a line
comment), blockCommentStart, blockCommentEnd
(strings that start and end block comments),
and blockCommentLead (a string to put at the start of
continued lines in a block comment). All of these are
optional.
Finally, a mode may define
an electricChars property, which should hold a string
containing all the characters that should trigger the behaviour
described for
the electricChars
option.
So, to summarize, a mode must provide
a token method, and it may
provide startState, copyState,
and indent methods. For an example of a trivial mode,
see the diff mode, for a more
involved example, see the C-like
mode.
Sometimes, it is useful for modes to nest—to have one
mode delegate work to another mode. An example of this kind of
mode is the mixed-mode HTML
mode. To implement such nesting, it is usually necessary to
create mode objects and copy states yourself. To create a mode
object, there are CodeMirror.getMode(options,
parserConfig), where the first argument is a configuration
object as passed to the mode constructor function, and the second
argument is a mode specification as in
the mode option. To copy a
state object, call CodeMirror.copyState(mode, state),
where mode is the mode that created the given
state.
In a nested mode, it is recommended to add an
extra methods, innerMode which, given a state object,
returns a {state, mode} object with the inner mode
and its state for the current position. These are used by utility
scripts such as the tag closer to
get context information. Use the CodeMirror.innerMode
helper function to, starting from a mode and a state, recursively
walk down to the innermost mode and state.
To make indentation work properly in a nested parser, it is
advisable to give the startState method of modes that
are intended to be nested an optional argument that provides the
base indentation for the block of code. The JavaScript and CSS
parser do this, for example, to allow JavaScript and CSS code
inside the mixed-mode HTML mode to be properly indented.
It is possible, and encouraged, to associate your mode, or a
certain configuration of your mode, with
a MIME type. For
example, the JavaScript mode associates itself
with text/javascript, and its JSON variant
with application/json. To do this,
call CodeMirror.defineMIME(mime, modeSpec),
where modeSpec can be a string or object specifying a
mode, as in the mode
option.
Sometimes, it is useful to add or override mode
object properties from external code.
The CodeMirror.extendMode can be used to add
properties to mode objects produced for a specific mode. Its first
argument is the name of the mode, its second an object that
specifies the properties that should be added. This is mostly
useful to add utilities that can later be looked
up through getMode.