lib/MooseX/ClassAttribute.pm

   1 package MooseX::ClassAttribute;
   2
   3 use strict;
   4 use warnings;
   5
   6 our $VERSION = '0.08';
   7 our $AUTHORITY = 'cpan:DROLSKY';
   8
   9 use Moose 0.74 ();
  10 use Moose::Exporter;
  11 use MooseX::ClassAttribute::Role::Meta::Class;
  12
  13 Moose::Exporter->setup_import_methods
  14     ( with_caller => [ 'class_has' ] );
  15
  16
  17 sub init_meta
  18 {
  19     shift;
  20     my %p = @_;
  21
  22     Moose->init_meta(%p);
  23
  24     return
  25         Moose::Util::MetaRole::apply_metaclass_roles
  26             ( for_class       => $p{for_class},
  27               metaclass_roles => [ 'MooseX::ClassAttribute::Role::Meta::Class' ],
  28             );
  29 }
  30
  31 sub class_has
  32 {
  33     my $caller  = shift;
  34     my $name    = shift;
  35     my %options = @_;
  36
  37     my $attrs = ref $name eq 'ARRAY' ? $name : [$name];
  38
  39     Class::MOP::class_of($caller)
  40         ->add_class_attribute( $_, %options )
  41             for @{ $attrs };
  42 }
  43
  44 1;
  45
  46 __END__
  47
  48 =pod
  49
  50 =head1 NAME
  51
  52 MooseX::ClassAttribute - Declare class attributes Moose-style
  53
  54 =head1 SYNOPSIS
  55
  56     package My::Class;
  57
  58     use Moose;
  59     use MooseX::ClassAttribute;
  60
  61     class_has 'Cache' =>
  62         ( is      => 'rw',
  63           isa     => 'HashRef',
  64           default => sub { {} },
  65         );
  66
  67     __PACKAGE__->meta()->make_immutable();
  68
  69     no Moose;
  70     no MooseX::ClassAttribute;
  71
  72     # then later ...
  73
  74     My::Class->Cache()->{thing} = ...;
  75
  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>), and
  84 attribute metaclasses, and it should just work. The one exception is
  85 the "required" flag, 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 it.
  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
  97 won't remove the C<class_has()> function. To do that you must include
  98 C<no MooseX::ClassAttribute> as well.
  99
 100 =head2 Implementation and Immutability
 101
 102 This module will add a role to your class's metaclass, See
 103 L<MooseX::ClassAttribute::Role::Meta::Class> for details. This role
 104 provides introspection methods for class attributes.
 105
 106 Class attributes themselves do the
 107 L<MooseX::ClassAttribute::Role::Meta::Attribute> role.
 108
 109 There is also a L<MooseX::ClassAttribute::Meta::Method::Accessor>
 110 which provides part of the inlining implementation for class
 111 attributes.
 112
 113 =head2 Cooperation with Metaclasses and Traits
 114
 115 This module should work with most attribute metaclasses and traits,
 116 but it's possible that conflicts could occur. This module has been
 117 tested to work with C<MooseX::AttributeHelpers>.
 118
 119 =head1 DONATIONS
 120
 121 If you'd like to thank me for the work I've done on this module,
 122 please consider making a "donation" to me via PayPal. I spend a lot of
 123 free time creating free software, and would appreciate any support
 124 you'd care to offer.
 125
 126 Please note that B<I am not suggesting that you must do this> in order
 127 for me to continue working on this particular software. I will
 128 continue to do so, inasmuch as I have in the past, for as long as it
 129 interests me.
 130
 131 Similarly, a donation made in this way will probably not make me work
 132 on this software much more, unless I get so many donations that I can
 133 consider working on free software full time, which seems unlikely at
 134 best.
 135
 136 To donate, log into PayPal and send money to autarch@urth.org or use
 137 the button on this page:
 138 L<http://www.urth.org/~autarch/fs-donation.html>
 139
 140 =head1 AUTHOR
 141
 142 Dave Rolsky, C<< <autarch@urth.org> >>
 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 =head1 COPYRIGHT & LICENSE
 152
 153 Copyright 2007-2008 Dave Rolsky, All Rights Reserved.
 154
 155 This program is free software; you can redistribute it and/or modify
 156 it under the same terms as Perl itself.
 157
 158 =cut