# NAME

**Evented::Configuration** - an event-driven objective configuration class and parser for
Perl software built upon [Evented::Object](https://metacpan.org/pod/Evented::Object).

# SYNOPSIS

## Example usage

````perl
# create a new configuration instance.
my $conf = Evented::Configuration->new(conffile => 'etc/some.conf');
```

````perl
# attach a callback to respond to changes of the user:age key.
$conf->on_change('user', 'name', sub {
   my ($event, $old, $new) = @_;
   say 'The user\'s age changed from ', $old || '(not born)', "to $new";
});
```

````perl
# parse the configuration file.
$conf->parse_config();
```

## Example configuration file

````perl
# some.conf file
```

````perl
# Comments
```

````perl
# Hello, I am a comment.
# I am also a comment.
```

````perl
# Unnamed blocks
```

````perl
[ someBlock ]
```

````perl
someKey  = "some string"
otherKey = 12
another  = ['hello', 'there']
evenMore = ['a'..'z']
```

````perl
# Named blocks
```

````perl
[ cookies: sugar ]
```

````perl
favorites = ['sugar cookie', 'snickerdoodle']
```

````perl
[ cookies: chocolate ]
```

````perl
favorites = ['chocolate macadamia nut', 'chocolate chip']
```

# DESCRIPTION

As the name suggests, event firing is what makes Evented::Configuration unique in
comparison to other configuration classes.

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

# 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";
}
```

````perl
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) = @_;
   ...
});
```

````perl
# an example with a name block.
$conf->on_change(['myNamedBlockType', 'myBlockName'], 'someKey', sub {
   my ($event, $old, $new) = @_;
   ...
});
```

````perl
# 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
`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
`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.

# SEE ALSO

- [Evented::Object](https://metacpan.org/pod/Evented::Object) - the event class that powers Evented::Configuration.

# AUTHOR

[Mitchell Cooper](https://github.com/cooper) <[email protected]>

Copyright � 2014. Released under BSD license.

- **IRC channel**: [irc.notroll.net #k](irc://irc.notroll.net/k)
- **Email**: [email protected]
- **CPAN**: [COOPER](http://search.cpan.org/~cooper/)
- **GitHub**: [cooper](https://github.com/cooper)

Comments, complaints, and recommendations are accepted. IRC is my preferred communication
medium. Bugs may be reported on
[RT](https://rt.cpan.org/Public/Dist/Display.html?Name=Evented-Configuration).

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.