ossp-pkg/var/var_qref.pod
##
## OSSP var -- Variable Expansion
## Copyright (c) 2001-2002 The OSSP Project (http://www.ossp.org/)
## Copyright (c) 2001-2002 Cable & Wireless Deutschland (http://www.cw.com/de/)
##
## This file is part of OSSP var, a variable expansion
## library which can be found at http://www.ossp.org/pkg/var/.
##
## Permission to use, copy, modify, and distribute this software for
## any purpose with or without fee is hereby granted, provided that
## the above copyright notice and this permission notice appear in all
## copies.
##
## THIS SOFTWARE IS PROVIDED `AS IS' AND ANY EXPRESSED OR IMPLIED
## WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
## MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
## IN NO EVENT SHALL THE AUTHORS AND COPYRIGHT HOLDERS AND THEIR
## CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
## SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
## LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
## USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
## ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
## OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
## OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
## SUCH DAMAGE.
##
## var_qref.pod: Quick Reference manual page source
##
=pod
=head1 NAME
var_qref -- OSSP var Quick Reference
=head1 DESCRIPTION
A string expanded through B<OSSP var> can consist of arbitrary text
characters plus one or more of the following special syntax constructs
which are expanded by B<OSSP var>. This is just a very brief summary.
For more details see var(3).
=over 4
=item C<\>I<NNN>
Character with the octal value I<NNN>
(I<N>: C<0>,...,C<7>).
=item C<\x>I<NN>, C<\x{>I<NNMM..>C<}>
Character with the hexadecimal value I<NN> or the characters
denoted by grouped hexadecimal numbers I<NNMM..>. (I<N>, I<M>:
C<0>,...,C<9>,[C<aA>],...,[C<fF>]).
=item C<\t>, C<\r>, C<\n>
Tabulator, Carriage Return and Newline character.
=item C<\\>, C<\>I<x>
Ordinary character C<\> and I<x>.
=item C<$>I<name>, C<${>I<name>C<}>
Contents of scalar variable I<name>.
=item C<${>I<name>C<[>I<index>C<]>C<}>
Contents of array variable I<name> at position I<index>.
For I<index> full arithmetic expressions are allowed.
=item C<${>I<name>C<:#}>
Length of C<$>I<name>.
=item C<${>I<name>C<:l}>, C<${>I<name>C<:u}>
C<$>I<name>, converted to all lower-case or all upper-case.
=item C<${>I<name>C<:->I<word>C<}>
If C<$>I<name> is not empty string, then C<$>I<name>, 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).
=item C<${>I<name>C<:*>I<word>C<}>
If C<$>I<name> is not empty string, then empty string, else I<word>
(negative alternative).
=item C<${>I<name>C<:o>I<start>C<,>[I<length>]C<}>
Substring of C<$>I<name> starting at position I<start> with I<length>
characters.
=item C<${>I<name>C<:o>I<start>C<->[I<end>]C<}>
Substring of C<$>I<name> starting at position I<start> and ending at
position I<end> (inclusive).
=item C<${>I<name>C<:s/>I<pattern>C</>I<string>C</>[C<itg>]C<}>
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
"C<i>" switches to case insensitive matching; flag "C<t>" switches
to plain text pattern; flag "C<g>" switches to replacements of all
occurances.
=item C<${>I<name>C<:y/>I<ochars>C</>I<nchars>C</}>
C<$>I<name> after replacing all characters found in the I<ochars>
character class by the corresponding character in the I<nchars>
character class.
=item C<${>I<name>C<:p/>I<width>C</>I<string>C</>{C<l>,C<c>,C<r>}C<}>
C<$>I<name> after padding to I<width> with I<string>. Original contents
of I<name> is either left justified (flag "C<l>"), centered (flag
"C<c>"), or right justified (flag "C<r>").
=item C<[>I<body>C<]>, C<[>I<body>C<]>C<{>I<start>C<,>I<step>C<,>I<end>C<}>
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
(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.
=back
=head1 SEE ALSO
var(3).
=cut
