--- var.h 2001/11/19 16:07:15 1.12
+++ var.h 2001/11/19 16:09:44 1.13
@@ -74,64 +74,19 @@
VAR_OK = 0
} var_rc_t;
-/*
- Expand the following named characters to their binary
- representation:
-
- \t tab
- \n newline
- \r return
- \033 octal char
- \x1B hex char
- \x{263a} wide hex char
-
- Any other character quoted by a backslash is copied verbatim.
-*/
+/* Expand quoted pairs to their binary representation. */
var_rc_t var_unescape(const char *src, size_t len, char *dst,
int unescape_all);
-/*
- The callback will be called by variable_expand(), providing the
- following parameters:
-
- context - passed through from variable_expand()'s
- parameters
- varname - pointer to the name of the variable to
- expand
- name_len - length of the string starting at varname
- data - location, where the callback should store
- the pointer to the contents of the looked-up
- variable
- data_len - location, where the callback should store
- the length of the data
- malloced_buffer - location, where the callback should store
- either TRUE or FALSE, telling the framework
- whether the buffer must be free(3)ed.
-
- The return code is interpreted as follows:
- >0 - OK
- 0 - undefined variable
- <0 - error
-*/
+/* Prototype for the lookup callback used in var_expand(). */
typedef int (*var_cb_t) (void *context,
const char *varname, size_t name_len,
const char **data, size_t *data_len,
-//FIXME THL: description "malloced_buffer" vs. prototype "size_t *buffer_size"
size_t *buffer_size);
-/*
- This structure configures the parser's specials. I think, the fields
- are pretty self-explanatory. The only one worth mentioning is
- force_expand, which is a boolean. If set to TRUE, variable_expand()
- will fail with an error if the lookup callback returns "undefined
- variable". If set to FALSE, variable_expand() will copy the
- expression that failed verbatimly to the output so that another pass
- may expand it.
-
- The comments after each field show the default configuration.
-*/
+/* Configure the var_expand() parser's tokens. */
typedef struct {
char varinit; /* '$' */
@@ -139,24 +94,17 @@
char enddelim; /* '}' */
char escape; /* '\' */
char *namechars; /* 'a-zA-Z0-9_' */
-//FIXME THL: should we support namechars with different first char, i.e. [a-z][a-z0-9]*
} var_config_t;
extern const var_config_t var_config_default;
-/*
- variable_expand() will parse the contents of input for variable
- expressions and expand them using the provided lookup callback. The
- pointer to the resulting buffer is stored in result, its length in
- result_len. The buffer is always terminated by a '\0' byte, which is
- not included in the result_len count. The buffer must be free(3)ed
- by the caller.
-*/
+/* Expand variable expressions in a text buffer. */
var_rc_t var_expand(const char *input, size_t input_len,
char **result, size_t *result_len,
var_cb_t lookup, void *lookup_context,
const var_config_t *config, int force_expand);
-//FIXME THL: "force_expand" used here but described and unused above in "var_config_t"
+
+/* Map an error code to a text message. */
const char* var_strerror(var_rc_t rc);
|
