Constant-Export-Lazy

 view release on metacpan or  search on metacpan

README  view on Meta::CPAN

DESCRIPTION
    This is a library to write lazy exporters of constant subroutines. It's
    not meant to be a user-facing constant exporting API, it's something you
    use to write user-facing constant exporting APIs.

    There's dozens of modules on the CPAN that define constants in one way
    or another, why did I need to write this one?

  It's lazy
    Our constants are 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 constant exporting module that runs in
    different environments, and generates some subset of its constants
    depending on what the program that's using it actually needs.

    Some data that you may want to turn into constants may require modules
    that aren't available everywhere, queries to databases that aren't
    available everywhere, or make certain assumptions about the environment
    they're running under that may not be true across all your environments.

    By only defining those constants you actually need via callbacks
    managing all these special-cases becomes a lot easier.

  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 say you have several hundred constants like that, managing the
    inter-dependencies and ensuring that they're all defined in the right
    order with dependencies before dependents quickly gets messy.

README  view on Meta::CPAN

    opposed to importing into their package will very quickly discover that
    it doesn't work.

    Because this is called really early on this routine doesn't get passed a
    $ctx object, just the name of the constant you might want to munge. To
    skip munging it return the empty list, otherwise return a munged name to
    be used in the private symbol table.

    We consider this a purely functional subroutine and you MUST return the
    same munged name for the same $gimme because we might resolve that
    $gimme multiple times. Failure to do so will result your callbacks being
    redundantly re-defined.

CONTEXT OBJECT
    As discussed above we pass around a context object to all callbacks that
    you can define. See $ctx in the "SYNOPSIS" for examples.

    This objects has only two methods:

    *   "call"

        This method will do all the work of fleshening constants via the sub
        provided in the "call" option, taking the "override" callback into
        account if provided, and if applicable calling the "after" callback
        after the constant is defined.

lib/Constant/Export/Lazy.pm  view on Meta::CPAN

This is a library to write lazy exporters of constant
subroutines. It's not meant to be a user-facing constant exporting
API, it's something you use to write user-facing constant exporting
APIs.

There's dozens of modules on the CPAN that define constants in one way
or another, why did I need to write this one?

=head2 It's lazy

Our constants are 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 constant exporting module that runs in
different environments, and generates some subset of its constants
depending on what the program that's using it actually needs.

Some data that you may want to turn into constants may require modules
that aren't available everywhere, queries to databases that aren't
available everywhere, or make certain assumptions about the
environment they're running under that may not be true across all your
environments.

By only defining those constants you actually need via callbacks
managing all these special-cases becomes a lot easier.

=head2 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 say you have several hundred constants like that, managing the
inter-dependencies and ensuring that they're all defined in the right

lib/Constant/Export/Lazy.pm  view on Meta::CPAN

that it doesn't work.

Because this is called really early on this routine doesn't get passed
a C<$ctx> object, just the name of the constant you might want to
munge. To skip munging it return the empty list, otherwise return a
munged name to be used in the private symbol table.

We consider this a purely functional subroutine and you B<MUST> return
the same munged name for the same C<$gimme> because we might resolve
that C<$gimme> multiple times. Failure to do so will result your
callbacks being redundantly re-defined.

=head1 CONTEXT OBJECT

As discussed above we pass around a context object to all callbacks
that you can define. See C<$ctx> in the L</SYNOPSIS> for examples.

This objects has only two methods:

=over

=item * C<call>

This method will do all the work of fleshening constants via the sub
provided in the L</call> option, taking the L</override> callback into