lib/Moose/Manual/Delta.pod

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