OSSP CVS Repository

ossp - Difference in ossp-pkg/var/var.pod versions 1.24 and 1.25
Not logged in
[Honeypot]  [Browse]  [Home]  [Login]  [Reports
[Search]  [Ticket]  [Timeline
  [History

ossp-pkg/var/var.pod 1.24 -> 1.25

--- 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

CVSTrac 2.0.1