Config-XPath

 view release on metacpan or  search on metacpan

lib/Config/XPath/Reloadable.pm  view on Meta::CPAN

=head1 DESCRIPTION

This subclass of C<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 C<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
C<add> and C<keep> event callbacks. This parameter will hold a child
C<Config::XPath::Reloadable> object with its XPath context pointing at the
corresponding node in the XML data, much like the C<get_sub()> method does.

=cut

=head1 CONSTRUCTOR

=cut

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

lib/Config/XPath/Reloadable.pm  view on Meta::CPAN

 $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
C<get_sub()> and C<get_sub_list()> methods are no longer allowed. They will
instead throw exceptions. The event callbacks in nodelists and nodesets
should be used instead, to obtain subconfigurations.

=cut

=head2 $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.

=cut

sub reload
{
   my $self = shift;
   if( exists $self->{filename} ) {
      $self->_reload_file;
   }

lib/Config/XPath/Reloadable.pm  view on Meta::CPAN

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 C<< $conf->reload() >> method is called, the nodeset given by the XPath
string $listpath is obtained. The C<add> or C<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 C<remove> callback called for those, in no particular
order.

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

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

=over 8

=item 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:

lib/Config/XPath/Reloadable.pm  view on Meta::CPAN

 $remove->( $index )

=back

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 C<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 C<add> or C<keep> callbacks, then the C<keep> callback should invoke
the C<reload> method on the node, to ensure full recursive reloading of the
content.

=cut

sub associate_nodelist
{
   my $self = shift;
   my ( $listpath, %events ) = @_;