NAME
Config::XPath - a module for retrieving configuration data from XML files by using XPath queries
SYNOPSIS
use Config::XPath;
my $conf = Config::XPath->new( filename => 'addressbook.xml' );
## Basic data retrieval
my $bob_phone = $conf->get_string( '//user[@name="bob"]/@phone' );
my %jim_details = $conf->get_attrs( '//user[@name="jim"]' );
my @everyone_with_fax = $conf->get_list( '//user[@fax]' );
print " $_ has a fax\n" for @everyone_with_fax;
my $phone_map = $conf->get_map( '//user', '@name', '@phone' );
print " $_ has a phone: $phone_map->{$_}\n" for sort keys %$phone_map;
## Subconfigurations
my $james_config = $conf->get_sub_config( '//user[@name="james"]' );
my $james_phone = $james_config->get_string( '@phone' );
foreach my $user_config ( $conf->get_sub_config_list( '//user[@email]' ) ) {
my $town = $user_config->get_string( 'address/town' );
print "Someone in $town has an email account\n";
}DESCRIPTION
This module provides easy access to configuration data stored in an XML file. Configuration is retrieved using XPath keys; various functions exist to convert the result to a variety of convenient forms. If the functions are called as static functions (as opposed to as object methods) then they access data stored in the default configuration file (details given below).
The functions are also provided as methods of objects in the Config::XPath class. They take the same parameters as for the static functions. This allows access to other XML configuration files.
Subconfigurations
By default, the XPath context is at the root node of the XML document. If some other context is required, then a subconfiguration object can be used. This is a child Config::XPath object, built from an XPath query on the parent. Whatever node the query matches becomes the context for the new object. The functions get_sub_config() and get_sub_config_list() perform this task; the former returning a single child, and the latter returning a list of all matches.
Default Configuration File
In the case of calling as static functions, the default configuration is accessed. When the module is loaded no default configuration exists, but one can be loaded by calling the read_default_config() function. This makes programs simpler to write in cases where only one configuration file is used by the program.
FUNCTIONS
read_default_config( $file )
This function reads the default configuration file, from the location given. If the file is not found, or an error occurs while reading it, then an exception of Config::XPath::Exception is thrown.
The default configuration is cached, so multiple calls to this function will not result in multiple reads of the file; subsequent requests will be silently ignored, even if a different filename is given.
CONSTRUCTOR
$conf = Config::XPath->new( %args )
This function returns a new instance of a Config::XPath object, containing the configuration in the named XML file. If the given file does not exist, or an error occured while reading it, an exception Config::XPath::Exception is thrown.
The %args hash takes the following keys:
METHODS
Each of the following can be called either as a static function, or as a method of an object returned by the new() constructor, or either of the get_sub_config functions.
$str = get_config_string( $path, %args )
$str = $config->get_string( $path, %args )
This function retrieves the string value of a single item in the XML file. This item should either be a text-valued element with no sub-elements, an attribute, or an XPath expression that returns a string, integer or boolean value.
If no suitable node was found matching the XPath query but a default key was passed in the %args hash, then the value of that key is returned instead.
If no suitable node was found matching the XPath query and no default argument was passed, then an exception of Config::XPath::ConfigNotFoundException class is thrown. If more than one node matched, or the returned node is not either a plain-text content containing no child nodes, or an attribute, then an exception of class Config::XPath::BadConfigException class is thrown.
- $path
-
The XPath to the required configuration node
- %args
-
A hash that may contain extra options to control the operation. Supports the following keys:
default-
If no XML node is found matching the path, return this value rather than throwing a
Config::XPath::ConfigNotFoundException.
- Throws
-
Config::XPath::ConfigNotFoundException,Config::XPath::BadConfigException,Config::XPath::NoDefaultConfigException
$attrs = get_config_attrs( $path )
$attrs = $config->get_attrs( $path )
This function retrieves the attributes of a single element in the XML file. The attributes are returned in a hash, along with the name of the element itself, which is returned in a special key named '+'. This name is not valid for an XML attribute, so this key will never clash with an actual value from the XML file.
If no suitable node was found matching the XPath query, then an exception of Config::XPath::ConfigNotFoundException class is thrown. If more than one node matched, or the returned node is not an element, then an exception of class Config::XPath::BadConfigException class is thrown.
$path-
The XPath to the required configuration node
- Throws
-
Config::XPath::ConfigNotFoundException,Config::XPath::BadConfigException,Config::XPath::NoDefaultConfigException
@values = get_config_list( $path )
@values = $config->get_list( $path )
This function obtains a list of nodes matching the given XPath query. Unlike the other functions, it is not an error for no nodes to match. The list contains one entry for each match of the XPath query, depending on what that match is. Attribute nodes return their value as a plain string. Element nodes return a hashref, identical to that which get_config_attrs() returns.
If any other node type is found in the response, then an exception of Config::XPath::BadConfigException class is thrown.
- $path
-
The XPath for the required configuration
- Throws
-
Config::XPath::BadConfigException,Config::XPath::NoDefaultConfigException
$map = get_config_map( $listpath, $keypath, $valuepath )
$map = $config->get_map( $listpath, $keypath, $valuepath )
This function obtains a map, returned as a hash, containing one entry for each node returned by the $listpath search, where the key and value are given by the $keypath and $valuepath within each node. It is not an error for no nodes to match the $listpath.
The result of the $listpath query must be a nodeset. The result of the $keypath and $valuepath queries for each node in the list must be convertable to a string, by the same rules as the get_string() method.
- $listpath
-
The XPath to generate the nodeset
- $keypath
-
The XPath within each node to generate the key
- $valuepath
-
The XPath within each node to generate the value
- Throws
-
Config::XPath::ConfigNotFoundException,Config::XPath::BadConfigException,Config::XPath::NoDefaultConfigException
$subconfig = get_sub_config( $path )
$subconfig = $config->get_sub_config( $path )
This function constructs a new Config::XPath object whose context is at the single node selected by the XPath query. The newly constructed child object is then returned.
If no suitable node was found matching the XPath query, then an exception of Config::XPath::ConfigNotFoundException class is thrown. If more than one node matched, then an exception of class Config::XPath::BadConfigException is thrown.
- $path
-
The XPath to the required configuration node
- Throws
-
Config::XPath::ConfigNotFoundException,Config::XPath::BadConfigException,Config::XPath::NoDefaultConfigException
@subconfigs = get_sub_config_list( $path )
@subconfigs = $config->get_sub_config_list( $path )
This function constructs a list of new Config::XPath objects whose context is at each node selected by the XPath query. The array of newly constructed objects is then returned. Unlike other functions, it is not an error for no nodes to match.
EXCEPTIONS
Config::XPath::Exception
This exception is used as a base class for config-related exceptions. It is derived from Error, and stores the config path involved.
$e = Config::XPath::Exception->new( $message; $path )The path is optional, and will only be stored if defined. It can be accessed using the path method.
$path = $e->pathConfig::XPath::ConfigNotFoundException
This exception indicates that the requested configuration was not found. It is derived from Config::XPath::Exception and is constructed and accessed in the same way.
Config::XPath::BadConfigException
This exception indicates that configuration found at the requested path was not of a type suitable for the request made. It is derived from Config::XPath::Exception and is constructed and accessed in the same way.
Config::XPath::NoDefaultConfigException
This exception indicates that no default configuration has yet been loaded when one of the accessor functions is called directly. It is derived from Config::XPath::Exception.
$e = Config::XPath::NoDefaultConfigException->new( $path )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>