lib/Moose/Cookbook/Snack/BUILD.pod

   1
   2 =pod
   3
   4 =head1 NAME
   5
   6 Moose::Cookbook::Snack::BUILD - Overriding the I<new()> method to customize
   7 the behaivor of Moose object creation
   8
   9 =head1 SYNOPSIS
  10
  11     package Build::Demo;
  12     use Moose;
  13
  14     has 'example_file' => ( is => 'rw', required => 1);
  15
  16     sub BUILD {
  17         my $self = shift;
  18         # create the object only if the file does exist
  19         if ( -e $self->example_file ) {
  20             return $self;
  21         }
  22         else {
  23             die('ERROR: file _' . $self->example_file . '_ does not exist');
  24         }
  25     } # sub BUILD
  26
  27     package main;
  28     use Moose;
  29
  30     # '$0' is the name of this script, set automatically by Perl
  31     # this works
  32     my $first_test = Build::Demo->new( example_file => $0 );
  33     # this should fail (unless there's a file named 'foo'
  34     # in the current directory)
  35     my $second_test = Build::Demo->new( example_file => 'foo' );
  36
  37 =head1 DESCRIPTION
  38
  39 The C<BUILD()> method allows you to write your own custom constructors for
  40 your Moose objects.
  41
  42 =head2 Creating new objects in Perl and Moose
  43
  44 By convention, most objects in Perl are created by calling a C<new()> method
  45 that they have created:
  46
  47     package My::Perl::Class;
  48
  49     sub new {
  50         # object initialization code goes here...
  51     }
  52
  53     package main;
  54     my $object = My::Perl::Class->new();
  55
  56 Moose is no different in this respect.  However, since Moose handles the
  57 C<new()> method for you, how do you change the default behaivor of the
  58 C<new()> method in Moose?  This is what the C<BUILD()> method was designed
  59 for.
  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
  72 If your object needs to verify some behaivor or internal state before it is
  73 created, a good time to do that is when the object is being created.  Why
  74 waste resources (CPU, memory) on objects that won't work because of missing
  75 resources?
  76
  77 =head2 What is 'BUILDALL'?
  78
  79 (Taken from L<Moose::Object>)  The C<BUILDALL> method will call every BUILD
  80 method in the inheritance hierarchy, and pass it a hash-ref of the the %params
  81 passed to new.
  82
  83 =head1 SEE ALSO
  84
  85 =over 4
  86
  87 =item L<Moose::Object> - The base object for Moose (BUILDALL)
  88
  89 =item L<Moose::Cookbook::FAQ> - Frequently asked questions about Moose (How do
  90 I write custom constructors with Moose?)
  91
  92 =item L<Moose::Cookbook::Recipe4> - Subtypes, and modeling a simple Company
  93 class heirarchy (Example usage of BUILD in action)
  94
  95 =item L<Moose::Cookbook::WTF> - For when things go wrong with Moose ('Roles'
  96 ѕection describes BUILD/BUILDALL)
  97
  98
  99
 100 The L<Moose::Cookbook::WTF> section entitled B<Roles> for more info about how
 101 the BUILD/BUILDALL methods work.
 102
 103 =back
 104
 105 =head1 AUTHOR
 106
 107 Brian Manning <elspicyjack at gmail dot com>
 108
 109 =head1 COPYRIGHT AND LICENSE
 110
 111 Copyright (c)2008 by Brian Manning
 112
 113 This documentation is free software; you can redistribute it and/or modify
 114 it under the same terms as Perl itself.
 115
 116 =cut