Import 1.0 supporting Firefox up to 14.*

[dactyl.git] / common / locale / en-US / map.xml

<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="dactyl://content/help.xsl"?>

<!DOCTYPE document SYSTEM "dactyl://cache/modes.dtd">

<document
    name="map"
    title="&dactyl.appName; Key Mappings"
    xmlns="&xmlns.dactyl;"
    xmlns:dactyl="&xmlns.dactyl;"
    xmlns:html="&xmlns.html;">

<h1 tag="keyboard-shortcuts">Keyboard shortcuts and commands</h1>
<toc start="2"/>

<p>
    &dactyl.appName; provides a number of commands to change the
    behavior of key presses. This can mean anything from
    automatically substituting one key for another or automatically
    replacing one typed word for another, to launching a dialog or
    running a command.
</p>

<h2 tag="key-mapping mapping map macro">Key mapping</h2>

<p>
    Key mappings are the most basic means &dactyl.appName; provides
    for altering the actions of key presses. Each key mapping is
    associated with a mode, such as <link topic="insert-mode">Insert</link>,
    <link>Normal</link>, or
    <link topic="command-line-mode">Command Line</link>, and only
    has effect when that mode is active. Although each mode has a
    full suite of internal mappings, they may be easily augmented,
    altered, or removed with the <ex>:map</ex> command and its
    variants. These commands, in essence, allow the user to quickly
    substitute one sequence of key presses for another.
    For instance,
</p>

<code><ex>:map <k name="F2" link="false"/></ex> <ex>:styletoggle</ex> <em>-name</em> <k name="A-Tab" link="c_&lt;Tab>"/></code>

<p>
    causes “<tt><ex>:styletoggle</ex> <em>-name</em> <k name="A-Tab" link="c_&lt;Tab"/></tt>” to be typed out
    whenever <k name="F2" link="false"/> is pressed, providing a way to toggle
    a tab-completed named user style.
</p>

<p>
    You can also map keys to <link topic="ex-scripts">Ex</link> or
    <link topic=":js">JavaScript</link> commands, see the
    <link topic="map-examples">examples</link>.
</p>

<p tag=":map-modes">
    Standard key mapping commands are provided for the five most
    common modes,
</p>

<dl dt="width: 8em;">
    <dt>n</dt> <dd>Normal mode: When browsing normally</dd>
    <dt>v</dt> <dd>Visual mode: When selecting text with the cursor keys</dd>
    <dt>i</dt> <dd>Insert mode: When interacting with text fields on a website</dd>
    <dt>t</dt> <dd>Text Edit mode: When editing text fields in Vim-like Normal mode</dd>
    <dt>c</dt> <dd>Command Line mode: When typing into the &dactyl.appName; command line</dd>
    <dt>o</dt> <dd>Operator mode: When moving the cursor</dd>
</dl>

<p>
    The ordinary <ex>:map</ex> command adds mappings for Normal and Visual
    mode. In order to map key bindings in a different mode, any of the mapping
    commands may be prefixed with one of the above letters. For instance,
    <ex>:imap</ex> creates a new key mapping in Insert mode, while
    <ex>:cunmap</ex> removes a key mapping from Command Line mode. Other modes
    can be specified using the <em>-modes</em> option described below.
</p>

<warning>
    It is important to note that mappings are <em>not</em>
    automatically saved between sessions. In order to preserve them,
    they must either be added to your <tt><t>&dactyl.name;rc</t></tt> or
    saved via the <ex>:mk&dactyl.name;rc</ex> command.
</warning>

<p tag="modes">
    The following tree represents all of the modes understood by
    dactyl. Mappings for a mode also apply to its children and
    descendants. So a mapping in the Base mode, for instance, is
    also active in Normal and Ex mode.
</p>

&modes.tree;

<h3 tag=":map-commands">Map commands</h3>

<item>
    <tags>:map</tags>
    <spec>:map <a>lhs</a> <a>rhs</a></spec>
    <tags>:nm :nmap</tags>
    <spec>:nm<oa>ap</oa> <a>lhs</a> <a>rhs</a></spec>
    <tags>:vm :vmap</tags>
    <spec>:vm<oa>ap</oa> <a>lhs</a> <a>rhs</a></spec>
    <tags>:im :imap</tags>
    <spec>:im<oa>ap</oa> <a>lhs</a> <a>rhs</a></spec>
    <tags>:tm :tmap</tags>
    <spec>:tm<oa>ap</oa> <a>lhs</a> <a>rhs</a></spec>
    <tags>:cm :cmap</tags>
    <spec>:cm<oa>ap</oa> <a>lhs</a> <a>rhs</a></spec>
    <description>
        <p>
            Map the <t>key-sequence</t> <a>lhs</a> to <a>rhs</a> for
            the applicable mode(s). The keys of <a>rhs</a> respect
            user-defined mappings, so the following will result in
            an infinite loop,
        </p>
        <code><ex>:map a b</ex>
<ex>:map b a</ex></code>
        <p>
            In order to avoid this shortcoming, the <ex>:noremap</ex> command
            or the <em>-builtin</em> option may be used.
        </p>
    </description>
</item>

<p tag=":map-overview">
    Below is an overview of which modes each map command applies to:
</p>

<dl dt="width: 20em;">
    <dt>:map   :unmap</dt>  <dd>Normal and Visual modes</dd>
    <dt>:nmap  :nunmap</dt> <dd>Normal mode</dd>
    <dt>:vmap  :vunmap</dt> <dd>Visual mode</dd>
    <dt>:imap  :iunmap</dt> <dd>Insert mode</dd>
    <dt>:tmap  :tunmap</dt> <dd>Text Edit mode</dd>
    <dt>:cmap  :cunmap</dt> <dd>Command Line mode</dd>
</dl>

<note>
    The <em>-modes</em> option, described below, provides a more flexible way
    to specify the applicable modes.
</note>

<h3 tag=":map-options">Map options</h3>
<p>
    Any of the map commands may be given the following options:
</p>

<dl dt="width: 12em;">
    <dt></dt> <dd></dd>

    <dt>-arg</dt> <dd>Accept an argument after the requisite key press. Sets the <tt>arg</tt> parameter to the result. (short name <em>-a</em>)</dd>
    <dt>-builtin</dt> <dd>Execute this mapping as if there were no user-defined mappings. (short name <em>-b</em>)</dd>
    <dt>-count</dt> <dd>Accept a count before the requisite key press. Sets the <tt>count</tt> parameter to the result. (short name <em>-c</em>)</dd>
    <dt>-description</dt> <dd>A description of this mapping. (short name <em>-d</em>)</dd>
    <dt>-ex</dt> <dd>Execute <a>rhs</a> as an Ex command rather than keys. (short name <em>-e</em>)</dd>
    <dt>-group=<a>group</a></dt> <dd>Add this command to the given <t>group</t> (short name <em>-g</em>). When listing commands this limits the output to the specified group.</dd>
    <dt>-javascript</dt> <dd>Execute <a>rhs</a> as JavaScript rather than keys. (short names <em>-js</em>, <em>-j</em>)</dd>
    <dt>-literal=<a>n</a></dt> <dd>Parse the <a>n</a>th argument without specially processing any quote or meta characters. (short name <em>-l</em>)</dd>
    <dt>-modes=<a>modes</a></dt> <dd>Create this mapping in the given modes. (short names <em>-mode</em>, <em>-m</em>)</dd>
    <dt>-nopersist</dt> <dd>Do not save this mapping to an auto-generated rc file. (short name <em>-n</em>)</dd>
    <dt>-silent</dt> <dd>Do not echo any generated keys to the command line. (short name <em>-s</em>, also <em>&lt;silent></em> for Vim compatibility)</dd>
</dl>

<item>
    <tags>:no :noremap</tags>
    <spec>:no<oa>remap</oa> <a>lhs</a> <a>rhs</a></spec>
    <tags>:nno :nnoremap</tags>
    <spec>:nno<oa>remap</oa> <a>lhs</a> <a>rhs</a></spec>
    <tags>:vno :vnoremap</tags>
    <spec>:vno<oa>remap</oa> <a>lhs</a> <a>rhs</a></spec>
    <tags>:ino :inoremap</tags>
    <spec>:ino<oa>remap</oa> <a>lhs</a> <a>rhs</a></spec>
    <tags>:tno :tnoremap</tags>
    <spec>:tno<oa>remap</oa> <a>lhs</a> <a>rhs</a></spec>
    <tags>:cno :cnoremap</tags>
    <spec>:cno<oa>remap</oa> <a>lhs</a> <a>rhs</a></spec>
    <description>
        <deprecated>These aliases are deprecated. The <em>-builtin</em> flag
            should be used in their stead.</deprecated>
        <p>
            Map the <t>key-sequence</t> <a>lhs</a> to <a>rhs</a> for
            the applicable mode(s). The keys in <a>rhs</a> do not
            respect user-defined key mappings, so the following
            effectively reverses the default meanings of the keys
            <k>d</k> and <k>D</k>
        </p>
        <code><ex>:noremap d D</ex>
<ex>:noremap D d</ex></code>
    </description>
</item>

<item>
    <spec>:unmap <a>lhs</a></spec>
    <tags>:unm :unmap</tags>
    <spec>:unmap!</spec>
    <spec>:nun<oa>map</oa> <a>lhs</a></spec>
    <tags>:nun :nunmap</tags>
    <spec>:nun<oa>map</oa>!</spec>
    <spec>:vun<oa>map</oa> <a>lhs</a></spec>
    <tags>:vun :vunmap</tags>
    <spec>:vun<oa>map</oa>!</spec>
    <spec>:iu<oa>nmap</oa> <a>lhs</a></spec>
    <tags>:iu :iunmap</tags>
    <spec>:iu<oa>nmap</oa>!</spec>
    <spec>:tu<oa>nmap</oa> <a>lhs</a></spec>
    <tags>:tu :tunmap</tags>
    <spec>:tu<oa>nmap</oa>!</spec>
    <spec>:cu<oa>nmap</oa> <a>lhs</a></spec>
    <tags>:cu :cunmap</tags>
    <spec>:cu<oa>nmap</oa>!</spec>
    <description>
        <p>Remove the mapping of <a>lhs</a> (or all mappings if <oa>!</oa> is
            given) for the applicable mode(s).</p>
    </description>
</item>

<item>
    <spec>:map</spec>
    <spec>:nm<oa>ap</oa></spec>
    <spec>:vm<oa>ap</oa></spec>
    <spec>:im<oa>ap</oa></spec>
    <spec>:tm<oa>ap</oa></spec>
    <spec>:cm<oa>ap</oa></spec>
    <description>
        <p>
            List all mappings for the applicable mode(s). Mappings are
            partitioned into <t>groups</t>.
        </p>
    </description>
</item>

<item>
    <tags>:map_l</tags>
    <spec>:map <a>lhs</a></spec>
    <tags>:nmap_l</tags>
    <spec>:nm<oa>ap</oa> <a>lhs</a></spec>
    <tags>:vmap_l</tags>
    <spec>:vm<oa>ap</oa> <a>lhs</a></spec>
    <tags>:imap_l</tags>
    <spec>:im<oa>ap</oa> <a>lhs</a></spec>
    <tags>:tmap_l</tags>
    <spec>:tm<oa>ap</oa> <a>lhs</a></spec>
    <tags>:cmap_l</tags>
    <spec>:cm<oa>ap</oa> <a>lhs</a></spec>
    <description>
        <p>List all mappings starting with <a>lhs</a> for the applicable mode(s).</p>
    </description>
</item>

<h3 tag=":map-timeout map-timeout">Mapping timeout</h3>
<p>
    When &dactyl.appName; receives a key event that has a separate binding and
    at the same time is part of a key chain, values of the <o>timeout</o> and
    <o>timeoutlen</o> options are used to decide what to do. See the
    documentation of those options for more information.
</p>

<h3 tag="key-notation key-sequence">Key sequences</h3>

<p>
    Most keys in key sequences are represented simply by the
    character that you see on the screen when you type them.
    However, as a number of these characters have special meanings,
    and a number of keys have no visual representation, a special
    notation is required.
</p>

<ul>
    <li>
        The first argument to the <ex>:map</ex> commands must be
        <link topic="quoting">quoted</link> if it contains spaces,
        quotation marks or back-slashes. A space may additionally be
        typed as <k name="Space"/>.
    </li>
    <li key="&lt;lt>">
        As special key names start with the <em>&lt;</em> character,
        a literal &lt; must be typed as <k name="lt" link="false"/>.
    </li>
    <li>
        <k name="Left"/>, <k name="Right"/>, <k name="Up"/>,
        and <k name="Down"/> represent the standard arrow keys.
    </li>
    <li>
        <k name="CapsLock" link="false"/>, <k name="NumLock" link="false"/>, <k name="Insert"/>
        <k name="Del" link="false"/>, <k name="Tab"/>, <k name="PageUp"/>,
        <k name="PageDown"/>, and <k name="Esc"/> work as
        expected.
   </li>
    <li>
        <k name="Return" link="false"/> or <k name="CR"/> represent the carriage
        return key.
    </li>
    <li><k name="BS" link="false"/> represents the backspace key.</li>
    <li><k name="F1"/> through <k name="F12" link="false"/> work as expected.</li>
    <li>
        <k name="K0" link="false"/> through <k name="K9" link="false"/> represent keys on the
        numeric keypad.
    </li>
    <li>
        <k name="Uxxxx" link="false"/>, where <em>xxxx</em> is any 4 hexadecimal
        digits, represents the character at that Unicode codepoint.
        For instance, <k name="U263a" link="false"/> represents ☺.
    </li>
</ul>

<p>
    In order to represent key presses using the Control, Alt, Meta,
    or Shift keys, the following prefixes may be used,
</p>

<ol>
    <li><k name="C-␣" link="false"/>: The control or ctrl key.</li>
    <li><k name="A-␣" link="false"/>: The alt key.</li>
    <li><k name="M-␣" link="false"/>: The meta key, windows key, or command key.</li>
    <li><k name="⌘-␣" link="false"/>: Same as <k name="M-␣" link="false"/>.</li>
    <li><k name="S-␣" link="false"/>: The shift key.</li>
</ol>

<p>
    These prefixes can be combined however you see fit.
</p>

<note>
    Within angle brackets all alphabetic characters are read as lowercase.
    Uppercase characters can only be specified with the <em>S-</em> modifier.
</note>

<p>
    The following key sequences are interpreted as described:
</p>

<dl dt="width: 10em;">
    <dt><k link="false">xc</k></dt>
    <dd>Press the ‘X’ key followed by the ‘C’ key.</dd>

    <dt><k name="C-x" link="false">c</k></dt>
    <dd>
        Press the ‘X’ key while holding the ‘Control’ key, followed
        by the ‘C’ key.
    </dd>

    <dt><k name="C-2" link="false"/></dt>
    <dd>Type ‘2’ while holding the ‘Control’ key.</dd>

    <dt><k name="C-@" link="false"/></dt>
    <dd>Press the ‘@’ key while holding the ‘Control’ key.</dd>

    <dt><k name="S-Space" link="false"/></dt>
    <dd>Press the space bar while holding the ‘Shift’ key.</dd>

    <dt><k name="C-A-j" link="false"/></dt>
    <dd>Press the ‘J’ key while holding both the ‘Control’ and ‘Alt’ keys.</dd>

    <dt><k name="C-A-J" link="false"/></dt>
    <dd>Exactly the same as above.</dd>

    <dt><k name="C-A-S-j" link="false"/></dt>
    <dd>Press the ‘J’ key while holding all of ‘Control’, ‘Alt’, and ‘Shift’ keys.</dd>
</dl>

<h3 tag=":map-special-chars">Special characters</h3>

<item>
    <tags><![CDATA[<Nop>]]></tags>
    <strut/>
    <spec><![CDATA[<Nop>]]></spec>
    <description>
        <p>
            Do nothing. This pseudo-key is useful for disabling a
            specific builtin mapping. For example,
            <ex>:map <k name="C-n"/> <k name="Nop"/></ex> will prevent <k name="C-n"/>
            from doing anything.
        </p>
    </description>
</item>

<item>
    <tags><![CDATA['mapleader' <Leader>]]></tags>
    <strut/>
    <spec><![CDATA[<Leader>]]></spec>
    <description>
        <p>
            An arbitrary and meaningless key that some people seem
            attached to. The <k>\</k> key will, by default, emit
            this pseudo-key so that it can be used at the start of
            other mappings. Note, however, that there is nothing
            special about it and any key can be mapped to emit any
            other arbitrary pseudo-key in the same way.
        </p>

        <code><ex>:map , <k name="Leader"/></ex>
<ex>:map ; <k name="AwesomestLeaderEver"/></ex>

<ex>:map <k name="Leader"/>k <key>-js</key> doStuff()</ex>
<ex>:map <k name="AwesomestLeaderEver"/>k <key>-js</key> doOtherReallyNiftyStuff()</ex></code>

        <p>
            Needless to say this behavior is considered childish and
            discouraged.
        </p>
    </description>
</item>

<item>
    <tags><![CDATA[<Pass>]]></tags>
    <spec><![CDATA[<Pass>]]></spec>
    <description short="true">
        <p>
            Pass the events consumed by the last executed mapping through to &dactyl.host;.
        </p>
    </description>
</item>

<item>
    <tags><![CDATA[<CR> map_return]]></tags>
    <strut/>
    <spec><![CDATA[<CR>]]></spec>
    <description>
        <p>
            Expand to a line terminator in a key mapping. An Ex command in the <a>rhs</a> of a
            mapping requires a line terminator after it so that it is executed when the
            mapping is expanded. <k name="CR"/> should be used for this purpose.
        </p>
    </description>
</item>

<h3 tag="map-examples">Mapping examples</h3>

<p>Make <k name="A-n" link="false"/> do the same as <k name="Down" link="false"/> in input <t>modes</t>:</p>

<code><ex>:map</ex> <em>-b</em> <em>-m</em> input <k name="A-n" link="false"/> <k name="Down" link="false"/></code>

<p>Toggle the tab line with <k name="A-t" link="false"/>:</p>

<code><ex>:map</ex> <em>-ex</em> <k name="A-t" link="false"/> <se opt="showtabline" op="!="><str delim="">always</str>,<str delim="">never</str></se></code>

<p>Make <k name="A-i" link="false"/> toggle image display:</p>

<code><ex>:map</ex> <k name="A-i" link="false"/> <em>-js</em> &lt;&lt;<em>EOF</em>
let (pref = <str>permissions.default.image</str>)
    prefs.set(pref, prefs.get(pref) == 1 ? 2 : 1);
tabs.reload(config.browser.mCurrentTab);
<em>EOF</em></code>


<h2 tag="bypassing-&dactyl.name;">Bypassing &dactyl.appName;</h2>

&dactyl.appName; overrides nearly all &dactyl.host; keys in order to
make browsing more pleasant for Vim users. On the occasions when you
want to bypass &dactyl.appName;'s key handling and pass keys directly to
&dactyl.host; or to a web page, you have several options:

<item>
    <tags><![CDATA[<pass-next-key-builtin> <A-b>]]></tags>
    <spec><![CDATA[<A-b>]]></spec>
    <description>
        <p>
            Process the next key as a builtin mapping, ignoring any user defined
            mappings and <o>passkeys</o> settings.
        </p>
    </description>
</item>

<item>
    <tags><![CDATA[send-key <pass-next-key> <C-v>]]></tags>
    <spec><![CDATA[<C-v>]]></spec>
    <description>
        <p>
            Pass the next key press directly to &dactyl.host;.
        </p>
    </description>
</item>

<item>
    <tags><![CDATA[pass-through <pass-all-keys> <C-z>]]></tags>
    <spec><![CDATA[<C-z>]]></spec>
    <description>
        <p>
            Pass all keys except for <k name="Esc"/> directly to
            &dactyl.host;. When <k name="Esc"/> is pressed,
            resume normal key handling. This is especially useful
            for web sites which make heavy use of key bindings.
        </p>
    </description>
</item>

<p>
    See also <o>passkeys</o> and <o>passunknown</o> for ways to permanently pass
    all or particular keys under certain conditions.
</p>

<h2 tag="abbreviations">Abbreviations</h2>

<p>
    In addition to basic mappings, &dactyl.appName; can also
    automatically replace whole words after they've been typed.
    These shortcuts are known as abbreviations, and are most often
    useful for correcting spelling of commonly mistyped words, as
    well as shortening the typing of oft-typed but long words or
    phrases. There are three basic types of abbreviations, defined
    by the types of characters they contain,
</p>

<ul>
    <li>‘full-id’ abbreviations consist entirely of keyword characters (e.g., ‘teh’, ‘msoft’).</li>
    <li>‘end-id’ abbreviations end in keyword character but otherwise contains all non-keyword characters (e.g., ‘'i’).</li>
    <li>‘non-id’ abbreviations end in a non-keyword character but otherwise contains any non-whitespace character (e.g., ‘def'’).</li>
    <li>Strings which fit none of the above patterns can not be defined as abbreviations (e.g., ‘a'b’ and ‘a b’).</li>
</ul>

<p>
    For the purposes of abbreviations, keyword characters include
    all non-whitespace characters except for single or double
    quotation marks. Abbreviations are expanded as soon as any
    non-keyword character, or the key <k name="C-]" mode="c"/>, is typed.
</p>

<item>
    <tags>:ab :abbreviate</tags>
    <spec>:ab<oa>breviate</oa> <oa>-group=<a>group</a></oa> <oa>-js</oa> <a>lhs</a> <a>rhs</a></spec>
    <spec>:ab<oa>breviate</oa> <oa>-group=<a>group</a></oa> <a>lhs</a></spec>
    <spec>:ab<oa>breviate</oa> <oa>-group=<a>group</a></oa></spec>
    <description>
        <p>
            Abbreviate <a>lhs</a> to <a>rhs</a>. If only <a>lhs</a>
            is given, list all abbreviations that start with
            <a>lhs</a>. If no arguments are given, list all
            abbreviations.
        </p>

        <p>
            If the <em>-javascript</em> (short names <em>-js</em>,
            <em>-j</em>) option is given, <a>lhs</a> is expanded to
            the value <em>return</em>ed by the JavaScript code
            <a>rhs</a>. The code is evaluated with the variable
            <em>editor</em> set to the editable element that the
            abbreviation is currently being expanded in. The code
            should <em>not</em> make any changes to the contents of
            the editor.
        </p>

        <p>
            If <a>group</a> is specified then abbreviations are created or
            listed for the given <t>group</t>.
        </p>
    </description>
</item>

<item>
    <tags>:ca :cabbreviate</tags>
    <spec>:ca<oa>bbreviate</oa> <a>lhs</a> <a>rhs</a></spec>
    <spec>:ca<oa>bbreviate</oa> <a>lhs</a></spec>
    <spec>:ca<oa>bbreviate</oa></spec>
    <description>
        <p>
            Abbreviate a key sequence for Command Line mode. Same as
            <ex>:ab<oa>breviate</oa></ex>, but for &mode.command-line; mode
            only.
        </p>
    </description>
</item>

<item>
    <tags>:ia :iabbreviate</tags>
    <spec>:ia<oa>bbreviate</oa> <a>lhs</a> <a>rhs</a></spec>
    <spec>:ia<oa>bbreviate</oa> <a>lhs</a></spec>
    <spec>:ia<oa>bbreviate</oa></spec>
    <description>
        <p>
            Abbreviate a key sequence for Insert mode. Same as
            <ex>:ab<oa>breviate</oa></ex>, but for Insert mode only.
        </p>
    </description>
</item>

<item>
    <tags>:una :unabbreviate</tags>
    <spec>:una<oa>bbreviate</oa> <a>lhs</a></spec>
    <spec>:una<oa>bbreviate</oa>!</spec>
    <description>
        <p>Remove an abbreviation. With <oa>!</oa>, remove all abbreviations.</p>
    </description>
</item>

<item>
    <tags>:cuna :cunabbreviate</tags>
    <spec>:cuna<oa>bbreviate</oa> <a>lhs</a></spec>
    <spec>:cuna<oa>bbreviate</oa>!</spec>
    <description>
        <p>
            Remove abbreviation(s) for Command Line mode. Same as
            <ex>:una<oa>bbreviate</oa></ex>, but for &mode.command-line; mode
            only.
        </p>
    </description>
</item>

<item>
    <tags>:iuna :iunabbreviate</tags>
    <spec>:iuna<oa>bbreviate</oa> <a>lhs</a></spec>
    <spec>:iuna<oa>bbreviate</oa>!</spec>
    <description>
        <p>
            Remove abbreviation(s) for Insert mode. Same as
            <ex>:una<oa>bbreviate</oa></ex> but for Insert mode
            only.
        </p>
    </description>
</item>

<h2 tag="user-commands">User-defined commands</h2>

<p>
    Defining new commands is perhaps the most straightforward way of
    repeating commonly used actions. User-defined commands may be
    entered from the command line or scripts exactly like standard
    commands, and may similarly accept arguments, options, counts,
    and <oa>!</oa>s, as well as provide command-line completion.
    These commands may be defined as either ordinary,
    macro-interpolated Ex commands, or otherwise as plain
    JavaScript statements.
</p>

<item>
    <tags>:com :command</tags>
    <spec>:com<oa>mand</oa></spec>
    <description short="true">
        <p>List all user-defined commands.</p>
    </description>
</item>

<item>
    <spec>:com<oa>mand</oa> <oa>cmd</oa></spec>
    <description>
        <p>
            List all user-defined commands that start with <oa>cmd</oa>. Commands
            are partitioned into <t>groups</t>.
        </p>
    </description>
</item>

<item>
    <spec>:com<oa>mand</oa><oa>!</oa> <oa><a>options</a>…</oa> <a>cmd</a> <a>rep</a></spec>
    <description>
        <p>
            Define a new user command. The name of the command is
            <a>cmd</a> and its replacement text is <a>rep</a>. If a
            command with this name already exists, an error is
            reported unless <oa>!</oa> is specified, in which case
            the command is redefined. Unlike Vim, the command may
            start with a lowercase letter. <a>cmd</a> may also be multiple
            alternative command names separated by commas.
        </p>

        <p>
            The new command is usually defined by a string to be
            executed as an Ex command. In this case, before
            execution, strings of the form
            <hl key="HelpKey">&lt;<a>var</a>></hl> are interpolated
            as described below, in order to insert arguments,
            options, and the like. If the <em>-javascript</em> (short
            name <em>-js</em>) flag is present, the command is
            executed as JavaScript, and the arguments are present as
            variables in its scope instead, and no interpolation is
            performed.
        </p>

        <p>
            The command's behavior can be altered by providing
            options when the command is defined.
        </p>

        <h3 tag=":command-group">Grouping</h3>

        <p>
            The <em>-group</em> flag (short name: <em>-g</em>) can be used to
            assign this command to a specific <t>group</t>.  When listing
            commands this limits the output to the specified group.
        </p>

        <h3 tag="E175 E176 :command-nargs">Argument handling</h3>

        <p>
            By default, user commands accept no arguments. This can be changed by specifying
            the <em>-nargs</em> option.
        </p>

        <p>The valid values are:</p>

        <dl>
            <dt>-nargs=0</dt><dd>No arguments are allowed (default)</dd>
            <dt>-nargs=1</dt><dd>One argument is allowed</dd>
            <dt>-nargs=*</dt><dd>Zero or more arguments are allowed</dd>
            <dt>-nargs=?</dt><dd>Zero or one argument is allowed</dd>
            <dt>-nargs=+</dt><dd>One or more arguments are allowed</dd>
        </dl>

        <h3 tag="E180 E181 :command-complete">Argument completion</h3>

        <p>
            Completion for arguments to user-defined commands is not available by default.
            Completion can be enabled by specifying one of the following arguments to the
            <em>-complete</em> option when defining the command.
        </p>

        <dl tag=":command-complete-arg-list"/>

        <h3 tag="E467 E468 :command-completion-custom">Custom completion</h3>

        <p>
            Custom completion can be provided by specifying the
            <str>custom,<a>thing</a></str> argument to <em>-complete</em>. If
            <a>thing</a> evaluates to a function (i.e., it is a variable holding
            a function value, or a string containing the definition itself), it
            is called with two arguments: a completion context, and an object
            describing the command's arguments. It should set the context's
            <tt>completions</tt> property to the list of completion results.
            Other influential properties include <tt>title</tt>, <tt>sort</tt>,
            <tt>anchored</tt>, and <tt>filters</tt>, which are documented in the
            <link topic="resource://dactyl/completion.jsm"
                line="17" dactyl:command="buffer.viewSource">source code</link>.
        </p>

        <p>
            <em>completions</em> is a two-dimensional array of the form:
            <tt>[[val1, description1], [val2, description2], …]</tt>
        </p>

        <p>
            Otherwise <a>thing</a> should evaluate to an array of the same form
            as the <tt>completions</tt> property of the context object.
        </p>

        <p>
            Example:
            <code><ex>:command foo -nargs=? -complete custom,<str delim="'">
    \ function (context) context.completions = [["val1", "description1"], ["val2", "description2"]]</str>
    \ <ex>:echo</ex> <str>Useless </str> + <em>&lt;q-args></em></ex>

<ex>:command foo -nargs=?
    \ -complete custom,<str delim="'">[["val1", "description1"], ["val2", "description2"]]</str>
    \ <ex>:echo</ex> <str>Same as above but simpler </str> + <em>&lt;q-args></em></ex></code>
        </p>

        <h3 tag="E177 E178 :command-count">Count handling</h3>

        <p>
            By default, user commands do not accept a count. Use the <em>-count</em> option if
            you'd like to have a count passed to your user command. This will then be
            available for expansion as &lt;count> in the replacement.
        </p>

        <h3 tag=":command-bang">Special cases</h3>

        <p>
            By default, a user command does not have a special version, i.e. a version
            executed with the ! modifier. Providing the <em>-bang</em> option will enable this
            and &lt;bang> will be available in the replacement.
        </p>

        <h3 tag=":command-description">Command description</h3>

        <p>
            The command's description text can be set with <em>-description</em>. Otherwise it will
            default to "User-defined command".
        </p>

        <h3 tag=":command-replacement-text">Replacement text</h3>

        <p>
            The replacement text <a>rep</a> is scanned for <t>macro-string</t>s and these are
            replaced with values from the user-entered command line. The resulting string
            is then executed as an Ex command.
        </p>

        <p>
            In addition to the standard parameters listed in
            <t>macro-string</t>, the following parameters are available:
        </p>

        <dl>
            <dt>&lt;args></dt> <dd>The command arguments exactly as supplied</dd>
            <dt>&lt;count></dt><dd>Any supplied count, e.g. 5</dd>
            <dt>&lt;bang></dt> <dd>! if the command was executed with the ! modifier</dd>
        </dl>
    </description>
</item>

<item>
    <tags>:delc :delcommand</tags>
    <spec>:delc<oa>ommand</oa> <a>cmd</a></spec>
    <spec>:delc<oa>ommand</oa>!</spec>
    <description>
        <p>Delete the user-defined command <a>cmd</a>. With <oa>!</oa>, delete
            all user commands.</p>
    </description>
</item>

<h3 tag="command-examples">Command examples</h3>

<p>A command to search via DuckDuckGo:</p>

<code><ex>:command</ex> <em>-nargs</em>=* <str delim="">ddg</str> open ddg &lt;args></code>

<p>
    A command to search for contents of the current selection using a
    tab-completed search engine in the current or a new tab (depending on how
    much you bang on the keyboard):
</p>

<code><ex>:com!</ex> <str delim="">search-selection</str>,<str delim="">ss</str> <em>-bang</em> <em>-nargs</em>=? <em>-complete</em> search
        \ <em>-js</em> commands.execute((bang ? <str>open </str> : <str>tabopen </str>)
        \ + args + <str> </str> + buffer.currentWord)</code>

</document>

<!-- vim:se sts=4 sw=4 et: -->