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 <[email protected]>

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.