Commit | Line | Data |
650d6350 |
1 | package MooseX::Attribute::ENV; |
2 | |
ce989a70 |
3 | use Moose::Role; |
4 | |
52f52357 |
5 | our $VERSION = "0.02"; |
ce989a70 |
6 | our $AUTHORITY = 'cpan:JJNAPIORK'; |
650d6350 |
7 | |
8 | =head1 NAME |
9 | |
10 | MooseX::Attribute::ENV - Set default of an attribute to a value from %ENV |
11 | |
650d6350 |
12 | =head1 SYNOPSIS |
13 | |
ce989a70 |
14 | The following is example usage for this attribute trait. |
650d6350 |
15 | |
ce989a70 |
16 | package MyApp::MyClass; |
c9868b1c |
17 | |
650d6350 |
18 | use Moose; |
19 | use MooseX::Attribute::ENV; |
c9868b1c |
20 | |
ce989a70 |
21 | ## Checks $ENV{username} and $ENV{USERNAME} |
22 | has 'username' => ( |
23 | traits => ['ENV'], |
24 | ); |
c9868b1c |
25 | |
ce989a70 |
26 | ## Checks $ENV{GLOBAL_PASSWORD} |
27 | has 'password' => ( |
c9868b1c |
28 | traits => ['ENV'], |
ce989a70 |
29 | env_key => 'GLOBAL_PASSWORD', |
30 | ); |
c9868b1c |
31 | |
ce989a70 |
32 | ## Checks $ENV{last_login}, $ENV{LAST_LOGIN} and then uses the default |
33 | has 'last_login' => ( |
34 | traits => ['ENV'], |
35 | default => sub {localtime}, |
36 | ); |
c9868b1c |
37 | |
38 | ## Checks $ENV{XXX_config_name} and $ENV{XXX_CONFIG_NAME} |
ce989a70 |
39 | has 'config_name' => ( |
40 | traits => ['ENV'], |
41 | env_prefix => 'XXX', |
42 | ); |
c9868b1c |
43 | |
44 | ## Checks $ENV{MyApp_MyClass_extra} and $ENV{MYAPP_MYCLASS_EXTRA} |
ce989a70 |
45 | has 'extra' => ( |
46 | traits => ['ENV'], |
47 | env_package_prefix => 1, |
c9868b1c |
48 | ); |
650d6350 |
49 | |
50 | Please see the test cases for more detailed examples. |
51 | |
52 | =head1 DESCRIPTION |
53 | |
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 |
ce989a70 |
56 | have set the environment variable USERNAME = 'John' you can do: |
650d6350 |
57 | |
58 | package MyApp::MyClass; |
c9868b1c |
59 | |
650d6350 |
60 | use Moose; |
61 | use MooseX::Attribute::ENV; |
c9868b1c |
62 | |
650d6350 |
63 | has 'username' => (is=>'ro', traits=>['ENV']); |
c9868b1c |
64 | |
650d6350 |
65 | package main; |
c9868b1c |
66 | |
650d6350 |
67 | my $myclass = MyApp::MyClass->new(); |
c9868b1c |
68 | |
650d6350 |
69 | print $myclass->username; # STDOUT => 'John'; |
70 | |
71 | This is basically similar functionality to something like: |
72 | |
73 | has 'attr' => ( |
74 | is=>'ro', |
75 | default=> sub { |
ce989a70 |
76 | $ENV{uc 'attr'}; |
650d6350 |
77 | }, |
78 | ); |
79 | |
80 | but this module has a few other features that offer merit, as well as being a |
ce989a70 |
81 | simple enough attribute trait that I hope it can serve as a learning tool. |
82 | |
83 | If the named key isn't found in %ENV, then defaults will execute as normal. |
84 | |
85 | =head1 ATTRIBUTES |
86 | |
87 | This role defines the following attributes. |
88 | |
89 | =head2 env_key ($Str) |
90 | |
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. |
93 | |
94 | =cut |
95 | |
96 | has 'env_key' => ( |
97 | is=>'ro', |
98 | isa=>'Str', |
99 | predicate=>'has_env_key', |
100 | ); |
101 | |
102 | =head2 env_prefix ($Str) |
103 | |
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}. |
107 | |
108 | =cut |
109 | |
110 | has 'env_prefix' => ( |
111 | is=>'ro', |
112 | isa=>'Str', |
113 | predicate=>'has_env_prefix', |
114 | ); |
115 | |
116 | =head2 env_package_prefix ($Bool) |
117 | |
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: |
121 | |
122 | * Myapp_Myclass_attr |
123 | * MYAPP_MYCLASS_ATTR |
124 | |
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 |
127 | this attribute. |
128 | |
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 |
132 | won't be missed. |
133 | |
134 | =cut |
135 | |
136 | has 'env_package_prefix' => ( |
137 | is=>'ro', |
138 | isa=>'Str', |
139 | predicate=>'has_env_package_prefix', |
140 | ); |
650d6350 |
141 | |
142 | =head1 METHODS |
143 | |
144 | This module defines the following methods. |
145 | |
ce989a70 |
146 | =head2 _process_options |
147 | |
148 | Overload method so that we can assign the default to be what's in %ENV |
149 | |
150 | =cut |
151 | |
152 | around '_process_options' => sub |
153 | { |
154 | my ($_process_options, $self, $name, $options) = (shift, @_); |
c9868b1c |
155 | |
ce989a70 |
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}; |
c9868b1c |
160 | |
ce989a70 |
161 | ## Make it lazy if we are using the package prefix option |
162 | if( defined $use_pp && $use_pp ) |
163 | { |
164 | $options->{lazy} = 1; |
165 | } |
c9868b1c |
166 | |
ce989a70 |
167 | ## Prepend any custom prefixes. |
168 | if($options->{env_prefix}) |
169 | { |
c9868b1c |
170 | $key = join('_', ($options->{env_prefix}, $key)); |
ce989a70 |
171 | } |
c9868b1c |
172 | |
ce989a70 |
173 | ## override/update the default method for this attribute. |
174 | CHECK_ENV: { |
c9868b1c |
175 | |
ce989a70 |
176 | $options->{default} = sub { |
c9868b1c |
177 | |
ce989a70 |
178 | if(defined $use_pp && $use_pp) |
179 | { |
180 | my $class = blessed $_[0]; |
181 | $class =~s/::/_/g; |
c9868b1c |
182 | |
ce989a70 |
183 | $key = join ('_', ($class, $key)); |
184 | } |
c9868b1c |
185 | |
ce989a70 |
186 | ## Wish we could use perl 5.10 given instead :) |
187 | if(defined $ENV{$key}) |
188 | { |
189 | return $ENV{$key}; |
190 | } |
191 | elsif(defined $ENV{uc $key}) |
192 | { |
193 | return $ENV{uc $key}; |
194 | } |
195 | elsif(defined $default) |
196 | { |
197 | return ref $default eq 'CODE' ? $default->(@_) : $default; |
198 | } |
ce989a70 |
199 | }; |
200 | } |
201 | |
202 | $_process_options->($self, $name, $options); |
203 | }; |
204 | |
650d6350 |
205 | =head1 AUTHOR |
206 | |
207 | John Napiorkowski, C<< <jjnapiork at cpan.org> >> |
208 | |
209 | =head1 BUGS |
210 | |
211 | Please report any bugs or feature requests to: |
212 | |
213 | C<MooseX-Attribute-ENV at rt.cpan.org> |
214 | |
215 | or through the web interface at: |
216 | |
217 | L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=MooseX-Attribute-ENV> |
218 | |
c9868b1c |
219 | I will be notified, and then you'll automatically be notified of progress on |
650d6350 |
220 | your bug as I make changes. |
221 | |
222 | =head1 SUPPORT |
223 | |
224 | You can find documentation for this module with the perldoc command. |
225 | |
226 | perldoc MooseX::Attribute::ENV |
227 | |
228 | You can also look for information at: |
229 | |
230 | =over 4 |
231 | |
232 | =item * RT: CPAN's request tracker |
233 | |
234 | L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=MooseX-Attribute-ENV> |
235 | |
236 | =item * AnnoCPAN: Annotated CPAN documentation |
237 | |
238 | L<http://annocpan.org/dist/MooseX-Attribute-ENV> |
239 | |
240 | =item * CPAN Ratings |
241 | |
242 | L<http://cpanratings.perl.org/d/MooseX-Attribute-ENV> |
243 | |
244 | =item * Search CPAN |
245 | |
246 | L<http://search.cpan.org/dist/DBIx-Class-PopulateMore> |
247 | |
248 | =back |
249 | |
250 | =head1 LICENSE |
251 | |
252 | This program is free software; you can redistribute it and/or modify it |
253 | under the same terms as Perl itself. |
254 | |
255 | =cut |
256 | |
ce989a70 |
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' } |
260 | |
650d6350 |
261 | 1; |