SAMPLE CONFIG CLASS

  package MyConfig;

  use Parse::PlainConfig;
  use Parse::PlainConfig::Constants;
  use base qw(Parse::PlainConfig);
  use vars qw(%_globals %_parameters %_prototypes);

  %_globals = (
        'comment'        => '#',
        'delimiter'      => ':',
        'list delimiter' => ',',
        'hash delimiter' => '=>',
        'subindentation' => 4,
        'here doc'       => 'EOF',
      );
  %_parameters = (
      'daemon ports'    => PPC_ARRAY,
      'banner'          => PPC_HDOC,
      'user'            => PPC_SCALAR,
      'group'           => PPC_SCALAR,
      'database'        => PPC_HASH,
      'acls'            => PPC_HASH,
      );
  %_prototypes = (
      'define net'      => PPC_ARRAY,
      );

  1;

  __DATA__

  # This is the default configuration for MyConfig.
  # Newly created objects based on this class will 
  # inherit the below configuration as default values.
  #
  # daemon ports:  list of ports to listen on
  daemon ports:  8888, 9010

  # banner:  default banner to display on each connection
  banner: 
      ********  WARNING  ********
         You are being watched
      ********  WARNING  ********  
  EOF

  user: nobody
  group: nogroup
  database:
      host => localhost,
      db   => mydb,
      user => dbuser,
      pass => dbpass

  define net loopback: 127.0.0.1/8, ::1/128
  define net localnet: 192.168.0.0/24, 192.168.35.0/24
  define net nonlocal:  ! 192.168.0.0/16

  acls:  loopback => allow, localnet => allow, nonlocal => deny

  __END__

  =head1 NAME

  normal pod text can be put here...

SAMPLE OBJECT USAGE

  $config = new MyConfig;

  print "default user: ", $config->get('user'), "\n";
  print "default group: ", $config->get('group'), "\n";

  # Override value
  $config->set('user', 'root');

  # Get config from a file
  $rv = $config->read($filename);

  # Parse config from in-memory text
  $rv = $config->parse(@lines);

  # Prototyps are accessed like parameters
  @localnets = $config->get('localnet');

  # Reset config values back to class defaults
  $config->reset;

  # Print default config file
  print $config->default;

%_globals

    Key             Default   Description
    ---------------------------------------------------------------
    comment         #         Character(s) used to denote comments
    delimiter       :         Parameter/value delimiter
    list delimiter  ,         Ordinal array values delimiter
    hash delimiter  =>        Hash values' key/value pair delimiter
    subindentation  4         Default level of indentation to 
                              expect for line continuations
    here doc        EOF       Token used for terminating here doc
                              parameter values

If all of the defaults are acceptable this hash can be omitted entirely.

Note that the subindentation is merely advisory, any additional level of subindentation on line continuations will work. What this does, however, is trim up to that amount of preceding white space on each line within a here-doc. This allows one to indent blocks of text to maintain the visual flow of the config file, while still allowing the editor the use of all columns in the display.

%_parameters

    Type        Description
    ----------------------------------------------------------------
    PPC_SCALAR  Simple strings
    PPC_ARRAY   Arrays/lists
    PPC_HASH    Hashes/Associative arrays
    PPC_HDOC    Essentially a PPC_SCALAR that preserves formatting

All but PPC_HDOC will trim leading/trailing white space and collapse all lines into a single line for parsing. That means that no string, ordinal value, key, or associative value can have embedded line breaks. You can, however, have delimiter characters as part of any values as long as they are encapusated in quoted text or escaped.

PPC_HDOC will preserve line breaks, but will trim leading white space on each line up to the value given to $_globals{subindentation}.

%_prototypes

Like parameters prototypes are assigned a data type. Unlike parameters prototypes are assigned types based on a declarative preamble since the the name (or token) is not known in advance.

To continue with the ACL example we could define a prototype like so:

    %_prototypes = ( 'define acl' => PPC_ARRAY );

The config editor could then define any number of ACLs:

    define acl loopback 127.0.0.1/8
    define acl localnet 192.168.0.0/24,192.168.1.0/24

Once parsed those ACL parameters can then be accessed simply by their unique token:

    @localnets = $config->get('localnet');

DELIMITERS

Hash and array delimiters can be embedded in elements as long as they're quoted or escaped appropriately. Those elements are split using Text::ParseWords' quotewords function.

LINE CONTINUATIONS

There is one exception to that rule: here docs. If you need to preserve formatting, which can include line breaks, the use of here docs will suck in everything up to the next here doc EOF token. The entire here doc, however, is treated as scalar value for purposes of parameter storage.

COMMENTS

PARAMETER NAMES

PROTOTYPES

Since these dynamic properties are also formal properties the token must not be in use as a formal property. In other words, all prototype tokens and parameter names must be unique as a set.

Parsing errors will be generated if the token occurs as a formal parameter. It will also be generated if you attempt to redfine a token as a different type of data structure.

new

  $conf = new MyConfig;

This creates a new config object based on the specified config class, initialized with the defaults merged in __DATA__. No additional arguments are supported. This will fail if the default config is invalid in any way.

settings

  $settings = $config->settings;

This provides a reference to the engine settings object from which you can interrogate various settings such as delimiters, etc. The full set of methods supported by the settings object is documented in Parse::PlainConfig::Settings.

default

   $text  = $config->default;
   @lines = $config->default;

This returns the text of the default configuration file embedded in the __DATA__ section of the config class.

get

  $val = $config->get($parameter);
  @val = $config->get($parameter);
  %val = $config->get($parameter);

This returns the store value(s) for the specified parameter. It is essentially the same as using the parent class property method, although this will not cause the program to croak like property does. It will carp, instead.

set

  $rv = $config->set($parameter);
  $rv = $config->set($parameter, $newval);
  $rv = $config->set($parameter, @newval);
  $rv = $config->set($parameter, %newval);

This method sets the desired parameter to the newly specified value(s). If no values are provided it will assume that you wish to set scalars to undef or empty arrays and hashes.

parse

  $rv = $config->parse($text);
  $rv = $config->parse(@lines);

This will parse and set any parameters or protoypes found in the content. It will return false if any parsing errors are found (spurious text, etc.) but will extract everything of intelligible value it can.

read

  $rv = $config->read($filename);
  $rv = $config->read(@files);
  $rv = $config->read($pglob);
  $rv = $config->read(*fh);

This method will attempt to read every file passed to it, whether it be passed by file name, file handle, Paranoid::Glob, or objec reference support I/O functions. Fair warning: this does observe file locking semantics (flock) and it will close any file handles passed to it after consuming the content.

Also note that this method uses Paranoid::IO::Line, which implements protections against memory-utilization attacks. You may need to adjust the following parameters depending on the size of your config files:

  use Paranoid::IO qw(PIOMAXFSIZE PIOBLKSIZE);
  use Paranoid::IO qw(PIOMAXLNSIZE);

  # Adjust read block size for performance
  PIOBLKSIZE = 16 * 1024;

  # Allow file sizes up to 128KB
  PIOMAXFSIZE = 128 * 1024;

  # Allow individual lines to be 4KB long
  PIOMAXLNSIZE = 4 * 1024;

reset

  $rv = $config->reset;

This method emptys the contents of all parameters and prototypes, then applies the default settings as found in __DATA__.

prototyped

    @protos = $config->prototyped;
    @protos = $config->prototyped($preamble);

This method returns a list of properties that were defined as the result of prototypes. With no arguments it returns all properties that were defined. With an argument it returns only those properties that were defined by that specific prototype preamble.

error

    $errStr = $config->error;

Returns the last error that occurred. Note that this isn't reset between method invocations.