-
-
07 Nov 2021 03:41:58 UTC
- Distribution: Moose
- Source (raw)
- Browse (raw)
- Changes
- Homepage
- How to Contribute
- Repository
- Issues (71)
- Testers (2836 / 3 / 1)
- Kwalitee
Bus factor: 3- 92.11% Coverage
- License: perl_5
- Perl: v5.8.3
- Activity
24 month- Tools
- Download (881.54KB)
- MetaCPAN Explorer
- Permissions
- Subscribe to distribution
- Permalinks
- This version
- Latest version
and 142 contributors-
Stevan Little
-
Dave Rolsky
-
Jesse Luehrs
-
Shawn M Moore
-
יובל קוג'מן (Yuval Kogman)
-
Florian Ragwitz
-
Hans Dieter Pearcey
-
Chris Prather
-
Matt S Trout
-
Upasana Shukla
-
Graham Knop
-
Tomas Doran
-
Ricardo Signes
-
Guillermo Roditi
-
John Napiorkowski
-
Aankhen
-
Todd Hepler
-
Jonathan Rockway
-
Gerda Shank
-
Perlover
-
Shlomi Fish
-
Brad Bowman
-
Justin Hunter
-
Kent Fredric
-
Paul Driver
-
Anders Nor Berle
-
Brian Manning
-
gfx
-
Jay Hannah
-
Lars Dɪᴇᴄᴋᴏᴡ 迪拉斯
-
Leon Brocard
-
Olivier Mengué
-
Rafael Kitover
-
Christian Hansen
-
Cory Watson
-
Dagfinn Ilmari Mannsåker
-
Paul Jamieson Fenwick
-
Robert Buels
-
Dan Dascalescu
-
Marcel Grünauer
-
Scott McWhirter
-
Ævar Arnfjörð Bjarmason
-
Daisuke Maki (lestrrat)
-
Dylan William Hardison
-
Patrick Donelan
-
Stefan O'Rear
-
Tokuhiro Matsuno
-
Ash Berlin
-
Chris Weyl
-
Eric Wilhelm
-
Jess Robinson
-
Marc Mims
-
Marcus Ramberg
-
Mark Allen
-
Mateu X Hunter
-
matthof
-
Robert 'phaylon' Sedlacek
-
Zachary Lome
-
Aran Clary Deltac
-
Chip
-
Christopher J. Madsen
-
Curtis Jewell
-
Evan Carroll
-
Mark A. Stratman
-
Mark Fowler
-
Matthew Horsfall
-
mauke
-
Michael LaGrasta
-
Michael Rykov
-
Mike Whitaker
-
Moritz Onken
-
Nelo Onyiah
-
Nick Perez
-
Robert Boone
-
Robin V
-
rodrigolive
-
shelling
-
Thomas Sibley
-
Tom Hukins
-
Wallace Reis
-
Aaron Cohen
-
Adam J. Foxson
-
Adam Kennedy
-
Andy Jack
-
Anirvan Chatterjee
-
Ansgar Burchardt
-
A. Sinan Unur
-
Ben Hutton
-
Brendan Byrd
-
Chad Granum
-
Chankey Pathak
-
Chia-liang Kao
-
Christian Walde (Mithaldu)
-
chromatic
-
Dann
-
Dave Romano
-
David Leadbeater
-
David Steinbrunner
-
dmaestro
-
E. Choroba
-
franck cuny
-
Frew Schmidt
-
gregor herrmann
-
hakim
-
Henry Van Styn
-
James Marca
-
Jason May
-
Jay Allen
-
Jay Kuri
-
Jeff Bisbee
-
Jens Berthold
-
Jesse Vincent
-
joel
-
John Douglas Porter
-
John Goulah
-
Justin DeVuyst
-
Kang-min Liu
-
Leon Timmermans
-
Mark O Grady
-
Matt Kraai
-
Michael Schout
-
Nathan Gray
-
Olaf Alders
-
Olof Johansson
-
Paul Cochrane
-
Paweł Murias
-
Pedro Melo
-
Peter Shangov
-
Philippe Bruhat (BooK)
-
Philipp Gortan
-
Phillip Smith
-
Piotr Roszatycki
-
pktm
-
rouzier
-
Sam Vilain
-
sherrardb
-
Simon Reinhardt
-
sue spence
-
Tuomas Jormola
-
wickline
-
Yanick Champoux
-
Zoffix Znet
- Dependencies
- Carp
- Class::Load
- Class::Load::XS
- Data::OptList
- Devel::GlobalDestruction
- Devel::OverloadInfo
- Devel::StackTrace
- Dist::CheckConflicts
- Eval::Closure
- List::Util
- MRO::Compat
- Module::Runtime
- Module::Runtime::Conflicts
- Package::DeprecationManager
- Package::Stash
- Package::Stash::XS
- Params::Util
- Scalar::Util
- Sub::Exporter
- Sub::Util
- Try::Tiny
- parent
- strict
- warnings
- Reverse dependencies
- CPAN Testers List
- Dependency graph
NAME
Moose::Cookbook::Basics::Company_Subtypes - Demonstrates the use of subtypes and how to model classes related to companies, people, employees, etc.
VERSION
version 2.2201
SYNOPSIS
package Address; use Moose; use Moose::Util::TypeConstraints; use Locale::US; use Regexp::Common 'zip'; my $STATES = Locale::US->new; subtype 'USState' => as Str => where { ( exists $STATES->{code2state}{ uc($_) } || exists $STATES->{state2code}{ uc($_) } ); }; subtype 'USZipCode' => as Value => where { /^$RE{zip}{US}{-extended => 'allow'}$/; }; has 'street' => ( is => 'rw', isa => 'Str' ); has 'city' => ( is => 'rw', isa => 'Str' ); has 'state' => ( is => 'rw', isa => 'USState' ); has 'zip_code' => ( is => 'rw', isa => 'USZipCode' ); package Company; use Moose; use Moose::Util::TypeConstraints; has 'name' => ( is => 'rw', isa => 'Str', required => 1 ); has 'address' => ( is => 'rw', isa => 'Address' ); has 'employees' => ( is => 'rw', isa => 'ArrayRef[Employee]', default => sub { [] }, ); sub BUILD { my ( $self, $params ) = @_; foreach my $employee ( @{ $self->employees } ) { $employee->employer($self); } } after 'employees' => sub { my ( $self, $employees ) = @_; return unless $employees; foreach my $employee ( @$employees ) { $employee->employer($self); } }; package Person; use Moose; has 'first_name' => ( is => 'rw', isa => 'Str', required => 1 ); has 'last_name' => ( is => 'rw', isa => 'Str', required => 1 ); has 'middle_initial' => ( is => 'rw', isa => 'Str', predicate => 'has_middle_initial' ); has 'address' => ( is => 'rw', isa => 'Address' ); sub full_name { my $self = shift; return $self->first_name . ( $self->has_middle_initial ? ' ' . $self->middle_initial . '. ' : ' ' ) . $self->last_name; } package Employee; use Moose; extends 'Person'; has 'title' => ( is => 'rw', isa => 'Str', required => 1 ); has 'employer' => ( is => 'rw', isa => 'Company', weak_ref => 1 ); override 'full_name' => sub { my $self = shift; super() . ', ' . $self->title; };
DESCRIPTION
This recipe introduces the
subtype
sugar function from Moose::Util::TypeConstraints. Thesubtype
function lets you declaratively create type constraints without building an entire class.In the recipe we also make use of Locale::US and Regexp::Common to build constraints, showing how constraints can make use of existing CPAN tools for data validation.
Finally, we introduce the
required
attribute option.In the
Address
class we define two subtypes. The first uses the Locale::US module to check the validity of a state. It accepts either a state abbreviation or full name.A state will be passed in as a string, so we make our
USState
type a subtype of Moose's builtinStr
type. This is done using theas
sugar. The actual constraint is defined usingwhere
. This function accepts a single subroutine reference. That subroutine will be called with the value to be checked in$_
(1). It is expected to return a true or false value indicating whether the value is valid for the type.We can now use the
USState
type just like Moose's builtin types:has 'state' => ( is => 'rw', isa => 'USState' );
When the
state
attribute is set, the value is checked against theUSState
constraint. If the value is not valid, an exception will be thrown.The next
subtype
,USZipCode
, uses Regexp::Common. Regexp::Common includes a regex for validating US zip codes. We use this constraint for thezip_code
attribute.subtype 'USZipCode' => as Value => where { /^$RE{zip}{US}{-extended => 'allow'}$/; };
Using a subtype instead of requiring a class for each type greatly simplifies the code. We don't really need a class for these types, as they're just strings, but we do want to ensure that they're valid.
The type constraints we created are reusable. Type constraints are stored by name in a global registry, which means that we can refer to them in other classes. Because the registry is global, we do recommend that you use some sort of namespacing in real applications, like
MyApp::Type::USState
(just as you would do with class names).These two subtypes allow us to define a simple
Address
class.Then we define our
Company
class, which has an address. As we saw in earlier recipes, Moose automatically creates a type constraint for each our classes, so we can use that for theCompany
class'saddress
attribute:has 'address' => ( is => 'rw', isa => 'Address' );
A company also needs a name:
has 'name' => ( is => 'rw', isa => 'Str', required => 1 );
This introduces a new attribute option,
required
. If an attribute is required, then it must be passed to the class's constructor, or an exception will be thrown. It's important to understand that arequired
attribute can still be false orundef
, if its type constraint allows that.The next attribute,
employees
, uses a parameterized type constraint:has 'employees' => ( is => 'rw', isa => 'ArrayRef[Employee]' default => sub { [] }, );
This constraint says that
employees
must be an array reference where each element of the array is anEmployee
object. It's worth noting that an empty array reference also satisfies this constraint, such as the value given as the default here.Parameterizable type constraints (or "container types"), such as
ArrayRef[`a]
, can be made more specific with a type parameter. In fact, we can arbitrarily nest these types, producing something likeHashRef[ArrayRef[Int]]
. However, you can also just use the type by itself, soArrayRef
is legal. (2)If you jump down to the definition of the
Employee
class, you will see that it has anemployer
attribute.When we set the
employees
for aCompany
we want to make sure that each of these employee objects refers back to the rightCompany
in itsemployer
attribute.To do that, we need to hook into object construction. Moose lets us do this by writing a
BUILD
method in our class. When your class defines aBUILD
method, it will be called by the constructor immediately after object construction, but before the object is returned to the caller. Note that allBUILD
methods in your class hierarchy will be called automatically; there is no need to (and you should not) call the superclassBUILD
method.The
Company
class uses theBUILD
method to ensure that each employee of a company has the properCompany
object in itsemployer
attribute:sub BUILD { my ( $self, $params ) = @_; foreach my $employee ( @{ $self->employees } ) { $employee->employer($self); } }
The
BUILD
method is executed after type constraints are checked, so it is safe to assume that if$self->employees
has a value, it will be an array reference, and that the elements of that array reference will beEmployee
objects.We also want to make sure that whenever the
employees
attribute for aCompany
is changed, we also update theemployer
for each employee.To do this we can use an
after
modifier:after 'employees' => sub { my ( $self, $employees ) = @_; return unless $employees; foreach my $employee ( @$employees ) { $employee->employer($self); } };
Again, as with the
BUILD
method, we know that the type constraint check has already happened, so we know that if$employees
is defined it will contain an array reference ofEmployee
objects.Note that
employees
is a read/write accessor, so we must return early if it's called as a reader.The Person class does not really demonstrate anything new. It has several
required
attributes. It also has apredicate
method, which we first used in Moose::Cookbook::Basics::BinaryTree_AttributeFeatures.The only new feature in the
Employee
class is theoverride
method modifier:override 'full_name' => sub { my $self = shift; super() . ', ' . $self->title; };
This is just a sugary alternative to Perl's built in
SUPER::
feature. However, there is one difference. You cannot pass any arguments tosuper
. Instead, Moose simply passes the same parameters that were passed to the method.A more detailed example of usage can be found in t/recipes/basics_company_subtypes.t.
CONCLUSION
This recipe was intentionally longer and more complex. It illustrates how Moose classes can be used together with type constraints, as well as the density of information that you can get out of a small amount of typing when using Moose.
This recipe also introduced the
subtype
function, therequired
attribute, and theoverride
method modifier.We will revisit type constraints in future recipes, and cover type coercion as well.
FOOTNOTES
- (1)
-
The value being checked is also passed as the first argument to the
where
block, so it can be accessed as$_[0]
. - (2)
-
Note that
ArrayRef[]
will not work. Moose will not parse this as a container type, and instead you will have a new type named "ArrayRef[]", which doesn't make any sense.
AUTHORS
Stevan Little <stevan@cpan.org>
Dave Rolsky <autarch@urth.org>
Jesse Luehrs <doy@cpan.org>
Shawn M Moore <sartak@cpan.org>
יובל קוג'מן (Yuval Kogman) <nothingmuch@woobling.org>
Karen Etheridge <ether@cpan.org>
Florian Ragwitz <rafl@debian.org>
Hans Dieter Pearcey <hdp@cpan.org>
Chris Prather <chris@prather.org>
Matt S Trout <mstrout@cpan.org>
COPYRIGHT AND LICENSE
This software is copyright (c) 2006 by Infinity Interactive, Inc.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
Module Install Instructions
To install Moose, copy and paste the appropriate command in to your terminal.
cpanm Moose
perl -MCPAN -e shell install Moose
For more information on module installation, please visit the detailed CPAN module installation guide.