The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
MooseX-Attribute-ENV-0.02
River stage two • 4 direct dependents • 34 total dependents
4 ++
/ MooseX::Attribute::ENV

NAME

MooseX::Attribute::ENV - Set default of an attribute to a value from %ENV

SYNOPSIS

The following is example usage for this attribute trait.

        package MyApp::MyClass;

        use Moose;
        use MooseX::Attribute::ENV;

        ## Checks $ENV{username} and $ENV{USERNAME}
        has 'username' => (
                traits => ['ENV'],
        );

        ## Checks $ENV{GLOBAL_PASSWORD}
        has 'password' => (
                traits => ['ENV'],
                env_key => 'GLOBAL_PASSWORD',
        );

        ## Checks $ENV{last_login}, $ENV{LAST_LOGIN} and then uses the default
        has 'last_login' => (
                traits => ['ENV'],
                default => sub {localtime},
        );

        ## Checks $ENV{XXX_config_name} and $ENV{XXX_CONFIG_NAME}
        has 'config_name' => (
                traits => ['ENV'],
                env_prefix => 'XXX',
        );

        ## Checks $ENV{MyApp_MyClass_extra} and $ENV{MYAPP_MYCLASS_EXTRA}
        has 'extra' => (
                traits => ['ENV'],
                env_package_prefix => 1,
        );

Please see the test cases for more detailed examples.

DESCRIPTION

This is a Moose attribute trait that you use when you want the default value for an attribute to be populated from the %ENV hash. So, for example if you have set the environment variable USERNAME = 'John' you can do:

        package MyApp::MyClass;

        use Moose;
        use MooseX::Attribute::ENV;

        has 'username' => (is=>'ro', traits=>['ENV']);

        package main;

        my $myclass = MyApp::MyClass->new();

        print $myclass->username; # STDOUT => 'John';

This is basically similar functionality to something like:

        has 'attr' => (
                is=>'ro',
                default=> sub {
                        $ENV{uc 'attr'};
                },
        );

but this module has a few other features that offer merit, as well as being a simple enough attribute trait that I hope it can serve as a learning tool.

If the named key isn't found in %ENV, then defaults will execute as normal.

ATTRIBUTES

This role defines the following attributes.

env_key ($Str)

By default we look for a key in %ENV based on the actual attribute name. If want or need to override this behavior, you can use this modifier.

env_prefix ($Str)

A prefix to attach to the generated filename. The prefix is prepended with a trailing underscore. For example, if you attribute was 'attr' and your set a prefix of 'xxx' then we'd check for $ENV{xxx_attr} and $ENV{XXX_ATTR}.

env_package_prefix ($Bool)

Similar to env_prefix, but automatically sets the prefix based on the consuming classes package name. So if your attribute is 'attr' and it's in a package called: 'Myapp::Myclass' the follow keys in %ENV will be examined:

* Myapp_Myclass_attr * MYAPP_MYCLASS_ATTR

Please be aware that if you use this feature, your attribute will automatically be converted to lazy, which might effect any default subrefs you also assign to this attribute.

Please note that you can't currently use this option along with the option 'lazy_build'. That might change in a future release, however since these attributes are likely to hold simple strings the lazy_build option probably won't be missed.

METHODS

This module defines the following methods.

_process_options

Overload method so that we can assign the default to be what's in %ENV

AUTHOR

John Napiorkowski, <jjnapiork at cpan.org>

BUGS

Please report any bugs or feature requests to:

        C<MooseX-Attribute-ENV at rt.cpan.org>

or through the web interface at:

        L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=MooseX-Attribute-ENV>

I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc MooseX::Attribute::ENV

You can also look for information at:

LICENSE

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