= Design document for hg_rawread =

Matt outlined the desired beahaviour as

{{{
char buf[4096];
hg_handle *handle;

handle = hg_open("some/repo");
hg_rawcommand(handle, "hg log -v");
while(hg_rawread(handle, buf, 4096))
        printf("got: %s", buf); 
printf("exit code is: %d", hg_exitcode(handle)); 
hg_close(handle); 
}}}

at http://markmail.org/message/tc6hsvl7fofdjqcl

Experimenting with the problem domain lead to something different, more like

{{{
while(hg_rawread(handle, buff, 4096)){
        printf("%s", buff);
}

if(hg_channel(handle) == 'r'){
        exitcode = hg_exitcode(handle);
        printf("exitcode = %d\n", exitcode);
}
}}}

Note how the channel type has to be checked before using `hg_rawread`. Moreover, in other usage case, the usage pattern is like

{{{
while(hg_channel(handle) != 'r'){
    if(hg_channel(handle) == 'o'){
        hg_rawread(handle, buff, 4096);
        printf("%s", buff);
    } else if(hg_channel(handle) == 'e'){
        hg_rawread(handle, buff, 4096);
        printf("%s", buff);
    } else if(hg_channel(handle) == 'L'){
        /* ... */
    }
}
}}}

== remarks ==

 * the two usage cases should be made consistent (i.e., wrap `hg_rawread` into a while loop in the second case too)
 * the above usages do not take into account the case where `hg_rawread` return -1 (error). 

== attachments ==

IRC conversation about this topic here: http://bpaste.net/show/z2YXazAQti2NFrCp8qFl/