head	1.14;
access;
symbols
	FSL_1_7_0:1.14
	CFG_0_9_11:1.14
	FSL_1_6_1:1.13
	CFG_0_9_10:1.13
	FSL_1_6_0:1.13
	FSL_1_6b2:1.13
	CFG_0_9_9:1.13
	FSL_1_6b1:1.13
	CFG_0_9_8:1.13
	CFG_0_9_7:1.12
	CFG_0_9_6:1.12
	CFG_0_9_5:1.12
	CFG_0_9_4:1.12
	FSL_1_5_0:1.11
	FSL_1_5a3:1.11
	CFG_0_9_3:1.11
	FSL_1_5a2:1.11
	FSL_1_5a1:1.11
	FSL_1_4_0:1.11
	FSL_1_4b1:1.11
	CFG_0_9_2:1.11
	CFG_0_9_1:1.11
	FSL_1_4a1:1.11
	FSL_1_3_0:1.11
	FSL_1_3b1:1.11
	FSL_1_2_1:1.11
	FSL_1_2_0:1.11
	FSL_1_1_0:1.11
	FSL_1_1b1:1.11
	FSL_1_0_8:1.11
	FSL_1_0_7:1.11
	FSL_1_0_6:1.8
	FSL_1_0_5:1.8
	FSL_1_0_4:1.8
	FSL_1_0_3:1.7
	FSL_1_0_2:1.7
	FSL_1_0_1:1.6
	FSL_1_0_0:1.6
	FSL_0_9_0:1.6
	CFG_0_9_0:1.6
	FSL_0_1_12:1.5
	FSL_0_1_11:1.5
	FSL_0_1_10:1.5
	FSL_0_1_9:1.4
	FSL_0_1_8:1.4
	FSL_0_1_7:1.4
	FSL_0_1_6:1.4
	FSL_0_1_5:1.4
	FSL_0_1_1:1.4;
locks; strict;
comment	@# @;


1.14
date	2006.08.10.19.35.56;	author rse;	state Exp;
branches;
next	1.13;
commitid	Isy241gp4yykKkIr;

1.13
date	2004.12.31.19.16.25;	author rse;	state Exp;
branches;
next	1.12;

1.12
date	2004.07.17.07.37.55;	author rse;	state Exp;
branches;
next	1.11;

1.11
date	2003.01.06.11.17.43;	author rse;	state Exp;
branches;
next	1.10;

1.10
date	2002.11.19.14.43.22;	author rse;	state Exp;
branches;
next	1.9;

1.9
date	2002.11.10.12.12.23;	author rse;	state Exp;
branches;
next	1.8;

1.8
date	2002.10.05.15.49.23;	author rse;	state Exp;
branches;
next	1.7;

1.7
date	2002.08.09.13.30.18;	author rse;	state Exp;
branches;
next	1.6;

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

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

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

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

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

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


desc
@@


1.14
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.pod: manual page
##

=pod

=head1 NAME

B<OSSP cfg> - Configuration Parsing

=head1 VERSION

OSSP cfg CFG_VERSION_STR

=head1 SYNOPSIS

=over 4

=item B<API Header:>

cfg.h

=item B<API Types:>

cfg_t,
cfg_rc_t,
cfg_node_type_t,
cfg_node_t,
cfg_node_attr_t,
cfg_fmt_t,
cfg_data_t,
cfg_data_ctrl_t,
cfg_data_cb_t,
cfg_data_attr_t

=item B<API Functions:>

cfg_create,
cfg_destroy,
cfg_error,
cfg_version,
cfg_import,
cfg_export,
cfg_node_create,
cfg_node_destroy,
cfg_node_clone,
cfg_node_set,
cfg_node_get,
cfg_node_root,
cfg_node_select,
cfg_node_find,
cfg_node_apply,
cfg_node_cmp,
cfg_node_link,
cfg_node_unlink,
cfg_data_set,
cfg_data_get,
cfg_data_ctrl

=back

=head1 DESCRIPTION

B<OSSP cfg> is a ISO-C library for parsing arbitrary C/C++-style
configuration files. A configuration is sequence of directives. Each
directive consists of zero or more tokens. Each token can be either a
string or again a complete sequence. This means the configuration syntax
has a recursive structure and this way allows to create configurations
with arbitrarily nested sections.

Additionally the configuration syntax provides complex
single/double/balanced quoting of tokens, hexadecimal/octal/decimal
character encodings, character escaping, C/C++ and Shell-style comments,
etc. The library API allows importing a configuration text into an
Abstract Syntax Tree (AST), traversing the AST and optionally exporting
the AST again as a configuration text.

=head2 CONFIGURATION SYNTAX

The configuration syntax is described by the following context-free
(Chomsky-2) grammar:

B<sequence>   ::= I<empty>
             | B<directive>
             | B<directive> B<SEP> B<sequence>

B<directive>  ::= B<token>
             | B<token> B<directive>

B<token>      ::= B<OPEN> B<sequence> B<CLOSE>
             | B<string>

B<string>     ::= B<DQ_STRING>   # double quoted string
             | B<SQ_STRING>   # single quoted string
             | B<FQ_STRING>   # flexible quoted string
             | B<PT_STRING>   # plain text string

The other contained terminal symbols are defined itself by the following
set of grammars production (regular sub-grammars for character
sequences given as Perl-style regular expressions "/I<regex>/"):

B<SEP>        ::= /;/

B<OPEN>       ::= /{/

B<CLOSE>      ::= /}/

B<DQ_STRING>  ::= /"/ B<DQ_CHARS> /"/

B<DQ_CHARS>   ::= I<empty>
             | B<DQ_CHAR> B<DQ_CHARS>

B<DQ_CHAR>    ::= /\\"/               # escaped quote
             | /\\x\{[0-9a-fA-F]+\}/ # hex-char group
             | /\\x[0-9a-fA-F]{2}/ # hex-char
             | /\\[0-7]{1,3}/      # octal character
             | /\\[nrtbfae]/       # special character
             | /\\\n[ \t]*/        # line continuation
             | /\\\\/              # escaped escape
             | /./                 # any other char

B<SQ_STRING>  ::= /'/ B<SQ_CHARS> /'/

B<SQ_CHARS>   ::= I<empty>
             | B<SQ_CHAR> B<SQ_CHARS>

B<SQ_CHAR>    ::= /\\'/               # escaped quote
             | /\\\n[ \t]*/        # line contination
             | /\\\\/              # escaped escape
             | /./                 # any other char

B<FQ_STRING>  ::= /q/ B<FQ_OPEN> B<FQ_CHARS> B<FQ_CLOSE>

B<FQ_CHARS>   ::= I<empty>
             | B<FQ_CHAR> B<FQ_CHARS>

B<FQ_CHAR>    ::= /\\/ B<FQ_OPEN>        # escaped open
             | /\\/ B<FQ_CLOSE>       # escaped close
             | /\\\n[ \t]*/        # line contination
             | /./                 # any other char

B<FQ_OPEN>    ::= /[!"#$%&'()*+,-./:;<=>?@@\[\\\]^_`{|}~]/

B<FQ_CLOSE>   ::= E<lt>E<lt> B<FQ_OPEN> or corresponding closing char
                  ('}])>') if B<FQ_OPEN> is a char of '{[(<' E<gt>E<gt>

B<PT_STRING>  ::= B<PT_CHAR> B<PT_CHARS>

B<PT_CHARS>   ::= I<empty>
             | B<PT_CHAR> B<PT_STRING>

B<PT_CHAR>    ::= /[^ \t\n;{}"']/     # none of specials

Additionally, white-space B<WS> and comment B<CO> tokens are allowed at
any position in the above productions of the previous grammar part.

B<WS>         ::= /[ \t\n]+/

B<CO>         ::= B<CO_C>                # style of C
             | B<CO_CXX>              # style of C++
             | B<CO_SH>               # style of /bin/sh

B<CO_C>       ::= /\/\*([^*]|\*(?!\/))*\*\//

B<CO_CXX>     ::= /\/\/[^\n]*/

B<CO_SH>      ::= /#[^\n]*/

Finally, any configuration line can have a trailing backslash character
(C<\>) just before the newline character for simple line continuation.
The backslash, the newline and (optionally) the leading whitespaces on
the following line are silently obsorbed and as a side-effect continue
the first line with the contents of the second lines.

=head2 CONFIGURATION EXAMPLE

A more intuitive description of the configuration syntax is perhaps given by
the following example which shows all features at once:

 /* single word */
 foo;

 /* multi word */
 foo bar quux;

 /* nested structure */
 foo { bar; baz } quux;

 /* quoted strings */
 'foo bar'
 "foo\x0a\t\n\
  bar"

=head1 APPLICATION PROGRAMMING INTERFACE (API)

...

=head1 NODE SELECTION SPECIFICATION

The B<cfg_node_select> function takes a I<node selection specification>
string B<select> for locating the intended nodes. This specification is
defined as:

B<select>           ::= I<empty>
                   | B<select-step> B<select>

B<select-step>      ::= B<select-direction>
                     B<select-pattern>
                     B<select-filter>

B<select-direction> ::= "./"        # current node
                   | "../"       # parent node
                   | "..../"     # anchestor nodes
                   | "-/"        # previous sibling node
                   | "--/"       # preceeding sibling nodes
                   | "+/"        # next sibling node
                   | "++/"       # following sibling nodes
                   | "/"         # child nodes
                   | "//"        # descendant nodes

B<select-pattern>   ::= /</ B<regex> />/
                   | B<token>

B<select-filter>    ::= I<empty>
                   | /\[/ B<filter-range> /\]/

B<filter-range>     ::= B<num>           # short for: num,num
                   | B<num> /,/          # short for: num,-1
                   | /,/ B<num>          # short for: 1,num
                   | B<num> /,/ B<num>

B<num>              ::= /^[+-]?[0-9]+/

B<regex>            ::= E<lt>E<lt> Regular Expression (PCRE-based) E<gt>E<gt>

B<token>            ::= E<lt>E<lt> Plain-Text Token String E<gt>E<gt>

=head1 IMPLEMENTATION ISSUES

Goal: non-hardcoded syntax tokens, only hard-coded syntax structure
Goal: time-efficient parsing
Goal: space-efficient storage
Goal: representation of configuration as AST
Goal: manipulation (annotation, etc) of AST via API
Goal: dynamic syntax verification

=head1 HISTORY

B<OSSP cfg> was implemented in lots of small steps over a very
long time. The first ideas date back to the year 1995 when
Ralf S. Engelschall attended his first compiler construction lessons at
university. But it was first time finished in summer 2002 by him for use
in the B<OSSP> project.

=head1 AUTHOR

 Ralf S. Engelschall
 rse@@engelschall.com
 www.engelschall.com

=cut

@


1.13
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.12
log
@Adjust copyright messages for new year 2004.
@
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.11
log
@update copyright messages for new year
@
text
@d3 3
a5 3
##  Copyright (c) 2002-2003 Ralf S. Engelschall <rse@@engelschall.com>
##  Copyright (c) 2002-2003 The OSSP Project (http://www.ossp.org/)
##  Copyright (c) 2002-2003 Cable & Wireless Deutschland (http://www.cw.com/de/)
@


1.10
log
@use my latest XRE+XCG syntax
@
text
@d3 3
a5 3
##  Copyright (c) 1999-2002 Ralf S. Engelschall <rse@@engelschall.com>
##  Copyright (c) 1999-2002 The OSSP Project (http://www.ossp.org/)
##  Copyright (c) 2001-2002 Cable & Wireless Deutschland (http://www.cw.com/de/)
@


1.9
log
@remove trailing whitespaces
@
text
@d170 2
a171 2
B<FQ_CLOSE>   ::= "B<FQ_OPEN> or corresponding closing char
               ('}])>') if B<FQ_OPEN> is a char of '{[(<'"
d222 1
a222 9
spec:

 parent  ..
 lbroth  ->
 rbroth  <-
 child[1]
 child[L]

 virtualhost[2].directory
d260 1
a260 1
B<regex>            ::= "Regular Expression (PCRE-based)"
d262 1
a262 1
B<token>            ::= "Plain-Text Token String"
@


1.8
log
@flush pending changes
@
text
@d64 6
a69 6
cfg_create,     
cfg_destroy,    
cfg_error,      
cfg_version,    
cfg_import,     
cfg_export,     
d72 4
a75 4
cfg_node_clone, 
cfg_node_set,   
cfg_node_get,   
cfg_node_root,  
d77 4
a80 4
cfg_node_find,  
cfg_node_apply, 
cfg_node_cmp,   
cfg_node_link,  
d82 2
a83 2
cfg_data_set,   
cfg_data_get,   
d113 1
a113 1
B<directive>  ::= B<token> 
d227 1
a227 1
 child[1] 
d241 2
a242 2
B<select-step>      ::= B<select-direction> 
                     B<select-pattern> 
d256 1
a256 1
                   | B<token> 
d265 1
a265 1
                   
@


1.7
log
@start documentation
@
text
@d272 9
@


1.6
log
@polishing for release
@
text
@d37 4
d43 44
a86 1
...
@


1.5
log
@some style cleanups
@
text
@d47 9
a55 2
has a recursive structure and this way allows to configure structures
which require arbitrarily nested sections.
@


1.4
log
@flush work of today: first cut for real cfg_node_select()
@
text
@d55 14
a68 14
B<sequence>      ::= I<empty>
                | B<directive>
                | B<directive> B<SEP> B<sequence>

B<directive>     ::= B<token> 
                | B<token> B<directive>

B<token>         ::= B<OPEN> B<sequence> B<CLOSE>
                | B<string>

B<string>        ::= B<DQ_STRING>   # double quoted string
                | B<SQ_STRING>   # single quoted string
                | B<FQ_STRING>   # flexible quoted string
                | B<PT_STRING>   # plain text string
d74 1
a74 1
B<SEP>           ::= /;/
d76 1
a76 1
B<OPEN>          ::= /{/
d78 1
a78 1
B<CLOSE>         ::= /}/
d80 1
a80 1
B<DQ_STRING>     ::= /"/ B<DQ_CHARS> /"/
d82 2
a83 2
B<DQ_CHARS>      ::= I<empty>
                | B<DQ_CHAR> B<DQ_CHARS>
d85 8
a92 8
B<DQ_CHAR>       ::= /\\"/               # escaped quote
                | /\\x\{[0-9a-fA-F]+\}/ # hex-char group
                | /\\x[0-9a-fA-F]{2}/ # hex-char
                | /\\[0-7]{1,3}/      # octal character
                | /\\[nrtbfae]/       # NL,CR,TAB,BS,FF,BEL,ESC
                | /\\\n[ \t]*/        # line continuation
                | /\\\\/              # escaped escape
                | /./                 # any other char
d94 1
a94 1
B<SQ_STRING>     ::= /'/ B<SQ_CHARS> /'/
d96 2
a97 2
B<SQ_CHARS>      ::= I<empty>
                | B<SQ_CHAR> B<SQ_CHARS>
d99 4
a102 4
B<SQ_CHAR>       ::= /\\'/               # escaped quote
                | /\\\n[ \t]*/        # line contination
                | /\\\\/              # escaped escape
                | /./                 # any other char
d104 1
a104 1
B<FQ_STRING>     ::= /q/ B<FQ_OPEN> B<FQ_CHARS> B<FQ_CLOSE>
d106 2
a107 2
B<FQ_CHARS>      ::= I<empty>
                | B<FQ_CHAR> B<FQ_CHARS>
d109 4
a112 4
B<FQ_CHAR>       ::= /\\/ B<FQ_OPEN>    # escaped open
                | /\\/ B<FQ_CLOSE>    # escaped close
                | /\\\n[ \t]*/        # line contination
                | /./                 # any other char
d114 1
a114 1
B<FQ_OPEN>       ::= /[!"#$%&'()*+,-./:;<=>?@@\[\\\]^_`{|}~]/
d116 2
a117 2
B<FQ_CLOSE>      ::= "B<FQ_OPEN> or corresponding closing char
                  ('}])>') if B<FQ_OPEN> is a char of '{[(<'"
d119 1
a119 1
B<PT_STRING>     ::= B<PT_CHAR> B<PT_CHARS>
d121 2
a122 2
B<PT_CHARS>      ::= I<empty>
                | B<PT_CHAR> B<PT_STRING>
d124 1
a124 1
B<PT_CHAR>       ::= /[^ \t\n;{}"']/     # none of specials
d129 1
a129 1
B<WS>            ::= /[ \t\n]+/
d131 3
a133 3
B<CO>            ::= B<CO_C>                # style of C
                | B<CO_CXX>              # style of C++
                | B<CO_SH>               # style of /bin/sh
d135 1
a135 1
B<CO_C>          ::= /\/\*([^*]|\*(?!\/))*\*\//
d137 1
a137 1
B<CO_CXX>        ::= /\/\/[^\n]*/
d139 1
a139 1
B<CO_SH>         ::= /#[^\n]*/
@


1.3
log
@just flush work of this evening
@
text
@d178 40
d221 4
a224 4
long time. The first ideas date back to the year 1995 when Ralf S.
Engelschall attended his first compiler construction lessons at
university. But it was first time finished in 2002 by him for use in the
B<OSSP> project.
@


1.2
log
@document flexible quoted string and line continuation
@
text
@d168 10
@


1.1
log
@Add this first cut for the forthcoming OSSP cfg library to CVS.
This is work in progress and still not ready for use anywhere.
@
text
@d67 1
d86 2
a87 1
                | /\\x[0-9a-zA-Z]{2}/ # hexadecimal char
d89 1
a89 1
                | /\\[trn]/           # TAB, CR, NL
d104 15
d140 6
@