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)