- changed snack description to better describe how Moose works
[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 }
26 } # sub BUILD
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
1ae6c427 77=head2 BUILD method is run only if it is defined in the object
78
79If your object does not have a C<BUILD> method, then Moose will skip trying to
80run it.
81
defceb0c 82=head2 What is 'BUILDALL'?
83
84(Taken from L<Moose::Object>) The C<BUILDALL> method will call every BUILD
85method in the inheritance hierarchy, and pass it a hash-ref of the the %params
1ae6c427 86passed to the C<new()> method.
defceb0c 87
88=head1 SEE ALSO
89
90=over 4
91
92=item L<Moose::Object> - The base object for Moose (BUILDALL)
93
1ae6c427 94=item L<Moose::Cookbook::FAQ> - Frequently asked questions about Moose (How do I write custom constructors with Moose?)
defceb0c 95
1ae6c427 96=item L<Moose::Cookbook::Recipe4> - Subtypes, and modeling a simple Company class heirarchy (Example usage of BUILD in action)
defceb0c 97
1ae6c427 98=item L<Moose::Cookbook::WTF> - For when things go wrong with Moose ('Roles' section describes BUILD/BUILDALL)
defceb0c 99
100=back
101
102=head1 AUTHOR
103
104Brian Manning <elspicyjack at gmail dot com>
105
106=head1 COPYRIGHT AND LICENSE
107
1ae6c427 108Copyright (c)2008 by Infinity Interactive, Inc.
defceb0c 109
110This documentation is free software; you can redistribute it and/or modify
111it under the same terms as Perl itself.
112
113=cut