# Evented::Configuration
Evented::Configuration is an event-driven objective configuration class and parser for Perl software built upon Evented::Object.
# Features
* **Blocks:** Evented::Configuration's configuration is block-styled, with all keys and values associated with a block. Blocks can be "named," meaning there are several blocks of one type with different names, or they can be "unnamed," meaning there is only one block of that type.
* **Objective:** Evented::Configuration's objective interface allows you to store nothing more than the configuration object. Then, make the object accessible where you need it.
* **Event-driven:** Evented::Configuration is based upon the Evented::Object framework, firing events each time a configuration changes. This allows software to respond immediately to changes of user settings, etc.
* **Convenience:** Most configuration parsers spit out nothing more than a hash reference of keys and values. Evented::Configuration instead supplies several convenient methods for fetching configuration data.
# Format
```
# Comments
# Hello, I am a comment.
# I am also a comment.
# Unnamed blocks
[ someBlock ]
someKey = "some string"
otherKey = 12
another = ['hello', 'there']
evenMore = ['a'..'z']
# Named blocks
[ cookies: sugar ]
favorites = ['sugar cookie', 'snickerdoodle']
[ cookies: chocolate ]
favorites = ['chocolate macadamia nut', 'chocolate chip']
```
# Methods
Evented::Configuration provides several convenient methods for fetching configuration values.
## Evented::Configuration->new(%options)
Creates a new instance of Evented::Configuration.
```perl
my $conf = Evented::Configuration->new(conffile => 'etc/some.conf');
```
### Parameters
* **options:** a hash of constructor options.
### %options - constructor options
* __conffile__: file location of a configuration file.
* __hashref__: *optional*, a hash ref to store configuration values in.
## $conf->parse_config()
Parses the configuration file. Used also to rehash configuration.
```perl
$conf->parse_config();
```
## $conf->get($block, $key)
Fetches a single configuration value.
```perl
my $value = $conf->get('unnamedBlock', 'someKey');
my $other = $conf->get(['blockType', 'namedBlock'], 'someKey');
```
### Parameters
* **block:** for unnamed blocks, should be the string block type. for named blocks, should be an array reference in the form of `[block type, block name]`.
* **key:** the key of the configuration value being fetched.
## $conf->names_of_block($block_type)
Returns an array of the names of all blocks of the specified type.
```perl
foreach my $block_name ($conf->names_of_block('cookies')) {
print "name of this cookie block: $block_name\n";
}
```
### Parameters
* **block_type:** the type of the named block.
## $conf->keys_of_block($block)
Returns an array of all the keys in the specified block.
```perl
foreach my $key ($conf->keys_of_block('someUnnamedBlock')) {
print "someUnnamedBlock unnamed block has key: $key\n";
}
foreach my $key ($conf->keys_of_block('someNamedBlock', 'someName')) {
print "someNamedBlock:someName named block has key: $key\n";
}
```
### Parameters
* **block:** for unnamed blocks, should be the string block type. for named blocks, should be an array reference in the form of `[block type, block name]`.
## $conf->on_change($block, $key, $code, %opts)
Attaches an event listener for the configuration change event. This event will be fired
even if the value never existed. If you want a listener to be called the first time the
configuration is parsed, simply add the listener before calling `->parse_config()`.
Otherwise, add listeners later.
```perl
# an example with an unnamed block
$conf->on_change('myUnnamedBlock', 'myKey', sub {
my ($event, $old, $new) = @_;
...
});
# an example with a name block.
$conf->on_change(['myNamedBlockType', 'myBlockName'], 'someKey', sub {
my ($event, $old, $new) = @_;
...
});
# an example with an unnamed block and ->register_event() options.
$conf->on_change('myUnnamedBlock', 'myKey', sub {
my ($event, $old, $new) = @_;
...
}, priority => 100, name => 'myCallback');
```
### Parameters
* __block__: for unnamed blocks, should be the string block type. for named blocks, should be an array reference in the form of `[block type, block name]`.
* __key__: the key of the configuration value being listened for.
* __code__: a code reference to be called when the value is changed.
* __opts__: *optional*, a hash of any other options to be passed to Evented::Object's `->register_event()`.
# Events
Evented::Configuration fires events when configuration values are changed.
In any case, events are fired with arguments `(old value, new value)`.
Say you have an unnamed block of type `myBlock`. If you changed the key `myKey` in `myBlock`, Evented::Configuration would fire the event `eventedConfiguration.change:myBlock:myKey`.
Now assume you have a named block of type `myBlock` with name `myName`. If you changed the key `myKey` in `myBlock:myName`, Evented::Configuration would fire event `eventedConfiguration.change:myBlock/myName:myKey`.
However, it is recommended that you use the `->on_change()` method rather than directly attaching event callbacks. This will insure compatibility for later versions that could possibly change the way events are fired.
# History
The Evented::Configuration parser first appeared procedurally in juno-ircd version 2. The format has not changed since. The parser was used in several other IRC softwares, including foxy-java IRC bot and ntirc IRC client. It was also included in all versions of juno-ircd succeeding juno2: juno3, juno-mesh, and juno5. In the Arinity IRC services package, the parser had a basic objective interface. However, Evented::Configuration was not based on this interface. Evented::Configuration appeared initially in UICd, the Universal Internet Chat server daemon.
# See also
* [Evented::Object](
https://github.com/cooper/evented-object) - an event framework and the base class of Evented::Configuration.
* [Evented::Database](
https://github.com/cooper/evented-database) - a database built upon Evented::Configuration with seamless database functionality added to a configuration class.
