bah
[gitmo/Moose.git] / lib / Moose / Cookbook / Snack / BUILD.pod
CommitLineData
defceb0c 1
2=pod
3
4=head1 NAME
5
1ae6c427 6Moose::Cookbook::Snack::BUILD - Custom initialization methods for Moose objects
defceb0c 7
8=head1 SYNOPSIS
9
10 package Build::Demo;
11 use Moose;
12
1ae6c427 13 # once the object has been created, don't allow
14 # changes to 'example_file'
15 has 'example_file' => (is => 'ro', required => 1);
defceb0c 16
17 sub BUILD {
18 my $self = shift;
1ae6c427 19 # create the object only if the 'example_file' exists
20 if (-e $self->example_file) {
defceb0c 21 return $self;
22 }
23 else {
24 die('ERROR: file _' . $self->example_file . '_ does not exist');
25 }
1b55c340 26 }
defceb0c 27
28 package main;
29 use Moose;
30
1ae6c427 31 # the name of this script, which works
32 my $first_test = Build::Demo->new(example_file => $0);
defceb0c 33 # this should fail (unless there's a file named 'foo'
34 # in the current directory)
1ae6c427 35 my $second_test = Build::Demo->new(example_file => 'foo');
defceb0c 36
37=head1 DESCRIPTION
38
1ae6c427 39The C<BUILD()> method allows you to write your own initialization methods for
defceb0c 40your Moose objects.
41
42=head2 Creating new objects in Perl and Moose
43
44By convention, most objects in Perl are created by calling a C<new()> method
1ae6c427 45inside that object:
defceb0c 46
47 package My::Perl::Class;
48
49 sub new {
1ae6c427 50 # object blessing and initialization code goes here...
defceb0c 51 }
52
53 package main;
54 my $object = My::Perl::Class->new();
55
56Moose is no different in this respect. However, since Moose handles the
57C<new()> method for you, how do you change the default behaivor of the
58C<new()> method in Moose? This is what the C<BUILD()> method was designed
59for.
60
61 package My::Moose::Class;
62
63 sub BUILD {
64 # object initialization code goes here...
65 }
66
67 package main;
68 my $object = My::Moose::Class->new();
69
70=head2 Why would you want a custom constructor?
71
72If your object needs to verify some behaivor or internal state before it is
73created, a good time to do that is when the object is being created. Why
74waste resources (CPU, memory) on objects that won't work because of missing
75resources?
76
80cca4cf 77=head2 When would you use an Moose type constraint instead of a custom constructor?
78
79Using type constraints via L<Moose::Util::TypeConstraints>, you can verify
80simple relationships when an object is created:
81
82 package Triangle;
83 use Moose;
84
85 has
86
87You would want to use the C<BUILD()> method in order to verify more complex
88relationships:
89
90 package IsoscelesTriangle;
91 use Moose;
92
1ae6c427 93=head2 BUILD method is run only if it is defined in the object
94
95If your object does not have a C<BUILD> method, then Moose will skip trying to
96run it.
97
defceb0c 98=head2 What is 'BUILDALL'?
99
100(Taken from L<Moose::Object>) The C<BUILDALL> method will call every BUILD
1b55c340 101method in the inheritance hierarchy, and pass it a hash-ref of the the
102C<%params> passed to the C<new()> method.
defceb0c 103
104=head1 SEE ALSO
105
106=over 4
107
108=item L<Moose::Object> - The base object for Moose (BUILDALL)
109
1b55c340 110=item L<Moose::Cookbook::FAQ> - Frequently asked questions about Moose
111(How do I write custom constructors with Moose?)
defceb0c 112
1b55c340 113=item L<Moose::Cookbook::Recipe4> - Subtypes, and modeling a simple
114Company class heirarchy (Example usage of BUILD in action)
defceb0c 115
1b55c340 116=item L<Moose::Cookbook::WTF> - For when things go wrong with Moose
117('Roles' section describes BUILD/BUILDALL)
defceb0c 118
119=back
120
121=head1 AUTHOR
122
123Brian Manning <elspicyjack at gmail dot com>
124
125=head1 COPYRIGHT AND LICENSE
126
1b55c340 127Copyright 2006-2008 by Infinity Interactive, Inc.
128
129L<http://www.iinteractive.com>
defceb0c 130
1b55c340 131This library is free software; you can redistribute it and/or modify
defceb0c 132it under the same terms as Perl itself.
133
134=cut