The mercurial commands for C-hglib

Iulian Stana julian.stana at gmail.com
Thu Jun 27 14:43:30 CDT 2013


The mercurial commands for C-hglib:

In the last two days, I've tried to come with a good approach for the
signatures of API functions. The biggest problem I found it was on the
mercurial commands. The number of options for a specific command can be
variable.

Here are some of the options that I have found. With pro and contra
arguments and some examples of usage.


USER:
{
   // Create a client
   chgclient *chg = chgopen();
   {
   //magic happens, here the commands are called
   }
   // Close the client
   chgclose(chg);
}


open a client → execute some commands → close the client


The problem is to make a easy way for client to use the API.
The first question can be, how the command must look?
Until now I've come with some approaches for those commands:

   -   returnvalue command(client, cmdopt);


Where returnvalue can be:

   - bool
   - char * (string)
   - char ** (list of string)
   - char *** (list of list of string)


and cmdopt:

   - the order of variables are predefine
   - using variable numbers of arguments (vararg)
   - using a structure that will be created



PRO vs CONTRA for the cmdopt:

The order of variables is predefine:
PRO:

   - know the order of variables
   - know all the variables for a command
   - easy to implement
   - easy to use (more intuitive)

CONTRA:

   - the user must use all the time the variables that doesn't need
   - maybe he use just an option and don't want to be bothering with the
   other ones

Ex:
add command could be of the following type:
bool add(chgclient *chg, char **files, size_t filesize, bool dryrun, bool
subrepo,
                      char *include, char *exclude);
add(chg, files, 3, false, false, NULL, NULL);


Using variable numbers of arguments (vararg):
PRO:

   - using just the variables/ options that user need


CONTRA:

   - a little harder to implement
   - a little harder to use
   - the user must use a documentation to know the options
   - there must exist an order or a mechanism for passing the variables

Ex:
add command could be of the following type:
bool add(chgclient *chg, ...);
add(chg, “files=1.py 2.c README”, “dryrun=True”);


Using a structure that is pre created:
PRO:

   - using just the variables/ options that user need
   - a nice way to create the structure and to pass to the commands
   - not to hard to implement
   - in my opinion easy to deal the data structures

CONTRA:

   - the user must use a documentation to know the options


A way to implement this thing:

   1. Using an enumeration list of options.
   2. Create a data structure named commandoptions.
   3. The user will use this data structure to create his options:

Ex:
cmdoption *cmdo = createcmd();
//void addopt(cmdoption *cmdo, cmd_type type, void cmd);
addopt(cmdo, FILE, “1.py”);
add(chg, cmdo);
deleteopt(cmdo);

where add will be of the form:
bool add( chgclient *chg, cmdoption *cmdo);


I would like your opinion on these approaches, and which ones might fit
better.


--
O zi buna,
Iulian
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://selenic.com/pipermail/mercurial-devel/attachments/20130627/e3e663ea/attachment.html>


More information about the Mercurial-devel mailing list