head	1.7;
access;
symbols
	FSL_1_7_0:1.7
	CFG_0_9_11:1.7
	FSL_1_6_1:1.6
	CFG_0_9_10:1.6
	FSL_1_6_0:1.6
	FSL_1_6b2:1.6
	CFG_0_9_9:1.6
	FSL_1_6b1:1.6
	CFG_0_9_8:1.6
	CFG_0_9_7:1.5
	CFG_0_9_6:1.5
	CFG_0_9_5:1.5;
locks; strict;
comment	@# @;


1.7
date	2006.08.10.19.36.00;	author rse;	state Exp;
branches;
next	1.6;
commitid	Isy241gp4yykKkIr;

1.6
date	2004.12.31.19.16.34;	author rse;	state Exp;
branches;
next	1.5;

1.5
date	2004.11.27.19.41.18;	author rse;	state Exp;
branches;
next	1.4;

1.4
date	2004.11.27.19.40.33;	author rse;	state Exp;
branches;
next	1.3;

1.3
date	2004.11.20.17.09.35;	author rse;	state Exp;
branches;
next	1.2;

1.2
date	2004.11.17.13.15.35;	author rse;	state Exp;
branches;
next	1.1;

1.1
date	2004.11.14.18.38.53;	author rse;	state Exp;
branches;
next	;


desc
@@


1.7
log
@cleanup source tree for status as of 2006
@
text
@##
##  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

@


1.6
log
@Adjust copyright messages for new year 2005.
@
text
@d3 2
a4 3
##  Copyright (c) 2002-2005 Ralf S. Engelschall <rse@@engelschall.com>
##  Copyright (c) 2002-2005 The OSSP Project <http://www.ossp.org/>
##  Copyright (c) 2002-2005 Cable & Wireless <http://www.cw.com/>
@


1.5
log
@fix POD syntax
@
text
@d3 3
a5 3
##  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/>
@


1.4
log
@Ok, let's rock: add four optional post-processing functions which allow
one to adjust an unpacked data structure in a way it can be used more
conveniently and intuitive.
@
text
@d62 1
a62 1
=item C<$tree = $cfg-E<gt>>B<unpack>C<(>[I<options]C<);>
@


1.3
log
@Add OSSP:::cfg::simple Perl convenience API which is an
ultra high-level API allowing especially the bi-directional
conversion between the C API node tree representation and a
simplified Perl data structure representation.
@
text
@d62 1
a62 1
=item C<$tree = $cfg-E<gt>>B<unpack>C<();>
d68 51
@


1.2
log
@document both the C and Perl APIs
@
text
@d43 24
a66 1
B<OSSP::cfg> provides two Perl APIs:
d71 1
a71 1
high-level and regular programming.
d77 1
a77 1
=item C<my $cfg = >B<new>C< OSSP::cfg;>
@


1.1
log
@Initial cut for Perl bindings to OSSP cfg. Still partly broken, of course ;-)
@
text
@d56 37
a92 1
=item C<$cfg-E<gt>>B<FIXME>C<($name);>
d94 1
a94 1
=item C<undef $cfg;>
d110 1
a110 1
=item C<$str = >B<cfg_FIXME>C<($rc);>
d112 1
a112 1
=item C<$str = >B<cfg_error>C<($rc);>
d116 33
a148 1
=item C<$rc = >B<cfg_destroy>C<($cfg);>
d152 2
a153 1
Additionally, the following constants are exported for use in C<$rc>, C<$mode>, C<$fmt> and C<$ver>:
d155 37
a191 6
C<CFG_RC_OK>,
C<CFG_RC_ARG>,
C<CFG_RC_MEM>,
C<CFG_RC_SYS>,
C<CFG_RC_INT>,
C<CFG_RC_IMP>.
@