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.
Configuration
Both the
CodeMirror
function and itsfromTextArea
method take as second (optional) argument an object containing configuration options. Any option not supplied like this will be taken fromCodeMirror.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.Doc
mode: string|object
name
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: integer
smartIndent: boolean
tabSize: integer
indentWithTabs: boolean
tabSize
spaces should be replaced by N tabs. Default is false.electricChars: boolean
specialChars: RegExp
/[\u0000-\u0019\u00ad\u200b\u2028\u2029\ufeff]/
.specialCharPlaceholder: function(char) → Element
specialChars
option, produces a DOM node that is used to represent the
character. By default, a red dot (•)
is shown, with a title tooltip to indicate the character code.rtlMoveVisually: boolean
false
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: object
keyMap
. Should be
either null, or a valid keymap value.lineWrapping: boolean
false
(scroll).lineNumbers: boolean
firstLineNumber: integer
lineNumberFormatter: function(line: integer) → string
gutters: 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: boolean
coverGutterNextToScrollbar: boolean
fixedGutter
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: boolean
undoDepth: integer
historyEventDelay: integer
tabindex: integer
autofocus: boolean
fromTextArea
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: boolean
onDragEvent: function(instance: CodeMirror, event: Event) → boolean
dragenter
, 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) → boolean
keydown
, 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: number
cursorScrollMargin: number
cursorHeight: number
0.85
),
which causes the cursor to not reach all the way to the bottom
of the line, looks betterresetSelectionOnContextMenu: boolean
true
.workTime, workDelay: number
workTime
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: number
workTime
.pollInterval: number
flattenSpans: boolean
addModeClass: boolean
"cm-m-"
. For example, tokens from the XML mode
will get the cm-m-xml
class.maxHighlightLength: number
Infinity
to turn off
this behavior.crudeMeasuringFrom: number
viewportMargin: integer
Infinity
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 registered 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."swapDoc" (instance: CodeMirror, oldDoc: Doc)
swapDoc
method."gutterClick" (instance: CodeMirror, line: integer, gutter: string, clickEvent: Event)
mousedown
event object as
fourth argument."gutterContextMenu" (instance: CodeMirror, line: integer, gutter: string, contextMenu: Event: Event)
contextmenu
event. Will pass the editor
instance as first argument, the (zero-based) number of the line
that was clicked as second argument, the CSS class of the
gutter that was clicked as third argument, and the raw
contextmenu
mouse event object as fourth argument.
You can preventDefault
the event, to signal that
CodeMirror should do no further handling."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
=======
Commands are parameter-less actions that can be performed on an
editor. Their main use is for key bindings. Commands are defined by
adding properties to the CodeMirror.commands
object.
A number of common commands are defined by the library itself,
most of them used by the default key bindings. The value of a
command property must be a function of one argument (an editor
instance).
Some of the commands below are referenced in the default key map, but not defined by the core library. These are intended to be defined by user code or addons.
Commands can also be run with
the execCommand
method.
selectAll
Ctrl-A (PC), Cmd-A (Mac)singleSelection
EsckillLine
Ctrl-K (Mac)deleteLine
Ctrl-D (PC), Cmd-D (Mac)delLineLeft
Cmd-Backspace (Mac)undo
Ctrl-Z (PC), Cmd-Z (Mac)redo
Ctrl-Y (PC), Shift-Cmd-Z (Mac), Cmd-Y (Mac)undoSelection
Ctrl-U (PC), Cmd-U (Mac)redoSelection
Alt-U (PC), Shift-Cmd-U (Mac)goDocStart
Ctrl-Up (PC), Cmd-Up (Mac)goDocEnd
Ctrl-Down (PC), Cmd-End (Mac), Cmd-Down (Mac)goLineStart
Alt-Left (PC), Cmd-Left (Mac), Ctrl-A (Mac)goLineStartSmart
HomegoLineEnd
Alt-Right (PC), Cmd-Right (Mac), Ctrl-E (Mac)goLineLeft
goLineRight
goLineUp
Up, Ctrl-P (Mac)goLineDown
Down, Ctrl-N (Mac)goPageUp
PageUp, Shift-Ctrl-V (Mac)goPageDown
PageDown, Ctrl-V (Mac)goCharLeft
Left, Ctrl-B (Mac)goCharRight
Right, Ctrl-F (Mac)goColumnLeft
goColumnRight
goWordLeft
Alt-B (Mac)goWordRight
Alt-F (Mac)goGroupLeft
Ctrl-Left (PC), Alt-Left (Mac)goGroupRight
Ctrl-Right (PC), Alt-Right (Mac)delCharBefore
Shift-Backspace, Ctrl-H (Mac)delCharAfter
Delete, Ctrl-D (Mac)delWordBefore
Alt-Backspace (Mac)delWordAfter
Alt-D (Mac)delGroupBefore
Ctrl-Backspace (PC), Alt-Backspace (Mac)delGroupAfter
Ctrl-Delete (PC), Ctrl-Alt-Backspace (Mac), Alt-Delete (Mac)indentAuto
Shift-TabindentMore
Ctrl-] (PC), Cmd-] (Mac)indentLess
Ctrl-[ (PC), Cmd-[ (Mac)insertTab
insertSoftTab
defaultTab
TabtransposeChars
Ctrl-T (Mac)newlineAndIndent
EntertoggleOverwrite
Insertsave
Ctrl-S (PC), Cmd-S (Mac)find
Ctrl-F (PC), Cmd-F (Mac)findNext
Ctrl-G (PC), Cmd-G (Mac)findPrev
Shift-Ctrl-G (PC), Shift-Cmd-G (Mac)replace
Shift-Ctrl-F (PC), Cmd-Alt-F (Mac)replaceAll
Shift-Ctrl-R (PC), Shift-Cmd-Alt-F (Mac)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:
CodeMirror
CodeMirror-scroll
overflow: 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-focused
CodeMirror-gutters
CodeMirror-linenumbers
CodeMirror-linenumber
CodeMirror-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-lines
CodeMirror-cursor
CodeMirror-selected
span
elements
with this class.CodeMirror-matchingbracket
,
CodeMirror-nonmatchingbracket
If 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) → string
n
.doc.setLine(n: integer, text: string)
n
.doc.removeLine(n: integer)
doc.lineCount() → integer
doc.firstLine() → integer
doc.lastLine() → integer
doc.lineCount() - 1
,
but for linked sub-views,
it might return other values.doc.getLineHandle(num: integer) → LineHandle
doc.getLineNumber(handle: LineHandle) → integer
null
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(?closeEvent: boolean) → integer
isClean
to test whether
any edits were made (and not undone) in the meantime.
If closeEvent
is true, the current history event
will be ‘closed’, meaning it can't be combined with further
changes (rapid typing or deleting events are typically
combined).doc.isClean(?generation: integer) → boolean
markClean
if no
argument is passed, or since the matching call
to changeGeneration
if a generation value is given.doc.getSelection() → string
doc.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() → boolean
doc.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. to
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.doc.getExtending() → boolean
cm.hasFocus() → boolean
cm.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) → any
cm.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() → Doc
doc.getEditor() → CodeMirror
null
.cm.swapDoc(doc: CodeMirror.Doc) → Doc
doc.copy(copyHistory: boolean) → Doc
copyHistory
is true, the history will also be
copied. Can not be called directly on an editor.doc.linkedDoc(options: object) → Doc
sharedHist: boolean
from: integer
to: integer
mode: string|object
doc.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() → object
doc.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) → TextMarker
from
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: string
inclusiveLeft: boolean
inclusiveRight: boolean
inclusiveLeft
,
but for the right side.atomic: boolean
inclusiveLeft
and inclusiveRight
have a different meaning—they
will prevent the cursor from being placed respectively
directly before and directly after the range.collapsed: boolean
clearOnEnter: boolean
"clear"
event
fired on the range handle can be used to be notified when this
happens.clearWhenEmpty: boolean
replacedWith: Element
handleMouseEvents: boolean
replacedWith
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: boolean
setValue
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: boolean
startStyle: string
endStyle: string
startStyle
, but for the rightmost span.title:
string
title
attribute with the
given value.shared: boolean
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) → TextMarker
find()
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: Element
replacedWith
option to markText
).insertLeft: boolean
doc.findMarks(from: {line, ch}, to: {line, ch}) → array<TextMarker>
doc.findMarksAt(pos: {line, ch}) → array<TextMarker>
doc.getAllMarks() → array<TextMarker>
cm.setGutterMarker(line: integer|LineHandle, gutterID: string, value: Element) → LineHandle
gutters
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) → LineHandle
line
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) → LineHandle
line
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) → LineWidget
line
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: boolean
noHScroll: boolean
above: boolean
showIfHidden: boolean
handleMouseEvents: boolean
insertAt: integer
line
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
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(what: {line, ch}|{left, top, right, bottom}|{from, to}|null, ?margin: number)
what
may
be null
to scroll the cursor into view,
a {line, ch}
position to scroll a character into
view, a {left, top, right, bottom}
pixel range (in
editor-local coordinates), or a range {from, to}
containing either two character positions or two pixel squares.
The margin
parameter is optional. When given, it
indicates the amount of vertical 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) → number
mode
can be one of the same strings
that coordsChar
accepts.cm.heightAtLine(line: number, ?mode: string) → number
mode
(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() → number
cm.defaultCharWidth() → number
cm.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() → object
getOption("mode")
, which gives you
the mode specification, rather than the resolved, instantiated
mode object.doc.getModeAt(pos: {line, ch}) → object
getMode
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:
start
end
string
type
"keyword"
or "comment"
(may also be null).state
precise
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}) → string
getTokenAt
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.getHelpers(pos: {line, ch}, type: string) → array<helper>
type
argument provides
the helper namespace (see
registerHelper
), in
which the values will be looked up. When the mode itself has a
property that corresponds to the type
, that
directly determines the keys that are used to look up the helper
values (it may be either a single string, or an array of
strings). Failing that, the mode's helperType
property and finally the mode's name are used.fold
containing "brace"
. When
the brace-fold
addon is loaded, that defines a
helper named brace
in the fold
namespace. This is then used by
the foldcode
addon to
figure out that it can use that folding function to fold
JavaScript code.cm.getHelper(pos: {line, ch}, type: string) → helper
getHelpers
.cm.getStateAfter(?line: integer, ?precise: boolean) → object
precise
is defined
as in getTokenAt()
.cm.operation(func: () → any) → any
cm.indentLine(line: integer, ?dir: string|integer)
"smart"
) may be one of:
"prev"
"smart"
"prev"
otherwise."add"
"subtract"
<integer>
cm.toggleOverwrite(?value: bool)
cm.execCommand(name: string)
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}) → integer
posFromIndex
.cm.focus()
cm.getInputField() → TextAreaElement
cm.getWrapperElement() → Element
cm.getScrollerElement() → Element
cm.getGutterElement() → Element
The 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() → TextAreaElement
CodeMirror.defaults: object
CodeMirror.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.registerGlobalHelper(type: string, name: string, predicate: fn(mode, CodeMirror), value: helper)
registerHelper
,
but also registers this helper as 'global', meaning that it will
be included by getHelpers
whenever the given predicate
returns true when
called with the local mode and editor.
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 (on top of extension functions
like defineOption
, defineExtension
,
and registerHelper
). In
brief, they are:
dialog/dialog.js
openDialog
method to
CodeMirror instances, which can be called with an HTML fragment
or a detached DOM node that provides the prompt (should include
an input
tag), and a callback function that is called
when text has been entered. Also adds
an openNotification
function that
simply shows an HTML fragment as a notification. Depends
on addon/dialog/dialog.css
.search/searchcursor.js
getSearchCursor(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() → boolean
findPrevious() → boolean
match
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.js
searchcursor.js
, and will make use
of openDialog
when
available to make prompting for search queries less ugly.edit/matchbrackets.js
matchBrackets
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.js
autoCloseBrackets
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.edit/matchtags.js
matchTags
that, when enabled,
will cause the tags around the cursor to be highlighted (using
the CodeMirror-matchingtag
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.js
showTrailingSpace
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.edit/closetag.js
edit/continuelist.js
"newlineAndIndentContinueMarkdownList"
command
command that can be bound to enter
to automatically
insert the leading characters for continuing a list. See
the Markdown mode
demo.comment/comment.js
lineComment(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) → boolean
true
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: string
padding: string
commentBlankLines: boolean
indent: boolean
fullLines: boolean
true
.toggleComment
command,
which will try to uncomment the current selection, and if that
fails, line-comments it.
fold/foldcode.js
foldCode
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)
CodeMirror.fold.auto
, which
uses getHelpers
with
a "fold"
type to find folding functions
appropriate for the local 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,
and CodeMirror.fold.comment
, for folding comment
blocks.widget: string|Element
CodeMirror-foldmarker
, or a DOM node.scanUp: boolean
minFoldSize: integer
fold/foldgutter.js
foldGutter
, 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. Note that
CSS styles should be applied to make the gutter, and the fold
markers within it, visible. A default set of CSS styles are
available in:
addon/fold/foldgutter.css
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). See the default gutter style rules above.indicatorOpen: string | Element
"CodeMirror-foldgutter-open"
.indicatorFolded: string | Element
"CodeMirror-foldgutter-folded"
.rangeFinder: fn(CodeMirror, Pos)
CodeMirror.fold.auto
will be used as default.runmode/runmode.js
runmode/colorize.js
runmode
addon (or
its standalone variant). Provides
a CodeMirror.colorize
function that can be called
with an array (or other array-ish collection) of DOM nodes that
represent the code snippets. By default, it'll get
all pre
tags. Will read the data-lang
attribute of these nodes to figure out their language, and
syntax-color their content using the relevant CodeMirror mode
(you'll have to load the scripts for the relevant modes
yourself). A second argument may be provided to give a default
mode, used when no language attribute is found for a node. Used
in this manual to highlight example code.mode/overlay.js
CodeMirror.overlayMode
, which is used to
create such a mode. See this
demo for a detailed example.mode/multiplex.js
CodeMirror.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.js
CodeMirror.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.CodeMirror.hint.auto
, with
calls getHelpers
with
the "hint"
type to find applicable hinting
functions, and tries them one by one. If that fails, it looks
for a "hintWords"
helper to fetch a list of
completable words for the mode, and
uses CodeMirror.hint.fromList
to complete from
those.text: string
displayText: string
className: string
render: fn(Element, self, data)
hint: fn(CodeMirror, self, data)
from: {line, ch}
from
position that will be used by pick()
instead
of the global one passed with the full list of completions.to: {line, ch}
to
position that will be used by pick()
instead
of the global one passed with the full list of completions.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: boolean
alignWithWord: boolean
closeOnUnfocus: boolean
customKeys: keymap
moveFocus(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. Additionnaly menuSize()
can give you access to the size of the current dropdown menu,
length
give you the number of availlable completions, and
data
give you full access to the completion returned by the
hinting function.extraKeys: keymap
customKeys
above, but the bindings will
be added to the set of default bindings, instead of replacing
them."shown" ()
"select" (completion, Element)
"pick" (completion)
"close" ()
addon/hint/show-hint.css
. Check
out the demo for an
example.
hint/javascript-hint.js
CodeMirror.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.js
CodeMirror.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.js
CodeMirror.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/css-hint.js
CodeMirror.hint.css
.hint/python-hint.js
CodeMirror.hint.python
.hint/anyword-hint.js
CodeMirror.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).hint/sql-hint.js
CodeMirror.hint.sql
.search/match-highlighter.js
highlightSelectionMatches
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.js
json-lint.js
,
javascript-lint.js
,
and css-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.js
CodeMirror-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.js
styleActiveLine
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.mode/loadmode.js
CodeMirror.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.comment/continuecomment.js
continueComments
option, which sets whether the
editor will make the next line continue a comment when you press Enter
inside a comment block. Can be set to a boolean to enable/disable this
functionality. Set to a string, it will continue comments using a custom
shortcut. Set to an object, it will use the key
property for
a custom shortcut and the boolean continueLineComment
property to determine whether single-line comments should be continued
(defaulting to true
).display/placeholder.js
placeholder
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.display/fullscreen.js
fullScreen
that, when set
to true
, will make the editor full-screen (as in,
taking up the whole browser window). Depends
on fullscreen.css
. Demo
here.display/rulers.js
rulers
option, which can be used to show
one or more vertical rulers in the editor. The option, if
defined, should be given an array of {column,
className}
objects or numbers. The ruler will be
displayed at the column indicated by the number or
the column
property. The className
property can be used to assign a custom style to a
ruler. Demo here.wrap/hardwrap.js
wrapParagraph(?pos: {line, ch}, ?options: object)
pos
is not given, it defaults to the cursor
position.wrapRange(from: {line, ch}, to: {line, ch}, ?options: object)
wrapParagraphsInRange(from: {line, ch}, to: {line, ch}, ?options: object)
paragraphStart, paragraphEnd: RegExp
column: number
wrapOn: RegExp
killTrailingSpace: boolean
merge/merge.js
CodeMirror.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).tern/tern.js
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.
A typical token string would
be "variable"
or "comment"
. Multiple
styles can be returned (separated by spaces), for
example "string error"
for a thing that looks like a
string but is invalid somehow (say, missing its closing quote).
When a style is prefixed by "line-"
or "line-background-"
, the style will be applied to
the whole line, analogous to what
the addLineClass
method
does—styling the "text"
in the simple case, and
the "background"
element
when "line-background-"
is prefixed.
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() → boolean
sol() → boolean
peek() → string
null
at the end of the
line.next() → string
null
when no more characters are
available.eat(match: string|regexp|function(char: string) → boolean) → string
match
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) → boolean
eat
with the given argument,
until it fails. Returns true if any characters were eaten.eatSpace() → boolean
eatWhile
when matching
white-space.skipToEnd()
skipTo(ch: string) → boolean
match(pattern: string, ?consume: boolean, ?caseFold: boolean) → boolean
match(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() → integer
indentation() → integer
current() → string
By 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 method, 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.
If a mode specification wants to add some properties to the
resulting mode object, typically for use
with getHelpers
, it may
contain a modeProps
property, which holds an object.
This object's properties will be copied to the actual mode
object.
Sometimes, it is useful to add or override mode
object properties from external code.
The CodeMirror.extendMode
function
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