NAME
    ProjectBuilder::Conf, part of the project-builder.org - module dealing
    with configuration files

DESCRIPTION
    This modules provides functions dealing with configuration files.

SYNOPSIS
      use ProjectBuilder::Conf;

      #
      # Read hash codes of values from a configuration file and return table of pointers
      #
      my ($k1, $k2) = pb_conf_read_if("$ENV{'HOME'}/.pbrc","key1","key2");
      my ($k) = pb_conf_read("$ENV{'HOME'}/.pbrc","key");

USAGE
    pb_conf_init
        This function setup the environment pb for project-builder function
        usage from other projects. The first parameter is the project name. It
        sets up environment variables (pb)

    pb_conf_add
        This function adds the configuration file to the list last.

    pb_conf_read_if
        This function returns a table of pointers on hashes corresponding to
        the keys in a configuration file passed in parameter. If that file
        doesn't exist, it returns undef.

        The format of the configuration file is as follows:

        key tag = value1,value2,...

        Supposing the file is called "$ENV{'HOME'}/.pbrc", containing the
        following:

          $ cat $HOME/.pbrc
          pbver pb = 3
          pbver default = 1
          pblist pb = 12,25

        calling it like this:

          my ($k1, $k2) = pb_conf_read_if("$ENV{'HOME'}/.pbrc","pbver","pblist");

        will allow to get the mapping:

          $k1->{'pb'}  contains 3
          $k1->{'default'} contains 1
          $k2->{'pb'} contains 12,25

        Valid chars for keys and tags are letters, numbers, '-' and '_'.

    pb_conf_read
        This function is similar to pb_conf_read_if except that it dies when
        the file in parameter doesn't exist.

    pb_conf_get_if
        This function returns a table, corresponding to a set of values
        queried in the conf files or undef if it doen't exist. It takes a
        table of keys as an input parameter.

        The format of the configurations file is as follows:

        key tag = value1,value2,...

        It will gather the values from all the configurations files passed to
        pb_conf_add, and return the values for the keys, taking in account the
        order of conf files, to manage overloading.

          $ cat $HOME/.pbrc
          pbver pb = 1
          pblist pb = 4
          $ cat $HOME/.pbrc2
          pbver pb = 3
          pblist default = 5

        calling it like this:

          pb_conf_add("$HOME/.pbrc","$HOME/.pbrc2");
          my ($k1, $k2) = pb_conf_get_if("pbver","pblist");

        will allow to get the mapping:

          $k1->{'pb'} contains 3
          $k2->{'pb'} contains 4

        Valid chars for keys and tags are letters, numbers, '-' and '_'.

    pb_conf_fromfile_if
        This function returns a pointer on a table, corresponding to a merge
        of values queried in the conf file and the pointer on another table
        passed as parameter. It takes a table of keys as last input parameter.

          my ($k1) = pb_conf_fromfile_if("$HOME/.pbrc",undef,"pbver","pblist");
          my ($k2) = pb_conf_fromfile_if("$HOME/.pbrc3",$k1,"pbver","pblist");

        It is used internally by pb_conf_get_if and is not exported yet.

    pb_conf_get
        This function is the same pb_conf_get_if, except that it tests each
        returned value as they need to exist in that case.

WEB SITES
    The main Web site of the project is available at
    <http://www.project-builder.org/>. Bug reports should be filled using the
    trac instance of the project at <http://trac.project-builder.org/>.

USER MAILING LIST
    None exists for the moment.

AUTHORS
    The Project-Builder.org team <http://trac.project-builder.org/> lead by
    Bruno Cornec <mailto:bruno@project-builder.org>.

COPYRIGHT
    Project-Builder.org is distributed under the GPL v2.0 license described in
    the file "COPYING" included with the distribution.