.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Required to disable full justification in groff 1.23.0. .if n .ds AD l .\" ======================================================================== .\" .IX Title "Moose::Cookbook::Basics::Point_AttributesAndSubclassing 3" .TH Moose::Cookbook::Basics::Point_AttributesAndSubclassing 3 2026-06-15 "perl v5.42.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH NAME Moose::Cookbook::Basics::Point_AttributesAndSubclassing \- Point and Point3D classes, showing basic attributes and subclassing. .SH VERSION .IX Header "VERSION" version 2.4000 .SH SYNOPSIS .IX Header "SYNOPSIS" .Vb 2 \& package Point; \& use Moose; \& \& has \*(Aqx\*(Aq => (isa => \*(AqInt\*(Aq, is => \*(Aqrw\*(Aq, required => 1); \& has \*(Aqy\*(Aq => (isa => \*(AqInt\*(Aq, is => \*(Aqrw\*(Aq, required => 1); \& \& sub clear { \& my $self = shift; \& $self\->x(0); \& $self\->y(0); \& } \& \& package Point3D; \& use Moose; \& \& extends \*(AqPoint\*(Aq; \& \& has \*(Aqz\*(Aq => (isa => \*(AqInt\*(Aq, is => \*(Aqrw\*(Aq, required => 1); \& \& after \*(Aqclear\*(Aq => sub { \& my $self = shift; \& $self\->z(0); \& }; \& \& package main; \& \& # hash or hashrefs are ok for the constructor \& my $point1 = Point\->new(x => 5, y => 7); \& my $point2 = Point\->new({x => 5, y => 7}); \& \& my $point3d = Point3D\->new(x => 5, y => 42, z => \-5); .Ve .SH DESCRIPTION .IX Header "DESCRIPTION" This is the classic Point example. It is taken directly from the Perl 6 Apocalypse 12 document, and is similar to the example found in the classic K&R C book as well. .PP As with all Perl 5 classes, a Moose class is defined in a package. Moose handles turning on \f(CW\*(C`strict\*(C'\fR and \f(CW\*(C`warnings\*(C'\fR for us, so all we need to do is say \f(CW\*(C`use Moose\*(C'\fR, and no kittens will die. .PP When Moose is loaded, it exports a set of sugar functions into our package. This means that we import some functions which serve as Moose "keywords". These aren\*(Aqt real language keywords, they\*(Aqre just Perl functions exported into our package. .PP Moose automatically makes our package a subclass of Moose::Object. The Moose::Object class provides us with a constructor that respects our attributes, as well other features. See Moose::Object for details. .PP Now, onto the keywords. The first one we see here is \f(CW\*(C`has\*(C'\fR, which defines an instance attribute in our class: .PP .Vb 1 \& has \*(Aqx\*(Aq => (isa => \*(AqInt\*(Aq, is => \*(Aqrw\*(Aq, required => 1); .Ve .PP This will create an attribute named \f(CW\*(C`x\*(C'\fR. The \f(CW\*(C`isa\*(C'\fR parameter says that we expect the value stored in this attribute to pass the type constraint for \f(CW\*(C`Int\*(C'\fR (1). The accessor generated for this attribute will be read\-write. .PP The \f(CW\*(C`required => 1\*(C'\fR parameter means that this attribute must be provided when a new object is created. A point object without coordinates doesn\*(Aqt make much sense, so we don\*(Aqt allow it. .PP We have defined our attributes; next we define our methods. In Moose, as with regular Perl 5 OO, a method is just a subroutine defined within the package: .PP .Vb 5 \& sub clear { \& my $self = shift; \& $self\->x(0); \& $self\->y(0); \& } .Ve .PP That concludes the \fBPoint\fR class. .PP Next we have a subclass of \fBPoint\fR, \fBPoint3D\fR. To declare our superclass, we use the Moose keyword \f(CW\*(C`extends\*(C'\fR: .PP .Vb 1 \& extends \*(AqPoint\*(Aq; .Ve .PP The \f(CW\*(C`extends\*(C'\fR keyword works much like \f(CW\*(C`use base\*(C'\fR/\f(CW\*(C`use parent\*(C'\fR. First, it will attempt to load your class if needed. However, unlike \f(CW\*(C`base\*(C'\fR, the \&\f(CW\*(C`extends\*(C'\fR keyword will \fIoverwrite\fR any previous values in your package\*(Aqs \f(CW@ISA\fR, where \f(CW\*(C`use base\*(C'\fR will \f(CW\*(C`push\*(C'\fR values onto the package\*(Aqs \f(CW@ISA\fR. .PP It is my opinion that the behavior of \f(CW\*(C`extends\*(C'\fR is more intuitive. (2). .PP Next we create a new attribute for \fBPoint3D\fR called \f(CW\*(C`z\*(C'\fR. .PP .Vb 1 \& has \*(Aqz\*(Aq => (isa => \*(AqInt\*(Aq, is => \*(Aqrw\*(Aq, required => 1); .Ve .PP This attribute is just like \fBPoint\fR\*(Aqs \f(CW\*(C`x\*(C'\fR and \f(CW\*(C`y\*(C'\fR attributes. .PP The \f(CW\*(C`after\*(C'\fR keyword demonstrates a Moose feature called "method modifiers" (or "advice" for the AOP inclined): .PP .Vb 4 \& after \*(Aqclear\*(Aq => sub { \& my $self = shift; \& $self\->z(0); \& }; .Ve .PP When \f(CW\*(C`clear\*(C'\fR is called on a \fBPoint3D\fR object, our modifier method gets called as well. Unsurprisingly, the modifier is called \fIafter\fR the real method. .PP In this case, the real \f(CW\*(C`clear\*(C'\fR method is inherited from \fBPoint\fR. Our modifier method receives the same arguments as those passed to the modified method (just \f(CW$self\fR here). .PP Of course, using the \f(CW\*(C`after\*(C'\fR modifier is not the only way to accomplish this. This \fBis\fR Perl, right? You can get the same results with this code: .PP .Vb 5 \& sub clear { \& my $self = shift; \& $self\->SUPER::clear(); \& $self\->z(0); \& } .Ve .PP You could also use another Moose method modifier, \f(CW\*(C`override\*(C'\fR: .PP .Vb 5 \& override \*(Aqclear\*(Aq => sub { \& my $self = shift; \& super(); \& $self\->z(0); \& }; .Ve .PP The \f(CW\*(C`override\*(C'\fR modifier allows you to use the \f(CW\*(C`super\*(C'\fR keyword to dispatch to the superclass\*(Aqs method in a very Ruby\-ish style. .PP The choice of whether to use a method modifier, and which one to use, is often a question of style as much as functionality. .PP Since \fBPoint\fR inherits from Moose::Object, it will also inherit the default Moose::Object constructor: .PP .Vb 2 \& my $point1 = Point\->new(x => 5, y => 7); \& my $point2 = Point\->new({x => 5, y => 7}); \& \& my $point3d = Point3D\->new(x => 5, y => 42, z => \-5); .Ve .PP The \f(CW\*(C`new\*(C'\fR constructor accepts a named argument pair for each attribute defined by the class, which you can provide as a hash or hash reference. In this particular example, the attributes are required, and calling \f(CW\*(C`new\*(C'\fR without them will throw an error. .PP .Vb 1 \& my $point = Point\->new( x => 5 ); # no y, kaboom! .Ve .PP From here on, we can use \f(CW$point\fR and \f(CW$point3d\fR just as you would any other Perl 5 object. For a more detailed example of what can be done, you can refer to the \&\fIt/recipes/basics_point_attributesandsubclassing.t\fR test file. .SS "Moose Objects are Just Hashrefs" .IX Subsection "Moose Objects are Just Hashrefs" While this all may appear rather magical, it\*(Aqs important to realize that Moose objects are just hash references under the hood (3). For example, you could pass \f(CW$self\fR to \f(CW\*(C`Data::Dumper\*(C'\fR and you\*(Aqd get exactly what you\*(Aqd expect. .PP You could even poke around inside the object\*(Aqs data structure, but that is strongly discouraged. .PP The fact that Moose objects are hashrefs means it is easy to use Moose to extend non\-Moose classes, as long as they too are hash references. If you want to extend a non\-hashref class, check out \&\f(CW\*(C`MooseX::InsideOut\*(C'\fR. .SH CONCLUSION .IX Header "CONCLUSION" This recipe demonstrates some basic Moose concepts, attributes, subclassing, and a simple method modifier. .SH FOOTNOTES .IX Header "FOOTNOTES" .IP (1) 4 .IX Item "(1)" Moose provides a number of builtin type constraints, of which \f(CW\*(C`Int\*(C'\fR is one. For more information on the type constraint system, see Moose::Util::TypeConstraints. .IP (2) 4 .IX Item "(2)" The \f(CW\*(C`extends\*(C'\fR keyword supports multiple inheritance. Simply pass all of your superclasses to \f(CW\*(C`extends\*(C'\fR as a list: .Sp .Vb 1 \& extends \*(AqFoo\*(Aq, \*(AqBar\*(Aq, \*(AqBaz\*(Aq; .Ve .IP (3) 4 .IX Item "(3)" Moose supports using instance structures other than blessed hash references (such as glob references \- see MooseX::GlobRef). .SH "SEE ALSO" .IX Header "SEE ALSO" .IP "Method Modifiers" 4 .IX Item "Method Modifiers" The concept of method modifiers is directly ripped off from CLOS. A great explanation of them can be found by following this link. .Sp .SH AUTHORS .IX Header "AUTHORS" .IP \(bu 4 Stevan Little .IP \(bu 4 Dave Rolsky .IP \(bu 4 Jesse Luehrs .IP \(bu 4 Shawn M Moore .IP \(bu 4 יובל קוג\*(Aqמן (Yuval Kogman) .IP \(bu 4 Karen Etheridge .IP \(bu 4 Florian Ragwitz .IP \(bu 4 Hans Dieter Pearcey .IP \(bu 4 Chris Prather .IP \(bu 4 Matt S Trout .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2006 by Infinity Interactive, Inc. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.