NAME

Config::XPath - a module for retrieving configuration data from XML files by using XPath queries

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.

$file

The filename of the default configuration to load

Throws

Config::XPath::Exception

$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:

filename => $file

The filename of the XML file to read

$conf = Config::XPath->new( $filename )

This form is now deprecated; please use the filename named argument instead. This form may be removed in some future version.

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

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

$path

The XPath for the required configuration

Throws

Config::XPath::NoDefaultConfigException

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->path

Config::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>

cpanm Config::XPath

perl -MCPAN -e shell
install Config::XPath