C-hglib - Level 0, API proposal.

[Iulian Stana]

After some of Matt's remarks I write a new API proposal for c-hglib.
I come with some answers for Matt's questions and a header file for
the level 0 ( here are some of the basic functions that will help me
to achieve the API purpose)
I would like to get feedback to know if I am on the good path.


What does this return?
- int hg_rawread(hg_handle *handle, char *buffer, size_t sizebuff);
- int hg_rawcommand(hg_handle *handle, const char *command);
- int hg_close(hg_handle *handle);

.h file:

typedef struct hg_handle hg_handle;
typedef struct hg_header{
   char channel;
   uint32_t length;
} hg_header;

/* return the handle for a connection */
hg_handle* hg_open(const char *path);

/* The function returns 0 if successful, -1 to indicate an error, with
errno set appropriately. */
int hg_close(hg_handle *handle);

/* The function returns 0 if successful, -1 to indicate an error, with
errno set appropriately. */
/* It's just sending the command to the cmdsrv.*/
int hg_rawcommand(hg_handle *handle, const char *command);

/* The function returns the number of bytes read. On end-of-file, 0 is
returned, on error it returns -1, setting errno to indicate the type of
error that occurred. */
int hg_rawread(hg_handle *handle, char *buffer, size_t sizebuff);

/* The function returns the number of bytes written to the file. A return
value of -1 indicates an error, with errno set appropriately. */
int hg_rawsend( hg_handle *handle, char *buffer);

/* The function returns the channel for the next chunk*/
char hg_channel(hg_handle *handle);

/* The function returns the header in advance. */
hg_header hg_ rawchunk(hg_handle *handle);

/* The function returns the exitcode received from cmdserver.*/
int hg_exitcode(hg_handle * handle);

/* It's just a proposal for how to send/receive data through connection
while 1:
    switch(hg_channel(handle)):
        case 'r':
            hg_exitcode(handle);
            break;
        case 'o':
            /* Make something with data save it into a data structure*/
            hg_rawread(handle, buffer , size);
            save_into_out_channel(buffer);
        case 'e':
            hg_rawread(handle, buffer , size);
            save_into_err_channel(buffer);
        case 'I':
        case 'L':
            hg_rawsend(handle, buffer);
*/

This doesn't mean "figure out how to wrap these commands" in C code,
instead it means "figure out how to expose enough of the protocol to the
user so that they can run these sorts commands"
In figuring out what needs to be in the level 0 API, here are the commands
you should probably figure out a story for:

a) hg init <- doesn't start with a repo
In this case, I will create a new process were I will execute the init
command, to create the new repo. After this, I will establish the
connection through pipes, with the cmdserver.
For the clone command, there I will execute the same steps.
The return in those cases will be the handle for the connection.

b) hg log <- can produce huge output
I know that some repo could have a huge log, but I don't know if the user
will use that huge output. My single thought right now is to set a limit
for the huge mass of data.
“The memory is full, the log data for this repo it's bigger than MAX_SIZE,
you can specify a file were the data to be store.”
I don't know if this is the best solution... Other ideas are welcome.

c) hg import - <- wants a patch fed to it from client
If patch is a list of files or a file-like, then the input for the command
server will be from those files. In this case the data will be send line by
line to the server.

d) hg merge <- has prompts
By default, if there will be any prompts the merge will abort.
There can be use the '-y' option or a function that gets a single argument
which are the contents of stdout. It should return one of the expected
choices (a single character).

e) hg verify <- might give warnings intermixed with output
Returns 0 on success, 1 if errors are encountered.
In handle I will save the good output and warnings/errors.
I will let the user to choose if he wants just a verification or the
error/output. I think that would be nice to have an option for the user
choose.

Have a nice day,
Iulian
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.mercurial-scm.org/pipermail/mercurial-devel/attachments/20130704/f1f13483/attachment-0002.html>