atom feed3 messages in com.selenic.mercurial-develThe mercurial commands for C-hglib
FromSent OnAttachments
Iulian StanaJun 27, 2013 12:43 pm 
Brendan CullyJun 27, 2013 12:47 pm 
Matt MackallJun 27, 2013 2:26 pm 
Subject:The mercurial commands for C-hglib
From:Iulian Stana (juli@gmail.com)
Date:Jun 27, 2013 12:43:04 pm
List:com.selenic.mercurial-devel

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.