/* User manual and reference guide */
CodeMirror is a code-editor component that can be embedded in Web pages. The code 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 add-ons included in the distribution, and the CodeMirror UI project, 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 few
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
and a theme stylesheet from theme/
. (See
also the compression helper.) 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 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)
mode (string or 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 are loaded with
the CodeMirror.listModes
and CodeMirror.listMIMEs
functions.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)
autoClearEmptyLines (boolean)
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)
gutter (boolean)
fixedGutter (boolean)
readOnly (boolean)
"nocursor"
is given (instead of
simply true
), focusing of the editor is also
disallowed.onChange (function)
{from, to, text, 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 line #19, at the first character. text
is an
array of strings representing the text that replaced the changed range
(split by line). 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).onCursorActivity (function)
onGutterClick (function)
mousedown
event object as third argument.onFocus, onBlur (function)
onScroll (function)
onHighlightComplete (function)
onUpdate (function)
matchBrackets (boolean)
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.pollInterval (number)
undoDepth (integer)
tabindex (integer)
document (DOM document)
document
object.onKeyEvent (function)
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).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 in 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.
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), or strings. 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. A key handler function may throw
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.
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 catchall
property, the
handler function under that property will be called for all keys
dispatched through the keymap.
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. Giving
this height: auto; overflow: visible;
will cause
the editor to resize to fit its content.CodeMirror-focused
CodeMirror-gutter
CodeMirror-gutter-text
for that. By default,
the gutter is 'fluid', meaning it will adjust its width to the
maximum line number or line marker width. You can also set a
fixed width if you want.CodeMirror-gutter-text
CodeMirror
class.CodeMirror-lines
CodeMirror-gutter
should have the same
padding.CodeMirror-cursor
CodeMirror-selected
span
elements
with this class.CodeMirror-matchingbracket
,
CodeMirror-nonmatchingbracket
The actual lines, as well as the cursor, are represented
by pre
elements. By default no text styling (such as
bold) that might change line height is applied. If you do want
such effects, you'll have to give CodeMirror pre
a
fixed height. Also, you must still take care that character width
is constant.
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. This has the disadvantage that you need to do work to enable them, and the advantage that CodeMirror will fit seamlessly into your application.
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.
getValue() → string
setValue(string)
getSelection() → string
replaceSelection(string)
focus()
scrollTo(x, y)
null
or undefined
to have no effect.setOption(option, value)
option
should the name of an option,
and value
should be a valid value for that
option.getOption(option) → value
cursorCoords(start) → object
{x, y, yBot}
object containing the
coordinates of the cursor relative to the top-left corner of the
page. yBot
is the coordinate of the bottom of the
cursor. start
is a boolean indicating whether you
want the start or the end of the selection.charCoords(pos) → object
cursorCoords
, but returns the position of
an arbitrary characters. pos
should be
a {line, ch}
object.coordsChar(object) → pos
{x, y}
object (in page coordinates),
returns the {line, ch}
position that corresponds to
it.undo()
redo()
historySize() → object
{undo, redo}
properties,
both of which hold integers, indicating the amount of stored
undo and redo operations.clearHistory()
indentLine(line, dir)
dir
is true) or
decreased (if false) by an indent
unit instead.getTokenAt(pos) → object
{line, ch}
object). The
returned object has the following properties:
start
end
string
className
state
markText(from, to, className) → object
from
and to
should
be {line, ch}
objects. The method will return an
object with two methods, clear()
, which removes the
mark, and find()
, which returns a {from,
to}
(both document positions), indicating the current
position of the marked range.setBookmark(pos) → object
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.setMarker(line, text, className) → lineHandle
text
and className
are
optional. Setting text
to a Unicode character like
● tends to give a nice effect. To put a picture in the gutter,
set text
to a space and className
to
something that sets a background image. If you
specify text
, the given text (which may contain
HTML) will, by default, replace the line number for that line.
If this is not what you want, you can include the
string %N%
in the text, which will be replaced by
the line number.clearMarker(line)
setMarker
. line
can be either a
number or a handle returned by setMarker
(since a
number may now refer to a different line if something was added
or deleted).setLineClass(line, className) → lineHandle
line
can be a number or a line handle (as returned
by setMarker
or this function).
Pass null
to clear the class for a line.hideLine(line) → lineHandle
showLine(line) → lineHandle
hideLine
—re-shows a previously
hidden line, by number or by handle.onDeleteLine(line, func)
lineInfo(line) → object
setMarker
. The returned object has the
structure {line, handle, text, markerText, markerClass}
.getLineHandle(num) → lineHandle
addWidget(pos, node, scrollIntoView)
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).matchBrackets()
lineCount() → number
getCursor(start) → object
start
is a boolean indicating whether the start
or the end of the selection must be retrieved. If it is not
given, the current cursor pos, i.e. the side of the selection
that would move if you pressed an arrow key, is chosen.
A {line, ch}
object will be returned.somethingSelected() → boolean
setCursor(pos)
{line, ch}
object, or the line and the
character as two separate parameters.setSelection(start, end)
start
and end
should be {line, ch}
objects.getLine(n) → string
n
.setLine(n, text)
n
.removeLine(n)
getRange(from, to) → string
{line, ch}
objects.replaceRange(string, from, to)
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
.posFromIndex(index) → object
{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.indexFromPos(object) → number
posFromIndex
.The following are more low-level methods:
operation(func) → result
refresh()
getInputField() → textarea
getWrapperElement() → node
getScrollerElement() → node
height
and width
styles of this
element to resize an editor. (You might have to call
the refresh
method
afterwards.)getGutterElement() → node
getStateAfter(line) → state
Finally, the CodeMirror
object
itself has a method fromTextArea
. This takes a
textarea DOM node as first argument and an optional configuration
object as second. It will replace the textarea with a CodeMirror
instance, and wire up the form of that textarea (if any) to make
sure the editor contents are put into the textarea when the form
is submitted. A CodeMirror instance created this way has two
additional methods:
save()
toTextArea()
getTextArea() → textarea
If you want to define extra methods in terms
of the CodeMirror API, it is possible to
use CodeMirror.defineExtension(name, value)
. This
will cause the given value (usually a method) to be added to all
CodeMirror instances created from then on.
The lib/util
directory in the distribution
contains a number of reusable components that implement extra
editor functionality. In brief, they are:
dialog.js
openDialog
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 lib/util/dialog.css
.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(), findPrevious() → boolean
match
method, in case you
want to extract matched groups.from(), to() → object
findNext
or findPrevious
did
not return false. They will return {line, ch}
objects pointing at the start and end of the match.replace(text)
search.js
searchcursor.js
, and will make use
of openDialog
when
available to make prompting for search queries less ugly.foldcode.js
CodeMirror.newFoldFunction
with a range-finder
helper function to create a function that will, when applied to
a CodeMirror instance and a line number, attempt to fold or
unfold the block starting at the given line. A range-finder is a
language-specific function that also takes an instance and a
line number, and returns an end line for the block, or null if
no block is started on that line. This file
provides CodeMirror.braceRangeFinder
, which finds
blocks in brace languages (JavaScript, C, Java,
etc), CodeMirror.indentRangeFinder
, for languages
where indentation determines block structure (Python, Haskell),
and CodeMirror.tagRangeFinder
, for XML-style
languages.runmode.js
simple-hint.js
CodeMirror.simpleHint
, which takes a
CodeMirror instance and a hinting function, and pops up a widget
that allows the user to select a completion. Hinting functions
are function that take an editor instance, and return
a {list, from, to}
object, where list
is an array of strings (the completions), and from
and to
give the start and end of the token that is
being completed. Depends
on lib/util/simple-hint.css
.javascript-hint.js
CodeMirror.javascriptHint
and CodeMirror.coffeescriptHint
, which are simple
hinting functions for the JavaScript and CoffeeScript
modes.match-highlighter.js
matchHighlight
method to CodeMirror
instances that can be called (typically from
a onCursorActivity
handler) to highlight all instances of a currently selected word
with the a classname given as a first argument to the method.
Depends on
the searchcursor
add-on. Demo here.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 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 can either use the 'standard' ones
defined in the themes (without the cm-
prefix), or
define your own (as the diff
mode does) and have people include a custom CSS file for your
mode.
The stream object 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() → character
undefined
at the end of the
line.next() → character
undefined
when no more characters are
available.eat(match) → character
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) → 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) → boolean
match(pattern, consume, caseFold) → boolean
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)
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.
By default, CodeMirror will stop re-parsing
a document as soon as it encounters a few lines that were
highlighted the same in the old parse as in the new one. It is
possible to provide an explicit way to test whether a state is
equivalent to another one, which CodeMirror will use (instead of
the unchanged-lines heuristic) to decide when to stop
highlighting. You do this by providing
a compareStates
method on your mode object, which
takes two state arguments and returns a boolean indicating whether
they are equivalent. See the XML mode, which uses this to provide
reliable highlighting of bad closing tags, as an example.
If you want your mode to provide smart indentation
(though the indentLine
method and the indentAuto
and newlineAndIndent
commands, which keys can be
bound to), 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.
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
,
compareStates
, 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.
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.
Finally, it is possible 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.