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     }
  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 When would you use an Moose type constraint instead of a custom constructor?
  78
  79 Using type constraints via L<Moose::Util::TypeConstraints>, you can verify
  80 simple relationships when an object is created:
  81
  82     package Triangle;
  83     use Moose;
  84
  85     has
  86
  87 You would want to use the C<BUILD()> method in order to verify more complex
  88 relationships:
  89
  90     package IsoscelesTriangle;
  91     use Moose;
  92
  93 =head2 BUILD method is run only if it is defined in the object
  94
  95 If your object does not have a C<BUILD> method, then Moose will skip trying to
  96 run it.
  97
  98 =head2 What is 'BUILDALL'?
  99
 100 (Taken from L<Moose::Object>)  The C<BUILDALL> method will call every BUILD
 101 method in the inheritance hierarchy, and pass it a hash-ref of the the
 102 C<%params> passed to the C<new()> method.
 103
 104 =head1 SEE ALSO
 105
 106 =over 4
 107
 108 =item L<Moose::Object> - The base object for Moose (BUILDALL)
 109
 110 =item L<Moose::Cookbook::FAQ> - Frequently asked questions about Moose
 111 (How do I write custom constructors with Moose?)
 112
 113 =item L<Moose::Cookbook::Recipe4> - Subtypes, and modeling a simple
 114 Company class heirarchy (Example usage of BUILD in action)
 115
 116 =item L<Moose::Cookbook::WTF> - For when things go wrong with Moose
 117 ('Roles' section describes BUILD/BUILDALL)
 118
 119 =back
 120
 121 =head1 AUTHOR
 122
 123 Brian Manning <elspicyjack at gmail dot com>
 124
 125 =head1 COPYRIGHT AND LICENSE
 126
 127 Copyright 2006-2008 by Infinity Interactive, Inc.
 128
 129 L<http://www.iinteractive.com>
 130
 131 This library is free software; you can redistribute it and/or modify
 132 it under the same terms as Perl itself.
 133
 134 =cut