add a warning for immutablizing a class with mutable ancestors
[gitmo/Moose.git] / lib / Moose / Manual / Delta.pod
CommitLineData
600f7f85 1=pod
2
3=head1 NAME
4
5Moose::Manual::Delta - Important Changes in Moose
6
7=head1 DESCRIPTION
8
0f13f53c 9This documents any important or noteworthy changes in Moose, with a
10focus on backwards. This does duplicate data from the F<Changes> file,
11but aims to provide more details and when possible workarounds.
12
13Besides helping keep up with changes, you can also use this document
14for finding the lowest version of Moose that supported a given
15feature. If you encounter a problem and have a solution but don't see
16it documented here, or think we missed an important feature, please
17send us a patch.
600f7f85 18
3023f1e4 19=head1 Version 0.89_02
871f82f8 20
c985327a 21=over 4
22
871f82f8 23=item New Native delegation methods from L<List::Util> and L<List::MoreUtils>
24
25In particular, we now have C<reduce>, C<shuffle>, C<uniq>, and C<natatime>.
26
3023f1e4 27=item The Moose::Exporter with_caller feature is now deprecated
28
29Use C<with_meta> instead. The C<with_caller> option will start warning in a
30future release.
31
871f82f8 32=back
33
21f1fbdc 34Moose now warns if you call C<make_immutable> for a class with mutable
35ancestors. This is dangerous because modifying a class after a subclass has
36been immutablized will lead to incorrect results in the subclass, due to
37inlining, caching, etc. This occasionally happens accidentally, when a class
38loads one of its subclasses in the middle of its class definition, so pointing
39out that this may cause issues should be helpful. Metaclasses (classes that
40inherit from L<Class::MOP::Object>) are currently exempt from this check, since
41at the moment we aren't very consistent about which metaclasses we immutablize.
42
4ada9618 43=head1 Version 0.89_01
a3d98218 44
af44c00c 45L<Moose::Meta::Attribute::Native> has been moved into the Moose core from
a3d98218 46L<MooseX::AttributeHelpers>. Major changes include:
47
ebaaa391 48=over 4
a3d98218 49
50=item C<traits>, not C<metaclass>
51
93ced2bd 52Method providers are only available via traits.
a3d98218 53
54=item C<handles>, not C<provides> or C<curries>
55
93ced2bd 56The C<provides> syntax was like core Moose C<< handles => HASHREF >>
57syntax, but with the keys and values reversed. This was confusing,
58and AttributeHelpers now uses C<< handles => HASHREF >> in a way that
59should be intuitive to anyone already familiar with how it is used for
60other attributes.
a3d98218 61
93ced2bd 62The C<curries> functionality provided by AttributeHelpers has been
63generalized to apply to all cases of C<< handles => HASHREF >>, though
64not every piece of functionality has been ported (currying with a
65CODEREF is not supported).
a3d98218 66
1853a27e 67=item C<empty> is now C<is_empty>, and means empty, not non-empty
af44c00c 68
69Previously, the C<empty> method provided by Arrays and Hashes returned true if
70the attribute was B<not> empty (no elements). Now it returns true if the
1853a27e 71attribute B<is> empty. It was also renamed to C<is_empty>, to reflect this.
af44c00c 72
9a14bd29 73=item C<find> was renamed to C<first>, and C<first> and C<last> were removed
28b96142 74
75L<List::Util> refers to the functionality that we used to provide under C<find>
76as L<first|List::Util/first>, so that will likely be more familiar (and will
9a14bd29 77fit in better if we decide to add more List::Util functions). C<first> and
78C<last> were removed, since their functionality is easily duplicated with
79curries of C<get>.
28b96142 80
81=item Helpers that take a coderef of one argument now use C<$_>
82
83Subroutines passed as the first argument to C<first>, C<map>, and C<grep> now
84receive their argument in C<$_> rather than as a parameter to the subroutine.
85Helpers that take a coderef of two or more arguments remain using the argument
86list (there are technical limitations to using C<$a> and C<$b> like C<sort>
87does).
88
af44c00c 89See L<Moose::Meta::Attribute::Native> for the new documentation.
a3d98218 90
ebaaa391 91=back
92
4ada9618 93=head1 Version 0.89
94
8a8856de 95C<< use Moose -metaclass => 'Foo' >> now does alias resolution, just like
96C<-traits> (and the C<metaclass> and C<traits> options to C<has>).
97
27f2f43f 98Added two functions C<meta_class_alias> and C<meta_attribute_alias> to
99L<Moose::Util>, to simplify aliasing metaclasses and metatraits. This is
100a wrapper around the old
101
102 package Moose::Meta::Class::Custom::Trait::FooTrait;
103 sub register_implementation { 'My::Meta::Trait' }
104
105way of doing this.
106
c8b8d92f 107The C<alias> and C<excludes> role parameters have been renamed to C<-alias>
108and C<-excludes>. The old names still work, but new code should use the new
109names, and eventually the old ones will be deprecated and removed.
110
4831e2de 111=head1 Version 0.84
112
9f52cce5 113When an attribute generates I<no> accessors, we now warn. This is to help
114users who forget the C<is> option. If you really do not want any accessors,
3de02fd8 115you can use C<< is => 'bare' >>. You can maintain back compat with older
116versions of Moose by using something like:
117
118 ($Moose::VERSION >= 0.84 ? is => 'bare' : ())
9f52cce5 119
120When an accessor overwrites an existing method, we now warn. To work around
121this warning (if you really must have this behavior), you can explicitly
122remove the method before creating it as an accessor:
123
124 sub foo {}
125
126 __PACKAGE__->meta->remove_method('foo');
127
128 has foo => (
129 is => 'ro',
130 );
131
132When an unknown option is passed to C<has>, we now warn. You can silence
133the warning by fixing your code. :)
134
4831e2de 135The C<Role> type has been deprecated. On its own, it was useless,
136since it just checked C<< $object->can('does') >>. If you were using
137it as a parent type, just call C<role_type('Role::Name')> to create an
138appropriate type instead.
139
7d6b451f 140=head1 Version 0.78
141
142C<use Moose::Exporter;> now imports C<strict> and C<warnings> into packages
143that use it.
144
c3fdacda 145=head1 Version 0.77
146
147C<DEMOLISHALL> and C<DEMOLISH> now receive an argument indicating whether or
148not we are in global destruction.
149
00c61603 150=head1 Version 0.76
151
9f0b3b64 152Type constraints no longer run coercions for a value that already matches the
153constraint. This may affect some (arguably buggy) edge case coercions that
154rely on side effects in the C<via> clause.
155
f869fc4a 156=head1 Version 0.75
157
158L<Moose::Exporter> now accepts the C<-metaclass> option for easily
159overriding the metaclass (without L<metaclass>). This works for classes
160and roles.
161
39ab7714 162=head1 Version 0.74
163
85cf0647 164Added a C<duck_type> sugar function to L<Moose::Util::TypeConstraints>
165to make integration with non-Moose classes easier. It simply checks if
166C<< $obj->can() >> a list of methods.
39ab7714 167
612fd754 168A number of methods (mostly inherited from L<Class::MOP>) have been
169renamed with a leading underscore to indicate their internal-ness. The
170old method names will still work for a while, but will warn that the
171method has been renamed. In a few cases, the method will be removed
172entirely in the future. This may affect MooseX authors who were using
173these methods.
174
600f7f85 175=head1 Version 0.73
176
0f13f53c 177Calling C<subtype> with a name as the only argument now throws an
600f7f85 178exception. If you want an anonymous subtype do:
179
180 my $subtype = subtype as 'Foo';
181
0f13f53c 182This is related to the changes in version 0.71_01.
600f7f85 183
501db4e6 184The C<is_needed> method in L<Moose::Meta::Method::Destructor> is now
185only usable as a class method. Previously, it worked as a class or
186object method, with a different internal implementation for each
187version.
188
189The internals of making a class immutable changed a lot in Class::MOP
1900.78_02, and Moose's internals have changed along with it. The
191external C<< $metaclass->make_immutable >> method still works the same
192way.
193
600f7f85 194=head1 Version 0.72
195
0f13f53c 196A mutable class accepted C<< Foo->new(undef) >> without complaint,
197while an immutable class would blow up with an unhelpful error. Now,
198in both cases we throw a helpful error instead.
600f7f85 199
0f13f53c 200This "feature" was originally added to allow for cases such as this:
600f7f85 201
202 my $args;
0f13f53c 203
204 if ( something() ) {
205 $args = {...};
600f7f85 206 }
0f13f53c 207
600f7f85 208 return My::Class->new($args);
209
0f13f53c 210But we decided this is a bad idea and a little too magical, because it
211can easily mask real errors.
600f7f85 212
213=head1 Version 0.71_01
214
0f13f53c 215Calling C<type> or C<subtype> without the sugar helpers (C<as>,
216C<where>, C<message>) is now deprecated.
217
218As a side effect, this meant we ended up using Perl prototypes on
219C<as>, and code like this will no longer work:
600f7f85 220
221 use Moose::Util::TypeConstraints;
222 use Declare::Constraints::Simple -All;
0f13f53c 223
224 subtype 'ArrayOfInts'
600f7f85 225 => as 'ArrayRef'
226 => IsArrayRef(IsInt);
227
228Instead it must be changed to this:
229
0f13f53c 230 subtype(
231 'ArrayOfInts' => {
232 as => 'ArrayRef',
233 where => IsArrayRef(IsInt)
234 }
600f7f85 235 );
236
0f13f53c 237If you want to maintain backwards compat with older versions of Moose,
238you must explicitly test Moose's C<VERSION>:
600f7f85 239
0f13f53c 240 if ( Moose->VERSION < 0.71_01 ) {
241 subtype 'ArrayOfInts'
600f7f85 242 => as 'ArrayRef'
243 => IsArrayRef(IsInt);
244 }
245 else {
0f13f53c 246 subtype(
247 'ArrayOfInts' => {
248 as => 'ArrayRef',
249 where => IsArrayRef(IsInt)
250 }
600f7f85 251 );
252 }
253
254=head1 Version 0.70
255
0f13f53c 256We no longer pass the meta-attribute object as a final argument to
257triggers. This actually changed for inlined code a while back, but the
258non-inlined version and the docs were still out of date.
259
260If by some chance you actually used this feature, the workaround is
261simple. You fetch the attribute object from out of the C<$self>
262that is passed as the first argument to trigger, like so:
263
264 has 'foo' => (
265 is => 'ro',
266 isa => 'Any',
267 trigger => sub {
268 my ( $self, $value ) = @_;
269 my $attr = $self->meta->find_attribute_by_name('foo');
270
271 # ...
272 }
273 );
600f7f85 274
275=head1 Version 0.66
276
0f13f53c 277If you created a subtype and passed a parent that Moose didn't know
278about, it simply ignored the parent. Now it automatically creates the
279parent as a class type. This may not be what you want, but is less
280broken than before.
600f7f85 281
0f13f53c 282You could declare a name with subtype such as "Foo!Bar". Moose would
283accept this allowed, but if you used it in a parameterized type such
284as "ArrayRef[Foo!Bar]" it wouldn't work. We now do some vetting on
285names created via the sugar functions, so that they can only contain
286alphanumerics, ":", and ".".
600f7f85 287
288=head1 Version 0.65
289
290Methods created via an attribute can now fulfill a C<requires>
0f13f53c 291declaration for a role. Honestly we don't know why Stevan didn't make
292this work originally, he was just insane or something.
600f7f85 293
0f13f53c 294Stack traces from inlined code will now report the line and file as
295being in your class, as opposed to in Moose guts.
600f7f85 296
297=head1 Version 0.62_02
298
0f13f53c 299When a class does not provide all of a role's required methods, the
300error thrown now mentions all of the missing methods, as opposed to
301just the first missing method.
600f7f85 302
0f13f53c 303Moose will no longer inline a constructor for your class unless it
5e26e3f2 304inherits its constructor from Moose::Object, and will warn when it
305doesn't inline. If you want to force inlining anyway, pass
b84f64da 306C<< replace_constructor => 1 >> to C<make_immutable>.
0f13f53c 307
308If you want to get rid of the warning, pass C<< inline_constructor =>
fbf7ba85 3090 >>.
600f7f85 310
311=head1 Version 0.62
312
0f13f53c 313Removed the (deprecated) C<make_immutable> keyword.
600f7f85 314
315Removing an attribute from a class now also removes delegation
0f13f53c 316(C<handles>) methods installed for that attribute. This is correct
600f7f85 317behavior, but if you were wrongly relying on it you might get bit.
318
319=head1 Version 0.58
320
0f13f53c 321Roles now add methods by calling C<add_method>, not
322C<alias_method>. They make sure to always provide a method object,
323which will be cloned internally. This means that it is now possible to
324track the source of a method provided by a role, and even follow its
325history through intermediate roles. This means that methods added by
326a role now show up when looking at a class's method list/map.
327
328Parameter and Union args are now sorted, this makes Int|Str the same
329constraint as Str|Int. Also, incoming type constraint strings are
330normalized to remove all whitespace differences. This is mostly for
331internals and should not affect outside code.
332
333L<Moose::Exporter> will no longer remove a subroutine that the
334exporting package re-exports. Moose re-exports the Carp::confess
335function, among others. The reasoning is that we cannot know whether
336you have also explicitly imported those functions for your own use, so
337we err on the safe side and always keep them.
600f7f85 338
339=head1 Version 0.56
340
0f13f53c 341C<Moose::init_meta> should now be called as a method.
600f7f85 342
0f13f53c 343New modules for extension writers, L<Moose::Exporter> and
344L<Moose::Util::MetaRole>.
600f7f85 345
346=head1 Version 0.55_01
347
348Implemented metaclass traits (and wrote a recipe for it):
349
350 use Moose -traits => 'Foo'
351
352This should make writing small Moose extensions a little
353easier.
354
355=head1 Version 0.55
356
357Fixed C<coerce> to accept anon types just like C<subtype> can.
358So that you can do:
359
360 coerce $some_anon_type => from 'Str' => via { ... };
361
362=head1 Version 0.51
363
52da380a 364Added C<BUILDARGS>, a new step in C<< Moose::Object->new() >>.
600f7f85 365
366=head1 Version 0.49
367
0f13f53c 368Fixed how the C<< is => (ro|rw) >> works with custom defined
369C<reader>, C<writer> and C<accessor> options. See the below table for
600f7f85 370details:
371
372 is => ro, writer => _foo # turns into (reader => foo, writer => _foo)
373 is => rw, writer => _foo # turns into (reader => foo, writer => _foo)
374 is => rw, accessor => _foo # turns into (accessor => _foo)
375 is => ro, accessor => _foo # error, accesor is rw
376
377=head1 Version 0.45
378
0f13f53c 379The C<before/around/after> method modifiers now support regexp
380matching of method names. NOTE: this only works for classes, it is
381currently not supported in roles, but, ... patches welcome.
600f7f85 382
0f13f53c 383The C<has> keyword for roles now accepts the same array ref form that
384L<Moose>.pm does for classes.
600f7f85 385
0f13f53c 386A trigger on a read-only attribute is no longer an error, as it's
387useful to trigger off of the constructor.
600f7f85 388
0f13f53c 389Subtypes of parameterizable types now are parameterizable types
390themselves.
600f7f85 391
392=head1 Version 0.44
393
0f13f53c 394Fixed issue where C<DEMOLISHALL> was eating the value in C<$@>, and so
395not working correctly. It still kind of eats them, but so does vanilla
396perl.
600f7f85 397
398=head1 Version 0.41
399
0f13f53c 400Inherited attributes may now be extended without restriction on the
600f7f85 401type ('isa', 'does').
402
0f13f53c 403The entire set of Moose::Meta::TypeConstraint::* classes were
404refactored in this release. If you were relying on their internals you
405should test your code carefully.
600f7f85 406
407=head1 Version 0.40
408
0f13f53c 409Documenting the use of '+name' with attributes that come from recently
410composed roles. It makes sense, people are using it, and so why not
411just officially support it.
600f7f85 412
0f13f53c 413The C<< Moose::Meta::Class->create >> method now supports roles.
600f7f85 414
86b96832 415It is now possible to make anonymous enum types by passing C<enum> an
416array reference instead of the C<< enum $name => @values >>.
600f7f85 417
418=head1 Version 0.37
419
0f13f53c 420Added the C<make_immutable> keyword as a shortcut to calling
421C<make_immutable> on the meta object. This eventually got removed!
600f7f85 422
0f13f53c 423Made C<< init_arg => undef >> work in Moose. This means "do not accept
600f7f85 424a constructor parameter for this attribute".
425
0f13f53c 426Type errors now use the provided message. Prior to this release they
427didn't.
600f7f85 428
429=head1 Version 0.34
430
431Moose is now a postmodern object system :)
432
0f13f53c 433The Role system was completely refactored. It is 100% backwards
434compat, but the internals were totally changed. If you relied on the
435internals then you are advised to test carefully.
600f7f85 436
437Added method exclusion and aliasing for Roles in this release.
438
0f13f53c 439Added the L<Moose::Util::TypeConstraints::OptimizedConstraints>
440module.
600f7f85 441
0f13f53c 442Passing a list of values to an accessor (which is only expecting one
443value) used to be silently ignored, now it throws an error.
600f7f85 444
445=head1 Version 0.26
446
0f13f53c 447Added parameterized types and did a pretty heavy refactoring of the
448type constraint system.
600f7f85 449
0f13f53c 450Better framework extendability and better support for "making your own
451Moose".
600f7f85 452
453=head1 Version 0.25 or before
454
0f13f53c 455Honestly, you shouldn't be using versions of Moose that are this old,
456so many bug fixes and speed improvements have been made you would be
457crazy to not upgrade.
600f7f85 458
0f13f53c 459Also, I am tired of going through the Changelog so I am stopping here,
460if anyone would like to continue this please feel free.
600f7f85 461
462=head1 AUTHOR
463
464Stevan Little E<lt>stevan@iinteractive.comE<gt>
465
466=head1 COPYRIGHT AND LICENSE
467
468Copyright 2009 by Infinity Interactive, Inc.
469
470L<http://www.iinteractive.com>
471
472This library is free software; you can redistribute it and/or modify
473it under the same terms as Perl itself.
474
0f13f53c 475=cut