mirror of
https://github.com/gryf/pentadactyl-pm.git
synced 2025-12-27 14:42:27 +01:00
725 lines
26 KiB
XML
725 lines
26 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
||
<?xml-stylesheet type="text/xsl" href="dactyl://content/help.xsl"?>
|
||
|
||
<!DOCTYPE document SYSTEM "dactyl://content/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>:echo Date()<k name="CR"/></ex></code>
|
||
|
||
<p>
|
||
causes “<ex>:echo Date()<k name="CR"/></ex>” to be typed out
|
||
whenever <k name="F2" link="false"/> is pressed, thus echoing the full date
|
||
to the command line.
|
||
</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>TextEdit 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>
|
||
</dl>
|
||
|
||
<p>
|
||
The ordinary <ex>:map</ex> and <ex>:noremap</ex> commands
|
||
add 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 -modes 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 :noremap :unmap</dt> <dd>Normal and Visual modes</dd>
|
||
<dt>:nmap :nnoremap :nunmap</dt> <dd>Normal mode</dd>
|
||
<dt>:vmap :vnoremap :vunmap</dt> <dd>Visual mode</dd>
|
||
<dt>:imap :inoremap :iunmap</dt> <dd>Insert mode</dd>
|
||
<dt>:tmap :tnoremap :tunmap</dt> <dd>Text Edit mode</dd>
|
||
<dt>:cmap :cnoremap :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>)</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><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>
|
||
<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>">
|
||
As special key names start with the <em><</em> character,
|
||
a literal < 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="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>Type the ‘X’ key followed by the ‘C’ key.</dd>
|
||
|
||
<dt><k name="C-x" link="false">c</k></dt>
|
||
<dd>
|
||
Type the ‘X’ key while holding the ‘Control’ key, followed
|
||
by the ‘C’ key.
|
||
</dd>
|
||
|
||
<dt><k name="C-2" link="false"/></dt>
|
||
<dd>Type the ‘2’ while holding the ‘Control’ key.</dd>
|
||
|
||
<dt><k name="C-@" link="false"/></dt>
|
||
<dd>Type 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>Type the ‘J’ key while 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>Type the ‘J’ key while while holding both the ‘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[<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>
|
||
|
||
<item>
|
||
<tags><![CDATA[<Leader> \]]></tags>
|
||
<strut/>
|
||
<spec><![CDATA[<Leader>]]></spec>
|
||
<description>
|
||
<p>
|
||
A pseudo-key which expands to the value of the <o>mapleader</o>
|
||
option. For example, by default,
|
||
</p>
|
||
<code><ex>:map <k name="Leader"/>h</ex> <ex>:echo <str>Hello</str><k name="CR"/></ex></code>
|
||
<p>works like</p>
|
||
<code><ex>:map \h</ex> <ex>:echo <str>Hello</str><k name="CR"/></ex></code>
|
||
<p>but after</p>
|
||
<set opt="mapleader"><str>,</str></set>
|
||
<p>it works like</p>
|
||
<code><ex>:map ,h</ex> <ex>:echo <str>Hello</str><k name="CR"/></ex></code>
|
||
</description>
|
||
</item>
|
||
|
||
<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> <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
|
||
<t>command-line</t> 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
|
||
<t>command-line</t> 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"><<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>.
|
||
</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 <tt>-nargs</tt> 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
|
||
-complete 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 <tt>-complete</tt>. 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><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><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 -count option if
|
||
you'd like to have a count passed to your user command. This will then be
|
||
available for expansion as <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 -bang option will enable this
|
||
and <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 -description. 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><args></dt> <dd>The command arguments exactly as supplied</dd>
|
||
<dt><count></dt><dd>Any supplied count, e.g. 5</dd>
|
||
<dt><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>
|
||
|
||
<h2 tag="command-examples">Examples</h2>
|
||
|
||
<p>Add a :Google command to search via google:</p>
|
||
<code><ex>:command -nargs=* Google open google <args></ex></code>
|
||
|
||
<!-- TODO: add decent examples -->
|
||
|
||
</document>
|
||
|
||
<!-- vim:se sts=4 sw=4 et: -->
|