lib/MooseX/ClassAttribute.pm

   1 package MooseX::ClassAttribute;
   2
   3 use strict;
   4 use warnings;
   5
   6 use Moose 1.23 ();
   7 use Moose::Exporter;
   8 use Moose::Util;
   9 use MooseX::ClassAttribute::Trait::Class;
  10 use MooseX::ClassAttribute::Trait::Role;
  11 use MooseX::ClassAttribute::Trait::Application::ToClass;
  12 use MooseX::ClassAttribute::Trait::Application::ToRole;
  13
  14 Moose::Exporter->setup_import_methods(
  15     with_meta       => ['class_has'],
  16     class_metaroles => {
  17         class => ['MooseX::ClassAttribute::Trait::Class'],
  18     },
  19     role_metaroles => {
  20         role => ['MooseX::ClassAttribute::Trait::Role'],
  21         application_to_class =>
  22             ['MooseX::ClassAttribute::Trait::Application::ToClass'],
  23         application_to_role =>
  24             ['MooseX::ClassAttribute::Trait::Application::ToRole'],
  25     },
  26 );
  27
  28 sub class_has {
  29     my $meta    = shift;
  30     my $name    = shift;
  31
  32     my $attrs = ref $name eq 'ARRAY' ? $name : [$name];
  33
  34     my %options = ( definition_context => _caller_info(), @_ );
  35
  36     $meta->add_class_attribute( $_, %options ) for @{$attrs};
  37 }
  38
  39 # Copied from Moose::Util in 2.06
  40 sub _caller_info {
  41     my $level = @_ ? ($_[0] + 1) : 2;
  42     my %info;
  43     @info{qw(package file line)} = caller($level);
  44     return \%info;
  45 }
  46
  47 1;
  48
  49 # ABSTRACT: Declare class attributes Moose-style
  50
  51 __END__
  52
  53 =pod
  54
  55 =head1 SYNOPSIS
  56
  57     package My::Class;
  58
  59     use Moose;
  60     use MooseX::ClassAttribute;
  61
  62     class_has 'Cache' =>
  63         ( is      => 'rw',
  64           isa     => 'HashRef',
  65           default => sub { {} },
  66         );
  67
  68     __PACKAGE__->meta()->make_immutable();
  69
  70     no Moose;
  71     no MooseX::ClassAttribute;
  72
  73     # then later ...
  74
  75     My::Class->Cache()->{thing} = ...;
  76
  77 =head1 DESCRIPTION
  78
  79 This module allows you to declare class attributes in exactly the same
  80 way as object attributes, using C<class_has()> instead of C<has()>.
  81
  82 You can use any feature of Moose's attribute declarations, including
  83 overriding a parent's attributes, delegation (C<handles>), attribute traits,
  84 etc. All features should just work. The one exception is the "required" flag,
  85 which is not allowed for class attributes.
  86
  87 The accessor methods for class attribute may be called on the class
  88 directly, or on objects of that class. Passing a class attribute to
  89 the constructor will not set that attribute.
  90
  91 =head1 FUNCTIONS
  92
  93 This class exports one function when you use it, C<class_has()>. This
  94 works exactly like Moose's C<has()>, but it declares class attributes.
  95
  96 One little nit is that if you include C<no Moose> in your class, you won't
  97 remove the C<class_has()> function. To do that you must include C<no
  98 MooseX::ClassAttribute> as well. Or you can just use L<namespace::autoclean>
  99 instead.
 100
 101 =head2 Implementation and Immutability
 102
 103 This module will add a role to your class's metaclass, See
 104 L<MooseX::ClassAttribute::Trait::Class> for details. This role
 105 provides introspection methods for class attributes.
 106
 107 Class attributes themselves do the
 108 L<MooseX::ClassAttribute::Trait::Attribute> role.
 109
 110 =head2 Cooperation with Metaclasses and Traits
 111
 112 This module should work with most attribute metaclasses and traits,
 113 but it's possible that conflicts could occur. This module has been
 114 tested to work with Moose's native traits.
 115
 116 =head2 Class Attributes in Roles
 117
 118 You can add a class attribute to a role. When that role is applied to a class,
 119 the class will have the relevant class attributes added. Note that attribute
 120 defaults will be calculated when the class attribute is composed into the
 121 class.
 122
 123 =head1 DONATIONS
 124
 125 If you'd like to thank me for the work I've done on this module,
 126 please consider making a "donation" to me via PayPal. I spend a lot of
 127 free time creating free software, and would appreciate any support
 128 you'd care to offer.
 129
 130 Please note that B<I am not suggesting that you must do this> in order
 131 for me to continue working on this particular software. I will
 132 continue to do so, inasmuch as I have in the past, for as long as it
 133 interests me.
 134
 135 Similarly, a donation made in this way will probably not make me work
 136 on this software much more, unless I get so many donations that I can
 137 consider working on free software full time, which seems unlikely at
 138 best.
 139
 140 To donate, log into PayPal and send money to autarch@urth.org or use
 141 the button on this page:
 142 L<http://www.urth.org/~autarch/fs-donation.html>
 143
 144 =head1 BUGS
 145
 146 Please report any bugs or feature requests to
 147 C<bug-moosex-classattribute@rt.cpan.org>, or through the web interface
 148 at L<http://rt.cpan.org>.  I will be notified, and then you'll
 149 automatically be notified of progress on your bug as I make changes.
 150
 151 =cut