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