lib/MooseX/ClassAttribute.pm

   1 package MooseX::ClassAttribute;
   2
   3 use strict;
   4 use warnings;
   5
   6 our $VERSION = '0.05';
   7 our $AUTHORITY = 'cpan:DROLSKY';
   8
   9 use Moose ();
  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
  40             ->initialize($caller)
  41             ->add_class_attribute( $_, %options )
  42                 for @{ $attrs };
  43 }
  44
  45 1;
  46
  47 __END__
  48
  49 =pod
  50
  51 =head1 NAME
  52
  53 MooseX::ClassAttribute - Declare class attributes Moose-style
  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     MooseX::ClassAttribute::container_class()->meta()->make_immutable();
  70
  71     no Moose;
  72     no MooseX::ClassAttribute;
  73
  74     # then later ...
  75
  76     My::Class->Cache()->{thing} = ...;
  77
  78
  79 =head1 DESCRIPTION
  80
  81 This module allows you to declare class attributes in exactly the same
  82 way as you declare object attributes, except using C<class_has()>
  83 instead of C<has()>. It is also possible to make these attributes
  84 immutable (and faster) just as you can with normal Moose attributes.
  85
  86 You can use any feature of Moose's attribute declarations, including
  87 overriding a parent's attributes, delegation (C<handles>), and
  88 attribute metaclasses, and it should just work.
  89
  90 The accessors methods for class attribute may be called on the class
  91 directly, or on objects of that class. Passing a class attribute to
  92 the constructor will not set it.
  93
  94 =head1 FUNCTIONS
  95
  96 This class exports one function when you use it, C<class_has()>. This
  97 works exactly like Moose's C<has()>, but it declares class attributes.
  98
  99 One little nit is that if you include C<no Moose> in your class, you
 100 won't remove the C<class_has()> function. To do that you must include
 101 C<no MooseX::ClassAttribute> as well.
 102
 103 If you want to use this module to create class attributes in I<other>
 104 classes, you can call the C<process_class_attribute()> function like
 105 this:
 106
 107   MooseX::ClassAttribute::process_class_attribute( $package, ... );
 108
 109 The first argument is the package which will have the class attribute,
 110 and the remaining arguments are the same as those passed to
 111 C<class_has()>.
 112
 113 =head2 Implementation and Immutability
 114
 115 Underneath the hood, this class creates one new class for each class
 116 which has class attributes and sets up delegating methods in the class
 117 for which you're creating class attributes. You don't need to worry
 118 about this too much, except when it comes to making a class immutable.
 119
 120 Since the class attributes are not really stored in your class, you
 121 need to make the container class immutable as well as your own ...
 122
 123   __PACKAGE__->meta()->make_immutable();
 124   MooseX::ClassAttribute::container_class()->meta()->make_immutable();
 125
 126 I<This may change in the future!>
 127
 128 =head1 AUTHOR
 129
 130 Dave Rolsky, C<< <autarch@urth.org> >>
 131
 132 =head1 BUGS
 133
 134 Please report any bugs or feature requests to
 135 C<bug-moosex-classattribute@rt.cpan.org>, or through the web interface
 136 at L<http://rt.cpan.org>.  I will be notified, and then you'll
 137 automatically be notified of progress on your bug as I make changes.
 138
 139 =head1 COPYRIGHT & LICENSE
 140
 141 Copyright 2007 Dave Rolsky, All Rights Reserved.
 142
 143 This program is free software; you can redistribute it and/or modify
 144 it under the same terms as Perl itself.
 145
 146 =cut