Pentadactyl 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.

Key mapping

Key mappings are the most basic means Pentadactyl provides
for altering the actions of key presses. Each key mapping is
associated with a mode, such as Insert,
Normal, or
Command Line, 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 :map command and its
variants. These commands, in essence, allow the user to quickly
substitute one sequence of key presses for another.
For instance,

Standard key mapping commands are provided for the five most
common modes,

n

Normal mode: When browsing normally

v

Visual mode: When selecting text with the cursor keys

i

Insert mode: When interacting with text fields on a website

t

Text Edit mode: When editing text fields in Vim-like Normal mode

c

Command Line mode: When typing into the Pentadactyl command line

The ordinary :map and :noremap 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,
:imap creates a new key mapping in Insert mode, while
:cunmap removes a key mapping from Command Line mode.
Other modes can be specified using the -modes option described below.

Warning:
It is important to note that mappings are not
automatically saved between sessions. In order to preserve them,
they must either be added to your pentadactylrc or
saved via the :mkpentadactylrc command.

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.

Base: The base mode for all other modes

Main: The base mode for most other modes

Command: The base mode for most modes which accept commands rather than input

Normal: Active when nothing is focused

Caret: Active when the caret is visible in the web content

Output Multiline: Active when the multi-line output buffer is open

Text Edit: Vim-like editing of input elements

Visual: Active when text is selected

Input: The base mode for input modes, including Insert and Command Line

Command Line: Active when the command line is focused

Ex: Ex command mode, active when the command line is open for Ex commands

File Input: Active when selecting a file

Find: Find mode, active when typing search input

Find Backward: Backward Find mode, active when typing search input

Find Forward: Forward Find mode, active when typing search input

Hints: Active when selecting elements with hints

Prompt: Active when a prompt is open in the command line

REPL: JavaScript Read Eval Print Loop

Embed: Active when an <embed> or <object> element is focused

Insert: Active when an input element is focused

Autocomplete: Active when an input autocomplete pop-up is active

Menu: Active when a menu or other pop-up is open

Pass Through: All keys but <C-v> are ignored by Pentadactyl

Quote: The next key sequence is ignored by Pentadactyl, unless in Pass Through mode

Map the key-sequence{lhs} to {rhs} for
the applicable mode(s). The keys in {rhs} do not
respect user-defined key mappings, so the following
effectively reverses the default meanings of the keys
d and D

Mapping timeout

When Pentadactyl receives a key event that has a separate binding and
at the same time is part of a key chain, values of the 'timeout' and
'timeoutlen' options are used to decide what to do. See the
documentation of those options for more information.

Key sequences

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.

The first argument to the :map commands must be
quoted if it contains spaces,
quotation marks or back-slashes. A space may additionally be
typed as <Space>.

As special key names start with the < character,
a literal < must be typed as <lt>.

Expand to a line terminator in a key mapping. An Ex command in the {rhs} of a
mapping requires a line terminator after it so that it is executed when the
mapping is expanded. <CR> should be used for this purpose.

Abbreviations

In addition to basic mappings, Pentadactyl 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,

‘end-id’ abbreviations end in keyword character but otherwise contains all non-keyword characters (e.g., ‘'i’).

‘non-id’ abbreviations end in a non-keyword character but otherwise contains any non-whitespace character (e.g., ‘def'’).

Strings which fit none of the above patterns can not be defined as abbreviations (e.g., ‘a'b’ and ‘a b’).

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 c_<C-]>, is typed.

Abbreviate {lhs} to {rhs}. If only {lhs}
is given, list all abbreviations that start with
{lhs}. If no arguments are given, list all
abbreviations.

If the -javascript (short names -js,
-j) option is given, {lhs} is expanded to
the value returned by the JavaScript code
{rhs}. The code is evaluated with the variable
editor set to the editable element that the
abbreviation is currently being expanded in. The code
should not make any changes to the contents of
the editor.

If {group} is specified then abbreviations are created or
listed for the given group.

User-defined commands

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 [!]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.

List all user-defined commands that start with [cmd]. Commands
are partitioned into groups.

:com[mand][!][{options}…]{cmd}{rep}

Define a new user command. The name of the command is
{cmd} and its replacement text is {rep}. If a
command with this name already exists, an error is
reported unless [!] is specified, in which case
the command is redefined. Unlike Vim, the command may
start with a lowercase letter. {cmd} may also be multiple
alternative command names separated by commas.

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
<{var}> are interpolated
as described below, in order to insert arguments,
options, and the like. If the -javascript (short
name -js) 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.

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

Custom completion

Custom completion can be provided by specifying the
custom,{thing} argument to -complete. If
{thing} 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
completions property to the list of completion results.
Other influential properties include title, sort,
anchored, and filters, which are documented in the
source code.

completions is a two-dimensional array of the form:
[[val1, description1], [val2, description2], …]

Otherwise {thing} should evaluate to an array of the same form
as the completions property of the context object.

Count handling

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.