NAME

       Sendpage::KeesConf - implements a configuration file reader

SYNOPSIS

           use Sendpage::KeesConf;
           $config = Sendpage::KeesConf->new();

           $config->define("variable", { DEFAULT => "setting" });

           $config->file("config.cfg");

           $setting=$config->get("variable");

DESCRIPTION

       I have borrowed VERY heavily from Andy Wardley's (abw@cre.canon.co.uk) "AppConfig" tool,
       which can be found on CPAN (http://cpan.perl.org) but I found it not dynamic enough for
       multi-instance variable defaults.  As a result, I wrote this massively trimmed-down
       version for my use.

       The following methods are available:

       $config = Sendpage::KeesConf->new();
           The constructor doesn't take an arguement, but it should in the future.

       $config->forget();
           This call will make $config forget about any variables it has loaded.  It does NOT
           forget "define"d variables, just instantiated ones via "file".

       $config->define($name, $options);
           This will define a variable by the name of $name.

           $options can contain:

           ARGCOUNT
               What type of variable this should be.  Default value is "1".  The available types
               are:

               0   Boolean (true/false, yes/no, 1/0)

               1   Scalar (any string)

               2   List (an array of strings)

           DEFAULT
               The default value the variable should have if it is not overridden during the call
               to "file".  The DEFAULT must be the same data type as ARGCOUNT.  The default
               DEFAULT is the string "<unset>".

           UNSET
               set this to 1 if you want the default value to be undefined.  This is a hack to
               get around the default DEFAULT.

       $config->instance_exists($name);
           This tests to see if there is a section loaded named $name

       $var=$config->ifset($name);
           This call will search for the variable named $name.  If it is not found, it will
           return undef.  If the value exists, it will return the value.  This is a way to call
           "get" without having a default passed through.

       $var=$config->exists($name);
           This call will search for the variable named $name.  If it is not found, it will
           return false.  If the value exists, it will return true.  This is a way for the user
           to find out if they will get a "default" on a call to "get".

       $var=$config->fallbackget($name,$quiet);
           This call will search for the variable named $name.  If it is not found, the section
           portion will be removed, and retried for a sectionless "get" call.

           That way, global variables can be overridden by section-specific variables.  If
           "SECTION:Instance@name" does not exist, "name" will be tried.

       $var=$config->get($name);
           This call will search for the variable named $name.  If it is not found, it will fall
           back to the default for the section.   Sections are explained in more detail later.

       $config->instances($class);
           Returns an array of the names of all the variables in the class $class.

       $config->file('program.cfg');
           Loads variables from the named file.  Syntax for this file is:

               [SECTION:INSTANCE]
               VARIABLE1 = VALUE1
               VARIABLE2 = VALUE2
               .
               .
               .

           If VARIABLE is an array, VALUE is loaded using commas (,) as the list separator.  The
           variable will be available under the name of the section.  For example, to see VALUE2,
           it would be accessed as:

               $config->get("SECTION:INSTANCE\@VARIABLE2");

           Notice, that "=", ":", and "@" are all not allowed in section or variable names.

       Sections can be defined (and loaded) so that defaults can pass back to a defined section
       default.  For example, lets say that you have several modems, and most of them have
       different settings.  You can define all the modem variables like so:

               $config->define("modem:baud",{ DEFAULT => 9600 });
               $config->define("modem:flowctl",{ DEFAULT => "hardware" });

       Then, when you load them, let's say the config file has:

               [modem:sportster]
               baud = 115200

               [modem:hayes]

       The baud rate for the sportster will come back as 115200, but the hayes will fall back
       during a "get" call, and find the default for the modem section: 9600.  Both fallback to
       have "flowctl" as "hardware":

           # returns specific value 115200
           $config->get("modem:sportster\@baud");

           # returns default value 9600
           $config->get("modem:hayes\@baud");

           # both return default value "hardware"
           $config->get("modem:sportster\@flowctl");
           $config->get("modem:hayes\@flowctl");

CAVEATS

       character limitations
           As mentioned above, variable names (and section names) cannot have the characters ":",
           "@", or "=" in them.

       default defaults
           There should be a way to pass default defaults into "new".  That would be handy, and
           could eliminate the need for the UNSET option in "define".

AUTHOR

       Kees Cook <kees@outflux.net>

SEE ALSO

       perl(1), sendpage(1), Sendpage::KeesLog(3), Sendpage::Modem(3),
       Sendpage::PagingCentral(3), Sendpage::PageQueue(3), Sendpage::Page(3),
       Sendpage::Recipient(3), Sendpage::Queue(3)

COPYRIGHT

       Copyright 2000 Kees Cook.

       This library is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.