NAME

   Evented::Configuration - an event-driven objective configuration class
   and parser for Perl software built upon Evented::Object.

SYNOPSIS

Example usage

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

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

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

Example configuration file

    # some.conf file

    # 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']

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.

    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.

    $conf->parse_config();

$conf->get($block, $key)

   Fetches a single configuration value.

    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.

    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.

    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.

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