NAME

Config::Constants - Configuration variables as constants

SYNOPSIS

  # in your perl modules
  
  package Foo::Bar;
  
  use Config::Constants qw/BAZ/;
  
  sub foo_bar { print "Foo::Bar is " . BAZ }
  
  # in the conf.xml
  
  <config>
      <module name='Foo::Bar'>
            <constant name='BAZ' value='the coolest module ever' />
      </module>
  </config>
  
  # or in the conf.pl
  
  {
      'Foo::Bar' => {
          'BAZ' => 'the coolest module ever',
      }
  }  
  
  # in the in your perl code
  
  use Config::Constants xml => 'conf.xml';
  # or ...
  use Config::Constants perl => 'conf.pl';
  
  use Foo::Bar;
  
  Foo::Bar::foo_bar(); # prints "Foo::Bar is the coolest module ever"

DESCRIPTION

Using configuration files can help to make you code more flexible. However, this flexiblity comes at a cost of reading and parsing the configuration file, and then making the configuration information available to your application. Most times this is a trade off which is well worth the price, and which works well in many situations.

However, sometimes what you want to configure is really very simple, and it can feel like overengineering to have to use a config object instance and fetch the config variable, and that is where this module comes into play.

Config::Constants allows you to avoid all that overhead by loading the configuration file very early (compile time) and using perl's compile time constant folding to inline your configuration variables.

If you want to see this module in action. Just run this command from within this distribution's folder, and compare what you see to the actual files.

  perl -I lib/ -MO=Deparse,-ft/lib/Foo/Bar.pm,-ft/lib/Bar/Baz.pm t/11a_Config_Constants_w_Perl.t

Interaction with OO

This module will work for OO modules, however it does have some restructions.

• The first restriction is that constants cannot be folded properly if they are treated as methods. So given this relationship:

    package Foo;
    use Config::Constants 'BAZ';
    
    package Foo::Bar;
    use base 'Foo';
    

  If you wanted to refer to Foo's constant BAZ in Foo::Bar, and still retain the constant folding behavior, you should use it's fully qualified form 'Foo::BAZ'. However, this means that you are hard-coding the name of the super class into it's subclass, something not usually considered good OO practice.

  If you want to avoid hardcoding the super class, then it is possible to call the constant in a number of other ways:

    $instance->BAZ;
    $instance->SUPER::BAZ;
    SUPER::BAZ;
    __PACKAGE__->SUPER::BAZ;
    

  The problem with these approaches is that it will prevent any compile time constant folding from happening. This does happens for a very good (and well understood) reason. In most OO langauges the class of the invocant may not be known until runtime, this makes it almost impossible for a constant to know which class to get the constant from at compile time.

• The next restriction is that classes will not inherit the constants from their super class.So given the relationship in the example above, if you wanted to configure BAZ for 'Foo::Bar', you would need to do this.

    package Foo;
    use Config::Constants 'BAZ';
  
    package Foo::Bar;
    use base 'Foo';
    use Config::Constants 'BAZ';
    

  You will still be able to access Foo's version of BAZ via either a SUPER:: call or the fully qualified Foo::BAZ.

Interaction with Apache & mod_perl

When developing with mod_perl is it useful to use a module like Apache::Reload to help reload modules which have been changed. Because of the way Config::Constants handles loading of constants, this should not require the config to be reloaded. However, if the config file itself is changed, it will require you to restart Apache in order for those changes to take effect.

Future plans include making a mod_perl handler which can be used to automatically reload the config file if it is modified.

METHODS

import

TO DO

A means to automatically reload the config while using Apache/mod_perl

More tests

re-write the docs, they are horrid

BUGS

None that I am aware of. Of course, if you find a bug, let me know, and I will be sure to fix it.

CODE COVERAGE

I use Devel::Cover to test the code coverage of my tests, below is the Devel::Cover report on this module test suite.

 ----------------------------------- ------ ------ ------ ------ ------ ------ ------
 File                                  stmt branch   cond    sub    pod   time  total
 ----------------------------------- ------ ------ ------ ------ ------ ------ ------
 Config/Constants.pm                   95.2   90.9    n/a   75.0    n/a   31.6   91.8
 Config/Constants/Perl.pm             100.0   50.0   33.3  100.0  100.0   23.8   82.0
 Config/Constants/XML.pm              100.0   50.0   33.3  100.0    n/a   23.9   90.6
 Config/Constants/XML/SAX/Handler.pm   96.7   82.4    n/a  100.0  100.0   20.7   92.7
 ----------------------------------- ------ ------ ------ ------ ------ ------ ------
 Total                                 97.0   79.4   33.3   91.2  100.0  100.0   90.3
 ----------------------------------- ------ ------ ------ ------ ------ ------ ------

SEE ALSO

generics - this module is largely based on ideas from the generics pragma I wrote.

AUTHOR

stevan little, <stevan@iinteractive.com>

COPYRIGHT AND LICENSE

Copyright 2005 by Infinity Interactive, Inc.

http://www.iinteractive.com

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Config::Constants

perl -MCPAN -e shell
install Config::Constants