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