--- var.pod 2002/02/28 14:58:07 1.24
+++ var.pod 2002/03/04 11:53:27 1.25
@@ -43,7 +43,8 @@
B<var_t>,
B<var_config_t>,
B<var_syntax_t>,
-B<var_cb_value_t>.
+B<var_cb_value_t>,
+B<var_cb_operation_t>.
=item Functions:
@@ -172,6 +173,11 @@
of I<name> is either left justified (flag "C<l>"), centered (flag
"C<c>"), or right justified (flag "C<r>").
+=item C<${>I<name>C<:%>I<func>[C<(>I<arg>C<)>]C<}>
+
+C<$>I<name> after passing it to an application-supplied function I<func>.
+The optional argument I<arg> is passed to the function, too.
+By default no such functions are defined.
=item C<[>I<body>C<]>, C<[>I<body>C<]>C<{>I<start>C<,>I<step>C<,>I<end>C<}>
@@ -224,6 +230,8 @@
| 'p' '/' NUMBER
'/' (variable|TEXT_SUBST)*
'/' ('r'|'l'|'c')
+ | '%' (name|variable)+
+ ('(' (TEXT_ARGS)? ')')?
| 'l'
| 'u'
@@ -241,7 +249,8 @@
NUMBER ::= ('0'|...|'9')+
- TEXT_SUBST ::= ^(DELIM_INIT|'/')
+ TEXT_SUBST ::= (^(DELIM_INIT|'/'))+
+ TEXT_ARGS ::= (^(DELIM_INIT|')'))+
TEXT_EXP ::= (^(DELIM_INIT|DELIM_CLOSE|':'))+
TEXT ::= (^(DELIM_INIT|INDEX_OPEN|INDEX_CLOSE))+
@@ -421,6 +430,94 @@
he subtract own callback return codes from this value, i.e., return
(C<VAR_ERR_CALLBACK> - I<n>) (I<n> E<gt>= 0) from the callback function.
+=item B<var_cb_operation_t>
+
+This is an exported function pointer type for variable value operation
+functions. Such a callback function B<cb> has to be of the following
+prototype:
+
+var_rc_t *B<cb>(var_t *I<var>, void *I<ctx>, const char *I<op_ptr>,
+size_t I<op_len>, const char *I<arg_ptr>, size_t I<arg_len>, const
+char *I<val_ptr>, size_t I<val_len>, const char **I<out_ptr>, size_t
+*I<out_len>, size_t *I<out_size>);
+
+This function will be called by var_expand() internally whenever a
+custom operation is used. Its parameters are:
+
+=over 4
+
+=item var_t *I<var>
+
+This is the passed-through argument as passed to var_expand() as the
+first argument. This can be used in the callback function to distinguish
+the expansion context or to resolve return codes, etc.
+
+=item void *I<ctx>
+
+This is the passed-through argument as passed to var_config() on
+C<VAR_CONFIG_CB_OPERATION> as the forth argument. This can be used
+to provide an internal context to the callback function through
+var_expand().
+
+=item const char *I<op_ptr>
+
+This is a pointer to the name of the operation which var_expand() wishes
+to perform. Please note that the string is NOT necessarily terminated
+by a C<NUL> ('C<\0>') character. If the callback function needs it
+C<NUL>-terminated, it has to copy the string into an a temporary buffer
+of its own and C<NUL>-terminate it there.
+
+=item size_t I<op_len>
+
+This is the length of the variable name at I<op_ptr>.
+
+=item const char *I<arg_ptr>
+
+This is a pointer to the optional argument string to the operation. If
+no argument string or an empty argument string was supplied this is
+C<NULL>.
+
+=item size_t I<arg_len>
+
+This is the length of the I<arg_ptr>.
+
+=item const char *I<val_ptr>
+
+This is a pointer to the value of the variable which the
+operation wants to adjust.
+
+=item size_t I<val_len>
+
+This is the length of the I<val_ptr>.
+
+=item const char **I<out_ptr>
+
+This is a pointer to the location where the callback function should
+store the pointer to the adjusted value.
+
+=item size_t *I<out_len>
+
+This is a pointer to the location where the callback function should
+store the length of the adjusted value of the variable.
+
+=item size_t *I<out_size>
+
+This is a pointer to the location where the callback function should
+store the size of the buffer that has been allocated to hold the
+adjusted value of the variable.
+
+If no buffer has been allocated by the callback at all, because the
+variable uses some other means of storing the contents, this should be
+set to zero (C<0>).
+
+In case a buffer size greater than zero is returned by the callback,
+var_expand() will make use of that buffer internally if possible. It
+will also free(3) the buffer when it is not needed anymore, so it
+is important that it was previously allocated with malloc(3) by the
+callback.
+
+=back
+
=back
=head2 FUNCTIONS
|
