Commit | Line | Data |
daa0fd7d |
1 | package Moose::Cookbook::Basics::Recipe10; |
c2a0627f |
2 | |
daa0fd7d |
3 | # ABSTRACT: Using BUILDARGS and BUILD to hook into object construction |
4 | |
5 | __END__ |
c2a0627f |
6 | |
c2a0627f |
7 | |
daa0fd7d |
8 | =pod |
c2a0627f |
9 | |
10 | =head1 SYNOPSIS |
11 | |
1f476b5f |
12 | package Person; |
c765b254 |
13 | |
1f476b5f |
14 | has 'ssn' => ( |
15 | is => 'ro', |
16 | isa => 'Str', |
17 | predicate => 'has_ssn', |
18 | ); |
c765b254 |
19 | |
1f476b5f |
20 | has 'country_of_residence' => ( |
21 | is => 'ro', |
22 | isa => 'Str', |
23 | default => 'usa' |
24 | ); |
c765b254 |
25 | |
1f476b5f |
26 | has 'first_name' => ( |
27 | is => 'ro', |
28 | isa => 'Str', |
29 | ); |
c765b254 |
30 | |
1f476b5f |
31 | has 'last_name' => ( |
32 | is => 'ro', |
33 | isa => 'Str', |
34 | ); |
c765b254 |
35 | |
c30bceb8 |
36 | around BUILDARGS => sub { |
37 | my $orig = shift; |
1f476b5f |
38 | my $class = shift; |
c765b254 |
39 | |
1f476b5f |
40 | if ( @_ == 1 && ! ref $_[0] ) { |
c30bceb8 |
41 | return $class->$orig(ssn => $_[0]); |
1f476b5f |
42 | } |
43 | else { |
c30bceb8 |
44 | return $class->$orig(@_); |
1f476b5f |
45 | } |
c30bceb8 |
46 | }; |
c2a0627f |
47 | |
1f476b5f |
48 | sub BUILD { |
49 | my $self = shift; |
c765b254 |
50 | |
1f476b5f |
51 | if ( $self->country_of_residence eq 'usa' ) { |
52 | die 'Cannot create a Person who lives in the USA without an ssn.' |
53 | unless $self->has_ssn; |
54 | } |
c2a0627f |
55 | } |
56 | |
1f476b5f |
57 | =head1 DESCRIPTION |
c2a0627f |
58 | |
1f476b5f |
59 | This recipe demonstrates the use of C<BUILDARGS> and C<BUILD>. By |
60 | defining these methods, we can hook into the object construction |
61 | process without overriding C<new>. |
c765b254 |
62 | |
1f476b5f |
63 | The C<BUILDARGS> method is called I<before> an object has been |
64 | created. It is called as a class method, and receives all of the |
65 | parameters passed to the C<new> method. It is expected to do something |
66 | with these arguments and return a hash reference. The keys of the hash |
67 | must be attribute C<init_arg>s. |
c765b254 |
68 | |
1f476b5f |
69 | The primary purpose of C<BUILDARGS> is to allow a class to accept |
70 | something other than named arguments. In the case of our C<Person> |
71 | class, we are allowing it to be called with a single argument, a |
72 | social security number: |
c765b254 |
73 | |
1f476b5f |
74 | my $person = Person->new('123-45-6789'); |
c765b254 |
75 | |
1f476b5f |
76 | The key part of our C<BUILDARGS> is this conditional: |
c765b254 |
77 | |
1f476b5f |
78 | if ( @_ == 1 && ! ref $_[0] ) { |
c30bceb8 |
79 | return $class->$orig(ssn => $_[0]); |
1f476b5f |
80 | } |
c2a0627f |
81 | |
1f476b5f |
82 | By default, Moose constructors accept a list of key-value pairs, or a |
83 | hash reference. We need to make sure that C<$_[0]> is not a reference |
84 | before assuming it is a social security number. |
c2a0627f |
85 | |
c30bceb8 |
86 | We call the original C<BUILDARGS> method to handle all the other |
1f476b5f |
87 | cases. You should always do this in your own C<BUILDARGS> methods, |
88 | since L<Moose::Object> provides its own C<BUILDARGS> method that |
89 | handles hash references and a list of key-value pairs. |
c2a0627f |
90 | |
1f476b5f |
91 | The C<BUILD> method is called I<after> the object is constructed, but |
92 | before it is returned to the caller. The C<BUILD> method provides an |
93 | opportunity to check the object state as a whole. This is a good place |
94 | to put logic that cannot be expressed as a type constraint on a single |
95 | attribute. |
c2a0627f |
96 | |
1f476b5f |
97 | In the C<Person> class, we need to check the relationship between two |
98 | attributes, C<ssn> and C<country_of_residence>. We throw an exception |
99 | if the object is not logically consistent. |
c765b254 |
100 | |
1f476b5f |
101 | =head1 MORE CONSIDERATIONS |
c765b254 |
102 | |
1f476b5f |
103 | This recipe is made significantly simpler because all of the |
104 | attributes are read-only. If the C<country_of_residence> attribute |
105 | were settable, we would need to check that a Person had an C<ssn> if |
106 | the new country was C<usa>. This could be done with a C<before> |
107 | modifier. |
c2a0627f |
108 | |
109 | =head1 CONCLUSION |
110 | |
1f476b5f |
111 | We have repeatedly discouraged overriding C<new> in Moose |
112 | classes. This recipe shows how you can use C<BUILDARGS> and C<BUILD> |
113 | to hook into object construction without overriding C<new> |
c2a0627f |
114 | |
1f476b5f |
115 | The C<BUILDARGS> method lets us expand on Moose's built-in parameter |
116 | handling for constructors. The C<BUILD> method lets us implement |
117 | logical constraints across the whole object after it is created. |
c2a0627f |
118 | |
1f476b5f |
119 | =cut |