RubyGems - erp_app - Versions diffs - 3.0.7 → 3.0.8 - Mend

erp_app 3.0.7 → 3.0.8

Files changed (537) hide show

data/public/javascripts/erp_app/codemirror/{manual.html → doc/manual.html} RENAMED Viewed

@@ -3,7 +3,7 @@
   <head>
     <title>CodeMirror: User Manual</title>
     <link rel="stylesheet" type="text/css" href="http://fonts.googleapis.com/css?family=Droid+Sans|Droid+Sans:bold"/>
-    <link rel="stylesheet" type="text/css" href="css/docs.css"/>
+    <link rel="stylesheet" type="text/css" href="docs.css"/>
     <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
     <style>dl dl {margin: 0;}</style>
   </head>
@@ -12,7 +12,7 @@
 <h1><span class="logo-braces">{ }</span> <a href="http://codemirror.net/">CodeMirror</a></h1>
 <pre class="grey">
-<img src="css/baboon.png" class="logo" alt="logo"/>/* User manual and
+<img src="baboon.png" class="logo" alt="logo"/>/* User manual and
    reference guide */
 </pre>
@@ -21,17 +21,19 @@
     <h2 id="overview">Overview</h2>
     <p>CodeMirror is a code-editor component that can be embedded in
-    Web pages. It provides <em>only</em> the editor component, no
-    accompanying buttons
-    (see <a href="http://www.octolabs.com/javascripts/codemirror-ui/">CodeMirror
-    UI</a> for a drop-in button bar), auto-completion, or other IDE
+    Web pages. The code library provides <em>only</em> 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.</p>
+    functionality can be straightforwardly implemented. See
+    the <a href="#addons">add-ons</a> included in the distribution,
+    and
+    the <a href="https://github.com/jagthedrummer/codemirror-ui">CodeMirror
+    UI</a> project, for reusable implementations of extra features.</p>
     <p>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 <code>mode/</code> directory), and it isn't hard
+    written in a given language. The distribution comes with a number
+    of modes (see the <code>mode/</code> directory), and it isn't hard
     to <a href="#modeapi">write new ones</a> for other languages.</p>
     <h2 id="usage">Basic Usage</h2>
@@ -40,18 +42,15 @@
     and style sheet found under <code>lib/</code> in the distribution,
     plus a mode script from one of the <code>mode/</code> directories
     and a theme stylesheet from <code>theme/</code>. (See
-    also <a href="compress.html">the compresion helper</a>.) For
+    also <a href="compress.html">the compression helper</a>.) For
     example:</p>
     <pre>&lt;script src="lib/codemirror.js">&lt;/script>
-&lt;link rel="stylesheet" href="lib/codemirror.css">
-&lt;script src="mode/javascript/javascript.js">&lt;/script>
-&lt;link rel="stylesheet" href="theme/default.css"></pre>
+&lt;link rel="stylesheet" href="../lib/codemirror.css">
+&lt;script src="mode/javascript/javascript.js">&lt;/script></pre>
-    <p>(If you use a them other than <code>default.css</code>, you
-    also have to specify the
-    <a href="#option_theme"><code>theme</code></a> option.) Having
-    done this, an editor instance can be created like this:</p>
+    <p>Having done this, an editor instance can be created like
+    this:</p>
     <pre>var myCodeMirror = CodeMirror(document.body);</pre>
@@ -106,12 +105,6 @@
     <p>Options are not checked in any way, so setting bogus option
     values is bound to lead to odd errors.</p>
-    <p><em>Note:</em> CodeMirror
-    2 <a href="internals.html#summary">does not support</a>
-    line-wrapping. I would have very much liked to support it, but it
-    combines extremely poorly with the way the editor is
-    implemented.</p>
     <p>These are the supported options:</p>
     <dl>
@@ -137,52 +130,29 @@
       <dd>The theme to style the editor with. You must make sure the
       CSS file defining the corresponding <code>.cm-s-[name]</code>
       styles is loaded (see
-      the <a href="theme/"><code>theme</code></a> directory in the
-      distribution).</dd>
+      the <a href="../theme/"><code>theme</code></a> directory in the
+      distribution). The default is <code>"default"</code>, for which
+      colors are included in <code>codemirror.css</code>. It is
+      possible to use multiple theming classes at once—for
+      example <code>"foo bar"</code> will assign both
+      the <code>cm-s-foo</code> and the <code>cm-s-bar</code> classes
+      to the editor.</dd>
       <dt id="option_indentUnit"><code>indentUnit (integer)</code></dt>
       <dd>How many spaces a block (whatever that means in the edited
       language) should be indented. The default is 2.</dd>
-      <dt id="option_indentWithTabs"><code>indentWithTabs (boolean)</code></dt>
-      <dd>Whether, when indenting, the first N*8 spaces should be
-      replaced by N tabs. Default is false.</dd>
+      <dt id="option_smartIndent"><code>smartIndent (boolean)</code></dt>
+      <dd>Whether to use the context-sensitive indentation that the
+      mode provides (or just indent the same as the line before).
+      Defaults to true.</dd>
-      <dt id="option_tabMode"><code>tabMode (string)</code></dt>
-      <dd>Determines what happens when the user presses the tab key.
-      Must be one of the following:
-        <dl>
-          <dt><code>"classic" (the default)</code></dt>
-          <dd>When nothing is selected, insert a tab. Otherwise,
-          behave like the <code>"shift"</code> mode. (When shift is
-          held, this behaves like the <code>"indent"</code> mode.)</dd>
-          <dt><code>"shift"</code></dt>
-          <dd>Indent all selected lines by
-          one <a href="#option_indentUnit"><code>indentUnit</code></a>.
-          If shift was held while pressing tab, un-indent all selected
-          lines one unit.</dd>
-          <dt><code>"indent"</code></dt>
-          <dd>Indent the line the 'correctly', based on its syntactic
-          context. Only works if the
-          mode <a href="#indent">supports</a> it.</dd>
-          <dt><code>"default"</code></dt>
-          <dd>Do not capture tab presses, let the browser apply its
-          default behaviour (which usually means it skips to the next
-          control).</dd>
-        </dl></dd>
+      <dt id="option_tabSize"><code>tabSize (integer)</code></dt>
+      <dd>The width of a tab character. Defaults to 4.</dd>
-      <dt id="option_enterMode"><code>enterMode (string)</code></dt>
-      <dd>Determines whether and how new lines are indented when the
-      enter key is pressed. The following modes are supported:
-        <dl>
-          <dt><code>"indent" (the default)</code></dt>
-          <dd>Use the mode's indentation rules to give the new line
-          the correct indentation.</dd>
-          <dt><code>"keep"</code></dt>
-          <dd>Indent the line the same as the previous line.</dd>
-          <dt><code>"flat"</code></dt>
-          <dd>Do not indent the new line.</dd>
-        </dl></dd>
+      <dt id="option_indentWithTabs"><code>indentWithTabs (boolean)</code></dt>
+      <dd>Whether, when indenting, the first N*<code>tabSize</code>
+      spaces should be replaced by N tabs. Default is false.</dd>
       <dt id="option_electricChars"><code>electricChars (boolean)</code></dt>
       <dd>Configures whether the editor should re-indent the current
@@ -190,10 +160,29 @@
       indentation (only works if the mode supports indentation).
       Default is true.</dd>
-      <dt id="option_smartHome"><code>smartHome (boolean)</code></dt>
-      <dd>Configures whether the home key takes you to the first
-      non-whitespace character (unless already there) or to the start
-      of the line. On by default.</dd>
+      <dt id="option_autoClearEmptyLines"><code>autoClearEmptyLines (boolean)</code></dt>
+      <dd>When turned on (default is off), this will clear
+      automatically clear lines consisting only of whitespace when the
+      cursor leaves them. This is mostly useful to prevent auto
+      indentation from introducing trailing whitespace in a file.</dd>
+      <dt id="option_keyMap"><code>keyMap (string)</code></dt>
+      <dd>Configures the keymap to use. The default
+      is <code>"default"</code>, which is the only keymap defined
+      in <code>codemirror.js</code> itself. Extra keymaps are found in
+      the <a href="../keymap/"><code>keymap</code></a> directory. See
+      the <a href="#keymaps">section on keymaps</a> for more
+      information.</dd>
+      <dt id="option_extraKeys"><code>extraKeys (object)</code></dt>
+      <dd>Can be used to specify extra keybindings for the editor,
+      alongside the ones defined
+      by <a href="#option_keyMap"><code>keyMap</code></a>. Should be
+      either null, or a valid <a href="#keymaps">keymap</a> value.</dd>
+      <dt id="option_lineWrapping"><code>lineWrapping (boolean)</code></dt>
+      <dd>Whether CodeMirror should scroll or wrap for long lines.
+      Defaults to <code>false</code> (scroll).</dd>
       <dt id="option_lineNumbers"><code>lineNumbers (boolean)</code></dt>
       <dd>Whether to show line numbers to the left of the editor.</dd>
@@ -201,31 +190,49 @@
       <dt id="option_firstLineNumber"><code>firstLineNumber (integer)</code></dt>
       <dd>At which number to start counting lines. Default is 1.</dd>
+      <dt id="option_lineNumberFormatter"><code>lineNumberFormatter (function(integer))</code></dt>
+      <dd>A function used to format line numbers. The function is passed the current line number. Default prints the line number verbatim.</dd>
       <dt id="option_gutter"><code>gutter (boolean)</code></dt>
       <dd>Can be used to force a 'gutter' (empty space on the left of
       the editor) to be shown even when no line numbers are active.
       This is useful for setting <a href="#setMarker">markers</a>.</dd>
+      <dt id="option_fixedGutter"><code>fixedGutter (boolean)</code></dt>
+      <dd>When enabled (off by default), this will make the gutter
+      stay visible when the document is scrolled horizontally.</dd>
       <dt id="option_readOnly"><code>readOnly (boolean)</code></dt>
-      <dd>This disables editing of the editor content by the user.
-      (Changes through API functions will still be possible.) If you
-      also want to disable the cursor, use <code>"nocursor"</code> as
-      a value for this option, instead of <code>true</code>.</dd>
+      <dd>This disables editing of the editor content by the user. If
+      the special value <code>"nocursor"</code> is given (instead of
+      simply <code>true</code>), focusing of the editor is also
+      disallowed.</dd>
       <dt id="option_onChange"><code>onChange (function)</code></dt>
       <dd>When given, this function will be called every time the
       content of the editor is changed. It will be given the editor
-      instance as only argument.</dd>
+      instance as first argument, and an <code>{from, to, text, next}</code>
+      object containing information about the changes
+      that occurred as second argument. <code>from</code>
+      and <code>to</code> are the positions (in the pre-change
+      coordinate system) where the change started and
+      ended (for example, it might be <code>{ch:0, line:18}</code> if the
+      position is at the beginning of line #19). <code>text</code>
+      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 <code>next</code> property pointing to
+      another change object (which may point to another, etc).</dd>
       <dt id="option_onCursorActivity"><code>onCursorActivity (function)</code></dt>
-      <dd>Like <code>onChange</code>, but will also be called when the
-      cursor moves without any changes being made.</dd>
+      <dd>Will be called when the cursor or selection moves, or any
+      change is made to the editor content.</dd>
       <dt id="option_onGutterClick"><code>onGutterClick (function)</code></dt>
       <dd>When given, will be called whenever the editor gutter (the
       line-number area) is clicked. Will be given the editor instance
-      as first argument, and the (zero-based) number of the line that
-      was clicked as second argument.</dd>
+      as first argument, the (zero-based) number of the line that was
+      clicked as second argument, and the raw <code>mousedown</code>
+      event object as third argument.</dd>
       <dt id="option_onFocus"><code>onFocus, onBlur (function)</code></dt>
       <dd>The given functions will be called whenever the editor is
@@ -240,6 +247,9 @@
       this function (if given) will be called. It'll be given a single
       argument, the editor instance.</dd>
+      <dt id="option_onUpdate"><code>onUpdate (function)</code></dt>
+      <dd>Will be called whenever CodeMirror updates its DOM display.</dd>
       <dt id="option_matchBrackets"><code>matchBrackets (boolean)</code></dt>
       <dd>Determines whether brackets are matched whenever the cursor
       is moved next to a bracket.</dd>
@@ -251,6 +261,13 @@
       defaults are 200 and 300, you can change these options to make
       the highlighting more or less aggressive.</dd>
+      <dt id="option_pollInterval"><code>pollInterval (number)</code></dt>
+      <dd>Indicates how quickly CodeMirror should poll its input
+      textarea for changes. Most input is captured by events, but some
+      things, like IME input on some browsers, doesn't generate events
+      that allow CodeMirror to properly detect it. Thus, it polls.
+      Default is 100 milliseconds.</dd>
       <dt id="option_undoDepth"><code>undoDepth (integer)</code></dt>
       <dd>The maximum number of undo levels that the editor stores.
       Defaults to 40.</dd>
@@ -260,10 +277,25 @@
       index</a> to assign to the editor. If not given, no tab index
       will be assigned.</dd>
-      <dt id="option_document"><code>document (DOM document)</code></dt>
-      <dd>Use this if you want to display the editor in another DOM.
-      By default it will use the global <code>document</code>
-      object.</dd>
+      <dt id="option_autofocus"><code>autofocus (boolean)</code></dt>
+      <dd>Can be used to make CodeMirror focus itself on
+      initialization. Defaults to off.
+      When <a href="#fromTextArea"><code>fromTextArea</code></a> is
+      used, and no explicit value is given for this option, it will
+      inherit the setting from the textarea's <code>autofocus</code>
+      attribute.</dd>
+      <dt id="option_dragDrop"><code>dragDrop (boolean)</code></dt>
+      <dd>Controls whether drag-and-drop is enabled. On by default.</dd>
+      <dt id="option_onDragEvent"><code>onDragEvent (function)</code></dt>
+      <dd>When given, this will be called when the editor is handling
+      a <code>dragenter</code>, <code>dragover</code>,
+      or <code>drop</code> 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 <code>true</code> to indicate that CodeMirror should not
+      do anything further.</dd>
       <dt id="option_onKeyEvent"><code>onKeyEvent (function)</code></dt>
       <dd>This provides a rather low-level hook into CodeMirror's key
@@ -285,6 +317,63 @@
       that need character data).</dd>
     </dl>
+    <h2 id="keymaps">Keymaps</h2>
+    <p>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.</p>
+    <p>Keys are identified either by name or by character.
+    The <code>CodeMirror.keyNames</code> object defines names for
+    common keys and associates them with their key codes. Examples of
+    names defined here are <code>Enter</code>, <code>F5</code>,
+    and <code>Q</code>. These can be prefixed
+    with <code>Shift-</code>, <code>Cmd-</code>, <code>Ctrl-</code>,
+    and <code>Alt-</code> (in that order!) to specify a modifier. So
+    for example, <code>Shift-Ctrl-Space</code> would be a valid key
+    identifier.</p>
+    <p>Alternatively, a character can be specified directly by
+    surrounding it in single quotes, for example <code>'$'</code>
+    or <code>'q'</code>. Due to limitations in the way browsers fire
+    key events, these may not be prefixed with modifiers.</p>
+    <p>The <code>CodeMirror.keyMap</code> 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 <code>"default"</code> keymap holding the
+    default bindings.</p>
+    <p>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
+    <code>CodeMirror.commands</code> 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
+    <code>CodeMirror.Pass</code> to indicate that it has decided not
+    to handle the key, and other handlers (or the default behavior)
+    should be given a turn.</p>
+    <p>Keys mapped to command names that start with the
+    characters <code>"go"</code> (which should be used for
+    cursor-movement actions) will be fired even when an
+    extra <code>Shift</code> modifier is present (i.e. <code>"Up":
+    "goLineUp"</code> matches both up and shift-up). This is used to
+    easily implement shift-selection.</p>
+    <p>Keymaps can defer to each other by defining
+    a <code>fallthrough</code> 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.</p>
+    <p>When a keymap contains a <code>nofallthrough</code> property
+    set to <code>true</code>, 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, and the default effect of
+    inserting a character will not occur).</p>
     <h2 id="styling">Customized Styling</h2>
     <p>Up to a certain extent, CodeMirror's look can be changed by
@@ -292,7 +381,7 @@
     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 <a href="lib/codemirror.css"><code>codemirror.css</code></a>.</p>
+    in <a href="../lib/codemirror.css"><code>codemirror.css</code></a>.</p>
     <p>Some care must be taken there, since a lot of the rules in this
     file are necessary to have CodeMirror function properly. Adjusting
@@ -302,16 +391,17 @@
     <dl>
       <dt id="class_CodeMirror"><code>CodeMirror</code></dt>
-      <dd>The outer element of the editor. This should be used for
-      borders and positioning. Can also be used to set styles that
-      should hold for everything inside the editor (such as font
-      and font size), or to set a background.</dd>
+      <dd>The outer element of the editor. This should be used for the
+      editor width, borders and positioning. Can also be used to set
+      styles that should hold for everything inside the editor (such
+      as font and font size), or to set a background.</dd>
       <dt id="class_CodeMirror_scroll"><code>CodeMirror-scroll</code></dt>
-      <dd>This determines whether the editor scrolls (<code>overflow:
-      auto</code> + fixed height). By default, it does. Giving
-      this <code>height: auto; overflow: visible;</code> will cause
-      the editor to resize to fit its content.</dd>
+      <dd>This determines the editor's height, and whether the editor
+      scrolls (<code>overflow: auto</code> + fixed height). By
+      default, it does. Giving this <code>height: auto; overflow:
+      visible;</code> will cause the editor to resize to fit its
+      content.</dd>
       <dt id="class_CodeMirror_focused"><code>CodeMirror-focused</code></dt>
       <dd>Whenever the editor is focused, the top element gets this
@@ -351,12 +441,18 @@
       <dd>These are used to style matched (or unmatched) brackets.</dd>
     </dl>
+    <p id="css-resize">So note carefully that, in order to resize the
+    editor, you should set a <code>width</code> on
+    the <a href="#getWrapperElement">wrapper</a>
+    (class <code>CodeMirror</code>) element, and a height on
+    the <a href="#getScrollerElement">scroller</a>
+    (class <code>CodeMirror-scroll</code>) element.</p>
     <p>The actual lines, as well as the cursor, are represented
     by <code>pre</code> 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 <code>CodeMirror pre</code> a
-    fixed height. Also, you must still take care that character width
-    is constant.</p>
+    fixed height.</p>
     <p>If your page's style sheets do funky things to
     all <code>div</code> or <code>pre</code> elements (you probably
@@ -364,6 +460,10 @@
     effects out again for elements under the <code>CodeMirror</code>
     class.</p>
+    <p>Themes are also simply CSS files, which define colors for
+    various syntactic elements. See the files in
+    the <a href="../theme/"><code>theme</code></a> directory.</p>
     <h2 id="api">Programming API</h2>
     <p>A lot of CodeMirror features are only available through its API.
@@ -382,7 +482,9 @@
     <dl>
       <dt id="getValue"><code>getValue() → string</code></dt>
-      <dd>Get the current editor content.</dd>
+      <dd>Get the current editor content. You can pass it an optional
+      argument to specify the string to be used to separate lines
+      (defaults to <code>"\n"</code>).</dd>
       <dt id="setValue"><code>setValue(string)</code></dt>
       <dd>Set the editor content.</dd>
@@ -391,8 +493,24 @@
       <dt id="replaceSelection"><code>replaceSelection(string)</code></dt>
       <dd>Replace the selection with the given string.</dd>
+      <dt id="setSize"><code>setSize(width, height)</code></dt>
+      <dd>Programatically set the size of the editor (overriding the
+      applicable <a href="#css-resize">CSS
+      rules</a>). <code>width</code> and <code>height</code> height
+      can be either numbers (interpreted as pixels) or CSS units
+      (<code>"100%"</code>, for example). You can
+      pass <code>null</code> for either of them to indicate that that
+      dimension should not be changed.</dd>
       <dt id="focus"><code>focus()</code></dt>
       <dd>Give the editor focus.</dd>
+      <dt id="scrollTo"><code>scrollTo(x, y)</code></dt>
+      <dd>Scroll the editor to a given (pixel) position. Both
+      arguments may be left as <code>null</code>
+      or <code>undefined</code> to have no effect.</dd>
+      <dt id="getScrollInfo"><code>getScrollInfo()</code></dt>
+      <dd>Get an <code>{x, y, width, height}</code> object that
+      represents the current scroll position and scrollable area size
+      of the editor.</dd>
       <dt id="setOption"><code>setOption(option, value)</code></dt>
       <dd>Change the configuration of the editor. <code>option</code>
@@ -403,13 +521,16 @@
       <dd>Retrieves the current value of the given option for this
       editor instance.</dd>
-      <dt id="cursorCoords"><code>cursorCoords(start) → object</code></dt>
+      <dt id="cursorCoords"><code>cursorCoords(start, mode) → object</code></dt>
       <dd>Returns an <code>{x, y, yBot}</code> object containing the
-      coordinates of the cursor relative to the top-left corner of the
+      coordinates of the cursor. If <code>mode</code>
+      is <code>"local"</code>, they will be relative to the top-left
+      corner of the editable document. If it is <code>"page"</code> or
+      not given, they are relative to the top-left corner of the
       page. <code>yBot</code> is the coordinate of the bottom of the
       cursor. <code>start</code> is a boolean indicating whether you
       want the start or the end of the selection.</dd>
-      <dt id="charCoords"><code>charCoords(pos) → object</code></dt>
+      <dt id="charCoords"><code>charCoords(pos, mode) → object</code></dt>
       <dd>Like <code>cursorCoords</code>, but returns the position of
       an arbitrary characters. <code>pos</code> should be
       a <code>{line, ch}</code> object.</dd>
@@ -426,6 +547,17 @@
       <dd>Returns an object with <code>{undo, redo}</code> properties,
       both of which hold integers, indicating the amount of stored
       undo and redo operations.</dd>
+      <dt id="clearHistory"><code>clearHistory()</code></dt>
+      <dd>Clears the editor's undo history.</dd>
+      <dt id="getHistory"><code>getHistory() → object</code></dt>
+      <dd>Get a (JSON-serializeable) representation of the undo history.</dd>
+      <dt id="setHistory"><code>setHistory(object)</code></dt>
+      <dd>Replace the editor's undo history with the one provided,
+      which must be a value as returned
+      by <a href="#getHistory"><code>getHistory</code></a>. Note that
+      this will have entirely undefined results if the editor content
+      isn't also the same as it was when <code>getHistory</code> was
+      called.</dd>
       <dt id="indentLine"><code>indentLine(line, dir)</code></dt>
       <dd>Reset the given line's indentation to the indentation
@@ -434,37 +566,9 @@
       decreased (if false) by an <a href="#option_indentUnit">indent
       unit</a> instead.</dd>
-      <dt id="getSearchCursor"><code>getSearchCursor(query, start, caseFold) → cursor</code></dt>
-      <dd>Used to implement search/replace
-      functionality. <code>query</code> can be a regular expression or
-      a string (only strings will match across lines—if they contain
-      newlines). <code>start</code> provides the starting position of
-      the search. It can be a <code>{line, ch}</code> object, or can
-      be left off to default to the start of the
-      document. <code>caseFold</code> is only relevant when matching a
-      string. It will cause the search to be case-insensitive. A
-      search cursor has the following methods:
-        <dl>
-          <dt><code>findNext(), findPrevious() → boolean</code></dt>
-          <dd>Search forward or backward from the current position.
-          The return value indicates whether a match was found. If
-          matching a regular expression, the return value will be the
-          array returned by the <code>match</code> method, in case you
-          want to extract matched groups.</dd>
-          <dt><code>from(), to() → object</code></dt>
-          <dd>These are only valid when the last call
-          to <code>findNext</code> or <code>findPrevious</code> did
-          not return false. They will return <code>{line, ch}</code>
-          objects pointing at the start and end of the match.</dd>
-          <dt><code>replace(text)</code></dt>
-          <dd>Replaces the currently found match with the given text
-          and adjusts the cursor position to reflect the
-          replacement.</dd>
-        </dl></dd>
       <dt id="getTokenAt"><code>getTokenAt(pos) → object</code></dt>
       <dd>Retrieves information about the token the current mode found
-      at the given position (a <code>{line, ch}</code> object). The
+      before the given position (a <code>{line, ch}</code> object). The
       returned object has the following properties:
       <dl>
         <dt><code>start</code></dt><dd>The character (on the given line) at which the token starts.</dd>
@@ -475,11 +579,26 @@
         <dt><code>state</code></dt><dd>The mode's state at the end of this token.</dd>
       </dl></dd>
-      <dt id="markText"><code>markText(from, to, className) → function</code></dt>
+      <dt id="markText"><code>markText(from, to, className) → object</code></dt>
       <dd>Can be used to mark a range of text with a specific CSS
       class name. <code>from</code> and <code>to</code> should
-      be <code>{line, ch}</code> objects. The method will return a
-      function that can be called to remove the marking.</dd>
+      be <code>{line, ch}</code> objects. The method will return an
+      object with two methods, <code>clear()</code>, which removes the
+      mark, and <code>find()</code>, which returns a <code>{from,
+      to}</code> (both document positions), indicating the current
+      position of the marked range.</dd>
+      <dt id="setBookmark"><code>setBookmark(pos) → object</code></dt>
+      <dd>Inserts a bookmark, a handle that follows the text around it
+      as it is being edited, at the given position. A bookmark has two
+      methods <code>find()</code> and <code>clear()</code>. The first
+      returns the current position of the bookmark, if it is still in
+      the document, and the second explicitly removes the
+      bookmark.</dd>
+      <dt id="findMarksAt"><code>findMarksAt(pos) → array</code></dt>
+      <dd>Returns an array of all the bookmarks and marked ranges
+      present at the given position.</dd>
       <dt id="setMarker"><code>setMarker(line, text, className) → lineHandle</code></dt>
       <dd>Add a gutter marker for the given line. Gutter markers are
@@ -500,17 +619,37 @@
       number or a handle returned by <code>setMarker</code> (since a
       number may now refer to a different line if something was added
       or deleted).</dd>
-      <dt id="setLineClass"><code>setLineClass(line, className) → lineHandle</code></dt>
+      <dt id="setLineClass"><code>setLineClass(line, className, backgroundClassName) → lineHandle</code></dt>
       <dd>Set a CSS class name for the given line. <code>line</code>
       can be a number or a line handle (as returned
-      by <code>setMarker</code> or this function).
-      Pass <code>null</code> to clear the class for a line.</dd>
+      by <code>setMarker</code> or this
+      function). <code>className</code> will be used to style the text
+      for the line, and <code>backgroundClassName</code> to style its
+      background (which lies behind the selection).
+      Pass <code>null</code> to clear the classes for a line.</dd>
+      <dt id="hideLine"><code>hideLine(line) → lineHandle</code></dt>
+      <dd>Hide the given line (either by number or by handle). Hidden
+      lines don't show up in the editor, and their numbers are skipped
+      when <a href="#option_lineNumbers">line numbers</a> are enabled.
+      Deleting a region around them does delete them, and coping a
+      region around will include them in the copied text.</dd>
+      <dt id="showLine"><code>showLine(line) → lineHandle</code></dt>
+      <dd>The inverse of <code>hideLine</code>—re-shows a previously
+      hidden line, by number or by handle.</dd>
+      <dt id="onDeleteLine"><code>onDeleteLine(line, func)</code></dt>
+      <dd>Register a function that should be called when the line is
+      deleted from the document.</dd>
       <dt id="lineInfo"><code>lineInfo(line) → object</code></dt>
       <dd>Returns the line number, text content, and marker status of
       the given line, which can be either a number or a handle
       returned by <code>setMarker</code>. The returned object has the
-      structure <code>{line, text, markerText, markerClass}</code>.</dd>
+      structure <code>{line, handle, text, markerText, markerClass,
+      lineClass, bgClass}</code>.</dd>
+      <dt id="getLineHandle"><code>getLineHandle(num) → lineHandle</code></dt>
+      <dd>Fetches the line handle for the given line number.</dd>
       <dt id="addWidget"><code>addWidget(pos, node, scrollIntoView)</code></dt>
       <dd>Puts <code>node</code>, which should be an absolutely
@@ -552,13 +691,24 @@
       <dt id="getRange"><code>getRange(from, to) → string</code></td>
       <dd>Get the text between the given points in the editor, which
-      should be <code>{line, ch}</code> objects.</dd>
+      should be <code>{line, ch}</code> objects. An optional third
+      argument can be given to indicate the line separator string to
+      use (defaults to <code>"\n"</code>).</dd>
       <dt id="replaceRange"><code>replaceRange(string, from, to)</code></dt>
       <dd>Replace the part of the document between <code>from</code>
       and <code>to</code> with the given string. <code>from</code>
       and <code>to</code> must be <code>{line, ch}</code>
       objects. <code>to</code> can be left off to simply insert the
       string at position <code>from</code>.</dd>
+      <dt id="posFromIndex"><code>posFromIndex(index) → object</code></dt>
+      <dd>Calculates and returns a <code>{line, ch}</code> object for a
+      zero-based <code>index</code> who's value is relative to the start of the
+      editor's text. If the <code>index</code> is out of range of the text then
+      the returned object is clipped to start or end of the text
+      respectively.</dd>
+      <dt id="indexFromPos"><code>indexFromPos(object) → number</code></dt>
+      <dd>The reverse of <a href="#posFromIndex"><code>posFromIndex</code></a>.</dd>
     </dl>
     <p>The following are more low-level methods:</p>
@@ -574,6 +724,11 @@
       lot faster. The return value from this method will be the return
       value of your function.</dd>
+      <dt id="compoundChange"><code>compoundChange(func) → result</code></dt>
+      <dd>Will call the given function (and return its result),
+      combining all changes made while that function executes into a
+      single undo event.</dd>
       <dt id="refresh"><code>refresh()</code></dt>
       <dd>If your code does something to change the size of the editor
       element (window resizes are already listened for), or unhides
@@ -581,15 +736,17 @@
       ensure CodeMirror is still looking as intended.</dd>
       <dt id="getInputField"><code>getInputField() → textarea</code></dt>
-      <dd>Returns the hiden textarea used to read input.</dd>
+      <dd>Returns the hidden textarea used to read input.</dd>
       <dt id="getWrapperElement"><code>getWrapperElement() → node</code></dt>
-      <dd>Returns the DOM node that represents the editor. Remove this
-      from your tree to delete an editor instance.</dd>
+      <dd>Returns the DOM node that represents the editor, and
+      controls its width. Remove this from your tree to delete an
+      editor instance. Set it's <code>width</code> style when
+      resizing.</dd>
       <dt id="getScrollerElement"><code>getScrollerElement() → node</code></dt>
-      <dd>Returns the DOM node that is responsible for the sizing and
-      the scrolling of the editor. You can change
-      the <code>height</code> and <code>width</code> styles of this
-      element to resize an editor. (You might have to call
+      <dd>Returns the DOM node that is responsible for the vertical
+      sizing and horizontal scrolling of the editor. You can change
+      the <code>height</code> style of this element to resize an
+      editor. (You might have to call
       the <a href="#refresh"><code>refresh</code></a> method
       afterwards.)</dd>
       <dt id="getGutterElement"><code>getGutterElement() → node</code></dt>
@@ -619,27 +776,163 @@
       <dt id="toTextArea"><code>toTextArea()</code></dt>
       <dd>Remove the editor, and restore the original textarea (with
       the editor's current content).</dd>
+      <dt id="getTextArea"><code>getTextArea() → textarea</code></dt>
+      <dd>Returns the textarea that the instance was based on.</dd>
     </dl>
-    <p id="defineExtension">If you want define extra methods in terms
-    of the CodeMirror API, is it possible to
+    <p id="defineExtension">If you want to define extra methods in terms
+    of the CodeMirror API, it is possible to
     use <code>CodeMirror.defineExtension(name, value)</code>. This
     will cause the given value (usually a method) to be added to all
     CodeMirror instances created from then on.</p>
-    <h2 id="modeapi">Writing CodeMirror Modes</h2>
+    <h2 id="addons">Add-ons</h2>
+    <p>The <code>lib/util</code> directory in the distribution
+    contains a number of reusable components that implement extra
+    editor functionality. In brief, they are:</p>
+    <dl>
+      <dt id="util_dialog"><a href="../lib/util/dialog.js"><code>dialog.js</code></a></dt>
+      <dd>Provides a very simple way to query users for text input.
+      Adds an <code>openDialog</code> method to CodeMirror instances,
+      which can be called with an HTML fragment that provides the
+      prompt (should include an <code>input</code> tag), and a
+      callback function that is called when text has been entered.
+      Depends on <code>lib/util/dialog.css</code>.</dd>
+      <dt id="util_searchcursor"><a href="../lib/util/searchcursor.js"><code>searchcursor.js</code></a></dt>
+      <dd>Adds the <code>getSearchCursor(query, start, caseFold) →
+      cursor</code> method to CodeMirror instances, which can be used
+      to implement search/replace functionality. <code>query</code>
+      can be a regular expression or a string (only strings will match
+      across lines—if they contain newlines). <code>start</code>
+      provides the starting position of the search. It can be
+      a <code>{line, ch}</code> object, or can be left off to default
+      to the start of the document. <code>caseFold</code> is only
+      relevant when matching a string. It will cause the search to be
+      case-insensitive. A search cursor has the following methods:
+        <dl>
+          <dt><code>findNext(), findPrevious() → boolean</code></dt>
+          <dd>Search forward or backward from the current position.
+          The return value indicates whether a match was found. If
+          matching a regular expression, the return value will be the
+          array returned by the <code>match</code> method, in case you
+          want to extract matched groups.</dd>
+          <dt><code>from(), to() → object</code></dt>
+          <dd>These are only valid when the last call
+          to <code>findNext</code> or <code>findPrevious</code> did
+          not return false. They will return <code>{line, ch}</code>
+          objects pointing at the start and end of the match.</dd>
+          <dt><code>replace(text)</code></dt>
+          <dd>Replaces the currently found match with the given text
+          and adjusts the cursor position to reflect the
+          replacement.</dd>
+        </dl></dd>
-    <p>Modes typically consist of a JavaScript file and a CSS file.
-    The CSS file (see, for
-    example <a href="mode/javascript/javascript.css"><code>javascript.css</code></a>)
-    defines the classes that will be used to style the syntactic
-    elements of the code, and the script contains the logic to
-    actually assign these classes to the right pieces of text.</p>
+      <dt id="util_search"><a href="../lib/util/search.js"><code>search.js</code></a></dt>
+      <dd>Implements the search commands. CodeMirror has keys bound to
+      these by default, but will not do anything with them unless an
+      implementation is provided. Depends
+      on <code>searchcursor.js</code>, and will make use
+      of <a href="#util_dialog"><code>openDialog</code></a> when
+      available to make prompting for search queries less ugly.</dd>
+      <dt id="util_foldcode"><a href="../lib/util/foldcode.js"><code>foldcode.js</code></a></dt>
+      <dd>Helps with code folding.
+      See <a href="../demo/folding.html">the demo</a> for an example.
+      Call <code>CodeMirror.newFoldFunction</code> 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 <code>CodeMirror.braceRangeFinder</code>, which finds
+      blocks in brace languages (JavaScript, C, Java,
+      etc), <code>CodeMirror.indentRangeFinder</code>, for languages
+      where indentation determines block structure (Python, Haskell),
+      and <code>CodeMirror.tagRangeFinder</code>, for XML-style
+      languages.</dd>
+      <dt id="util_runmode"><a href="../lib/util/runmode.js"><code>runmode.js</code></a></dt>
+      <dd>Can be used to run a CodeMirror mode over text without
+      actually opening an editor instance.
+      See <a href="../demo/runmode.html">the demo</a> for an
+      example.</dd>
+      <dt id="util_overlay"><a href="../lib/util/overlay.js"><code>overlay.js</code></a></dt>
+      <dd>Mode combinator that can be used to extend a mode with an
+      'overlay' — a secondary mode is run over the stream, along with
+      the base mode, and can color specific pieces of text without
+      interfering with the base mode.
+      Defines <code>CodeMirror.overlayMode</code>, which is used to
+      create such a mode. See <a href="../demo/mustache.html">this
+      demo</a> for a detailed example.</dd>
+      <dt id="util_multiplex"><a href="../lib/util/multiplex.js"><code>multiplex.js</code></a></dt>
+      <dd>Mode combinator that can be used to easily 'multiplex'
+      between several modes.
+      Defines <code>CodeMirror.multiplexingMode</code> which, when
+      given as first argument a mode object, and as other arguments
+      any number of <code>{open, close, mode [, delimStyle]}</code>
+      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 <code>open</code> fields of the passed objects. When in a
+      sub-mode, it will go back to the top mode again when
+      the <code>close</code> string is encountered.
+      When <code>delimStyle</code> is specified, it will be the token
+      style returned for the delimiter tokens. The outer mode will not
+      see the content between the delimiters.
+      See <a href="../demo/multiplex.html">this demo</a> for an
+      example.</dd>
+      <dt id="util_simple-hint"><a href="../lib/util/simple-hint.js"><code>simple-hint.js</code></a></dt>
+      <dd>Provides a framework for showing autocompletion hints.
+      Defines <code>CodeMirror.simpleHint</code>, 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 <code>{list, from, to}</code> object, where <code>list</code>
+      is an array of strings (the completions), and <code>from</code>
+      and <code>to</code> give the start and end of the token that is
+      being completed. Depends
+      on <code>lib/util/simple-hint.css</code>.</dd>
+      <dt id="util_javascript-hint"><a href="../lib/util/javascript-hint.js"><code>javascript-hint.js</code></a></dt>
+      <dd>Defines <code>CodeMirror.javascriptHint</code>
+      and <code>CodeMirror.coffeescriptHint</code>, which are simple
+      hinting functions for the JavaScript and CoffeeScript
+      modes.</dd>
+      <dt id="util_match-highlighter"><a href="../lib/util/match-highlighter.js"><code>match-highlighter.js</code></a></dt>
+      <dd>Adds a <code>matchHighlight</code> method to CodeMirror
+      instances that can be called (typically from
+      a <a href="#option_onCursorActivity"><code>onCursorActivity</code></a>
+      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 <a href="#util_searchcursor"><code>searchcursor</code></a>
+      add-on. Demo <a href="../demo/matchhighlighter.html">here</a>.</dd>
+      <dt id="util_closetag"><a href="../lib/util/closetag.js"><code>closetag.js</code></a></dt>
+      <dd>Provides utility functions for adding automatic tag closing
+      to XML modes. See
+      the <a href="../demo/closetag.html">demo</a>.</dd>
+      <dt id="util_loadmode"><a href="../lib/util/loadmode.js"><code>loadmode.js</code></a></dt>
+      <dd>Defines a <code>CodeMirror.requireMode(modename,
+      callback)</code> function that will try to load a given mode and
+      call the callback when it succeeded. You'll have to
+      set <code>CodeMirror.modeURL</code> to a string that mode paths
+      can be constructed from, for
+      example <code>"mode/%N/%N.js"</code>—the <code>%N</code>'s will
+      be replaced with the mode name. Also
+      defines <code>CodeMirror.autoLoadMode(instance, mode)</code>,
+      which will ensure the given mode is loaded and cause the given
+      editor instance to refresh its mode when the loading
+      succeeded. See the <a href="../demo/loadmode.html">demo</a>.</dd>
+    </dl>
+    <h2 id="modeapi">Writing CodeMirror Modes</h2>
-    <p>You'll usually want to use some kind of prefix for your CSS
-    classes, so that they are unlikely to clash with other classes,
-    both those used by other modes and those defined by the page in
-    which CodeMirror is embedded.</p>
+    <p>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.</p>
     <p id="defineMode">The mode script should
     call <code>CodeMirror.defineMode</code> to register itself with
@@ -649,9 +942,10 @@
     mode (i.e. <code>"xml"</code> is defined <code>xml.js</code>). The
     second argument should be a function that, given a CodeMirror
     configuration object (the thing passed to
-    the <code>CodeMirror</code> function) and a mode configuration
-    object (as in the <a href="#option_mode"><code>mode</code></a>
-    option), returns a mode object.</p>
+    the <code>CodeMirror</code> function) and an optional mode
+    configuration object (as in
+    the <a href="#option_mode"><code>mode</code></a> option), returns
+    a mode object.</p>
     <p>Typically, you should use this second argument
     to <code>defineMode</code> as your module scope function (modes
@@ -665,8 +959,8 @@
     meaning that they look at one element (<em>token</em>) 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 <em>state
-    object</em>, which is an object that can be mutated every time a
-    new token is read.</p>
+    object</em>, which is an object that is always passed when
+    reading a token, and which can be mutated by the tokenizer.</p>
     <p id="startState">Modes that use a state must define
     a <code>startState</code> method on their mode object. This is a
@@ -680,8 +974,7 @@
     style string, or <code>null</code> 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 <code>cm-</code> prefix), or
-    define your own (as the <a href="../mode/diff/index.html">diff</a>
-    mode does) and have people include a custom theme for your
+    define your own and have people include a custom CSS file for your
     mode.<p>
     <p id="StringStream">The stream object encapsulates a line of code
@@ -721,7 +1014,9 @@
       <dd>Moves the position to the end of the line.</dd>
       <dt><code>skipTo(ch) → boolean</code></dt>
       <dd>Skips to the next occurrence of the given character, if
-      found. Returns true if the character was found.</dd>
+      found on the current line (doesn't advance the stream if the
+      character does not occur on the line). Returns true if the
+      character was found.</dd>
       <dt><code>match(pattern, consume, caseFold) → boolean</code></dt>
       <dd>Act like a
       multi-character <code>eat</code>—if <code>consume</code> is true
@@ -782,9 +1077,10 @@
     reliable highlighting of bad closing tags, as an example.</p>
     <p id="indent">If you want your mode to provide smart indentation
-    (see <a href="#option_enterMode"><code>entermode</code></a>
-    and <a href="#option_tabMode"><code>tabMode</code></a> when they
-    have a value of <code>"indent"</code>), you must define
+    (though the <a href="#indentLine"><code>indentLine</code></a>
+    method and the <code>indentAuto</code>
+    and <code>newlineAndIndent</code> commands, which keys can be
+    <a href="#option_extraKeys">bound</a> to), you must define
     an <code>indent(state, textAfter)</code> method on your mode
     object.</p>
@@ -805,15 +1101,15 @@
     <p>So, to summarize, a mode <em>must</em> provide
     a <code>token</code> method, and it <em>may</em>
     provide <code>startState</code>, <code>copyState</code>,
-    and <code>indent</code> methods. For an example of a trivial mode,
-    see the <a href="mode/diff/diff.js">diff mode</a>, for a more
-    involved example, see
-    the <a href="mode/javascript/javascript.js">JavaScript
+    <code>compareStates</code>, and <code>indent</code> methods. For
+    an example of a trivial mode, see
+    the <a href="../mode/diff/diff.js">diff mode</a>, for a more involved
+    example, see the <a href="../mode/clike/clike.js">C-like
     mode</a>.</p>
     <p>Sometimes, it is useful for modes to <em>nest</em>—to have one
     mode delegate work to another mode. An example of this kind of
-    mode is the <a href="mode/htmlmixed/htmlmixed.js">mixed-mode HTML
+    mode is the <a href="../mode/htmlmixed/htmlmixed.js">mixed-mode HTML
     mode</a>. To implement such nesting, it is usually necessary to
     create mode objects and copy states yourself. To create a mode
     object, there are <code>CodeMirror.getMode(options,
@@ -851,8 +1147,10 @@
       <li><a href="#overview">Overview</a></li>
       <li><a href="#usage">Basic Usage</a></li>
       <li><a href="#config">Configuration</a></li>
+      <li><a href="#keymaps">Keymaps</a></li>
       <li><a href="#styling">Customized Styling</a></li>
       <li><a href="#api">Programming API</a></li>
+      <li><a href="#addons">Add-ons</a></li>
       <li><a href="#modeapi">Writing CodeMirror Modes</a></li>
     </ul>