##
**  VAR - OSSP variable expression library.
##  Copyright (c) 2001 The OSSP Project (http://www.ossp.org/)
##  Copyright (c) 2001 Cable & Wireless Deutschland (http://www.cw.com/de/)
##
##  This file is part of OSSP VAR, an extensible data serialization
##  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.pod: Unix manual page source
##

=pod

=head1 NAME

var - OSSP variable expression library.

=head1 SYNOPSIS

=head1 DESCRIPTION

The purpose of VAR is ...


=head1 SUPPORTED VARIABLE EXPRESSIONS

=over 4

=item ${name:#}

=item ${name:l}

=item ${name:u}

=item ${name:*<word>}

=item ${name:-<word>}

=item ${name:?<word>}

=item ${name:+<word>}

=item ${name:o<start>-<end>}

=item ${name:o<start>,<length>}

=item ${name:s/<pattern>/<string>/[gti]}

=item ${name:y/<ochars>/<nchars>/}

=item ${name:p/<width>/<string>/<align>}

=back

=head1 EBNF GRAMMAR OF SUPPORTED EXPRESSIONS

input      : (TEXT|variable)*

variable   : '$' (name|expression)

expression : START-DELIM (name|variable)+ (':' command)* END-DELIM

name       : (VARNAME|SPECIAL1|SPECIAL2)+

command    : '-' (EXPTEXT|variable)+
           | '+' (EXPTEXT|variable)+
           | 'o' (NUMBER ('-'|',') (NUMBER)?)
           | '#'
           | '*' (EXPTEXT|variable)+
           | 's' '/' (variable|SUBSTTEXT)+ '/' (variable|SUBSTTEXT)* '/' ('g'|'i'|'t')*
           | 'y' '/' (variable|SUBSTTEXT)+ '/' (variable|SUBSTTEXT)* '/'
           | 'p' '/' NUMBER '/' (variable|SUBSTTEXT)* '/' ('r'|'l'|'c')
           | 'l'
           | 'u'

START-DELIM: '{'

END-DELIM  : '}'

VARNAME    : '[a-zA-Z0-9_]+'

SPECIAL1   : '['

SPECIAL2   : ']'

NUMBER     : '[0-9]+'

SUBSTTEXT  : '[^$/]'

EXPTEXT    : '[^$}:]+'

TEXT       : '[^$]+'

=head1 CODES RETURNED BY THE LIBRARY

=over 4

=item VAR_EMPTY_PADDING_FILL_STRING

=item VAR_MISSING_PADDING_WIDTH

=item VAR_MALFORMATTED_PADDING

=item VAR_INCORRECT_TRANSPOSE_CLASS_SPEC

=item VAR_EMPTY_TRANSPOSE_CLASS

=item VAR_TRANSPOSE_CLASSES_MISMATCH

=item VAR_MALFORMATTED_TRANSPOSE

=item VAR_OFFSET_LOGIC_ERROR

=item VAR_OFFSET_OUT_OF_BOUNDS

=item VAR_RANGE_OUT_OF_BOUNDS

=item VAR_INVALID_OFFSET_DELIMITER

=item VAR_MISSING_START_OFFSET

=item VAR_EMPTY_SEARCH_STRING

=item VAR_MISSING_PARAMETER_IN_COMMAND

=item VAR_INVALID_REGEX_IN_REPLACE

=item VAR_UNKNOWN_REPLACE_FLAG

=item VAR_MALFORMATTED_REPLACE

=item VAR_UNKNOWN_COMMAND_CHAR

=item VAR_INPUT_ISNT_TEXT_NOR_VARIABLE

=item VAR_UNDEFINED_VARIABLE

=item VAR_INCOMPLETE_VARIABLE_SPEC

=item VAR_OUT_OF_MEMORY

=item VAR_INVALID_CONFIGURATION

=item VAR_INCORRECT_CLASS_SPEC

=item VAR_INCOMPLETE_GROUPED_HEX

=item VAR_INCOMPLETE_OCTAL

=item VAR_INVALID_OCTAL

=item VAR_OCTAL_TOO_LARGE

=item VAR_INVALID_HEX

=item VAR_INCOMPLETE_HEX

=item VAR_INCOMPLETE_NAMED_CHARACTER

=item VAR_INCOMPLETE_QUOTED_PAIR

=item VAR_OK

=back

=head1 SO ALSO

regex(7)

=cut