OSSP CVS Repository

ossp - Check-in [4793]
Not logged in
[Honeypot]  [Browse]  [Home]  [Login]  [Reports
[Search]  [Ticket]  [Timeline
  [Patchset]  [Tagging/Branching

Check-in Number: 4793
Date: 2004-Oct-29 22:40:18 (local)
2004-Oct-29 20:40:18 (UTC)
User:rse
Branch:
Comment: Cleanup and extend the Unix manual page var(3)
Tickets:
Inspections:
Files:
ossp-pkg/var/ChangeLog      1.11 -> 1.12     3 inserted, 0 deleted
ossp-pkg/var/var.pod      1.36 -> 1.37     56 inserted, 39 deleted

ossp-pkg/var/ChangeLog 1.11 -> 1.12

--- ChangeLog    2004/10/29 19:44:40     1.11
+++ ChangeLog    2004/10/29 20:40:18     1.12
@@ -13,6 +13,9 @@
 
   Changes between 1.1.1 and 1.1.2 (12-Sep-2004 to xx-Oct-2004)
 
+   o Cleanup and extend the Unix manual page var(3).
+     [Ralf S. Engelschall <rse@engelschall.com>]
+
    o Added minimum C++ support by enclosing API declaration
      into 'extern "C"' scope.
      [Ralf S. Engelschall <rse@engelschall.com>]


ossp-pkg/var/var.pod 1.36 -> 1.37

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

CVSTrac 2.0.1