[Monotone-devel] [PATCH] allow Lua registered commands to have a proper parameter description

[Ralf S. Engelschall]

When using the recently introduced Lua command register_command() one
cannot specify a string describing the _parameters_ a command expects.
On "mtn <command> -h" or "mtn help <command>" the part "Syntax specific
to 'mtn <command>':" is always just an empty line. The reason simply is
because commands::cmd_lua() calls commands::command() with always an
empty string for the parameter description.

The following patch enhances the situation by introducing an additional
parameter to register_command() which is then passed through to
commands::command() and this way allows Lua registered commands to
show a proper parameter string on the help outputs (in case they have
parameters).

Backward compatibility is not an issue here as register_command() will
be released with Monotone 0.37 the first time. I've also adjusted the
documentation and the sample uses of register_command() in contrib/.

Any objections on the appended patch?

                                       Ralf S. Engelschall
                                       address@hidden
                                       www.engelschall.com

============================================================
--- contrib/extra-commands.lua  4ad86255ae43a32fbf1ad67f5328ff78075e322f
+++ contrib/extra-commands.lua  b5765df0e7533d406743d254a7038e8e7d876f08
@@ -9,7 +9,7 @@ end
     mtn_automate("update")
 end

-register_command("pup", "Pull and update a workspace",
+register_command("pup", "", "Pull and update a workspace",
       "This command approximates the update command of a centralised revision 
control system.  " ..
       "It first contacts the server to gather new revisions and then it 
updates the workspace.", "pup")

@@ -30,7 +30,7 @@ end
     end
 end

-register_command("cpp", "Commit, pull and push a workspace",
+register_command("cpp", "", "Commit, pull and push a workspace",
       "This command approximates the commit command of a centralised revision 
control system.  " ..
       "It first commits your work to the local repository, then contacts the 
server to gather " ..
       "new revisions.  If there is a single head at this point, then the local 
changes are pushed " ..
@@ -42,7 +42,7 @@ end
     mtn_automate("update")
 end

-register_command("mup", "Merge and update a workspace",
+register_command("mup", "", "Merge and update a workspace",
       "This command merges multiple heads of a branch, and then updates the 
current workspace" ..
       "to the resulting revision.", "mup")

============================================================
--- lua_hooks.cc        8db4abc61015882eff57df28d1fa14cdb46ade88
+++ lua_hooks.cc        57900637d5588e80197752a936229e320993202f
@@ -969,11 +969,12 @@ namespace commands {
     std::string const f_name;
   public:
     cmd_lua(std::string const & primary_name,
+                   std::string const & params,
                    std::string const & abstract,
                    std::string const & desc,
                    lua_State *L_st,
                    std::string const & func_name) :
-         command(primary_name, "", CMD_REF(user), false, "",
+         command(primary_name, "", CMD_REF(user), false, params,
                  abstract, desc, true, options::options_type() | 
options::opts::none, true),
                  st(L_st), f_name(func_name)
     {
@@ -1031,15 +1032,16 @@ LUAEXT(register_command, )

 LUAEXT(register_command, )
 {
-  const char *cmd_name = luaL_checkstring(L, -4);
+  const char *cmd_name = luaL_checkstring(L, -5);
+  const char *cmd_params = luaL_checkstring(L, -4);
   const char *cmd_abstract = luaL_checkstring(L, -3);
   const char *cmd_desc = luaL_checkstring(L, -2);
   const char *cmd_func = luaL_checkstring(L, -1);

-  N(cmd_name && cmd_abstract && cmd_desc && cmd_func,
+  N(cmd_name && cmd_params && cmd_abstract && cmd_desc && cmd_func,
     F("%s called with an invalid parameter") % "register_command");

-  new commands::cmd_lua(cmd_name, cmd_abstract, cmd_desc, L, cmd_func);  // 
leak this - commands can't be removed anyway
+  new commands::cmd_lua(cmd_name, cmd_params, cmd_abstract, cmd_desc, L, 
cmd_func);  // leak this - commands can't be removed anyway

   lua_pushboolean(L, true);
   return 1;
============================================================
--- monotone.texi       9bdc10fe42bccd03dae526214854bc4d08f863b5
+++ monotone.texi       f36f9ea6bc0159051867e484d01421952f71f9ef
@@ -9118,7 +9118,7 @@ @section Additional Lua Functions
 Returns true if a match for @var{regexp} is found in @var{str}, return
 false otherwise.  @xref{Regexps}, for the syntax of @var{regexp}.

address@hidden register_command(@var{name}, @var{abstract}, @var{description}, 
@var{function})
address@hidden register_command(@var{name}, @var{params}, @var{abstract}, 
@var{description}, @var{function})

 Add a command named @var{name} to the @var{user} command group in monotone.  
This function is
 normally called directly from a @file{monotonerc} file rather than a hook.  
When the user issues the