NAME

Boucherot::config - A configuration system for boucherot

SYNOPSIS

  use Boucherot::config;

  print configuration()->{"ircname"}."\n";

DESCRIPTION

This package auto-load a set of configuration files, and let the other packages or class use the current configuration throught the configuration function.

GISSUML MODEL

package Boucherot::config

Attributs:

 -$ files : [ file1, file2, file3, ... ] : Array
 -$ configuration : { 'nick' => Array, 'server' => Array, ... } : Hash

Functions:

 +$ configuration () : { 'nick' => Array, 'server' => Array, ... } : Hash
 +$ load () :
 +$ update ( configuration : Hash, localconfiguration : Hash ) :
 +$ getIrcConnections () : [ connection1 : Hash, : Hash, ... ] : Array

CONFIGURATION FILES

The configuration files scanned are those ones:

  C:/Program Files/boucherot/boucherotrc.ini
  C:/Program Files/boucherot/boucherot.rc
  C:/Program Files/boucherot/boucherotrc
  /usr/local/lib/boucherot/boucherotrc
  /usr/local/share/boucherot/boucherotrc
  /usr/local/etc/boucherotrc
  /usr/lib/boucherot/boucherotrc
  /usr/share/boucherot/boucherotrc
  /usr/etc/boucherotrc
  /etc/boucherotrc
  ~/.boucherotrc
  ~/etc/boucherotrc
  boucherotrc

If some data is found in two files, the last one will overide the first one. Note that for arrays and for hashes, this can be configured, see the update section.

Note that ~/etc/boucherotrc under Unix and C:/Program Files/boucherot/boucherotrc are consided as good places for global configurations. boucherotrc can also be used for local configuration.

Note that foreach configuration file, is a directory is found, all the files located in, are considered as a configuration, and they will load in alphabetical order.

So you can create something like that:

  ~/etc/boucherotrc/01-default
  ~/etc/boucherotrc/50-modules/Foo::Bar.cfg
  ~/etc/boucherotrc/50-modules/My::Module.cfg
  ~/etc/boucherotrc/99-myConfig

And for exemple, you can imagine a tool or even the bot itself, that will help to confiure just a subset of the whole configuration, by auto-generating a file, without having to handle the parts that he don't know.

METHODS

configuration

 +$ configuration () : { 'nick' => Array, 'server' => Array, ... } : Hash

Exported function. Let someone acces to the configuration from any other package.

load

 +$ load () :

Load the configuration. That function is auto-called.

update

 +$ update ( configuration : Hash, localconfiguration : Hash ) :

Update ``localconfiguration'' into ``configuration''. Those are references on HASHs.

- If a keyhash is in ``localconfiguration'' and not in ``configuration'', it will be.

- If a keyhash is in ``configuration'' and not in ``localconfiguration'', the key won't be affected.

- If a keyhash is in both, the defaut will overwrite it. But... You can change the default by applying a modifier.

  $conf={ 'key1' => [ arg1, arg2 ], 'key3' => poide };
  $localconf={ 'key1' => [ arg3, arg4 ], 'key4' => pido };

  update($conf,$localconf);

  # Now $conf={
  #   'key1' => [ arg3, arg4 ],
  #   'key3' => poide,
  #   'key4' => pido
  # };

But

  $conf={ 'key1' => [ arg1, arg2 ], 'key3' => poide };
  $localconf={ 'key1:push' => [ arg3, arg4 ], 'key4' => pido };

  update($conf,$localconf);

  # Now $conf={
  #   'key1' => [ arg1, arg2, arg3, arg4 ],
  #   'key3' => poide,
  #   'key4' => pido 
  # };

And

  $conf={ 'key1' => [ arg1, arg2 ], 'key3' => poide };
  $localconf={ 'key1:unshift' => [ arg3, arg4 ], 'key4' => pido };

  update($conf,$localconf);

  # Now $conf={ 
  #   'key1' => [ arg3, arg4, arg1, arg2 ], 
  #   'key3' => poide, 
  #   'key4' => pido 
  # };

And

  $conf={ 'key1' => { 'arg1'=>1, 'arg2'=>2 }, 'key3' => poide };
  $localconf={ 'key1' => { 'arg2'=>22, 'arg3'=>3 }, 'key4' => pido };

  update($conf,$localconf);

  # Now $conf={
  #   'key1' => { 'arg2'=>22, 'arg3'=>3 }, 
  #   'key3' => poide, 
  #   'key4' => pido 
  # };

But

  $conf={ 'key1' => { 'arg1' => 1, 'arg2' =>2 }, 'key3' => poide };
  $localconf={ 'key1:update' => { 'arg2' => 22, 'arg3' => 3 }, 'key4' => pido };

  update($conf,$localconf);

  # Now $conf={ 
  #  'key1' => { 'arg1'=>1, 'arg2'=>22, 'arg3'=>3 }, 
  #  'key3' => poide,
  #  'key4' => pido 
  # };

getIrcConnections

 +$ getIrcConnections () : [ connection1 : Hash, : Hash, ... ] : Array

Get all the irc connections.

WRITTING MODULES

You're writting modules, and you want to use the configuration.

You can't do as you like. Let's suppose you're writting a module named Foo::Bar (file Foo/Bar.pm from PERL5LIB path...)

You're only autorized to use as your own configuration space, the sub space {'module'}{'Foo'}{'Bar'}.

Exemple:

  my $foobar=configuration()->{'module'}{'Foo'}{'Bar'}{'foobar'};

Note that usually, the I<case sensitive> keys are usually lower cases.
The package names are exeptions.

A configuration file for your module may look like:

  {
    'module' => {
      'Foo' => {
        'Bar' => {
          'foobar' => 7,
          'barbar' => [
            'Komm Susser Tod',
          ],
          'foofoo' => {
            'nick' => 'Ikari',
            'Event' => '3rd Impact',
          },
        },
      },
    },
  }

Note also that you can put your configuration in a separate file, if you want, because you can have as many configuration file as you want (see the CONFIGURATION FILES section)

AUTHORS

This class was written by Arthibus Gissehel <gissehel@vachefolle.com> in 2000.

NOTES

This package is part of the Boucherot project.