=pod

=head1 NAME

Moose::Cookbook::Snack::BUILD - Overriding the I<new()> method to customize
the behaivor of Moose object creation

=head1 SYNOPSIS

    package Build::Demo;
    use Moose; 

    has 'example_file' => ( is => 'rw', required => 1);

    sub BUILD {
        my $self = shift;
        # create the object only if the file does exist
        if ( -e $self->example_file ) {
            return $self;
        } 
        else {
            die('ERROR: file _' . $self->example_file . '_ does not exist');
        } 
    } # sub BUILD 

    package main;
    use Moose;
    
    # '$0' is the name of this script, set automatically by Perl
    # this works
    my $first_test = Build::Demo->new( example_file => $0 );
    # this should fail (unless there's a file named 'foo'
    # in the current directory)
    my $second_test = Build::Demo->new( example_file => 'foo' );

=head1 DESCRIPTION

The C<BUILD()> method allows you to write your own custom constructors for
your Moose objects. 

=head2 Creating new objects in Perl and Moose

By convention, most objects in Perl are created by calling a C<new()> method
that they have created:

    package My::Perl::Class;

    sub new {
        # object initialization code goes here...
    } 

    package main;
    my $object = My::Perl::Class->new();

Moose is no different in this respect.  However, since Moose handles the
C<new()> method for you, how do you change the default behaivor of the
C<new()> method in Moose?  This is what the C<BUILD()> method was designed
for.

    package My::Moose::Class;

    sub BUILD {
        # object initialization code goes here...
    }

    package main;
    my $object = My::Moose::Class->new();

=head2 Why would you want a custom constructor?

If your object needs to verify some behaivor or internal state before it is
created, a good time to do that is when the object is being created.  Why
waste resources (CPU, memory) on objects that won't work because of missing
resources?

=head2 What is 'BUILDALL'?

(Taken from L<Moose::Object>)  The C<BUILDALL> method will call every BUILD
method in the inheritance hierarchy, and pass it a hash-ref of the the %params
passed to new.

=head1 SEE ALSO

=over 4

=item L<Moose::Object> - The base object for Moose (BUILDALL) 

=item L<Moose::Cookbook::FAQ> - Frequently asked questions about Moose (How do
I write custom constructors with Moose?)

=item L<Moose::Cookbook::Recipe4> - Subtypes, and modeling a simple Company
class heirarchy (Example usage of BUILD in action)

=item L<Moose::Cookbook::WTF> - For when things go wrong with Moose ('Roles'
ѕection describes BUILD/BUILDALL)



The L<Moose::Cookbook::WTF> section entitled B<Roles> for more info about how
the BUILD/BUILDALL methods work.

=back

=head1 AUTHOR

Brian Manning <elspicyjack at gmail dot com>

=head1 COPYRIGHT AND LICENSE

Copyright (c)2008 by Brian Manning

This documentation is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.

=cut