From: Dave Rolsky Date: Wed, 10 Dec 2008 21:06:31 +0000 (+0000) Subject: Add first draft of classes manual document X-Git-Tag: 0.66~27^2~41 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=6c40a460d693f8a731a5a711cd045370563bc622;p=gitmo%2FMoose.git Add first draft of classes manual document --- diff --git a/lib/Moose/Manual/Classes.pod b/lib/Moose/Manual/Classes.pod new file mode 100644 index 0000000..b4081ae --- /dev/null +++ b/lib/Moose/Manual/Classes.pod @@ -0,0 +1,141 @@ +=pod + +=head1 NAME + +Moose::Manual::Classes - Making your classes use Moose (and subclassing) + +=head1 USING MOOSE + +Using Moose is very simple, you just C: + + package Person; + + use Moose; + +That's it, you've now made a Moose-based class! + +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. + +When you load Moose, you get a bunch of sugar functions 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 ... + + package Person; + + use Moose; + + has 'ssn' => ( is => 'rw' ); + +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. + +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 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). + +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 +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. + +=head1 SUBCLASSING + +Moose provides a simple sugar function for declaring your parent +classes, C: + + package User; + + use Moose; + + extends 'Person'; + + 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. + +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. + +=head1 NO MOOSE + +Moose also allows you to remove its sugar functions from your class's +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 +that C<< Person->can('has') >> will no longer return true. + +=head1 MAKING IT FASTER + +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. + +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. + +To make your class immutable you simply call C on your +class's metaclass object. + +=head1 RECOMMENDATIONS + +We recommend that you end your Moose class definitions by removing the +Moose sugar and making your class immutable. + + package Person; + + use Moose; + + # extends, roles, attributes, etc. + + # methods + + no Moose; + + __PACKAGE__->meta->make_immutable; + + 1; + +=head1 AUTHOR + +Dave Rolsky Eautarch@urth.orgE + +=head1 COPYRIGHT AND LICENSE + +Copyright 2008 by Infinity Interactive, Inc. + +L + +This library is free software; you can redistribute it and/or modify +it under the same terms as Perl itself. + +=cut +