--- var.pod 2002/03/07 12:19:46 1.30
+++ var.pod 2002/03/07 12:39:30 1.31
@@ -76,7 +76,7 @@
value (C<${>I<name>C<:>I<op>[C<:>I<op>...]]C<}>).
The supported post-operations are length determination, case
-conversion, defaults, postive and negative alternatives, sub-strings,
+conversion, defaults, positive and negative alternatives, sub-strings,
regular expression based substitutions, character translations, and
padding. Additionally, a meta-construct plus arithmetic expressions for
index and range calculations allow (even nested) iterations over array
@@ -289,7 +289,7 @@
code of all API functions. On success, every API functions returns
C<VAR_OK>. On error, they return C<VAR_ERR_XXX>. For a list of all
possible return codes see F<var.h>. Their corresponding describing text
-can be determined with var_strerror().
+can be determined with B<var_strerror>.
=item B<var_t>
@@ -299,7 +299,7 @@
=item B<var_config_t>
This is an exported enumerated integer type describing configuration
-parameters for var_config(). Currently C<VAR_CONFIG_SYNTAX> (for
+parameters for B<var_config>. Currently C<VAR_CONFIG_SYNTAX> (for
configuring the syntax via B<var_syntax_t>) and C<VAR_CONFIG_CB_VALUE>
(for configuring the callback for value lookups via B<var_cb_value_t>)
are defined.
@@ -307,7 +307,7 @@
=item B<var_syntax_t>
This is an exported structural data type describing the variable
-construct syntax. It is passed to var_config() on C<VAR_CONFIG_SYNTAX>
+construct syntax. It is passed to B<var_config> on C<VAR_CONFIG_SYNTAX>
and consists of the following members (directly corresponding to the
upper-case non-terminals in the grammar above):
@@ -336,28 +336,28 @@
size_t I<var_len>, int I<var_idx>, const char **I<val_ptr>, size_t
*I<val_len>, size_t *I<val_size>);
-This function will be called by var_expand() internally whenever it has
+This function will be called by B<var_expand> internally whenever it has
to resolve the contents of a variable. Its parameters are:
=over 4
=item var_t *I<var>
-This is the passed-through argument as passed to var_expand() as the
+This is the passed-through argument as passed to B<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
+This is the passed-through argument as passed to B<var_config> on
C<VAR_CONFIG_CB_VALUE> as the forth argument. This can be used
to provide an internal context to the callback function through
-var_expand().
+B<var_expand>.
=item const char *I<var_ptr>
-This is a pointer to the name of the variable which's contents
-var_expand() wishes to resolve. Please note that the string is NOT
+This is a pointer to the name of the variable whose contents
+B<var_expand> wishes to resolve. 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.
@@ -399,7 +399,7 @@
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
+B<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.
@@ -407,25 +407,25 @@
=back
The return code of the lookup function B<cb> is interpreted by
-var_expand() according to the following convention: C<VAR_OK> means
+B<var_expand> according to the following convention: C<VAR_OK> means
success, that is, the contents of the variable has been resolved
successfully and the I<val_ptr>, I<val_len>, and I<val_size> variables
have been filled with appropriate values. A return code C<VAR_ERR_XXX>
means that the resolving failed, such as a system error or lack of
resources. In the latter two cases, the contents of I<val_ptr>,
I<val_len> and I<val_size> is assumed to be undefined. Hence,
-var_expand() will not free(3) any possibly allocated buffers, the
+B<var_expand> will not free(3) any possibly allocated buffers, the
callback must take care of this itself.
If a callback returns the special C<VAR_ERR_UNDEFINED_VARIABLE> return
-code, the behaviour of var_expand() depends on the setting of its
-I<force_expand> parameter. If I<force_expand> has been set, var_expand()
+code, the behavior of B<var_expand> depends on the setting of its
+I<force_expand> parameter. If I<force_expand> has been set, B<var_expand>
will pass-through this error to the caller. If I<force_expand> 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
+not been set, B<var_expand> will copy the expression that caused the
+lookup to fail verbatim into the output buffer so that an additional
expanding pass may expand it later.
-If the callback returns an C<VAR_ERR_XXX>, var_expand() will fail with
+If the callback returns an C<VAR_ERR_XXX>, B<var_expand> will fail with
this return code. If the cause for the error can not be denoted by an
error code defined in F<var.h>, callback implementors should use the
error code C<VAR_ERR_CALLBACK> (which is currently defined to -64).
@@ -446,27 +446,27 @@
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
+This function will be called by B<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
+This is the passed-through argument as passed to B<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
+This is the passed-through argument as passed to B<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().
+B<var_expand>.
=item const char *I<op_ptr>
-This is a pointer to the name of the operation which var_expand() wishes
+This is a pointer to the name of the operation which B<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
@@ -516,7 +516,7 @@
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
+B<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.
@@ -550,7 +550,7 @@
This overrides the syntax configuration in I<var> with the one provided
in I<syntax>. The complete structure contents is copied, so the caller
-is allowed to immediately destroy I<syntax> after the var_config() call.
+is allowed to immediately destroy I<syntax> after the B<var_config> call.
The default is the contents as shown above under the type description of
B<var_syntax_t>.
@@ -558,7 +558,7 @@
This overrides the syntax configuration in I<var> with the one provided
The default is C<NULL> for I<cb> and I<ctx>. At least C<NULL> for I<cb>
-is not valid for proper operation of var_expand(), so the caller has to
+is not valid for proper operation of B<var_expand>, so the caller has to
configure the callback before variable expansions can be successfully
performed.
@@ -570,7 +570,7 @@
I<src_ptr>/I<src_len>. The I<dst_ptr>/I<dst_len> point to a output
buffer, into which the expanded data is copied if processing is
successful. The size of this buffer must be at least I<src_len>+1
-characters. The reason is that var_unescape() always adds a terminating
+characters. The reason is that B<var_unescape> always adds a terminating
C<NUL> ('C<\0>') character at the end of the output buffer, so that
you can use the result comfortably with other C library routines. The
supplied I<dst_ptr> either has to be point to a pre-allocated buffer or
@@ -578,14 +578,14 @@
guarrantied to either keep the size or reduce the size of the input).
The parameter I<all> is a boolean flag that modifies the behavior
-of var_unescape(). If is set to true (any value except zero),
-var_unescape() will expand B<any> escape sequences it sees, even those that
+of B<var_unescape>. If is set to true (any value except zero),
+B<var_unescape> will expand B<any> escape sequences it sees, even those that
it does not know about. This means that "C<\1>" will become "C<1>",
-even though "C<\1>" has no special meaning to var_unescape(). If I<all>
+even though "C<\1>" has no special meaning to B<var_unescape>. If I<all>
is set to false (the value zero), such escape sequences will be copied
-verbatimly to the output buffer.
+verbatim to the output buffer.
-The quoted pairs supported by var_unescape() are "C<\t>" (tabulator),
+The quoted pairs supported by B<var_unescape> are "C<\t>" (tabulator),
"C<\r>" (carriage return), "C<\n>" (line feed), "C<\NNN>" (octal value),
"C<\xNN>" (hexadecimal value), and "C<\x{NNMM..}>" (grouped hexadecimal
values).
@@ -596,32 +596,32 @@
I<src_ptr>/I<src_len> and stores them in an allocated buffer returned
in I<dst_ptr>/I<dst_len>.
-The output buffer I<dst_ptr>/I<dst_len> is allocated by var_expand()
+The output buffer I<dst_ptr>/I<dst_len> is allocated by B<var_expand>
using the system call malloc(3), thus it is the caller's responsibility
to free(3) that buffer once it is no longer used anymore. The output
-buffer for convinience reasons is always C<NUL>-terminated by
-var_expand(), but this C<NUL> character is not counted for I<dst_len>.
+buffer for convenience reasons is always C<NUL>-terminated by
+B<var_expand>, but this C<NUL> character is not counted for I<dst_len>.
The I<dst_len> pointer can be specified as C<NULL> if you are not
interested in the output buffer length.
-The I<force_expand> flag determines how var_expand() deals with
+The I<force_expand> flag determines how B<var_expand> deals with
undefined variables (indicated by the callback function through the
return code C<VAR_ERR_UNDEFINED_VARIABLE>). If it is set to true
-(any value except zero), var_expand() will fail with error code
+(any value except zero), B<var_expand> will fail with error code
C<VAR_ERR_UNDEFINED_VARIABLE> whenever an undefined variable is
encountered. That is, it just passes-through the return code of the
-callback function. If set to false (value zero), var_expand() will copy
-the expression it failed to expand verbatimly into the output buffer,
+callback function. If set to false (value zero), B<var_expand> will copy
+the expression it failed to expand verbatim into the output buffer,
in order to enable you to go over the buffer with an additional pass.
-Generally, if you do not plan to use muli-pass expansion, you should set
+Generally, if you do not plan to use multi-pass expansion, you should set
I<force_expand> to true in order to make sure no unexpanded variable
constructs are left over in the buffer.
-If var_expand() fails with an error, I<dst_ptr> will point to I<src_ptr>
+If B<var_expand> fails with an error, I<dst_ptr> will point to I<src_ptr>
and I<dst_len> will contain the number of characters that have been
-consumed from I<src_ptr> before the error occured. In other words,
+consumed from I<src_ptr> before the error occurred. In other words,
if an error occurs, I<dst_ptr>/I<dst_len> point to the last parsing
-location in I<src_ptr>/I<src_len> before the error occured. The only
+location in I<src_ptr>/I<src_len> before the error occurred. The only
exceptions for this error semantics are: on C<VAR_ERR_INVALID_ARGUMENT>
and C<VAR_ERR_OUT_OF_MEMORY> errors, I<dst_ptr> and I<dst_len> are
undefined.
@@ -667,22 +667,22 @@
=head1 COMBINING UNESCAPING AND EXPANSION
For maximum power and flexibility, you usually want to combine
-var_unescape() and var_expand(). That is, you will want to use
-var_unescape() to turn all escape sequences into their real
-representation before you call var_expand() for expanding variable
+B<var_unescape> and B<var_expand>. That is, you will want to use
+B<var_unescape> to turn all escape sequences into their real
+representation before you call B<var_expand> for expanding variable
constructs. This way the user can safely use specials like "C<\n>" or
"C<\t>" throughout the template and achieve the desired effect. These
escape sequences are particularly useful if search-and-replace or
transpose actions are performed on variables before they are expanded.
-Be sure, though, to make the first var_unescape() pass with the I<all>
+Be sure, though, to make the first B<var_unescape> pass with the I<all>
flag set to false, or the routine will also expand escape sequences like
"C<\1>", which might have a special meaning (regular expression
-back-references) in the var_expand() pass to follow.
+back-references) in the B<var_expand> pass to follow.
Once, all known escape sequences are expanded, expand the variables
-with var_expand(). After that, you will want to have a second pass
-with var_unescape() and the flag I<all> set to true, to make sure all
-remaining escape sequences are expanded. Also, the var_expand() pass
+with B<var_expand>. After that, you will want to have a second pass
+with B<var_unescape> and the flag I<all> set to true, to make sure all
+remaining escape sequences are expanded. Also, the B<var_expand> pass
might have introduced now quoted pairs into the output text, which you
need to expand to get the desired effect.
@@ -844,10 +844,14 @@
=head1 HISTORY
-B<OSSP var> was written by Peter Simons E<lt>simons@crypt.toE<gt> in
-November 2001. Its API and internal code structure was revamped in
-February 2002 by Ralf S. Engelschall E<lt>rse@engelschall.comE<gt> to
-fully conform to the B<OSSP> library standards.
+B<OSSP var> was initially written by Peter Simons
+E<lt>simons@crypt.toE<gt> in November 2001 under contract with the
+B<OSSP> sponsor B<Cable & Wireless Germany>. Its API and internal
+code structure was revamped in February 2002 by Ralf S. Engelschall
+E<lt>rse@engelschall.comE<gt> to fully conform to the B<OSSP> library
+standards. Before its initial public release, Ralf S. Engelschall in
+March 2002 finally added support for custom operations, the formatting
+functionality, optional multi-line matching, etc.
=cut
|
