1 package MooseX::Attribute::ENV;
6 our $AUTHORITY = 'cpan:JJNAPIORK';
10 MooseX::Attribute::ENV - Set default of an attribute to a value from %ENV
14 The following is example usage for this attribute trait.
16 package MyApp::MyClass;
19 use MooseX::Attribute::ENV;
21 ## Checks $ENV{username} and $ENV{USERNAME}
26 ## Checks $ENV{GLOBAL_PASSWORD}
29 env_key => 'GLOBAL_PASSWORD',
32 ## Checks $ENV{last_login}, $ENV{LAST_LOGIN} and then uses the default
35 default => sub {localtime},
38 ## Checks $ENV{XXX_config_name} and $ENV{XXX_CONFIG_NAME}
39 has 'config_name' => (
44 ## Checks $ENV{MyApp_MyClass_extra} and $ENV{MYAPP_MYCLASS_EXTRA}
47 env_package_prefix => 1,
50 Please see the test cases for more detailed examples.
54 This is a L<Moose> attribute trait that you use when you want the default value
55 for an attribute to be populated from the %ENV hash. So, for example if you
56 have set the environment variable USERNAME = 'John' you can do:
58 package MyApp::MyClass;
61 use MooseX::Attribute::ENV;
63 has 'username' => (is=>'ro', traits=>['ENV']);
67 my $myclass = MyApp::MyClass->new();
69 print $myclass->username; # STDOUT => 'John';
71 This is basically similar functionality to something like:
80 but this module has a few other features that offer merit, as well as being a
81 simple enough attribute trait that I hope it can serve as a learning tool.
83 If the named key isn't found in %ENV, then defaults will execute as normal.
87 This role defines the following attributes.
91 By default we look for a key in %ENV based on the actual attribute name. If
92 want or need to override this behavior, you can use this modifier.
99 predicate=>'has_env_key',
102 =head2 env_prefix ($Str)
104 A prefix to attach to the generated filename. The prefix is prepended with a
105 trailing underscore. For example, if you attribute was 'attr' and your set a
106 prefix of 'xxx' then we'd check for $ENV{xxx_attr} and $ENV{XXX_ATTR}.
110 has 'env_prefix' => (
113 predicate=>'has_env_prefix',
116 =head2 env_package_prefix ($Bool)
118 Similar to env_prefix, but automatically sets the prefix based on the consuming
119 classes package name. So if your attribute is 'attr' and it's in a package
120 called: 'Myapp::Myclass' the follow keys in %ENV will be examined:
125 Please be aware that if you use this feature, your attribute will automatically
126 be converted to lazy, which might effect any default subrefs you also assign to
129 Please note that you can't currently use this option along with the option
130 'lazy_build'. That might change in a future release, however since these
131 attributes are likely to hold simple strings the lazy_build option probably
136 has 'env_package_prefix' => (
139 predicate=>'has_env_package_prefix',
144 This module defines the following methods.
146 =head2 _process_options
148 Overload method so that we can assign the default to be what's in %ENV
152 around '_process_options' => sub
154 my ($_process_options, $self, $name, $options) = (shift, @_);
156 ## get some stuff we need.
157 my $key = $options->{env_key} || $name;
158 my $default = $options->{default};
159 my $use_pp = $options->{env_package_prefix};
161 ## Make it lazy if we are using the package prefix option
162 if( defined $use_pp && $use_pp )
164 $options->{lazy} = 1;
167 ## Prepend any custom prefixes.
168 if($options->{env_prefix})
170 $key = join('_', ($options->{env_prefix}, $key));
173 ## override/update the default method for this attribute.
176 $options->{default} = sub {
178 if(defined $use_pp && $use_pp)
180 my $class = blessed $_[0];
183 $key = join ('_', ($class, $key));
186 ## Wish we could use perl 5.10 given instead :)
187 if(defined $ENV{$key})
191 elsif(defined $ENV{uc $key})
193 return $ENV{uc $key};
195 elsif(defined $default)
197 return ref $default eq 'CODE' ? $default->(@_) : $default;
202 $_process_options->($self, $name, $options);
207 John Napiorkowski, C<< <jjnapiork at cpan.org> >>
211 Please report any bugs or feature requests to:
213 C<MooseX-Attribute-ENV at rt.cpan.org>
215 or through the web interface at:
217 L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=MooseX-Attribute-ENV>
219 I will be notified, and then you'll automatically be notified of progress on
220 your bug as I make changes.
224 You can find documentation for this module with the perldoc command.
226 perldoc MooseX::Attribute::ENV
228 You can also look for information at:
232 =item * RT: CPAN's request tracker
234 L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=MooseX-Attribute-ENV>
236 =item * AnnoCPAN: Annotated CPAN documentation
238 L<http://annocpan.org/dist/MooseX-Attribute-ENV>
242 L<http://cpanratings.perl.org/d/MooseX-Attribute-ENV>
246 L<http://search.cpan.org/dist/DBIx-Class-PopulateMore>
252 This program is free software; you can redistribute it and/or modify it
253 under the same terms as Perl itself.
257 ## Register the trait so this can be used without verbose invocation.
258 package Moose::Meta::Attribute::Custom::Trait::ENV;
259 sub register_implementation { 'MooseX::Attribute::ENV' }