From b5f81976c5427177e16633cca1fff2e24f779ef4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=A0t=C4=9Bp=C3=A1n=20N=C4=9Bmec?= Date: Wed, 19 Jan 2011 13:38:18 +0100 Subject: [PATCH] Document the :command improvements added in the previous changeset. --- common/locale/en-US/map.xml | 60 ++++++++++++++++++++------------ melodactyl/locale/en-US/map.xml | 2 +- pentadactyl/NEWS | 3 ++ pentadactyl/locale/en-US/map.xml | 2 +- teledactyl/locale/en-US/map.xml | 2 +- 5 files changed, 43 insertions(+), 26 deletions(-) diff --git a/common/locale/en-US/map.xml b/common/locale/en-US/map.xml index 6bbf9686..13ffa3bd 100644 --- a/common/locale/en-US/map.xml +++ b/common/locale/en-US/map.xml @@ -556,7 +556,7 @@ - :command! attr… cmd rep + :command! options… cmd rep

Define a new user command. The name of the command is @@ -564,7 +564,8 @@ 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. + start with a lowercase letter. cmd may also be multiple + alternative command names separated by commas.

@@ -582,14 +583,14 @@

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

Argument handling

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

The valid values are:

@@ -615,11 +616,15 @@

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. + 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, or return an object with + items and start properties describing the + completions and where the replacement is to start.

@@ -628,22 +633,36 @@ [[arg1, description1], [arg2, description2], …]

- +

+ Otherwise thing should be an array of the same form as the + completions property of the context object. +

+ +

+ Example: + :command foo -complete custom, +\ function (context) context.completions = [["arg1", "description1"], ["arg2", "description2"]] +\ :echo Useless + +:command foo -complete custom,[["arg1", "description1"], ["arg2, "description2"]] +\ :echo Same as above but simpler + +

Count handling

- By default, user commands do not accept a count. Use the -count attribute if + 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 argument. + available for expansion as <count> in the replacement.

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. + executed with the ! modifier. Providing the -bang option will enable this + and <bang> will be available in the replacement.

Command description

@@ -656,27 +675,22 @@

Replacement text

- The replacement text rep is scanned for escape sequences and these are + The replacement text rep is scanned for macro strings 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:

+

The valid macro strings 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> -
+
<lt>
A literal '<' character

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

diff --git a/melodactyl/locale/en-US/map.xml b/melodactyl/locale/en-US/map.xml index 103abdb5..e8b1e129 100644 --- a/melodactyl/locale/en-US/map.xml +++ b/melodactyl/locale/en-US/map.xml @@ -43,7 +43,7 @@
toolbar
toolbars
url
URLs
usercommand
user commands
-
custom,func
custom completion, provided by func
+
custom,thing
custom completion, provided by thing
diff --git a/pentadactyl/NEWS b/pentadactyl/NEWS index 94862607..da191ad6 100644 --- a/pentadactyl/NEWS +++ b/pentadactyl/NEWS @@ -84,6 +84,9 @@ - Added :yank command. - :delmarks, :marks and :qmarks now also accept ranges, same as :delqmarks. + - :command now accepts comma-separated alternative command names + - :command -complete custom now also accepts a completions array, see + :h :command-completion-custom. * Improvements to :style and :highlight: - Added -agent flag to :style. - The -append flag now updates existing properties rather than diff --git a/pentadactyl/locale/en-US/map.xml b/pentadactyl/locale/en-US/map.xml index 0245b700..054fad3d 100644 --- a/pentadactyl/locale/en-US/map.xml +++ b/pentadactyl/locale/en-US/map.xml @@ -40,7 +40,7 @@
url
URLs
usercommand
user commands
window
windows
-
custom,func
custom completion, provided by func
+
custom,thing
custom completion, provided by thing
diff --git a/teledactyl/locale/en-US/map.xml b/teledactyl/locale/en-US/map.xml index 672f78cb..4038530f 100644 --- a/teledactyl/locale/en-US/map.xml +++ b/teledactyl/locale/en-US/map.xml @@ -39,7 +39,7 @@
toolbar
toolbars
url
URLs
usercommand
user commands
-
custom,func
custom completion, provided by func
+
custom,thing
custom completion, provided by thing