diff --git a/qe-manual.md b/qe-manual.md index fe15ddc..7d918a3 100644 --- a/qe-manual.md +++ b/qe-manual.md @@ -170,6 +170,119 @@ FILENAME. # C functions +### `struct buf_t;` + +Fixed length character array handling +All output functions return the number of bytes actually written to the +output buffer and set a null terminator after any output. + +### `buf_t *buf_attach(buf_t *bp, char *buf, int size, int pos);` + +Initialize a `buf_t` to output to a fixed length array at a given position. + +* argument `bp` a valid pointer to fixed length buffer + +* argument `buf` a valid pointer to a destination array of bytes + +* argument `size` the length of the destination array + +* argument `pos` the initial position for output. + +Return the `buf_t` argument. + +Note: `size` must be strictly positive and `pos` must be in range: `0 <= pos < size` + +Note: this function does not set a null terminator at offset `pos`. + +### `int buf_avail(buf_t *bp);` + +Compute the number of bytes available in the destination array + +* argument `bp` a valid pointer to fixed length buffer + +Return the number of bytes, or `0` if the buffer is full. + +### `buf_t *buf_init(buf_t *bp, char *buf, int size);` + +Initialize a `buf_t` to output to a fixed length array. + +* argument `bp` a valid pointer to fixed length buffer + +* argument `buf` a valid pointer to a destination array of bytes + +* argument `size` the length of the destination array + +Return the `buf_t` argument. + +### `int buf_printf(buf_t *bp, const char *fmt, ...);` + +Format contents at the end of a fixed length buffer. + +* argument `bp` a valid pointer to fixed length buffer + +* argument `fmt` a valid pointer to a format string + +Return the number of bytes actually written. + +### `int buf_put_byte(buf_t *bp, unsigned char ch);` + +Append a byte to a fixed length buffer. + +* argument `bp` a valid pointer to fixed length buffer + +* argument `ch` a byte + +Return the number of bytes actually written. + +### `int buf_putc_utf8(buf_t *bp, char32_t c);` + +Encode a codepoint in UTF-8 at the end of a fixed length buffer. + +* argument `bp` a valid pointer to fixed length buffer + +* argument `c` a valid codepoint to encode + +Return the number of bytes actually written. + +Note: if the conversion does not fit in the destination, the +`len` field is not updated to avoid partial UTF-8 sequences. + +### `int buf_puts(buf_t *bp, const char *str);` + +Append a string to a fixed length buffer. + +* argument `bp` a valid pointer to fixed length buffer + +* argument `str` a valid pointer to a C string + +Return the number of bytes actually written. + +### `int buf_quote_byte(buf_t *bp, unsigned char ch);` + +Encode a byte as a source code escape sequence into a fixed length buffer + +* argument `bp` a valid pointer to fixed length buffer + +* argument `ch` a byte value to encode as source + +Return the number of bytes produced in the destination array, +not counting the null terminator + +### `int buf_write(buf_t *bp, const void *src, int size);` + +Write an array of bytes to a fixed length buffer. + +* argument `bp` a valid pointer to fixed length buffer + +* argument `src` a valid pointer to an array of bytes + +* argument `size` the number of bytes to write. + +Return the number of bytes actually written. + +Note: content is truncated if it does not fit in the available +space in the destination buffer. + ### `void qe_free(T **pp);` Free the allocated memory pointed to by a pointer whose address is passed. @@ -344,6 +457,19 @@ Return the updated path length. Note: truncation cannot be detected reliably +### `int byte_quote(char *dest, int size, unsigned char c);` + +Encode a byte as a source code escape sequence + +* argument `dest` a valid pointer to an array of bytes + +* argument `size` the length of the destination array + +* argument `c` a byte value to encode as source + +Return the number of bytes produced in the destination array, +not counting the null terminator + ### `void canonicalize_path(char *buf, int buf_size, const char *path);` Normalize a path, removing redundant `.`, `..` and `/` parts. @@ -915,6 +1041,21 @@ Find a chunk of characters inside a string. Return a pointer to the first character of the match if found, `NULL` otherwise. +### `int strquote(char *dest, int size, const char *str, int len);` + +Encode a string using source code escape sequences + +* argument `dest` a valid pointer to an array of bytes + +* argument `size` the length of the destination array + +* argument `src` a valid pointer to a string to encode + +* argument `len` the number of bytes to encode + +Return the length of the converted string, not counting the null +terminator, possibly longer than the destination array length. + ### `int strstart(const char *str, const char *val, const char **ptr);` Test if `val` is a prefix of `str`. diff --git a/qe.c b/qe.c index f099ef1..9ed8cfb 100644 --- a/qe.c +++ b/qe.c @@ -2001,7 +2001,7 @@ static void do_unknown_key(EditState *s) { buf_init(out, buf, sizeof buf); for (i = 0; i < qs->input_len; i++) - buf_encode_byte(out, qs->input_buf[i]); + buf_quote_byte(out, qs->input_buf[i]); put_status(s, "Unknown key: %s", buf); } diff --git a/util.c b/util.c index 3ddb13f..fbe7ed0 100644 --- a/util.c +++ b/util.c @@ -1672,6 +1672,15 @@ void free_strings(StringArray *cs) { int buf_write(buf_t *bp, const void *src, int size) { + /*@API buf + Write an array of bytes to a fixed length buffer. + @argument `bp` a valid pointer to fixed length buffer + @argument `src` a valid pointer to an array of bytes + @argument `size` the number of bytes to write. + @return the number of bytes actually written. + @note content is truncated if it does not fit in the available + space in the destination buffer. + */ int n = 0; if (bp->pos < bp->size) { @@ -1688,26 +1697,44 @@ int buf_write(buf_t *bp, const void *src, int size) int buf_printf(buf_t *bp, const char *fmt, ...) { + /*@API buf + Format contents at the end of a fixed length buffer. + @argument `bp` a valid pointer to fixed length buffer + @argument `fmt` a valid pointer to a format string + @return the number of bytes actually written. + */ va_list ap; + char *dest = NULL; + int size = 0; + int written = 0; int len; + if (bp->pos < bp->size) { + dest = bp->buf + bp->pos; + size = bp->size - bp->pos; + } va_start(ap, fmt); - len = vsnprintf(bp->buf + bp->len, - (bp->pos < bp->size) ? bp->size - bp->pos : 1, fmt, ap); + len = vsnprintf(dest, size, fmt, ap); va_end(ap); - bp->pos += len; - bp->len += len; - if (bp->len >= bp->size) { - bp->len = bp->size - 1; - if (bp->len < 0) - bp->len = 0; + if (bp->pos < bp->size) { + written = (len < size) ? len : size - 1; + bp->len += written; } - return len; + bp->pos += len; + return written; } int buf_putc_utf8(buf_t *bp, char32_t c) { + /*@API buf + Encode a codepoint in UTF-8 at the end of a fixed length buffer. + @argument `bp` a valid pointer to fixed length buffer + @argument `c` a valid codepoint to encode + @return the number of bytes actually written. + @note: if the conversion does not fit in the destination, the + `len` field is not updated to avoid partial UTF-8 sequences. + */ if (c < 0x80) { bp->pos++; if (bp->pos < bp->size) { @@ -1755,12 +1782,29 @@ int strsubst(char *buf, int buf_size, const char *from, } int byte_quote(char *dest, int size, unsigned char c) { + /*@API utils + Encode a byte as a source code escape sequence + @argument `dest` a valid pointer to an array of bytes + @argument `size` the length of the destination array + @argument `c` a byte value to encode as source + @return the number of bytes produced in the destination array, + not counting the null terminator + */ buf_t buf[1]; buf_init(buf, dest, size); - return buf_encode_byte(buf, c); + return buf_quote_byte(buf, c); } int strquote(char *dest, int size, const char *str, int len) { + /*@API utils + Encode a string using source code escape sequences + @argument `dest` a valid pointer to an array of bytes + @argument `size` the length of the destination array + @argument `src` a valid pointer to a string to encode + @argument `len` the number of bytes to encode + @return the length of the converted string, not counting the null + terminator, possibly longer than the destination array length. + */ buf_t out[1]; buf_init(out, dest, size); if (str) { @@ -1769,12 +1813,12 @@ int strquote(char *dest, int size, const char *str, int len) { len = strlen(str); buf_put_byte(out, '"'); for (i = 0; i < len; i++) - buf_encode_byte(out, str[i]); + buf_quote_byte(out, str[i]); buf_put_byte(out, '"'); - return out->pos; } else { - return buf_puts(out, "null"); + buf_puts(out, "null"); } + return out->pos; } #if 0 @@ -1784,7 +1828,14 @@ int strunquote(char *dest, int size, const char *str, int len) } #endif -int buf_encode_byte(buf_t *out, unsigned char ch) { +int buf_quote_byte(buf_t *bp, unsigned char ch) { + /*@API buf + Encode a byte as a source code escape sequence into a fixed length buffer + @argument `bp` a valid pointer to fixed length buffer + @argument `ch` a byte value to encode as source + @return the number of bytes produced in the destination array, + not counting the null terminator + */ int c; if (((void)(c = 'n'), ch == '\n') || ((void)(c = 'r'), ch == '\r') @@ -1795,19 +1846,19 @@ int buf_encode_byte(buf_t *out, unsigned char ch) { || ((void)(c = '\''), ch == '\'') // XXX: need flag to make this optional || ((void)(c = '\"'), ch == '\"') // XXX: need flag to make this optional || ((void)(c = '\\'), ch == '\\')) { - return buf_printf(out, "\\%c", c); + return buf_printf(bp, "\\%c", c); } else if (ch < 32) { //if (*p == '\e' && col > 9) { // eb_write(b, b->total_size, "\n ", 10); // col = 9; //} - return buf_printf(out, "\\^%c", (ch + '@') & 127); // XXX: need flag to make this optional + return buf_printf(bp, "\\^%c", (ch + '@') & 127); // XXX: need flag to make this optional } else if (ch < 127) { - return buf_put_byte(out, ch); + return buf_put_byte(bp, ch); } else { - return buf_printf(out, "\\0x%02X", ch); // XXX: need flag to make this optional + return buf_printf(bp, "\\0x%02X", ch); // XXX: need flag to make this optional } } diff --git a/util.h b/util.h index dcfd98e..d289726 100644 --- a/util.h +++ b/util.h @@ -380,13 +380,25 @@ void free_strings(StringArray *cs); typedef struct buf_t buf_t; struct buf_t { - char *buf; /* pointer to the array holding the dynamic string */ + /*@API buf + Fixed length character array handling + All output functions return the number of bytes actually written to the + output buffer and set a null terminator after any output. + */ + char *buf; /* pointer to the output array */ int size; /* size of the array pointed to by buf */ int len; /* length of output in buf. buf is null terminated */ int pos; /* output position into or beyond the end of buf */ }; static inline buf_t *buf_init(buf_t *bp, char *buf, int size) { + /*@API buf + Initialize a `buf_t` to output to a fixed length array. + @argument `bp` a valid pointer to fixed length buffer + @argument `buf` a valid pointer to a destination array of bytes + @argument `size` the length of the destination array + @return the `buf_t` argument. + */ if (size > 0) { bp->buf = buf; bp->size = size; @@ -400,8 +412,16 @@ static inline buf_t *buf_init(buf_t *bp, char *buf, int size) { } static inline buf_t *buf_attach(buf_t *bp, char *buf, int size, int pos) { - /* assuming 0 <= pos < size */ - // XXX: Does not set a null byte? + /*@API buf + Initialize a `buf_t` to output to a fixed length array at a given position. + @argument `bp` a valid pointer to fixed length buffer + @argument `buf` a valid pointer to a destination array of bytes + @argument `size` the length of the destination array + @argument `pos` the initial position for output. + @return the `buf_t` argument. + @note `size` must be strictly positive and `pos` must be in range: `0 <= pos < size` + @note this function does not set a null terminator at offset `pos`. + */ bp->buf = buf; bp->size = size; bp->len = bp->pos = pos; @@ -409,11 +429,22 @@ static inline buf_t *buf_attach(buf_t *bp, char *buf, int size, int pos) { } static inline int buf_avail(buf_t *bp) { - return bp->size - bp->pos - 1; + /*@API buf + Compute the number of bytes available in the destination array + @argument `bp` a valid pointer to fixed length buffer + @return the number of bytes, or `0` if the buffer is full. + */ + return (bp->pos < bp->size) ? bp->size - bp->pos - 1 : 0; } static inline int buf_put_byte(buf_t *bp, unsigned char ch) { - if (bp->len < bp->size - 1) { + /*@API buf + Append a byte to a fixed length buffer. + @argument `bp` a valid pointer to fixed length buffer + @argument `ch` a byte + @return the number of bytes actually written. + */ + if (bp->pos + 1 < bp->size) { bp->buf[bp->len++] = ch; bp->buf[bp->len] = '\0'; } @@ -423,6 +454,12 @@ static inline int buf_put_byte(buf_t *bp, unsigned char ch) { int buf_write(buf_t *bp, const void *src, int size); static inline int buf_puts(buf_t *bp, const char *str) { + /*@API buf + Append a string to a fixed length buffer. + @argument `bp` a valid pointer to fixed length buffer + @argument `str` a valid pointer to a C string + @return the number of bytes actually written. + */ return buf_write(bp, str, strlen(str)); } @@ -460,7 +497,7 @@ int strtokey(const char **pp); int strtokeys(const char *keystr, unsigned int *keys, int max_keys, const char **endp); int buf_put_key(buf_t *out, int key); int buf_put_keys(buf_t *out, unsigned int *keys, int nb_keys); -int buf_encode_byte(buf_t *out, unsigned char ch); +int buf_quote_byte(buf_t *out, unsigned char ch); /* XXX: should use a more regular key mapping scheme: - 0000..001F: standard control keys: KEY_CTRL('@') to KEY_CTRL('@') to KEY_CTRL('_')