##
##  OSSP cfg - Configuration Parsing
##  Copyright (c) 2002-2004 Ralf S. Engelschall <rse@engelschall.com>
##  Copyright (c) 2002-2004 The OSSP Project <http://www.ossp.org/>
##  Copyright (c) 2002-2004 Cable & Wireless <http://www.cw.com/>
##
##  This file is part of OSSP cfg, a configuration parsing library which
##  can be found at http://www.ossp.org/pkg/lib/cfg/.
##
##  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.
##
##  cfg.pm: Perl Binding (Perl/POD part)
##

=pod

=head1 NAME

OSSP::cfg - B<OSSP cfg> Perl Binding

=head1 DESCRIPTION

B<OSSP::cfg> is the Perl binding to the B<OSSP cfg> API.

B<OSSP cfg> is ...

B<OSSP::cfg> provides three Perl APIs:

=head2 SIMPLE API

The simple API is a wrapper around the OO-style API and intended
for working with configurations the really simple but less flexible way:

=over 4

=item C<use OSSP::cfg;>

=item C<$cfg = >B<new>C< OSSP::cfg::simple;>

=item C<$cfg-E<gt>>B<parse>C<($txt);>

=item C<$cfg-E<gt>>B<pack>C<($tree);>

=item C<$txt  = $cfg-E<gt>>B<format>C<();>

=item C<$tree = $cfg-E<gt>>B<unpack>C<(>[I<options>]C<);>

=item C<undef $cfg;>

=back

The B<unpack()> I<options> are:

=over 4

=item C<-merge =E<gt> >I<dir-regex>

Merge all directives with a start token matching against I<dir-regex> by
appending the argument tokens of second and following directives to the
first directive. The resulting data structure is changed as following:
 
  before: [['foo','foo1'],['bar'],['foo','foo2']]
  after:  [['foo','foo1','foo2'],['bar']]

=item C<-index =E<gt> >I<dir-regex>

Add all directives start tokens matching against I<dir-regex> to a
pseudo-directive element pointing to the first occurrence of the
directive.

  before: [['foo','foo1'],['bar','bar1'],['quux','quux1']]
  after:  [{'foo'=>1,'bar'=>2,'quux'=>3},
           ['foo','foo1'],['bar','bar1'],['quux','quux1']]

This leverages perlref(1)'s "Pseudo-hashes: Using an array as a hash"
approach to allow one to directly access directives by name. The
following are then equivalent:

  ...->{'bar'}
  ...->[2]

=item C<-strip =E<gt> >I<dir-regex>

Strip start token of all directives where it matches the I<dir-regex>.
This is useful in combination with B<-index> only.

  before: [['foo','foo1'],['bar','bar1'],['quux','quux1']]
  after:  [['foo1'],['bar1'],['quux1']]

=item C<-flatten =E<gt> >I<boolean-value>

Flatten the tokens of all directives with a start token matching
against I<dir-regex> by replacing empty arrays with I<boolean-value>,
arrays containing a single token with just the token and leaving arrays
containing more than one token as is. This is useful in combination with
B<-index> and B<-strip>.

  before: [['foo','foo1'],['bar'],['']]
  after:  [['foo','foo1'],'bar',1]

=back

=head2 OO-STYLE API

The OO-style API is a wrapper around the C-style API and intended for
high-level and flexible programming.

=over 4

=item C<use OSSP::cfg;>

=item C<$cfg = >B<new>C< OSSP::cfg;>

=item C<undef $cfg;>

=item [C<(>]C<$error>[C<, $rc)>]C< = $cfg-E<gt>>B<error>C<($cfg>[C<, $rc>]C<);>

=item C<$ver = $cfg-E<gt>>B<version>C<();>

=item C<$cfg-E<gt>>B<import>C<($name, $fmt, $str);>

=item C<$str = $cfg-E<gt>>B<export>C<($name, $fmt);>

=item C<$node = $cfg-E<gt>>B<node_create>C<();>

=item C<$cfg-E<gt>>B<node_destroy>C<($node);>

=item C<$node2 = $cfg-E<gt>>B<node_clone>C<($node);>

=item C<$cfg-E<gt>>B<node_set>C<($node, $attr, $value);>

=item C<$value = $cfg-E<gt>>B<node_get>C<($node, $attr);>

=item C<$node = $cfg-E<gt>>B<node_root>C<();>

=item C<$result = $cfg-E<gt>>B<node_select>C<($node, $spec);>

=item C<$cont = $cfg-E<gt>>B<node_find>C<($node, \&cb_fct_cmp, $cb_ctx_cmp);>

=item C<$cfg-E<gt>>B<node_apply>C<($node, \&cb_fct_cmp, $cb_ctx_cmp, \&cb_fct_cb, $cb_ctx_cb);>

=item C<$cfg-E<gt>>B<node_cmp>C<($node, $token);>

=item C<$cfg-E<gt>>B<node_link>C<($node, $id, $node2);>

=item C<$cfg-E<gt>>B<node_unlink>C<($node);>

=item C<$cfg-E<gt>>B<data_set>C<($data, $attr, $value);>

=item C<$value = $cfg-E<gt>>B<data_get>C<($data, $attr);>

=item C<$cfg-E<gt>>B<data_ctrl>C<($data, $ctrl>[C<, $value>]C<);>

=back

=head2 C-STYLE API

The C-style API is a direct mapping of the B<OSSP cfg> ISO-C API to Perl
and is intended for low-level programming. See cfg(3) for a description
of the functions and their expected arguments.

=over 4

=item C<use OSSP::cfg qw(:all);>

=item C<my $cfg; $rc = >B<cfg_create>C<($cfg);>

=item C<$rc = >B<cfg_destroy>C<($cfg);>

=item C<$rc = >B<cfg_error>C<($cfg, $rc, $error);>

=item C<$ver = >B<cfg_version>C<();>

=item C<$rc = >B<cfg_import>C<($cfg, $node, $fmt, $in_ptr, $in_len);>

=item C<$rc = >B<cfg_export>C<($cfg, $node, $fmt, $ex_ptr, $ex_len);>

=item C<$rc = >B<cfg_node_create>C<($cfg, $node);>

=item C<$rc = >B<cfg_node_destroy>C<($cfg, $node);>

=item C<$rc = >B<cfg_node_clone>C<($cfg, $node, $node2);>

=item C<$rc = >B<cfg_node_set>C<($cfg, $node, $attr, ...);>

=item C<$rc = >B<cfg_node_get>C<($cfg, $node, $attr, ...);>

=item C<$rc = >B<cfg_node_root>C<($cfg, $node);>

=item C<$rc = >B<cfg_node_select>C<($cfg, $node, $result, $spec);>

=item C<$rc = >B<cfg_node_find>C<($cfg, $node, $cb_fct_cmp, $cb_ctx_cmp, $cont);>

=item C<$rc = >B<cfg_node_apply>C<($cfg, $node, $cb_fct_cmp, $cb_ctx_cmp, $cb_fct_cb, $cb_ctx_cb);>

=item C<$rc = >B<cfg_node_cmp>C<($cfg, $node, $token);>

=item C<$rc = >B<cfg_node_link>C<($cfg, $node, $id, $node2);>

=item C<$rc = >B<cfg_node_unlink>C<($cfg, $node);>

=item C<$rc = >B<cfg_data_set>C<($data, $attr, ...);>

=item C<$rc = >B<cfg_data_get>C<($data, $attr, ...);>

=item C<$rc = >B<cfg_data_ctrl>C<($data, $ctrl, ...);>

=back

Additionally, the following constants are exported for use in C<$rc>, C<$attr>, C<$ctrl> and variable
arguments:

C<CFG_OK>,
C<CFG_ERR_ARG>,
C<CFG_ERR_USE>,
C<CFG_ERR_MEM>,
C<CFG_ERR_SYS>,
C<CFG_ERR_FMT>,
C<CFG_ERR_INT>,
C<CFG_ERR_SYN>,
C<CFG_ERR_NDE>,
C<CFG_FMT_CFG>,
C<CFG_FMT_XML>,
C<CFG_NODE_TYPE_SEQ>,
C<CFG_NODE_TYPE_DIR>,
C<CFG_NODE_TYPE_OPT>,
C<CFG_NODE_TYPE_ARG>,
C<CFG_NODE_ATTR_PARENT>,
C<CFG_NODE_ATTR_LBROTH>,
C<CFG_NODE_ATTR_RBROTH>,
C<CFG_NODE_ATTR_CHILD1>,
C<CFG_NODE_ATTR_CHILDL>,
C<CFG_NODE_ATTR_CHILDS>,
C<CFG_NODE_ATTR_NODES>,
C<CFG_NODE_ATTR_DEPTH>,
C<CFG_NODE_ATTR_SRCNAME>,
C<CFG_NODE_ATTR_SRCPOS>,
C<CFG_NODE_ATTR_TYPE>,
C<CFG_NODE_ATTR_TOKEN>,
C<CFG_NODE_ATTR_DATA>,
C<CFG_DATA_TYPE_PTR>,
C<CFG_DATA_TYPE_STR>,
C<CFG_DATA_TYPE_INT>,
C<CFG_DATA_TYPE_FLT>,
C<CFG_DATA_CTRL_CLONE>,
C<CFG_DATA_CTRL_DESTROY>,
C<CFG_DATA_ATTR_TYPE>,
C<CFG_DATA_ATTR_VALUE>,
C<CFG_DATA_ATTR_CTRL>.

=head1 EXAMPLES

FIXME

=head1 SEE ALSO

cfg(3), cfg-config(1).

=head1 HISTORY

The Perl binding B<OSSP::cfg> to B<OSSP cfg> was implemented in
November 2004 by Ralf S. Engelschall E<lt>rse@engelschall.comE<gt>.

=cut