6 Moose::Cookbook::Basics::Recipe10 - Using BUILDARGS and BUILD to hook into object construction
15 predicate => 'has_ssn',
18 has 'country_of_residence' => (
37 if ( @_ == 1 && ! ref $_[0] ) {
38 return { ssn => $_[0] };
41 return $class->SUPER::BUILDARGS(@_);
48 if ( $self->country_of_residence eq 'usa' ) {
49 die 'Cannot create a Person who lives in the USA without an ssn.'
50 unless $self->has_ssn;
56 This recipe demonstrates the use of C<BUILDARGS> and C<BUILD>. By
57 defining these methods, we can hook into the object construction
58 process without overriding C<new>.
60 The C<BUILDARGS> method is called I<before> an object has been
61 created. It is called as a class method, and receives all of the
62 parameters passed to the C<new> method. It is expected to do something
63 with these arguments and return a hash reference. The keys of the hash
64 must be attribute C<init_arg>s.
66 The primary purpose of C<BUILDARGS> is to allow a class to accept
67 something other than named arguments. In the case of our C<Person>
68 class, we are allowing it to be called with a single argument, a
69 social security number:
71 my $person = Person->new('123-45-6789');
73 The key part of our C<BUILDARGS> is this conditional:
75 if ( @_ == 1 && ! ref $_[0] ) {
76 return { ssn => $_[0] };
79 By default, Moose constructors accept a list of key-value pairs, or a
80 hash reference. We need to make sure that C<$_[0]> is not a reference
81 before assuming it is a social security number.
83 We call C<< $class->SUPER::BUILDARGS(@_) >> to handle all the other
84 cases. You should always do this in your own C<BUILDARGS> methods,
85 since L<Moose::Object> provides its own C<BUILDARGS> method that
86 handles hash references and a list of key-value pairs.
88 The C<BUILD> method is called I<after> the object is constructed, but
89 before it is returned to the caller. The C<BUILD> method provides an
90 opportunity to check the object state as a whole. This is a good place
91 to put logic that cannot be expressed as a type constraint on a single
94 In the C<Person> class, we need to check the relationship between two
95 attributes, C<ssn> and C<country_of_residence>. We throw an exception
96 if the object is not logically consistent.
98 =head1 MORE CONSIDERATIONS
100 This recipe is made significantly simpler because all of the
101 attributes are read-only. If the C<country_of_residence> attribute
102 were settable, we would need to check that a Person had an C<ssn> if
103 the new country was C<usa>. This could be done with a C<before>
108 We have repeatedly discouraged overriding C<new> in Moose
109 classes. This recipe shows how you can use C<BUILDARGS> and C<BUILD>
110 to hook into object construction without overriding C<new>
112 The C<BUILDARGS> method lets us expand on Moose's built-in parameter
113 handling for constructors. The C<BUILD> method lets us implement
114 logical constraints across the whole object after it is created.
118 Dave Rolsky E<lt>autarch@urth.orgE<gt>
120 =head1 COPYRIGHT AND LICENSE
122 Copyright 2006-2009 by Infinity Interactive, Inc.
124 L<http://www.iinteractive.com>
126 This library is free software; you can redistribute it and/or modify
127 it under the same terms as Perl itself.