--- var.pod 2004/04/04 08:07:34 1.36
+++ var.pod 2004/10/29 20:40:18 1.37
@@ -107,7 +107,7 @@
=item C<\t>, C<\r>, C<\n>
-Tabulator, Carriage Return and Newline character.
+Tabulator (TAB), Carriage Return (CR) and Newline (NL) character.
=item C<\\>, C<\>I<x>
@@ -133,17 +133,17 @@
=item C<${>I<name>C<:->I<word>C<}>
If C<$>I<name> is not empty string and not undefined, then C<$>I<name>,
-else I<word> (default value).
+else I<word> (Default Value).
=item C<${>I<name>C<:+>I<word>C<}>
If C<$>I<name> is empty string, then empty string, else I<word>
-(positive alternative).
+(Positive Alternative).
=item C<${>I<name>C<:*>I<word>C<}>
If C<$>I<name> is not empty string, then empty string, else I<word>
-(negative alternative).
+(Negative Alternative).
=item C<${>I<name>C<:o>I<start>C<,>[I<length>]C<}>
@@ -159,10 +159,10 @@
C<$>I<name> after replacing characters matching I<pattern> with
I<string>. By default, case-sensitive regular expression matching is
-performed and only the first occurance of I<pattern> is replaced. Flag
+performed and only the first occurrence of I<pattern> is replaced. Flag
"C<i>" switches to case insensitive matching; flag "C<t>" switches
to plain text pattern; flag "C<g>" switches to replacements of all
-occurances; flag "C<m>" switches to multi-line matching (That is, change
+occurrences; flag "C<m>" switches to multi-line matching (That is, change
"C<^>" and "C<$>" from matching the start or end of the string to
matching the start or end of any line).
@@ -189,14 +189,15 @@
Repeat expansion of I<body> as long as at least one array variable
does not expand to the empty string (first variant) or exactly
(I<end>-I<start>)/I<step> times (second variant). In both cases the
-character "C<#>" is expanded in C<body> as the current loop index
+character "C<#>" is expanded in I<body> as the current loop index
(C<0>,... for first variant and I<start>,...,I<end> with stepping
-I<step> for second variant). I<index> of array variable lookups. For
-I<start>, I<step> and I<end>, full arithmetic expressions are allowed.
-This loop construct can be nested, too. In this case an inner loop is
-fully repeated for each iteration of the outer loop. Additionally,
-arithmetic expressions are supported in both I<start>, I<step>, I<end>
-and I<index> parts of variable constructs in I<body>.
+I<step> for second variant). The "C<#>" is usually used in the I<index>
+of array variable lookups. For I<start>, I<step> and I<end>, full
+arithmetic expressions are allowed. This loop construct can be nested,
+too. In this case an inner loop is fully repeated for each iteration of
+the outer loop. Additionally, arithmetic expressions are supported in
+both I<start>, I<step>, I<end> and I<index> parts of variable constructs
+in I<body>.
=back
@@ -287,10 +288,10 @@
=item B<var_rc_t>
This is an exported enumerated integer type describing the return
-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
+code of all API functions. On success, every API function returns
+C<VAR_OK>. On error, it returns C<VAR_ERR_XXX>. For a list of all
possible return codes see F<var.h>. Their corresponding describing text
-can be determined with B<var_strerror>.
+can be determined with function B<var_strerror>.
=item B<var_t>
@@ -300,10 +301,11 @@
=item B<var_config_t>
This is an exported enumerated integer type describing configuration
-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.
+parameters for function B<var_config>. Currently C<VAR_CONFIG_SYNTAX>
+for configuring the syntax via B<var_syntax_t>, C<VAR_CONFIG_CB_VALUE>
+for configuring the callback for value lookups via B<var_cb_value_t>,
+and C<VAR_CONFIG_CB_OPERATION> for configuring the callback for custom
+value operation functions via B<var_cb_operation_t> are defined.
=item B<var_syntax_t>
@@ -557,11 +559,16 @@
=item C<VAR_CONFIG_CB_VALUE>, var_cb_value_t I<cb>, void *I<ctx>
-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 B<var_expand>, so the caller has to
-configure the callback before variable expansions can be successfully
-performed.
+This overrides the value expansion in I<var>. 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 B<var_expand>, so the caller has to configure the callback
+before variable expansions can be successfully performed.
+
+=item C<VAR_CONFIG_CB_OPERATION>, var_cb_operation_t I<cb>, void *I<ctx>
+
+This provides a custom value operation function for I<var>. The default
+is C<NULL> for I<cb> and I<ctx> which means no custom operation is
+available.
=back
@@ -574,9 +581,9 @@
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
+supplied I<dst_ptr> either has to point to a pre-allocated buffer or
is allowed to point to I<src_ptr> (because the unescaping operation is
-guarrantied to either keep the size or reduce the size of the input).
+guaranteed 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 B<var_unescape>. If is set to true (any value except zero),
@@ -659,10 +666,18 @@
=head2 VARIABLES
+The B<OSSP var> API consists of the following B<ISO-C> exported variables:
+
=over 4
=item B<var_id>
+This is just a pointer to the constant string "C<OSSP var>". It is used
+as the first argument in B<ex_trow> calls if B<OSSP var> is built with
+B<OSSP ex> support. It then allows the application to determine whether
+a caught exception was thrown by B<OSSP var>. See B<EXCEPTION HANDLING>
+below for more details.
+
=back
=head1 COMBINING UNESCAPING AND EXPANSION
@@ -680,7 +695,7 @@
"C<\1>", which might have a special meaning (regular expression
back-references) in the B<var_expand> pass to follow.
-Once, all known escape sequences are expanded, expand the variables
+Once all known escape sequences are expanded, expand the variables
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
@@ -696,12 +711,12 @@
returning C<VAR_ERR_XXX> return codes.
The thrown exceptions can be identified as B<OSSP var> exceptions by
-checking the exception attribute C<ex_class>. It is the B<OSSP var>
-API symbol C<var_id> for all B<OSSP var> exceptions. The C<ex_object>
-attribute is always C<NULL>. The C<ex_value> attribute is the
-C<var_rc_t> which forced the throwing of the exception.
+checking the exception attribute B<ex_class>. It is the B<OSSP var>
+API symbol B<var_id> for all B<OSSP var> exceptions. The B<ex_object>
+attribute is always C<NULL>. The B<ex_value> attribute is the
+B<var_rc_t> which forced the throwing of the exception.
-Exception throwing can be suppressed with C<ex_shield> only.
+Exception throwing can be suppressed with B<ex_shield> only.
=head1 EXAMPLE (DEVELOPER)
@@ -801,11 +816,13 @@
return 0;
}
-Copy & paste the source code it into F<var_play.c> (or use the version
-already shipped with the B<OSSP var> source distribution), compile it
-with
-
- $ cc `var-config --cflags` -o var_play var_play.c `var-config --ldflags --libs`
+Copy & paste the source code into a file F<var_play.c> (or use the
+version already shipped with the B<OSSP var> source distribution),
+compile it with
+
+ $ cc `var-config --cflags` \
+ -o var_play var_play.c \
+ `var-config --ldflags --libs`
and use it to play with the various B<OSSP var> variable expansion
possibilities.
@@ -841,7 +858,7 @@
=head1 SEE ALSO
-pcre(3), regex(7), B<OSSP val> (Value Access).
+pcre(3), regex(7), B<OSSP val> (Value Access), B<OSSP ex> (Exception Handling).
=head1 HISTORY
|
