ossp-pkg/cfg/perl/cfg.pod
##
## OSSP cfg - Configuration Parsing
## Copyright (c) 2002-2006 Ralf S. Engelschall <rse@engelschall.com>
## Copyright (c) 2002-2006 The OSSP Project <http://www.ossp.org/>
##
## 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
