lib/Moose/Cookbook/Snack/BUILD.pod

   1
   2 =pod
   3
   4 =head1 NAME
   5
   6 Moose::Cookbook::Snack::BUILD - Custom initialization methods for Moose objects
   7
   8 =head1 SYNOPSIS
   9
  10     package Build::Demo;
  11     use Moose;
  12
  13     # once the object has been created, don't allow
  14     # changes to 'example_file'
  15     has 'example_file' => (is => 'ro', required => 1);
  16
  17     sub BUILD {
  18         my $self = shift;
  19         # create the object only if the 'example_file' exists
  20         if (-e $self->example_file) {
  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
  31     # the name of this script, which 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 initialization methods 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 inside that object:
  46
  47     package My::Perl::Class;
  48
  49     sub new {
  50         # object blessing and 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 BUILD method is run only if it is defined in the object
  78
  79 If your object does not have a C<BUILD> method, then Moose will skip trying to
  80 run it.
  81
  82 =head2 What is 'BUILDALL'?
  83
  84 (Taken from L<Moose::Object>)  The C<BUILDALL> method will call every BUILD
  85 method in the inheritance hierarchy, and pass it a hash-ref of the the %params
  86 passed to the C<new()> method.
  87
  88 =head1 SEE ALSO
  89
  90 =over 4
  91
  92 =item L<Moose::Object> - The base object for Moose (BUILDALL)
  93
  94 =item L<Moose::Cookbook::FAQ> - Frequently asked questions about Moose (How do I write custom constructors with Moose?)
  95
  96 =item L<Moose::Cookbook::Recipe4> - Subtypes, and modeling a simple Company class heirarchy (Example usage of BUILD in action)
  97
  98 =item L<Moose::Cookbook::WTF> - For when things go wrong with Moose ('Roles' section describes BUILD/BUILDALL)
  99
 100 =back
 101
 102 =head1 AUTHOR
 103
 104 Brian Manning <elspicyjack at gmail dot com>
 105
 106 =head1 COPYRIGHT AND LICENSE
 107
 108 Copyright (c)2008 by Infinity Interactive, Inc.
 109
 110 This documentation is free software; you can redistribute it and/or modify
 111 it under the same terms as Perl itself.
 112
 113 =cut