Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Moose::Cookbook::BasicUseroContributedePerlokbook::Basics::Company_Subtypes(3)

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.2013

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. The "subtype" 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 builtin "Str"	type. This is done using the "as"
       sugar. The actual constraint is defined using "where". 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 the
       "USState" 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 the "zip_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 the "Company" class's "address"
       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 a
       "required" attribute can	still be false or "undef", 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 an "Employee" 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 like
       "HashRef[ArrayRef[Int]]". However, you can also just use	the type by
       itself, so "ArrayRef" is	legal. (2)

       If you jump down	to the definition of the "Employee" class, you will
       see that	it has an "employer" attribute.

       When we set the "employees" for a "Company" we want to make sure	that
       each of these employee objects refers back to the right "Company" in
       its "employer" 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
       a "BUILD" method, it will be called by the constructor immediately
       after object construction, but before the object	is returned to the
       caller. Note that all "BUILD" methods in	your class hierarchy will be
       called automatically; there is no need to (and you should not) call the
       superclass "BUILD" method.

       The "Company" class uses	the "BUILD" method to ensure that each
       employee	of a company has the proper "Company" object in	its "employer"
       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
       be "Employee" objects.

       We also want to make sure that whenever the "employees" attribute for a
       "Company" is changed, we	also update the	"employer" 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 of "Employee" 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 a "predicate"	method,	which
       we first	used in	Moose::Cookbook::Basics::BinaryTree_AttributeFeatures.

       The only	new feature in the "Employee" class is the "override" 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 to
       "super".	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, the "required"
       attribute, and the "override" 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
       o   Stevan Little <stevan.little@iinteractive.com>

       o   Dave	Rolsky <autarch@urth.org>

       o   Jesse Luehrs	<doy@tozt.net>

       o   Shawn M Moore <code@sartak.org>

       o   xxxx	x<section>xx'xx	(Yuval Kogman) <nothingmuch@woobling.org>

       o   Karen Etheridge <ether@cpan.org>

       o   Florian Ragwitz <rafl@debian.org>

       o   Hans	Dieter Pearcey <hdp@weftsoar.net>

       o   Chris Prather <chris@prather.org>

       o   Matt	S Trout	<mst@shadowcat.co.uk>

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.

perl v5.32.0			  Moose::Cookbook::Basics::Company_Subtypes(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | CONCLUSION | FOOTNOTES | AUTHORS | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Moose::Cookbook::Basics::Company_Subtypes&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help