--- var.pod 2001/12/16 23:40:16 1.15
+++ var.pod 2001/12/17 10:29:43 1.16
@@ -311,10 +311,10 @@
variable up itself. Instead, it relies on a caller-supplied callback
function, which adheres to the var_cb_t function interface:
- int lookup(void *context,
- const char *varname, size_t name_len, int index,
- const char **data, size_t *data_len,
- size_t *buffer_size);
+ var_rc_t lookup(void *context,
+ const char *varname, size_t name_len, int index,
+ const char **data, size_t *data_len,
+ size_t *buffer_size);
This function will be called by var_expand() whenever it has to
retrieve the contents of, say, the variable $name, using the following
@@ -379,38 +379,30 @@
=back
The return code of the lookup function is interpreted by var_expand()
-accordin to the following convention: Any return code greater than
-zero means success, that is, the contents of the variable has been
-looked-up successfully and the "data", "data_len", and "buffer_size"
-locations have been filled with appropriate values. A return code of
-zero (0) means that the variable was undefined and its contents
-therefore could not be looked-up. A return code of less than zero
-means that the lookup failed for some other reason, such as a system
-error or lack of resources. In the latter two cases, the contents of
-"data", "data_len" and "buffer_size" is assumed to be undefined.
-Hence, var_expand() will not free(3) any possibly allocated buffers,
-the callback must take care of that itself.
-
-If a callback returns zero -- meaning the variable is undefined --,
-the behavior of var_expand() depends on the setting of the
-"force_expand" parameter. If force-expand mode has been set,
-var_expand() will fail with a VAR_ERR_UNDEFINED_VARIABLE error. If
-force-expand mode has not been set, var_expand() will copy the
-expression that caused the lookup to fail verbatimly into the output
-buffer so that an additional expanding pass may expand it later.
-
-If the callback returns an error -- meaning a return code less than
-zero --, var_expand() will fail with the return code it got from the
-callback. Callback implementors are encouraged to re-use the error
-codes defined in var.h whereever possible. An example of an error code
-a callback might want to reuse is VAR_ERR_OUT_OF_MEMORY. If the cause
-for the error can not be denoted by an error code defined in var.h,
-callback implementors should use the error code VAR_ERR_CALLBACK,
-which is currently defined to -64. It is guaranteed that no error code
-smaller than VAR_ERR_CALLBACK is ever used by var_expand() or
-VAR_UNESCAPE(), so if the callback implementor wishes to distinguish
-between different reasons for failure, he can define his own set of
-errors
+according to the following convention: VAR_OK means success, that
+is, the contents of the variable has been looked-up successfully and
+the "data", "data_len", and "buffer_size" locations have been filled
+with appropriate values. A return code VAR_ERR_XXX means that the lookup
+failed, such as a system error or lack of resources. In the latter two
+cases, the contents of "data", "data_len" and "buffer_size" is assumed
+to be undefined. Hence, var_expand() will not free(3) any possibly
+allocated buffers, the callback must take care of that itself.
+
+If a callback returns the special VAR_ERR_UNDEFINED_VARIABLE return
+code, the behaviour of var_expand() depends on the setting of
+the "force_expand" parameter. If force-expand mode has been set,
+var_expand() will fail with this error. If force-expand mode has
+not been set, var_expand() will copy the expression that caused the
+lookup to fail verbatimly into the output buffer so that an additional
+expanding pass may expand it later.
+
+If the callback returns an VAR_ERR_XXX, var_expand() will fail with the return
+code it got from the callback. If the cause for the error can not be denoted
+by an error code defined in var.h, callback implementors should use the error
+code VAR_ERR_CALLBACK, which is currently defined to -64. It is guaranteed
+that no error code smaller than VAR_ERR_CALLBACK is ever used by var_expand()
+or VAR_UNESCAPE(), so if the callback implementor wishes to distinguish
+between different reasons for failure, he can define his own set of errors
typedef enum {
LOOKUP_ERROR_ONE = -3,
@@ -424,30 +416,25 @@
the following expamle that accesses the system environment via
getenv(3) to lookup variables and to return them to var_expand():
- int env_lookup(void *context,
- const char *varname, size_t name_len, int index,
+ var_rc_t env_lookup(
+ void *context,
+ const char *varname, size_t name_len, int idx,
const char **data, size_t *data_len,
size_t *buffer_size)
{
char tmp[256];
- if (index != 0)
+ if (idx != 0)
return VAR_ERR_ARRAY_LOOKUPS_ARE_UNSUPPORTED;
-
- if (name_len > sizeof(tmp) - 1) {
- /* Callback can't expand variable names longer than
- sizeof(tmp) characters. */
-
+ if (name_len > sizeof(tmp) - 1)
return VAR_ERR_CALLBACK;
- }
memcpy(tmp, varname, name_len);
tmp[name_len] = '\0';
- *data = getenv(tmp);
- if (*data == NULL)
- return 0;
+ if ((*data = getenv(tmp)) == NULL)
+ return VAR_ERR_UNDEFINED_VARIABLE;
*data_len = strlen(*data);
*buffer_size = 0;
- return 1;
+ return VAR_OK;
}
=head1 SUPPORTED NAMED CHARACTERS
|
