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

Adam Kenndey's original post

Adam's original post that inspired this module was on use.perl.org, and is not longer available online.

constant modules

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

REPOSITORY

https://github.com/neilbowers/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.

cpanm Constant::FromGlobal

perl -MCPAN -e shell
install Constant::FromGlobal