X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FMoose%2FManual%2FClasses.pod;h=5619db33c5c75f95630c61a651654b2eb6224517;hb=079191e18e51457fea4cf4b10fecca653660f02c;hp=a8ce70c0d7054083103930b5a6ea4c6fd3f06a97;hpb=34ae31e16cacd55eec6952331eb654c42c2f82dd;p=gitmo%2FMoose.git diff --git a/lib/Moose/Manual/Classes.pod b/lib/Moose/Manual/Classes.pod index a8ce70c..5619db3 100644 --- a/lib/Moose/Manual/Classes.pod +++ b/lib/Moose/Manual/Classes.pod @@ -12,12 +12,12 @@ Using Moose is very simple, you just C: use Moose; -That's it, you've now made a Moose-based class! +That's it, you've made a class with Moose! There's actually a lot going on here under the hood, so let's step -through it. The L package does several things when you load it. +through it. -When you load Moose, you get a bunch of sugar functions exported into +When you load L, a bunch of sugar functions are exported into your class. These include things like C, C, C, and more. These functions are what you use to define your class. For example, you might define an attribute ... @@ -31,30 +31,28 @@ example, you might define an attribute ... Attributes are described in the L documentation. -Loading Moose in your class also turns on the C and -C pragmas in your class for you. - -The metaclass object an introspection API for your class. It is also -used by Moose itself under the hood to add attributes, define parent -classes, and so on. In fact, all of Moose's sugar does the real work -by calling methods on this metaclass object (and other meta level -objects). +Loading Moose also enables C and C pragmas in your +class. When you load Moose, your class will become a subclass of L. The L class provides a default -constructor, destructor, as well as object construction helper +constructor and destructor, as well as object construction helper methods. You can read more about this in the L document. -As a convenience, Moose creates a new class type with the name of your -class, by calling the C function in -L. See the L document -for more about types. +As a convenience, Moose creates a new class type for your class. See +the L document to learn more about types. It also creates a L object for your class. This metaclass object is now available by calling a C method on your class, for example C<< Person->meta >>. +The metaclass object provides an introspection API for your class. It +is also used by Moose itself under the hood to add attributes, define +parent classes, and so on. In fact, all of Moose's sugar does the real +work by calling methods on this metaclass object (and other meta API +objects). + =head1 SUBCLASSING Moose provides a simple sugar function for declaring your parent @@ -68,16 +66,15 @@ classes, C: has 'username' => ( is => 'rw' ); -When you call extends, Moose takes the class(es) you provide and makes -those the parent of the current class. Note, that each call to -C will I your parents, so for multiple inheritance you -should provide all you parents at once, C. +Note that each call to C will I your parents. For +multiple inheritance you must provide all the parents at once, +C. You can use Moose to extend a non-Moose parent. However, when you do this, you will inherit the parent class's constructor (assuming it is also called C). In that case, you will have to take care of initializing attributes manually, either in the parent's constructor, -or in your subclass, and you will generally lose a lot of Moose magic. +or in your subclass, and you will lose a lot of Moose magic. =head1 NO MOOSE @@ -86,7 +83,15 @@ namespace. We recommend that you take advantage of this feature, since it just makes your classes "cleaner". You can do this by simply adding C at the end of your module file. -What this does is delete the functions from your class's namespace, so + package Person; + + use Moose; + + has 'ssn' => ( is => 'rw' ); + + no Moose; + +This deletes Moose's sugar functions from your class's namespace, so that C<< Person->can('has') >> will no longer return true. =head1 MAKING IT FASTER @@ -94,24 +99,37 @@ that C<< Person->can('has') >> will no longer return true. Moose has a feature called "immutabilization" that you can use to greatly speed up your classes at runtime. However, using it does incur a cost when your class is first being loaded. When you make your class -immutable you tell Moose that you will not be changing it, -specifically not adding any attributes, methods, roles, etc. +immutable you tell Moose that you will not be changing it in the +future. You will not adding any more attributes, methods, roles, etc. -This allows Moose to generate code specific to your class for its -constructor and other methods, making object construction much -faster. It also makes some of the introspection methods faster as -well. +This allows Moose to generate code specific to your class. In +particular, it creates an "inline" constructor, making object +construction much faster. To make your class immutable you simply call C on your class's metaclass object. + __PACKAGE__->meta->make_immutable; + +=head2 Immutabilization and C + +If you override C in your class, then the immutabilization code +will not be able to provide an optimized constructor for your +class. Instead, you should use a C method, which will be +called from the inlined constructor. + +Alternately, if you really need to provide a different C, you +can also provide your own immutabilization method. Doing so requires +extending the Moose metaclasses, and is well beyond the scope of this +manual. + =head1 AUTHOR Dave Rolsky Eautarch@urth.orgE =head1 COPYRIGHT AND LICENSE -Copyright 2008 by Infinity Interactive, Inc. +Copyright 2008-2009 by Infinity Interactive, Inc. L @@ -119,4 +137,3 @@ This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =cut -