=head1 NAME
-Moose::Cookbook::Recipe4
+Moose::Cookbook::Recipe4 - Subtypes, and modeling a simple B<Company> class hierarchy
=head1 SYNOPSIS
package Address;
- use strict;
- use warnings;
use Moose;
+ use Moose::Util::TypeConstraints;
use Locale::US;
use Regexp::Common 'zip';
has 'zip_code' => (is => 'rw', isa => 'USZipCode');
package Company;
- use strict;
- use warnings;
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 => subtype ArrayRef => where {
- ($_->isa('Employee') || return) for @$_; 1
- });
+ has 'employees' => (is => 'rw', isa => 'ArrayRef[Employee]');
sub BUILD {
my ($self, $params) = @_;
}
}
- sub get_employee_count { scalar @{(shift)->employees} }
+ after 'employees' => sub {
+ my ($self, $employees) = @_;
+ if (defined $employees) {
+ foreach my $employee (@{$employees}) {
+ $employee->company($self);
+ }
+ }
+ };
package Person;
- use strict;
- use warnings;
use Moose;
has 'first_name' => (is => 'rw', isa => 'Str', required => 1);
}
package Employee;
- use strict;
- use warnings;
use Moose;
extends 'Person';
my $self = shift;
super() . ', ' . $self->title
};
-
+
=head1 DESCRIPTION
In this recipe we introduce the C<subtype> keyword, and show
-how that can be useful for specifying specific type constraints
-without having to build an entire class to represent them. We
+how it can be useful for specifying type constraints
+without building an entire class to represent them. We
will also show how this feature can be used to leverage the
-usefulness of CPAN modules. In addition to this, we will also
-introduce another attribute option as well.
+usefulness of CPAN modules. In addition to this, we will
+introduce another attribute option.
-Lets first get into the C<subtype> features. In the B<Address>
-class we have defined two subtypes. The first C<subtype> uses
-the L<Locale::US> module, which provides two hashes which can be
-used to do existence checks for state names and their two letter
-state codes. It is a very simple, and very useful module, and
-perfect to use in a C<subtype> constraint.
+Let's first look at the C<subtype> feature. In the B<Address> class we have
+defined two subtypes. The first C<subtype> uses the L<Locale::US> module, which
+provides two hashes which can be used to perform existential checks for state
+names and their two letter state codes. It is a very simple and very useful
+module, and perfect for use in a C<subtype> constraint.
my $STATES = Locale::US->new;
subtype USState
Because we know that states will be passed to us as strings, we
can make C<USState> a subtype of the built-in type constraint
-C<Str>. This will assure that anything which is a C<USState> will
+C<Str>. This will ensure that anything which is a C<USState> will
also pass as a C<Str>. Next, we create a constraint specializer
using the C<where> keyword. The value being checked against in
the C<where> clause can be found in the C<$_> variable (1). Our
-constraint specializer will then look to see if the string given
+constraint specializer will then check whether the given string
is either a state name or a state code. If the string meets this
criteria, then the constraint will pass, otherwise it will fail.
We can now use this as we would any built-in constraint, like so:
C<USState> constraint, thereby only allowing valid state names or
state codes to be stored in the C<state> slot.
-The next C<subtype>, does pretty much the same thing using the
-L<Regexp::Common> module, and constrainting the C<zip_code> slot.
+The next C<subtype> does pretty much the same thing using the L<Regexp::Common>
+module, and is used as the constraint for the C<zip_code> slot.
subtype USZipCode
=> as Value
/^$RE{zip}{US}{-extended => 'allow'}$/
};
-Using subtypes can save a lot of un-needed abstraction by not
-requiring you to create many small classes for these relatively
-simple values. It also allows you to define these constraints
-and share them among many different classes (avoiding unneeded
-duplication) because type constraints are stored by string in a
-global registry and always accessible to C<has>.
+Using subtypes can save a lot of unnecessary abstraction by not requiring you to
+create many small classes for these relatively simple values. They also allow
+you to reuse the same constraints in a number of classes (thereby avoiding
+duplication), since all type constraints are stored in a global registry and
+always accessible to C<has>.
-With these two subtypes and some attributes, we pretty much define
-as much as we need for a basic B<Address> class. Next we define
+With these two subtypes and some attributes, we have defined
+as much as we need for a basic B<Address> class. Next, we define
a basic B<Company> class, which itself has an address. As we saw in
earlier recipes, we can use the C<Address> type constraint that
-Moose automatically created for us.
+Moose automatically created for us:
has 'address' => (is => 'rw', isa => 'Address');
-A company also needs a name, so we define that too.
+A company also needs a name, so we define that as well:
has 'name' => (is => 'rw', isa => 'Str', required => 1);
This option tells Moose that C<name> is a required parameter in
the B<Company> constructor, and that the C<name> accessor cannot
accept an undefined value for the slot. The result is that C<name>
-should always have a value.
+will always have a value.
+
+The next attribute option is not actually new, but a new variant
+of options we have already introduced:
+
+ has 'employees' => (is => 'rw', isa => 'ArrayRef[Employee]');
+
+Here, we are passing a more complex string to the C<isa> option, we
+are passing a container type constraint. Container type constraints
+can either be C<ArrayRef> or C<HashRef> with a contained type given
+inside the square brackets. This basically checks that all the values
+in the ARRAY ref are instances of the B<Employee> class.
+
+This will ensure that our employees will all be of the correct type. However,
+the B<Employee> object (which we will see in a moment) also maintains a
+reference to its associated B<Company>. In order to maintain this relationship
+(and preserve the referential integrity of our objects), we need to perform some
+processing of the employees over and above that of the type constraint check.
+This is accomplished in two places. First we need to be sure that any employees
+array passed to the constructor is properly initialized. For this we can use the
+C<BUILD> method (2):
+
+ sub BUILD {
+ my ($self, $params) = @_;
+ if ($params->{employees}) {
+ foreach my $employee (@{$params->{employees}}) {
+ $employee->company($self);
+ }
+ }
+ }
+
+The C<BUILD> method will be executed after the initial type constraint
+check, so we can simply perform a basic existential check on the C<employees>
+param here, and assume that if it does exist, it is both an ARRAY ref
+and contains I<only> instances of B<Employee>.
+
+The next aspect we need to address is the C<employees> read/write
+accessor (see the C<employees> attribute declaration above). This
+accessor will correctly check the type constraint, but we need to extend it
+with some additional processing. For this we use an C<after> method modifier,
+like so:
+
+ after 'employees' => sub {
+ my ($self, $employees) = @_;
+ if (defined $employees) {
+ foreach my $employee (@{$employees}) {
+ $employee->company($self);
+ }
+ }
+ };
+
+Again, as with the C<BUILD> method, we know that the type constraint
+check has already happened, so we can just check for defined-ness on the
+C<$employees> argument.
+
+At this point, our B<Company> class is complete. Next comes our B<Person>
+class and its subclass, the previously mentioned B<Employee> class.
+
+The B<Person> class should be obvious to you at this point. It has a few
+C<required> attributes, and the C<middle_initial> slot has an additional
+C<predicate> method (which we saw in the previous recipe with the
+B<BinaryTree> class).
+
+Next, the B<Employee> class, which should also be pretty obvious at this
+point. It requires a C<title>, and maintains a weakened reference to a
+B<Company> instance. The only new item, which we have seen before in
+examples, but never in the recipe itself, is the C<override> method
+modifier:
+
+ override 'full_name' => sub {
+ my $self = shift;
+ super() . ', ' . $self->title
+ };
+
+This just tells Moose that I am intentionally overriding the superclass
+C<full_name> method here, and adding the value of the C<title> slot at
+the end of the employee's full name.
+
+And that's about it.
+
+Once again, as with all the other recipes, you can go about using
+these classes like any other Perl 5 class. A more detailed example of
+usage can be found in F<t/004_recipe.t>.
+
+=head1 CONCLUSION
+
+This recipe was intentionally longer and more complex to illustrate both
+how easily Moose classes can interact (using class type constraints, etc.)
+and the sheer density of information and behaviors which Moose can pack
+into a relatively small amount of typing. Ponder for a moment how much
+more code a non-Moose plain old Perl 5 version of this recipe would have
+been (including all the type constraint checks, weak references, and so on).
+
+And of course, this recipe also introduced the C<subtype> keyword, and
+its usefulness within the Moose toolkit. In the next recipe we will
+focus more on subtypes, and introduce the idea of type coercion as well.
=head1 FOOTNOTES
the C<where> block as well, so it can also be accessed as C<$_[0]>
as well.
+=item (2)
+
+The C<BUILD> method is called by C<Moose::Object::BUILDALL>, which is
+called by C<Moose::Object::new>. C<BUILDALL> will climb the object
+inheritance graph and call the appropriate C<BUILD> methods in the
+correct order.
+
=back
=head1 AUTHOR
=head1 COPYRIGHT AND LICENSE
-Copyright 2006 by Infinity Interactive, Inc.
+Copyright 2006, 2007 by Infinity Interactive, Inc.
L<http://www.iinteractive.com>
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.
-=cut
\ No newline at end of file
+=cut