NAME

Constant::Export::Lazy - Utility to write lazy exporters of constant subroutines

DESCRIPTION

This is a utility to write lazy exporters of constant subroutines. I.e. it's not meant to be a user-facing constant exporting API, it's meant to write user-facing constant exporting APIs.

There's dozens of similar constant defining modules on the CPAN, why did I need to write this one?

• It's lazy

  Our constants fleshened via callbacks that are guaranteed to be called only once for the lifetime of the process (not once per importer or whatever), and we only call the callbacks lazily if someone actually requests that a constant of ours be defined.

  This makes it easy to have one file that runs in different environments and e.g. generates some subset of its constants with a module that you may not want to use, or may not be available in all your environments. You can just require it in the callback that generates the constant that requires it.

• It makes it easier to manage creating constants that require other constants

  Maybe you have one constant indicating whether you're running in a dev environment, and a bunch of other constants that are defined differently if the dev environment constant is true.

  Now imagine you have several hundred constants like that, managing the inter-dependencies and that everything is defined in the right order quickly gets messy.

  Constant::Import::Lazy takes away all this complexity. When you define a constant you get a callback object that can give you the value of other constants, and will either generate them if they haven't been generated, or look them up in the symbol table if they have.

  Thus we end up with a Makefile-like system where you can freely use whatever other constants you like when defining your constants, just be careful not to introduce circular dependencies.

SYNOPSIS

So how does all this work? This example demonstrates all our features. This is an example of your My::Constants package that you write using Constant::Export::Lazy:

package My::Constants;
use strict;
use warnings;
use Exporter 'import';
use constant {
    X => -2,
    Y => -1,
};
our @EXPORT_OK = qw(X Y);
use Constant::Export::Lazy (
    constants => {
        A => sub { 1 },
        B => sub { 2 },
        SUM => sub {
            # You get a $ctx object that you can ->call() to retrieve
            # the values of other constants if some of your constants
            # depend on others. Constants are still guaranteed to only
            # be fleshened once!
            my ($ctx) = @_;
            $ctx->call('A') + $ctx->call('B'),
        },
        # We won't call this and die unless someone requests it when
        # they import us.
        DIE => sub { die },
        PI  => {
            # We can also supply a HashRef with "call" with the sub,
            # and "options" with options that clobber the global
            # options.
            call    => sub { 3.14 },
            options => {
                override => sub {
                    my ($ctx, $name) = @_;
                    # You can simply "return;" here to say "I don't
                    # want to override", and "return undef;" if you
                    # want the constant to be undef.
                    return $ENV{PI} ? "Pi is = $ENV{PI}" : $ctx->call($name);
                },
            },
        },
    },
    options => {
        # We're still exporting some legacy constants via Exporter.pm
        wrap_existing_import => 1,
        # A general override so you can override other constants in
        # %ENV
        override => sub {
            my ($ctx, $name) = @_;
            return unless exists $ENV{$name};
            return $ENV{$name};
        },
    },
);

1;

And this is an example of using it in some user code:

package My::User::Code;
use strict;
use warnings;
use Test::More qw(no_plan);
use lib 't/lib';
BEGIN {
    # Supply a more accurate PI
    $ENV{PI} = 3.14159;
    # Override B
    $ENV{B} = 3;
}
use My::Constants qw(
    X
    Y
    A
    B
    SUM
    PI
);

is(X, -2);
is(Y, -1);
is(A, 1);
is(B, 3);
is(SUM, 4);
is(PI,  "Pi is = 3.14159");

Things to note about this example:

• We're using $ctx-call($name)> to get the value of other constants while defining ours.

• That you can use either a global override option or a local per-sub one to override your constants via %ENV variables, or anything else you can think of.

• We're using the global wrap_existing_import option, and Exporter to export some of our constants via constant.

  This demonstrates migrating an existing module that takes a list of constants (or labels) that don't overlap with our list of constants to Constant::Export::Lazy.

  As well as supplying this option you have to use Constant::Export::Lazy after the other module defines its import subroutine. Then we basically compose a list of constants we know we can handle, and dispatch anything we don't know about to the import subroutine we clobbered.

AUTHOR

Ævar Arnfjörð Bjarmason <avar@cpan.org>