Class XmlConfigFile
In: xmlconfigfile.rb
Parent: Object

This class represents an XML configuration file as it is used by many modern applications. Using this class you can access an XML file's content easily using XPath.

Methods
close    false_values=    get_boolean    get_float    get_int    get_parameters    get_string    get_string_array    new    set_parameter    store    to_hash    to_s    true_values=   
Attributes
:expand_attributes  [RW] 
:false_values  [R] 
:filename  [R] 
:path_prefix  [RW] 
:true_values  [R] 
Included modules
Observable REXML
Public Class methods
new(filename, reloadPeriod = nil)

Creates and initializes a new XmlConfigFile object.

filename:Name of the configuration file to be loaded.
reloadPeriod:If the configuration file should be reloaded periodically, set this parameter to a numeric value greater than zero, which specifies the reload period measured in seconds.

The following exceptions may be raised:

Errno::ENOENT:If the specified file does not exist.
REXML::ParseException:If the specified file is not wellformed.
ArgumentError:If the reload period is not a number greater than zero.
Public Instance methods
get_string(xpath, default = nil)

Returns a configuration parameter as a String. The parameter itself has to be identified by an XPath expression.

xpath:An XPath expression identifying the configuration parameter to be read and returned as String value.
default:Default value to be returned, if the XPath expression returned an empty node list. Of course, the default value should be a String value in such a case. The method does not check this explicitly.
set_parameter(xpath, value, create = false)

Sets a configuration parameter. The parameter has to be specified by an XPath expression. If the parameter was set successfully, all observers will be notified.

xpath:An XPath expression identifying the configuration parameter to be read and returned as String value.
value:The parameter value to be set.
create:If the node specified by xpath does not exist, it will be created, if this parameter is set to true. Otherwise, an exception will be thrown.
get_int(xpath, default = nil)

Returns a configuration parameter as an Integer. The parameter itself has to be identified by an XPath expression.

xpath:An XPath expression identifying the configuration parameter to be read and returned as Integer value.
default:Default value to be returned, if the XPath expression returned an empty node list. Of course, the default value should be an Integer value in such a case. The method does not check this explicitly.

The following exception may be raised:

ArgumentError:If a parameter was found and could not be converted into an Integer.
get_float(xpath, default = nil)

Returns a configuration parameter as a Float. The parameter itself has to be identified by an XPath expression.

xpath:An XPath expression identifying the configuration parameter to be read and returned as Float value.
default:Default value to be returned, if the XPath expression returned an empty node list. Of course, the default value should be a Float value in such a case. The method does not check this explicitly.

The following exception may be raised:

ArgumentError:If a parameter was found and could not be converted into a Float.
get_boolean(xpath, default = nil)

Returns a configuration parameter as a boolean. The parameter itself has to be identified by an XPath expression.

By default, the values in DEFAULT_TRUE_VALUES are assumed to be true and the values in DEFAULT_FALSE_VALUES are assumed to be false. You can define your own values by setting true_values respectively false_values to an array containing the values of your choice.

xpath:An XPath expression identifying the configuration parameter to be read and returned as boolean value.
default:Default value to be returned, if the XPath expression returned an empty node list. Of course, the default value should be a boolean value in such a case. The method does not check this explicitly.

The following exception may be raised:

ArgumentError:If a parameter was found and could not be converted into a boolean.
get_parameters(xpath, pathSeparator = DEFAULT_SEPARATOR)

Returns a set of String parameters as a one-dimensional Hash. If no parameters specified by xpath were found, an empty Hash will be returned.

E.g. the document snippet

...

  <db>
    <name>shop</shop>
    <user>scott</user>
  </db>

...

will become the following Hash

{ db.name => shop, db.user => scott }

xpath:An XPath expression specifying the nodes to be selected.
pathSeparator:String separating the single path elements in the Hash keys.
to_hash(xpath)

Converts a node list into a Hash completely analogous to the Perl module XML::Simple.

get_string_array(xpath, pathSeparator = DEFAULT_SEPARATOR)

Returns an array of Hashes. Each element contains a set of String parameters as Hash. If no parameters specified by xpath were found, an empty Array will be returned.

E.g. the document snippet

...

  <db>
    <name>shop</shop>
    <user>scott</user>
  </db>
  <db>
    <name>factory</shop>
    <user>anna</user>
  </db>

...

will become the following Array

[{ db.name => shop, db.user => scott },

 { db.name => factory, db.user => anna }]

This method was originally contributed by Nigel Ball.

xpath:An XPath expression specifying the nodes to be selected.
pathSeparator:String separating the single path elements in the Hash keys.
true_values=(values)

Sets the list of values, that will be interpreted as true boolean parameters. The case of all the elements will be set to downcase and all leading and trailing whitespaces will be removed.

values:List of values to be interpreted as true boolean values.
false_values=(values)

Sets the list of values, that will be interpreted as false boolean parameters. The case of all the elements will be set to downcase and all leading and trailing whitespaces will be removed.

values:List of values to be interpreted as false boolean values.
store(filename = nil)

Stores the current configuration into a file.

filename:Name of the file to store configuration in. Defaults to the current configuration file's name.
to_s()

Returns the current configuration as an XML string.

close()

Closes the configuration file, i.e. stops the reloader thread.