/ 
Constant-FromGlobal-0.10
River stage one • 5 direct dependents • 9 total dependents
/ Constant::FromGlobal

NAME

Constant::FromGlobal - declare constant(s) with value from global or environment variable

SYNOPSIS

package Foo;

use Constant::FromGlobal qw(DEBUG);

sub foo {
    # to enable debug, set $Foo::DEBUG=1 before loading Foo
    warn "lalala" if DEBUG:
}

DESCRIPTION

This module lets you define constants that either take their values from global variables, or from environment variables. The constants are function-style constants, like those created using the constant pragma.

Here's a minimal example showing how to set a constant from a global variable:

our $DEBUG;
BEGIN {
    $DEBUG = 1;
}
use Constant::FromGlobal qw/ DEBUG /;

You might wonder why you might want to do that? A better example is where a module sets a constant from a global variable in its package, but you can set that variable before using the module. First, here's the module:

package Foobar;
use Constant::FromGlobal LOGLEVEL => { default => 0 };

Then elsewhere you can write something like this:

BEGIN {
  $Foobar::LOGLEVEL = 3;
}
use Foobar;

Environment variables

By default Constant::FromGlobal will only look at the relevant global variable. If you pass the env option, then it will also look for an appropriately named environment variable:

use Constant::FromGlobal DEBUG => { env => 1, default => 0 };

Note that you can also set a default value, which will be used if neither a global variable nor environment variable was found.

METHODS

import

This routine takes an optional hash of options for all constants, followed by an option list (see Data::OptList) of constant names.

For example:

use Constant::FromGlobal { env => 1 }, "DSN", MAX_FOO => { int => 1, default => 3 };

is the same as

use Constant::FromGlobal DSN => { env => 1 }, MAX_FOO => { int => 1, default => 3, env => 1 };

which will define two constants, DSN and MAX_FOO. DSN is a string and MAX_FOO is an integer. Both will take their values from $Foo::DSN if defined or $ENV{FOO_DSN} as a fallback.

Note: if you define constants in the main namespace, version 0.01 of this module looked for environment variables prefixed with MAIN_. From version 0.02 onwards, you don't need the MAIN_ prefix.

There are three types you can specify for constants:

  • int - constains the constant to take an integer value. Will croak if a non-integer value is found.

  • num - constains the constant to take a numeric value. Will croak if a non-numeric value is found.

  • bool - coerces the constant to take a boolean value. Whatever value is found will be converted to a boolean value.

SEE ALSO

constant - core module for defining constants, and used by Constant::FromGlobal.

constant::lexical - very similar to the constant pragma, but defines lexically-scoped constants.

Const::Fast - CPAN module for defining immutable variables (scalars, hashes, and arrays).

Config::Constants is a module that will load a configuration file into a number of function-style constants.

Adam Kennedy's original post that inspired this module.

constant modules - A review of all perl modules for defining constants, by Neil Bowers.

REPOSITORY

https://github.com/neilb/Constant-FromGlobal

AUTHOR

This module was originally written by Yuval Kogman, inspired by a blog post by Adam Kennedy, describing the "Constant Global" pattern.

The module is now being maintained by Neil Bowers <neilb@cpan.org>.

LICENSE

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