add rough -nargs, -bang and -count support to :command

NEWS

@@ -7,6 +7,7 @@
       special versions for the old behavior
     * IMPORTANT: renamed Startup and Quit autocmd events to VimperatorEnter and
       VimperatorLeave respectively
+    * add -nargs, -bang, and -count attribute support to :command
     * much improved completion support, including javascript, option, and search keyword
     * add <PageUp>/<S-Up> and <PageDown>/<S-Down> command-line mappings for
       selecting the previous and next history items
@@ -323,7 +324,6 @@
     * showmode setting which shows the current mode in the command line (patch from Виктор Кожухаров)
     * gh goes home :) gH in a new tab
     * :open! bypasses cache
-    
     * :buffer and :buffers support (patch from Lars Kindler)
     * added :edit, :e and :tabedit aliases for :open, :tabopen
     * settings can now be changed with += and -= like in vim (patch from Виктор Кожухаров)

content/commands.js

@@ -235,6 +235,8 @@ liberator.Commands = function () //{{{
             description = description || "User defined command";
 
             var command = new liberator.Command(names, description, action, extra);
+            // FIXME: shouldn't this be testing for an existing command by name?
+            // Requiring uppercase user command names like Vim would be easier
             if (!command)
                 return false;
 
@@ -255,6 +257,7 @@ liberator.Commands = function () //{{{
             }
 
             exCommands.push(command);
+
             return true;
         },
 
@@ -318,7 +321,7 @@ liberator.Commands = function () //{{{
         parseArgs: function (str, options, argCount, allowUnknownOptions) //{{{
         {
             // returns [count, parsed_argument]
-            function getNextArg(str)
+            function getNextArg(str) // {{{
             {
                 var inSingleString = false;
                 var inDoubleString = false;
@@ -415,7 +418,7 @@ liberator.Commands = function () //{{{
                     return [-1, "trailing \\"];
                 else
                     return [str.length, arg];
-            }
+            } // }}}
 
             if (!options)
                 options = [];
@@ -426,6 +429,8 @@ liberator.Commands = function () //{{{
             var args = {};       // parsed options
             args.arguments = []; // remaining arguments
             args.string = str;   // for access to the unparsed string
+            // FIXME: quick hack! Best way to do this? -- djk
+            args.argumentsString = "";
 
             var invalid = false;
             var onlyArgumentsRemaining = allowUnknownOptions || false; // after a -- has been found
@@ -452,7 +457,7 @@ liberator.Commands = function () //{{{
                 }
 
                 var optname = "";
-                if (!onlyArgumentsRemaining)
+                if (!onlyArgumentsRemaining) //{{{
                 {
                     for (let opt = 0; opt < options.length; opt++)
                     {
@@ -578,7 +583,11 @@ liberator.Commands = function () //{{{
                             }
                         }
                     }
-                }
+                } //}}}
+
+                // FIXME: quick hack! -- djk
+                if (!args.argumentsString)
+                    args.argumentsString = str.substr(i);
 
                 // if not an option, treat this token as an argument
                 var [count, arg] = getNextArg(sub);
@@ -674,35 +683,74 @@ liberator.Commands = function () //{{{
     ////////////////////// COMMANDS ////////////////////////////////////////////////
     /////////////////////////////////////////////////////////////////////////////{{{
 
+    // TODO: Vim allows commands to be defined without {rep} if there are {attr}s
+    // specified - useful?
     commandManager.add(["com[mand]"],
         "List and define commands",
         function (args, special)
         {
-            if (args)
+            if (args.argumentsString)
             {
-                var res = args.match(/^(\w+)(?:\s+(.+))?$/);
+                let matches = args.argumentsString.match(/^(\w+)(?:\s+(.+))?$/);
-                if (!res)
+
+                if (!matches)
                 {
                     liberator.echoerr("E182: Invalid command name");
-                    return false;
+                    return;
                 }
-                var [cmd, rep] = [res[1], res[2]];
+
+                var [cmd, rep] = [matches[1], matches[2]];
             }
 
             if (rep)
             {
-                if (!liberator.commands.addUserCommand([cmd],
+                let nargsOpt = args["-nargs"] || "0";
+                let bangOpt  = "-bang"  in args;
+                let countOpt = "-count" in args;
+
+                if (!liberator.commands.addUserCommand(
+                        [cmd],
                         "User defined command",
                         function (args, special, count, modifiers)
                         {
-                            var replaced = rep.replace("<args>", args);
+                            function replaceTokens(token)
-                            replaced = replaced.replace("<q-args>", '"' + args.replace('"', '\\"', "g") + '"');
+                            {
-                            replaced = replaced.replace("<lt>", "<");
+                                let ret;
+                                let quote = false;
 
-                            liberator.execute(replaced);
+                                // ignore quoting of <lt> like Vim, not needed for <count>
+                                if (/^<q-(?!(lt|count))[a-z]+>$/.test(token))
+                                    quote = true;
+
+                                token = token.replace("q-", "");
+
+                                switch (token)
+                                {
+                                    case "<args>":
+                                        ret = args.argumentsString;
+                                        break;
+                                    case "<bang>":
+                                        ret = bangOpt ? (special ? "!" : "") : token;
+                                        break;
+                                    case "<count>":
+                                        ret = countOpt ? (count > -1 ? count : 0) : token;
+                                        break;
+                                    case "<lt>":
+                                        ret = "<";
+                                        break;
+                                    default:
+                                        ret = token;
+                                }
+
+                                return quote ? '"' + ret.replace('"', '\\"', "g") + '"' : ret;
+                            }
+
+                            liberator.execute(rep.replace(/<(?:q-)?[a-z]+>/g, replaceTokens));
                         },
                         {
-                            bang: true, // FIXME: until we implement -bang
+                            argCount: nargsOpt,
+                            bang: bangOpt,
+                            count: countOpt,
                             replacementText: rep
                         },
                         special)
@@ -713,14 +761,17 @@ liberator.Commands = function () //{{{
             }
             else
             {
-                var cmdlist = getMatchingUserCommands(cmd);
+                let cmds = getMatchingUserCommands(cmd);
-                if (cmdlist.length > 0)
+
+                if (cmds.length > 0)
                 {
-                    var str = liberator.template.tabular(["Name", "Args", "Definition"], [],
+                    let str = liberator.template.tabular(["", "Name", "Args", "Range", "Definition"], ["padding-right: 2em;"],
-                        ([cmd.name,
+                        ([cmd.bang ? "!" : " ",
-                          "*",
+                          cmd.name,
-                          cmd.replacementText || "function () { ... }"]
+                          cmd.argCount,
-                            for each (cmd in cmdlist)));
+                          cmd.count ? "0c" : "",
+                          cmd.replacementText || "function () { ... }"] for each (cmd in cmds)));
+
                     liberator.commandline.echo(str, liberator.commandline.HL_NORMAL, liberator.commandline.FORCE_MULTILINE);
                 }
                 else
@@ -731,10 +782,12 @@ liberator.Commands = function () //{{{
         },
         {
             bang: true,
-            completer: function (filter) liberator.completion.userCommand(filter)
+            completer: function (filter) liberator.completion.userCommand(filter),
-            /*options: [[["-nargs"],    OPTION_STRING, function (arg) { return /^(0|1|\*|\?|\+)$/.test(arg); }],
+            options: [
-                   [["-bang"],     OPTION_NOARG],
+                [["-nargs"], commandManager.OPTION_STRING, function (arg) /^[01*?+]$/.test(arg), ["0", "1", "*", "?", "+"]],
-                   [["-bar"],      OPTION_NOARG]] */
+                [["-bang"],  commandManager.OPTION_NOARG],
+                [["-count"], commandManager.OPTION_NOARG],
+            ]
         });
 
     commandManager.add(["comc[lear]"],

locale/en-US/autocommands.txt

@@ -58,15 +58,15 @@ section:Examples[autocmd-examples]
 
 Enable _passthrough_ mode on all Google sites:
 
-  :au LocationChange .* js modes.passAllKeys = /google\.com/.test(buffer.URL)
+  :autocmd LocationChange .* js modes.passAllKeys = /google\.com/.test(buffer.URL)
 
 Enable _passthrough_ mode on *some* Google sites:
 
-  :au LocationChange .* js modes.passAllKeys = /(www|mail)\.google\.com/.test(buffer.URL)
+  :autocmd LocationChange .* js modes.passAllKeys = /(www|mail)\.google\.com/.test(buffer.URL)
 
 Set the filetype to mail when editing email at Gmail:
 
-  :au LocationChange .* :set editor=gvim -f
+  :autocmd LocationChange .* :set editor=gvim -f
-  :au LocationChange mail\.google\.com :set editor=gvim -f -c 'set ft=mail'
+  :autocmd LocationChange mail\.google\.com :set editor=gvim -f -c 'set ft=mail'
 
 // vim: set syntax=asciidoc:

locale/en-US/map.txt

@@ -55,8 +55,10 @@ ________________________________________________________________________________
 ||:map||
 ________________________________________________________________________________
 Map the key sequence {lhs} to {rhs}. The {rhs} is remapped, allowing for
-nested and recursive mappings. Mappings are NOT saved during sessions, make
+nested and recursive mappings.
-sure you put them in your vimperatorrc file!
+
+Warning: Mappings are NOT saved during sessions, make sure you put them in your
+vimperatorrc file!
 ________________________________________________________________________________
 
 
@@ -66,8 +68,10 @@ ________________________________________________________________________________
 ||:cmap||
 ________________________________________________________________________________
 Map the key sequence {lhs} to {rhs} (in Command-line mode). The {rhs} is
-remapped, allowing for nested and recursive mappings. Mappings are NOT saved
+remapped, allowing for nested and recursive mappings.
-during sessions, make sure you put them in your vimperatorrc file!
+
+Warning: Mappings are NOT saved during sessions, make sure you put them in your
+vimperatorrc file!
 ________________________________________________________________________________
 
 
@@ -77,8 +81,10 @@ ________________________________________________________________________________
 ||:imap||
 ________________________________________________________________________________
 Map the key sequence {lhs} to {rhs} (in insert mode). The {rhs} is remapped,
-allowing for nested and recursive mappings. Mappings are NOT saved during
+allowing for nested and recursive mappings.
-sessions, make sure you put them in your vimperatorrc file!
+
+Warning: Mappings are NOT saved during sessions, make sure you put them in your
+vimperatorrc file!
 ________________________________________________________________________________
 
 
@@ -248,11 +254,46 @@ ________________________________________________________________________________
 ||:com[mand][!] [{attr}...] {cmd} {rep}|| +
 ________________________________________________________________________________
 Define a new user command. The name of the command is {cmd} and its relacement
-text is {rep}.  The command's attributes are {attr}.  If a command with this
+text is {rep}. The command's attributes are {attr}. If a command with this name
-name already exists an error is reported unless [!] is specified, in which case
+already exists an error is reported unless [!] is specified, in which case the
-the command is redefined.  Unlike Vim, the command may start with a lowercase
+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.
+
+|E175| |E176| |:command-nargs| +
+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 argument is allowd
+--------------------------------------------------------------------------------
+
+|E177| |E178| |:command-count| +
+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.
+
+|:command-bang| +
+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-replacement-text| +
+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.
@@ -260,11 +301,13 @@ is then executed as an Ex command.
 The valid escape sequences are:
 `----------`--------------------------------------------------------------------
 *<args>*   The command arguments exactly as supplied
-*<q-args>* The command arguments quoted as a single value in a manner suitable for expression evaluation
+*<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>
 --------------------------------------------------------------------------------
 
-Note: {attr} not implemented yet.
+"q-" can be prefixed to the escape sequence so that the value is quoted, making
+it suitable for expression evaluation. Example: <q-args> 
 ________________________________________________________________________________
 
 
@@ -281,4 +324,12 @@ ________________________________________________________________________________
 Delete the user-defined command {cmd}.
 ________________________________________________________________________________
 
+section:Examples[command-examples]
+
+Add a :Google command to search via google:
+
+  :command -nargs=* Google open google <args>
+
+// TODO: add decent examples
+
 // vim: set syntax=asciidoc: