Key mappings, abbreviations, and user-defined commands

Key mapping

The key mapping commands can be used to either redefine the standard key bindings or define new ones. A mapping consists of a key, or key-sequence, which is translated to a string of characters. Example:

:map :echo new Date().toDateString()

will echo the current date to the command line when is pressed.

:map-modes

Keys can be mapped in four distinct modes:

Mappings are NOT saved between sessions, make sure you put them in your &liberator.name;rc file!

Map commands

:map :map lhs rhs :nm :nmap :nmap lhs rhs :vm :vmap :vmap lhs rhs :im :imap :imap lhs rhs :cm :cmap :cmap lhs rhs

Map the key-sequence lhs to rhs for the applicable mode(s). The rhs is remapped, allowing for nested and recursive mappings.

:no :noremap :noremap lhs rhs :nn :nnoremap :nnoremap lhs rhs :vn :vnoremap :vnoremap lhs rhs :ino :inoremap :inoremap lhs rhs :cno :cnoremap :cnoremap lhs rhs

Map the key-sequence lhs to rhs for the applicable mode(s). No remapping of the rhs is performed.

:unm :unmap :map lhs rhs :nun :nunmap :nunmap lhs rhs :vun :vunmap :vunmap lhs rhs :iu :iunmap :iunmap lhs rhs :cu :cunmap :cunmap lhs rhs

Remove the mapping of lhs for the applicable mode(s).

 :mapc :mapclear :mapclear :nmapc :nmapclear :nmapclear :vmapc :vmapclear :vmapclear :imapc :imapclear :imapclear :cmapc :cmapclear :cmapclear

Remove all mappings for the applicable mode(s). All user-defined mappings are cleared.

:map :nmap :vmap :imap :cmap

List all mappings for the applicable mode(s).

 :map_l :map lhs :nmap_l :nmap lhs :vmap_l :vmap lhs :imap_l :imap lhs :cmap_l :cmap lhs

List all mappings starting with lhs for the applicable mode(s).

Special arguments

:map-<silent>

When the first argument to one of the mapping commands is , rhs is not echoed to the command line, nor, for that matter, anything else until the command has completed.

Below is an overview of which modes each map command applies to:

:map :noremap :unmap :mapclear – both Normal and Visual modes :nmap :nnoremap :nunmap :nmapclear – Normal mode :vmap :vnoremap :vunmap :vmapclear – Visual mode :imap :inoremap :iunmap :imapclear – Insert mode :cmap :cnoremap :cunmap :cmapclear – Command-line mode

Key sequences

For most keys, the key-sequence is the same as the character you see when you type that key, however there are some exceptions which allow for a much larger number of keys to be used in mappings.

Most keyboards have some modifiers such as the control, alt or meta keys. In order to create a mapping that uses these keys the correct prefix must be used within the angle brackets.

  1. : The control or ctrl key.
  2. : The alt key.
  3. : The meta key, windows key, or command key
  4. : The shift key.

These prefixes can be combined however you see fit, though you should note that within angle brackets all alphabetic characters are read as lowercase. In order to force them to be uppercase, you must specify the S- prefix as well. Additionally, you should never use the S- prefix with a number or piece of punctuation, even if you require a shift to type that character; doing so will give you a mapping that cannot be typed. With non-character keys, tab and space, the S- modifier works just like C- A- and M-. Some examples may clarify the situation:

  1. xc: type x, and then type c
  2. c: hold control and type x, then type c without control
  3. : type 2 while holding control
  4. : type @ while holding control
  5. : press space while holding shift
  6. : press j while holding control and alt
  7. : exactly the same as above
  8. : press J while holding control and alt

Special characters

]]> <Nop>

Do nothing. This command is useful for disabling a specific mapping. :map will prevent from doing anything.

map_return]]> <CR>

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. should be used for this purpose.

mapleader]]> <Leader>

Expands to the value of the "mapleader" variable in key mapping. If "mapleader" is unset or empty then \ is used. Example:

:map h :echo Hello

works like

:map \h :echo Hello

but after

let mapleader = ,

it works like

:map ,h :echo Hello

Abbreviations

&liberator.appname; can automatically replace words identified as abbreviations, which may be used to save typing or to correct commonly misspelled words. An abbreviation can be one of three types that are defined by the types of constituent characters. Whitespace and quotes are non-keyword types, and all other characters are keyword types.

  1. A "full-id" abbreviation consists entirely of keyword characters (e.g., "teh", "msoft").
  2. An "end-id" abbreviation ends in keyword character but otherwise contains all non-keyword characters (e.g., "'i").
  3. A "non-id" abbreviation ends in a non-keyword character but otherwise contains any non-whitespace character (e.g., "def'").

Strings that cannot be abbreviations include "a'b" and "a b".

An abbreviation is recognized when a space, quote character, or is typed after the abbreviation. There are no default abbreviations, and abbreviations are never recursive.

:ab :abbreviate :abbreviate lhs rhs :abbreviate lhs :abbreviate

Abbreviate a key sequence. Abbreviate lhs to rhs. If only lhs is given, list all abbreviations that start with lhs. If no arguments are given, list all abbreviations.

:ca :cabbrev :cabbrev lhs rhs :cabbrev lhs :cabbrev

Abbreviate a key sequence for Command-line mode. Same as :abbreviate, but for Command-line mode only.

:ia :iabbrev :iabbrev lhs rhs :iabbrev lhs :iabbrev

Abbreviate a key sequence for Insert mode. Same as :abbreviate but for Insert mode only.

:una :unabbreviate :unabbreviate lhs

Remove an abbreviation.

 :cuna :cunabbrev :cunabbrev lhs

Remove an abbreviation for Command-line mode. Same as :unabbreviate, but for Command-line mode only.

:iuna :iunabbrev :iunabbrev lhs

Remove an abbreviation for Insert mode. Same as :unabbreviate but for Insert mode only.

:abc :abclear :abclear

Remove all abbreviations.

 :cabc :cabclear :cabclear

Remove all abbreviations for Command-line mode.

 :iabc :iabclear :iabclear

Remove all abbreviations for Insert mode.

User-defined commands

:com :command :command

List all user-defined commands.

 :command cmd

List all user-defined commands that start with cmd.

 :command! attr… cmd rep

Define a new user command. The name of the command is cmd and its replacement text is rep. The command's attributes are attr. 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.

The command's behavior can be specified by providing attributes when the command is defined.

Argument handling

By default user commands accept no arguments. This can be changed by specifying the -nargs attribute.

The valid values are:

-nargs=0
No arguments are allowed (default)
-nargs=1
One argument is allowed
-nargs=*
Zero or more arguments are allowed
-nargs=?
Zero or one argument is allowed
-nargs=+
One or more arguments are allowed

Argument completion

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.

altstyle
alternate author style sheets
bookmark
bookmarks
buffer
buffers
color
color schemes
command
Ex commands
dialog
&liberator.host; dialogs
dir
directories
environment
environment variables
event
autocommand events
file
files
help
help tags
highlight
highlight groups
javascript
JavaScript expressions
macro
named macros
mapping
user mappings
menu
menu items
option
&liberator.appname; options
preference
&liberator.host; preferences
search
search engines and keywords
shellcmd
shell commands
sidebar
sidebar panels
url
URLs
usercommand
user commands
custom,func
custom completion, provided by func

Custom completion

Custom completion can be provided by specifying the custom,func argument to -complete. The func is called with two arguments, a completion context, and an object describing the command's arguments. It should set the context's completions property, or return an object, with items and start properties, describing the completions and where the replacement is to start.

start is the index into the word being completed at which the returned values should be applied and completions is a two dimensional array of the form: [[arg1, description1], [arg2, description2], …]

Count handling

By default user commands do not accept a count. Use the -count attribute if you'd like to have a count passed to your user command. This will then be available for expansion as <count> in the argument.

Special cases

By default a user command does not have a special version, i.e. a version executed with the ! modifier. Providing the -bang attribute will enable this and <bang> will be available in the argument.

Command description

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

Replacement text

The replacement text rep is scanned for escape sequences and these are replaced with values from the user-entered command line. The resulting string is then executed as an Ex command.

The valid escape sequences are:

<args>
The command arguments exactly as supplied
<count>
Any supplied count, e.g. 5
<bang>
! if the command was executed with the ! modifier
<lt>
A literal '<' character to allow for a literal copy of one of the escape sequences. E.g., <lt>args> will expand to a literal <args>

"q-" can be prefixed to the escape sequence so that the value is quoted, making it suitable for expression evaluation. Example: <q-args>

:comc :comclear :comclear

Delete all user-defined commands.

 :delc :delcommand :delcommand cmd

Delete the user-defined command cmd.

Examples

Add a :Google command to search via google:

:command -nargs=* Google open google <args>