NAME

Config::XPath::Reloadable - a subclass of Config::XPath that supports reloading

SYNOPSIS

 use Config::XPath::Reloadable;

 my $conf = Config::XPath::Reloadable->new( filename => 'addressbook.xml' );

 $SIG{HUP} = sub { $conf->reload };

 $conf->associate_nodeset( '//user', '@name',
    add => sub {
       my ( $name, $user_conf ) = @_;
       print "New user called $name, whose phone is " .
          $user_conf->get_string( '@phone' ) . "\n";
    },

    keep => sub {
       my ( $name, $user_conf ) = @_;
       print "User $name phone is now " .
          $user_conf->get_string( '@phone' ) . "\n";
    },

    remove => sub {
       my ( $name ) = @_;
       print "User $name has now gone\n";
    },
     );

 # Main body of code here ...

DESCRIPTION

This subclass of Config::XPath supports reloading the underlying XML file and updating the containing program's data structures. This is achieved by taking control of the lifetimes of the program's data structures that use it.

Where a simple name=value config file could be reloaded just by reapplying string values, a whole range of new problems occur with the richer layout afforded to XML-based files. New nodes can appear, old nodes can move, change their data, or disappear. All these changes may involve data structure changes within the containing program. To cope with these types of events, callbacks in the form of closures can be registered that are called when various changes happen to the underlying XML data.

As with the non-reloadable parent class, configuration is generally processed by forming a tree of objects which somehow maps onto the XML data tree. The way this is done in this class, is to use the $node parameter passed in to the add and keep event callbacks. This parameter will hold a child Config::XPath::Reloadable object with its XPath context pointing at the corresponding node in the XML data, much like the get_sub() method does.

CONSTRUCTOR

$conf = Config::XPath::Reloadable->new( %args )

This function returns a new instance of a Config::XPath::Reloadable object, initially containing the configuration in the named XML file. The file is closed by the time this method returns, so any changes of the file itself will not be noticed until the reload method is called.

The %args hash takes the following keys

filename => $file

The filename of the XML file to read

METHODS

All of the simple data access methods of the Config::XPath manpage are supported:

 $str = $config->get_string( $path, %args )

 $attrs = $config->get_attrs( $path )

 @values = $config->get_list( $path )

 $map = $config->get_map( $listpath, $keypath, $valuepath )

Because of the dynamically-reloadable nature of objects in this class, the get_sub() and get_sub_list() methods are no longer allowed. They will instead throw exceptions of Config::XPath::Exception type. The event callbacks in nodelists and nodesets should be used instead, to obtain subconfigurations.

$conf->reload()

This method requests that the configuration object reloads the configuration data that constructed it.

If called on the root object, the XML file that was named in the constructor is reopened and reparsed. The file is re-opened by name, rather than by rereading the filehandle that was opened in the constructor. (This distinction is only of significance for systems that allow open files to be renamed). If called on a child object, the stored XPath data tree is updated from the parent.

In either case, after the data is reloaded, each nodelist stored by the object is reevlauated, by requerying the XML nodeset using the stored XPaths, and the event callbacks being invoked as appropriate.

$conf->associate_nodelist( $listpath, %events )

This method associates callback closures with events that happen to a given nodelist in the XML data. When the function is first called, and every time the $conf->reload() method is called, the nodeset given by the XPath string $listpath is obtained. The add or keep callback is then called as appropriate on each node, in the order they appear in the current XML data.

Finally, the list of nodes that were present last time which no longer exist is determined, and the remove callback called for those, in no particular order.

When this method is called, the add callbacks will be invoked before the method returns, for any matching items found in the data.

The %events hash should be passed keys for the following events:

add => CODE

Called when a node is returned in the list that has a name that wasn't present on the last loading of the file. Called as:

 $add->( $index, $node )

keep => CODE

Called when a node is returned in the list that has a name that was present on the last loading of the file. Note that the contents of this node may or may not have changed; the containing program would have to requery the config node to determine if this is the case. Called as:

 $keep->( $index, $node )

remove => CODE

Called at the end of the list enumeration, when a node was present last time but is not present in the latest loading of the file. Called as:

 $remove->( $index )

In each callback, the $index parameter will contain the index of the config nodewithin the nodelist given by the $listpath, and the $node parameter will contain a Config::XPath::Reloadable object reference, with the XPath context at the respective XML data node.

If further recursive nodesets are associated on the inner config node given to the add or keep callbacks, then the keep callback should invoke the reload method on the node, to ensure full recursive reloading of the content.

$conf->associate_nodeset( $listpath, $namepath, %events )

This method is similar in operation to associate_nodelist, except that each node in the set is identified by some value, rather than just its index within the list. The value given by $namepath is obtained by using the get_string() method (so it must be a plain text node, attribute value, or any other XPath query that gives a string value). This name is then used to determine whether the node has been added, or kept since the last time.

The %events hash should be passed keys for the following events:

add => CODE

Called when a node is returned in the list that has a name that wasn't present on the last loading of the file. Called as:

 $add->( $name, $node )

keep => CODE

Called when a node is returned in the list that has a name that was present on the last loading of the file. Note that the contents of this node may or may not have changed; the containing program would have to requery the config node to determine if this is the case. Called as:

 $keep->( $name, $node )

remove => CODE

Called at the end of the list enumeration, when a node was present last time but is not present in the latest loading of the file. Called as:

 $remove->( $name )

In each callback, the $name parameter will contain the string value returned by the $namepath path on each node, and the $node parameter will contain a Config::XPath::Reloadable object reference, with the XPath context at the respective XML data node.

SEE ALSO

• XML::XPath - Perl XML module that implements XPath queries

• Error - Base module for exception-based error handling

AUTHOR

Paul Evans <leonerd@leonerd.org.uk>