NAME

       Nagios::Object::Config - Perl objects to represent Nagios configuration

DESCRIPTION

       This is a module for parsing and processing Nagios object configuration files into perl
       objects.

METHODS

       new()
           Create a new configuration object.  If Version is not specified, the already weak
           validation will be weakened further to allow mixing of Nagios 1.0 and 2.0
           configurations.  For now, the minor numbers of Version are ignored.  Do not specify
           any letters as in '2.0a1'.

           To enable regular expression matching, use either the "regexp_matching" or
           "true_regexp_matching" arguments to new().    See enable_regexp_matching() and
           enable_true_regexp_matching() below.

            my $objects = Nagios::Object::Config->new();
            my $objects = Nagios::Object::Config->new( Version => 1.2 );

            my $objects = Nagios::Object::Config->new(
                               Version => 2.0,
                               regexp_matching => 1,
                               true_regexp_matching => 2
            );

       parse()
           Parse a nagios object configuration file into memory.  Although Nagios::Objects will
           be created, they are not really usable until the register() method is called.

            $parser->parse( "myfile.cfg" );

       find_object()
           Search through the list of objects' names and return the first match.  The second
           argument is optional.  Always using it can considerably reduce the size of the list to
           be searched, so it is recommended.

            my $object = $parser->find_object( "localhost" );
            my $object = $parser->find_object( "oracle", "Nagios::Service" );

       find_objects()
           Search through the list of objects' names and return all the matches.  The second
           argument is required.

            my @object_list = $parser->find_objects( "load", "Nagios::Service" );

       find_objects_by_regex()
           Search through the list of objects' names and return a list of matches.  The first
           argument will be evaluated as a regular expression.   The second argument is required
           and specifies what kind of object to search for.

           The regular expressions are created by translating the "*" to ".*?" and "?"  to ".".
           For now (v0.9), this code completely ignores Nagios's use_regexp_matching and
           use_true_regexp_matching and does full RE matching all the time.

            my @objects = $parser->find_objects_by_regex( "switch_*", "Nagios::Host" );
            my @objects = $parser->find_objects_by_regex( "server0?", "Nagios::Host" );

       all_objects_for_type()
           Obtain a reference to all objects of the specified Nagios object type.

           Usage: $objects = all_objects_for_type($object_type)

           Parameters:
               $object_type - A specific Nagios object type, i.e. "Nagios::Contact"..

           Returns:
               A reference to an array of references to all objects of the specified
               type associated with this configuration.  Objects of this type added
               to the configuration following the call to this method _will_ be
               accessible through this reference after the fact.

               Note that the array reference by the return value may be empty.

           Example:

               my $contacts = $config->all_objects_for_type("Nagios::Contact");
               if (scalar(@$contacts) == 0) {
                   print "No contacts have yet been defined\n";
               } else {
                   foreach $contact (@$contacts) {
                       ...
                   }
               }

       all_objects()
           Returns an arrayref with all objects parsed from the config in it.

            my $everything = $config->all_objects;

       find_attribute()
           Search through the objects parsed thus far, looking for a particular textual name.
           When found, return that object.  If called with two arguments, it will search through
           all objects currently loaded until a match is found.  A third argument may specify the
           type of object to search for, which may speed up the search considerably.

            my $object = $parser->find_attribute( "command_name", "check_host_alive" );
            my $object = $parser->find_attribute( "command_name", "check_host_alive", 'Nagios::Host' );

       resolve()
           Resolve the template for the specified object.  Templates will not work until this has
           been done.

            $parser->resolve( $object );

       register()
           Examine all attributes of an object and link all of it's references to other Nagios
           objects to their respective perl objects.  If this isn't called, some methods will
           return the textual name instead of a perl object.

            $parser->register( $host_object );
            my $timeperiod_object = $host_object->notification_period;

       resolve_objects()
           Resolve all objects currently loaded into memory.  This can be called any number of
           times without corruption.

            $parser->resolve_objects();

       register_objects()
           Same deal as resolve_objects(), but as you'd guess, it registers all objects currently
           loaded into memory.

            $parser->register_objects();

       enable_regexp_matching()/disable_regexp_matching()
           This correlates to the "use_regexp_matching" option in nagios.cfg.  When this option
           is enabled, Nagios::Object::Config will translate "*" to ".*?" and "?" to "." and
           evaluate the result as a perl RE, anchored at both ends for any value that can point
           to multiple other objects (^ and $ are added to either end).

            $parser->enable_regexp_matching;
            $parser->disable_regexp_matching;

       enable_true_regexp_matching()/disable_true_regexp_matching()
           This correlates to the "use_true_regexp_matching" option in nagios.cfg.   This is very
           similar to the enable_regexp_matching() option, but matches more data and allows more
           powerful RE syntax.  These modules will allow you the full power of perl RE's - this
           is probably more than is available in Nagios, so don't blame me if something works
           here but not in Nagios (it's usually the other way around anyways).

           The generated RE's have the same translation as above, but do not have the anchors to
           ^ and $.

           This option always supercedes enable_regexp_matching.

            $parser->enable_true_regexp_matching;
            $parser->disable_true_regexp_matching;

       list_hosts(), list_hostgroups(), etc.
           Returns an array/arrayref of objects of the given type.

            $config->list_hosts
            $config->list_hostgroups
            $config->list_services
            $config->list_timeperiods
            $config->list_commands
            $config->list_contacts
            $config->list_contactgroups
            $config->list_hostdependencies
            $config->list_servicedependencies
            $config->list_hostescalations
            $config->list_hostgroupescalations
            $config->list_serviceescalations
            $config->list_servicegroups
            $config->list_hostextinfo
            $config->list_serviceextinfo

AUTHOR

       Al Tobey <tobeya@cpan.org> Contributions From:
           Lynne Lawrence (API & bugs)