Index: ossp-pkg/var/ChangeLog RCS File: /v/ossp/cvs/ossp-pkg/var/ChangeLog,v rcsdiff -q -kk '-r1.11' '-r1.12' -u '/v/ossp/cvs/ossp-pkg/var/ChangeLog,v' 2>/dev/null --- 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 ] + o Added minimum C++ support by enclosing API declaration into 'extern "C"' scope. [Ralf S. Engelschall ] Index: ossp-pkg/var/var.pod RCS File: /v/ossp/cvs/ossp-pkg/var/var.pod,v rcsdiff -q -kk '-r1.36' '-r1.37' -u '/v/ossp/cvs/ossp-pkg/var/var.pod,v' 2>/dev/null --- 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 @@ -133,17 +133,17 @@ =item C<${>IC<:->IC<}> If C<$>I is not empty string and not undefined, then C<$>I, -else I (default value). +else I (Default Value). =item C<${>IC<:+>IC<}> If C<$>I is empty string, then empty string, else I -(positive alternative). +(Positive Alternative). =item C<${>IC<:*>IC<}> If C<$>I is not empty string, then empty string, else I -(negative alternative). +(Negative Alternative). =item C<${>IC<:o>IC<,>[I]C<}> @@ -159,10 +159,10 @@ C<$>I after replacing characters matching I with I. By default, case-sensitive regular expression matching is -performed and only the first occurance of I is replaced. Flag +performed and only the first occurrence of I is replaced. Flag "C" switches to case insensitive matching; flag "C" switches to plain text pattern; flag "C" switches to replacements of all -occurances; flag "C" switches to multi-line matching (That is, change +occurrences; flag "C" 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 as long as at least one array variable does not expand to the empty string (first variant) or exactly (I-I)/I times (second variant). In both cases the -character "C<#>" is expanded in C as the current loop index +character "C<#>" is expanded in I as the current loop index (C<0>,... for first variant and I,...,I with stepping -I for second variant). I of array variable lookups. For -I, I and I, 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, I, I -and I parts of variable constructs in I. +I for second variant). The "C<#>" is usually used in the I +of array variable lookups. For I, I and I, 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, I, I and I parts of variable constructs +in I. =back @@ -287,10 +288,10 @@ =item B This is an exported enumerated integer type describing the return -code of all API functions. On success, every API functions returns -C. On error, they return C. For a list of all +code of all API functions. On success, every API function returns +C. On error, it returns C. For a list of all possible return codes see F. Their corresponding describing text -can be determined with B. +can be determined with function B. =item B @@ -300,10 +301,11 @@ =item B This is an exported enumerated integer type describing configuration -parameters for B. Currently C (for -configuring the syntax via B) and C -(for configuring the callback for value lookups via B) -are defined. +parameters for function B. Currently C +for configuring the syntax via B, C +for configuring the callback for value lookups via B, +and C for configuring the callback for custom +value operation functions via B are defined. =item B @@ -557,11 +559,16 @@ =item C, var_cb_value_t I, void *I -This overrides the syntax configuration in I with the one provided -The default is C for I and I. At least C for I -is not valid for proper operation of B, so the caller has to -configure the callback before variable expansions can be successfully -performed. +This overrides the value expansion in I. The default is C for +I and I. At least C for I is not valid for proper +operation of B, so the caller has to configure the callback +before variable expansions can be successfully performed. + +=item C, var_cb_operation_t I, void *I + +This provides a custom value operation function for I. The default +is C for I and I which means no custom operation is +available. =back @@ -574,9 +581,9 @@ characters. The reason is that B always adds a terminating C ('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 either has to be point to a pre-allocated buffer or +supplied I either has to point to a pre-allocated buffer or is allowed to point to I (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 is a boolean flag that modifies the behavior of B. If is set to true (any value except zero), @@ -659,10 +666,18 @@ =head2 VARIABLES +The B API consists of the following B exported variables: + =over 4 =item B +This is just a pointer to the constant string "C". It is used +as the first argument in B calls if B is built with +B support. It then allows the application to determine whether +a caught exception was thrown by B. See B +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 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. After that, you will want to have a second pass with B and the flag I set to true, to make sure all remaining escape sequences are expanded. Also, the B pass @@ -696,12 +711,12 @@ returning C return codes. The thrown exceptions can be identified as B exceptions by -checking the exception attribute C. It is the B -API symbol C for all B exceptions. The C -attribute is always C. The C attribute is the -C which forced the throwing of the exception. +checking the exception attribute B. It is the B +API symbol B for all B exceptions. The B +attribute is always C. The B attribute is the +B which forced the throwing of the exception. -Exception throwing can be suppressed with C only. +Exception throwing can be suppressed with B only. =head1 EXAMPLE (DEVELOPER) @@ -801,11 +816,13 @@ return 0; } -Copy & paste the source code it into F (or use the version -already shipped with the B 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 (or use the +version already shipped with the B 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 variable expansion possibilities. @@ -841,7 +858,7 @@ =head1 SEE ALSO -pcre(3), regex(7), B (Value Access). +pcre(3), regex(7), B (Value Access), B (Exception Handling). =head1 HISTORY