lib/Moose.pm

   1
   2 package Moose;
   3
   4 use strict;
   5 use warnings;
   6
   7 our $VERSION = '0.03_01';
   8
   9 use Scalar::Util 'blessed', 'reftype';
  10 use Carp         'confess';
  11 use Sub::Name    'subname';
  12
  13 use UNIVERSAL::require;
  14
  15 use Class::MOP;
  16
  17 use Moose::Meta::Class;
  18 use Moose::Meta::TypeConstraint;
  19 use Moose::Meta::TypeCoercion;
  20 use Moose::Meta::Attribute;
  21
  22 use Moose::Object;
  23 use Moose::Util::TypeConstraints;
  24
  25 sub import {
  26         shift;
  27         my $pkg = caller();
  28
  29         # we should never export to main
  30         return if $pkg eq 'main';
  31
  32         Moose::Util::TypeConstraints->import($pkg);
  33
  34         # make a subtype for each Moose class
  35     subtype $pkg
  36         => as 'Object'
  37         => where { $_->isa($pkg) };
  38
  39         my $meta;
  40         if ($pkg->can('meta')) {
  41                 $meta = $pkg->meta();
  42                 (blessed($meta) && $meta->isa('Class::MOP::Class'))
  43                         || confess "Whoops, not møøsey enough";
  44         }
  45         else {
  46                 $meta = Moose::Meta::Class->initialize($pkg => (
  47                         ':attribute_metaclass' => 'Moose::Meta::Attribute'
  48                 ));
  49                 $meta->add_method('meta' => sub {
  50                         # re-initialize so it inherits properly
  51                         Moose::Meta::Class->initialize($pkg => (
  52                                 ':attribute_metaclass' => 'Moose::Meta::Attribute'
  53                         ));
  54                 })
  55         }
  56
  57         # NOTE:
  58         # &alias_method will install the method, but it
  59         # will not name it with
  60
  61         # handle superclasses
  62         $meta->alias_method('extends' => subname 'Moose::extends' => sub {
  63         _load_all_classes(@_);
  64             $meta->superclasses(@_)
  65         });
  66
  67         # handle roles
  68         $meta->alias_method('with' => subname 'Moose::with' => sub {
  69             my ($role) = @_;
  70         _load_all_classes($role);
  71         $role->meta->apply($meta);
  72         });
  73
  74         # handle attributes
  75         $meta->alias_method('has' => subname 'Moose::has' => sub {
  76                 my ($name, %options) = @_;
  77                 $meta->add_attribute($name, %options)
  78         });
  79
  80         # handle method modifers
  81         $meta->alias_method('before' => subname 'Moose::before' => sub {
  82                 my $code = pop @_;
  83                 $meta->add_before_method_modifier($_, $code) for @_;
  84         });
  85         $meta->alias_method('after'  => subname 'Moose::after' => sub {
  86                 my $code = pop @_;
  87                 $meta->add_after_method_modifier($_, $code) for @_;
  88         });
  89         $meta->alias_method('around' => subname 'Moose::around' => sub {
  90                 my $code = pop @_;
  91                 $meta->add_around_method_modifier($_, $code) for @_;
  92         });
  93
  94         $meta->alias_method('super' => subname 'Moose::super' => sub {});
  95         $meta->alias_method('override' => subname 'Moose::override' => sub {
  96             my ($name, $method) = @_;
  97             $meta->add_override_method_modifier($name => $method);
  98         });
  99
 100         $meta->alias_method('inner' => subname 'Moose::inner' => sub {});
 101         $meta->alias_method('augment' => subname 'Moose::augment' => sub {
 102             my ($name, $method) = @_;
 103             $meta->add_augment_method_modifier($name => $method);
 104         });
 105
 106         # make sure they inherit from Moose::Object
 107         $meta->superclasses('Moose::Object')
 108        unless $meta->superclasses();
 109
 110         # we recommend using these things
 111         # so export them for them
 112         $meta->alias_method('confess' => \&Carp::confess);
 113         $meta->alias_method('blessed' => \&Scalar::Util::blessed);
 114 }
 115
 116 ## Utility functions
 117
 118 sub _load_all_classes {
 119     foreach my $super (@_) {
 120         # see if this is already
 121         # loaded in the symbol table
 122         next if _is_class_already_loaded($super);
 123         # otherwise require it ...
 124         ($super->require)
 125             || confess "Could not load superclass '$super' because : " . $UNIVERSAL::require::ERROR;
 126     }
 127 }
 128
 129 sub _is_class_already_loaded {
 130         my $name = shift;
 131         no strict 'refs';
 132         return 1 if defined ${"${name}::VERSION"} || defined @{"${name}::ISA"};
 133         foreach (keys %{"${name}::"}) {
 134                 next if substr($_, -2, 2) eq '::';
 135                 return 1 if defined &{"${name}::$_"};
 136         }
 137     return 0;
 138 }
 139
 140 1;
 141
 142 __END__
 143
 144 =pod
 145
 146 =head1 NAME
 147
 148 Moose - Moose, it's the new Camel
 149
 150 =head1 SYNOPSIS
 151
 152   package Point;
 153   use Moose;
 154
 155   has 'x' => (isa => 'Int', is => 'rw');
 156   has 'y' => (isa => 'Int', is => 'rw');
 157
 158   sub clear {
 159       my $self = shift;
 160       $self->x(0);
 161       $self->y(0);
 162   }
 163
 164   package Point3D;
 165   use Moose;
 166
 167   extends 'Point';
 168
 169   has 'z' => (isa => 'Int');
 170
 171   after 'clear' => sub {
 172       my $self = shift;
 173       $self->{z} = 0;
 174   };
 175
 176 =head1 CAVEAT
 177
 178 This is an early release of this module, it still needs
 179 some fine tuning and B<lots> more documentation. I am adopting
 180 the I<release early and release often> approach with this module,
 181 so keep an eye on your favorite CPAN mirror!
 182
 183 =head1 DESCRIPTION
 184
 185 Moose is an extension of the Perl 5 object system.
 186
 187 =head2 Another object system!?!?
 188
 189 Yes, I know there has been an explosion recently of new ways to
 190 build object's in Perl 5, most of them based on inside-out objects,
 191 and other such things. Moose is different because it is not a new
 192 object system for Perl 5, but instead an extension of the existing
 193 object system.
 194
 195 Moose is built on top of L<Class::MOP>, which is a metaclass system
 196 for Perl 5. This means that Moose not only makes building normal
 197 Perl 5 objects better, but it also provides the power of metaclass
 198 programming.
 199
 200 =head2 What does Moose stand for??
 201
 202 Moose doesn't stand for one thing in particular, however, if you
 203 want, here are a few of my favorites, feel free to contribute
 204 more :)
 205
 206 =over 4
 207
 208 =item Make Other Object Systems Envious
 209
 210 =item Makes Object Orientation So Easy
 211
 212 =item Makes Object Orientation Spiffy- Er  (sorry ingy)
 213
 214 =item Most Other Object Systems Emasculate
 215
 216 =item My Overcraft Overfilled (with) Some Eels
 217
 218 =item Moose Often Ovulate Sorta Early
 219
 220 =item Many Overloaded Object Systems Exists
 221
 222 =item Moose Offers Often Super Extensions
 223
 224 =back
 225
 226 =head1 BUILDING CLASSES WITH MOOSE
 227
 228 Moose makes every attempt to provide as much convience during class
 229 construction/definition, but still stay out of your way if you want
 230 it to. Here are some of the features Moose provides:
 231
 232 Unless specified with C<extends>, any class which uses Moose will
 233 inherit from L<Moose::Object>.
 234
 235 Moose will also manage all attributes (including inherited ones) that
 236 are defined with C<has>. And assuming that you call C<new> which is
 237 inherited from L<Moose::Object>, then this includes properly initializing
 238 all instance slots, setting defaults where approprtiate and performing any
 239 type constraint checking or coercion.
 240
 241 For more details, see the ever expanding L<Moose::Cookbook>.
 242
 243 =head1 EXPORTED FUNCTIONS
 244
 245 Moose will export a number of functions into the class's namespace, which
 246 can then be used to set up the class. These functions all work directly
 247 on the current class.
 248
 249 =over 4
 250
 251 =item B<meta>
 252
 253 This is a method which provides access to the current class's metaclass.
 254
 255 =item B<extends (@superclasses)>
 256
 257 This function will set the superclass(es) for the current class.
 258
 259 This approach is recommended instead of C<use base>, because C<use base>
 260 actually C<push>es onto the class's C<@ISA>, whereas C<extends> will
 261 replace it. This is important to ensure that classes which do not have
 262 superclasses properly inherit from L<Moose::Object>.
 263
 264 =item B<with ($role)>
 265
 266 This will apply a given C<$role> to the local class. Role support is
 267 currently very experimental, see L<Moose::Role> for more details.
 268
 269 =item B<has ($name, %options)>
 270
 271 This will install an attribute of a given C<$name> into the current class.
 272 The list of C<%options> are the same as those provided by both
 273 L<Class::MOP::Attribute> and L<Moose::Meta::Attribute>, in addition to a
 274 few convience ones provided by Moose which are listed below:
 275
 276 =over 4
 277
 278 =item I<is =E<gt> 'rw'|'ro'>
 279
 280 The I<is> option accepts either I<rw> (for read/write) or I<ro> (for read
 281 only). These will create either a read/write accessor or a read-only
 282 accessor respectively, using the same name as the C<$name> of the attribute.
 283
 284 If you need more control over how your accessors are named, you can use the
 285 I<reader>, I<writer> and I<accessor> options inherited from L<Moose::Meta::Attribute>.
 286
 287 =item I<isa =E<gt> $type_name>
 288
 289 The I<isa> option uses Moose's type constraint facilities to set up runtime
 290 type checking for this attribute. Moose will perform the checks during class
 291 construction, and within any accessors. The C<$type_name> argument must be a
 292 string. The string can be either a class name, or a type defined using
 293 Moose's type defintion features.
 294
 295 =back
 296
 297 =item B<before $name|@names =E<gt> sub { ... }>
 298
 299 =item B<after $name|@names =E<gt> sub { ... }>
 300
 301 =item B<around $name|@names =E<gt> sub { ... }>
 302
 303 This three items are syntactic sugar for the before, after and around method
 304 modifier features that L<Class::MOP> provides. More information on these can
 305 be found in the L<Class::MOP> documentation for now.
 306
 307 =item B<super>
 308
 309 The keyword C<super> is a noop when called outside of an C<override> method. In
 310 the context of an C<override> method, it will call the next most appropriate
 311 superclass method with the same arguments as the original method.
 312
 313 =item B<override ($name, &sub)>
 314
 315 An C<override> method, is a way of explictly saying "I am overriding this
 316 method from my superclass". You can call C<super> within this method, and
 317 it will work as expected. The same thing I<can> be accomplished with a normal
 318 method call and the C<SUPER::> pseudo-package, it is really your choice.
 319
 320 =item B<inner>
 321
 322 The keyword C<inner>, much like C<super>, is a no-op outside of the context of
 323 an C<augment> method. You can think of C<inner> as being the inverse of
 324 C<super>, the details of how C<inner> and C<augment> work is best described in
 325 the L<Moose::Cookbook>.
 326
 327 =item B<augment ($name, &sub)>
 328
 329 An C<augment> method, is a way of explictly saying "I am augmenting this
 330 method from my superclass". Once again, the details of how C<inner> and
 331 C<augment> work is best described in the L<Moose::Cookbook>.
 332
 333 =item B<confess>
 334
 335 This is the C<Carp::confess> function, and exported here beause I use it
 336 all the time. This feature may change in the future, so you have been warned.
 337
 338 =item B<blessed>
 339
 340 This is the C<Scalar::Uti::blessed> function, it is exported here beause I
 341 use it all the time. It is highly recommended that this is used instead of
 342 C<ref> anywhere you need to test for an object's class name.
 343
 344 =back
 345
 346 =head1 ACKNOWLEDGEMENTS
 347
 348 =over 4
 349
 350 =item I blame Sam Vilain for introducing me to the insanity that is meta-models.
 351
 352 =item I blame Audrey Tang for then encouraging my meta-model habit in #perl6.
 353
 354 =item Without Yuval "nothingmuch" Kogman this module would not be possible,
 355 and it certainly wouldn't have this name ;P
 356
 357 =item The basis of the TypeContraints module was Rob Kinyon's idea
 358 originally, I just ran with it.
 359
 360 =item Thanks to mst & chansen and the whole #moose poose for all the
 361 ideas/feature-requests/encouragement
 362
 363 =back
 364
 365 =head1 SEE ALSO
 366
 367 =over 4
 368
 369 =item L<Class::MOP> documentation
 370
 371 =item The #moose channel on irc.perl.org
 372
 373 =item L<http://forum2.org/moose/>
 374
 375 =item L<http://www.cs.utah.edu/plt/publications/oopsla04-gff.pdf>
 376
 377 This paper (suggested by lbr on #moose) was what lead to the implementation
 378 of the C<super>/C<overrride> and C<inner>/C<augment> features. If you really
 379 want to understand this feature, I suggest you read this.
 380
 381 =back
 382
 383 =head1 BUGS
 384
 385 All complex software has bugs lurking in it, and this module is no
 386 exception. If you find a bug please either email me, or add the bug
 387 to cpan-RT.
 388
 389 =head1 AUTHOR
 390
 391 Stevan Little E<lt>stevan@iinteractive.comE<gt>
 392
 393 =head1 COPYRIGHT AND LICENSE
 394
 395 Copyright 2006 by Infinity Interactive, Inc.
 396
 397 L<http://www.iinteractive.com>
 398
 399 This library is free software; you can redistribute it and/or modify
 400 it under the same terms as Perl itself.
 401
 402 =cut