NAME
    Config::General::Validate - Validate Config Hashes

SYNOPSIS
     use Config::General::Validate;
     my $validator = new Config::General::Validate($reference);
     if ( $validator->validate($config_hash_reference) ) {
       print "valid\n";
     }
     else {
       print "invalid\n";
     }

DESCRIPTION
    This module validates a config hash reference against a given hash
    structure. This hash could be the result of Config::General or just any
    other hash structure. Eg. the hash returned by XML::Simple could also be
    validated using this module. You may also use it to validate CGI input,
    just fetch the input data from CGI, map it to a hash and validate it.

    The following builtin data types can be used:

    int integer

    number
        real number

    word
        single word

    line
        line of text

    text
        a whole text(blob) including newlines.

    regex
        regex starting with qr.

        Please note, that this doesn't mean you can provide here a regex
        against config options must match.

        Instead this means that the config options contains a regex.

        eg:

         <cfg>
           grp  = qr/root|wheel/
         </cfg>

        regex would match the content of the variable 'grp' in this example.

        To add your own rules for validation, use the type() method, see
        below.

    uri uri, right

    ipv4
        ip address (v4)

    cidr
        same as above with cidr netmast (/24)

    quoted
        text quoted with single quotes

    hostname
        valid hostname

    resolvablehost
        hostname resolvable via dns lookup

    path
        valid absolute path (portable)

    fileexists
        file which must exists

    user
        existent user

    group
        existent group

    port
        valid tcp/udp port

    novars
        text shall not contain variables

VALIDATOR STRUCTURE
    The expected structure must be a standard perl hash reference. This hash
    may look like the config you are validating but instead of real-live
    values it contains types that define of what type a given value has to
    be.

    In addition the hash may be deeply nested. In this case the validated
    config must be nested the same way as the reference hash.

    Example:

     $reference = { user => 'word', uid => 'int' };

    The following config would be validated successful:

     $config = { user => 'HansDampf',  uid => 92 };

    this one not:

     $config = { user => 'Hans Dampf', uid => 'nine' };
                              ^                ^^^^
                              |                |
                              |                +----- is not a number
                              +---------------------- space not allowed

    For easier writing of references you are encouraged to use
    Config::General, just write the definition using the syntax of
    Config::General, get the hash of it and use this hash for validation.

    See t/run.t there are some examples of this technique.

SUBROUTINES/METHODS
    validate($config)
        $config must be a hash reference you'd like to validate.

        It returns a true value if the given structure looks valid.

        If the return value is false (0), then the error message will be
        written to the variable $!.

    type(%types)
        You can enhance the validator by adding your own rules. Just add one
        or more new types using a simple hash using the type() method.
        Values in this hash can be regexes or anonymous subs.

        Example:

         $v3->type(
          (
          address => qr(^\w+\s\s*\d+$),
          list    =>
            sub {
              my $list = $_[0];
              my @list = split /\s*,\s*/, $list;
              if (scalar @list > 1) {
                return 1;
              }
              else {
                return 0;
              }
            }
          )
         );

        In this example we add 2 new types, 'list' and 'address', which are
        really simple. 'address' is a regex which matches a word followed by
        an integer. 'list' is a subroutine which gets called during
        evaluation for each option which you define as type 'list'.

        Such subroutines must return a true value in order to produce a
        match.

        You can also add reversive types, which are like all other types but
        start with no. The validator does a negative match in such a case,
        thus you will have a match if a variable does not match the type.
        The builtin type 'novars' is such a type.

        Regexes will be executed exactly as given. No flags or ^ or $ will
        be used by the module. Eg. if you want to match the whole value from
        beginning to the end, add ^ and $, like you can see in our 'address'
        example above.

    debug()
        Enables debug output which gets printed to STDERR.

    errstr()
        Returns the last error, which is useful to notify the user about
        what happened.

ARRAYS
    Arrays must be handled in a special way, just define an array with two
    elements and the second empty. The config will only validated against
    the first element in the array.

    We assume all elements in an array must have the same structure.

    Example for array of hashes:

     $reference = {
                    [
                      {
                         user => 'word',
                         uid => 'int'
                      },
                      {} # empty 2nd element
                    ]
                   };

    Example of array of values:

     $reference = {
      var => [ 'int', '' ]
     }

EXAMPLES
    Take a look to t/run.t for lots of examples.

CONFIGURATION AND ENVIRONMENT
    No environment variables will be used.

SEE ALSO
    I recommend you to read the following documentations, which are supplied
    with perl:

     perlreftut                     Perl references short introduction
     perlref                        Perl references, the rest of the story
     perldsc                        Perl data structures intro
     perllol                        Perl data structures: arrays of arrays

     XML::Simple                    The very same but with xml files.

LICENSE AND COPYRIGHT
    Copyright (c) 2007 Thomas Linden

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

BUGS AND LIMITATIONS
    See rt.cpan.org for current bugs, if any.

INCOMPATIBILITIES
    None known.

DIAGNOSTICS
    To debug Config::General::Validate use debug() or the perl debugger, see
    perldebug.

    For example to debug the regex matching during processing try this:

     perl -Mre=debug yourscript.pl

DEPENDENCIES
    Config::General::Validate depends on the module Regexp::Common,
    File::Spec and File::stat.

AUTHOR
    Thomas Linden <tlinden |AT| cpan.org>

VERSION
    1.01