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.76
  20
  21 L<Moose> now warns about a class overriding methods from roles it
  22 consumes. This warning is useful for discovering I<accidental> name
  23 collisions, which is part of why using roles is much less painful than
  24 multiple inheritance. You can silence this warning by explicitly
  25 excluding methods you override from roles. For example,
  26
  27     package Role;
  28     sub foo { "Default role implementation" }
  29
  30     package Class;
  31     with 'Role' => { excludes => 'foo' };
  32     sub foo { "Overriding class implementation" }
  33
  34 Since this warning has been decried by some (such as chromatic in
  35 L<http://www.modernperlbooks.com/mt/2009/04/the-value-of-a-warning.html>),
  36 we ask that you provide feedback about whether this warning has helped or
  37 hindered you. If it turns out to have been a bad idea, we will not
  38 hesitate to remove it from future versions.
  39
  40 =head1 Version 0.75
  41
  42 L<Moose::Exporter> now accepts the C<-metaclass> option for easily
  43 overriding the metaclass (without L<metaclass>). This works for classes
  44 and roles.
  45
  46 =head1 Version 0.74
  47
  48 Added a C<duck_type> sugar function to L<Moose::Util::TypeConstraints>
  49 to make integration with non-Moose classes easier. It simply checks if
  50 C<< $obj->can() >> a list of methods.
  51
  52 A number of methods (mostly inherited from L<Class::MOP>) have been
  53 renamed with a leading underscore to indicate their internal-ness. The
  54 old method names will still work for a while, but will warn that the
  55 method has been renamed. In a few cases, the method will be removed
  56 entirely in the future. This may affect MooseX authors who were using
  57 these methods.
  58
  59 =head1 Version 0.73
  60
  61 Calling C<subtype> with a name as the only argument now throws an
  62 exception. If you want an anonymous subtype do:
  63
  64     my $subtype = subtype as 'Foo';
  65
  66 This is related to the changes in version 0.71_01.
  67
  68 The C<is_needed> method in L<Moose::Meta::Method::Destructor> is now
  69 only usable as a class method. Previously, it worked as a class or
  70 object method, with a different internal implementation for each
  71 version.
  72
  73 The internals of making a class immutable changed a lot in Class::MOP
  74 0.78_02, and Moose's internals have changed along with it. The
  75 external C<< $metaclass->make_immutable >> method still works the same
  76 way.
  77
  78 =head1 Version 0.72
  79
  80 A mutable class accepted C<< Foo->new(undef) >> without complaint,
  81 while an immutable class would blow up with an unhelpful error. Now,
  82 in both cases we throw a helpful error instead.
  83
  84 This "feature" was originally added to allow for cases such as this:
  85
  86   my $args;
  87
  88   if ( something() ) {
  89       $args = {...};
  90   }
  91
  92   return My::Class->new($args);
  93
  94 But we decided this is a bad idea and a little too magical, because it
  95 can easily mask real errors.
  96
  97 =head1 Version 0.71_01
  98
  99 Calling C<type> or C<subtype> without the sugar helpers (C<as>,
 100 C<where>, C<message>) is now deprecated.
 101
 102 As a side effect, this meant we ended up using Perl prototypes on
 103 C<as>, and code like this will no longer work:
 104
 105   use Moose::Util::TypeConstraints;
 106   use Declare::Constraints::Simple -All;
 107
 108   subtype 'ArrayOfInts'
 109       => as 'ArrayRef'
 110       => IsArrayRef(IsInt);
 111
 112 Instead it must be changed to this:
 113
 114   subtype(
 115       'ArrayOfInts' => {
 116           as    => 'ArrayRef',
 117           where => IsArrayRef(IsInt)
 118       }
 119   );
 120
 121 If you want to maintain backwards compat with older versions of Moose,
 122 you must explicitly test Moose's C<VERSION>:
 123
 124   if ( Moose->VERSION < 0.71_01 ) {
 125       subtype 'ArrayOfInts'
 126           => as 'ArrayRef'
 127           => IsArrayRef(IsInt);
 128   }
 129   else {
 130       subtype(
 131           'ArrayOfInts' => {
 132               as    => 'ArrayRef',
 133               where => IsArrayRef(IsInt)
 134           }
 135       );
 136   }
 137
 138 =head1 Version 0.70
 139
 140 We no longer pass the meta-attribute object as a final argument to
 141 triggers. This actually changed for inlined code a while back, but the
 142 non-inlined version and the docs were still out of date.
 143
 144 If by some chance you actually used this feature, the workaround is
 145 simple. You fetch the attribute object from out of the C<$self>
 146 that is passed as the first argument to trigger, like so:
 147
 148   has 'foo' => (
 149       is      => 'ro',
 150       isa     => 'Any',
 151       trigger => sub {
 152           my ( $self, $value ) = @_;
 153           my $attr = $self->meta->find_attribute_by_name('foo');
 154
 155           # ...
 156       }
 157   );
 158
 159 =head1 Version 0.66
 160
 161 If you created a subtype and passed a parent that Moose didn't know
 162 about, it simply ignored the parent. Now it automatically creates the
 163 parent as a class type. This may not be what you want, but is less
 164 broken than before.
 165
 166 You could declare a name with subtype such as "Foo!Bar". Moose would
 167 accept this allowed, but if you used it in a parameterized type such
 168 as "ArrayRef[Foo!Bar]" it wouldn't work. We now do some vetting on
 169 names created via the sugar functions, so that they can only contain
 170 alphanumerics, ":", and ".".
 171
 172 =head1 Version 0.65
 173
 174 Methods created via an attribute can now fulfill a C<requires>
 175 declaration for a role. Honestly we don't know why Stevan didn't make
 176 this work originally, he was just insane or something.
 177
 178 Stack traces from inlined code will now report the line and file as
 179 being in your class, as opposed to in Moose guts.
 180
 181 =head1 Version 0.62_02
 182
 183 When a class does not provide all of a role's required methods, the
 184 error thrown now mentions all of the missing methods, as opposed to
 185 just the first missing method.
 186
 187 Moose will no longer inline a constructor for your class unless it
 188 inherits its constructor from Moose::Object, and will warn when it
 189 doesn't inline. If you want to force inlining anyway, pass
 190 C<< "replace_constructor => 1 >> to C<make_immutable>.
 191
 192 If you want to get rid of the warning, pass C<< inline_constructor =>
 193 1 >>.
 194
 195 =head1 Version 0.62
 196
 197 Removed the (deprecated) C<make_immutable> keyword.
 198
 199 Removing an attribute from a class now also removes delegation
 200 (C<handles>) methods installed for that attribute. This is correct
 201 behavior, but if you were wrongly relying on it you might get bit.
 202
 203 =head1 Version 0.58
 204
 205 Roles now add methods by calling C<add_method>, not
 206 C<alias_method>. They make sure to always provide a method object,
 207 which will be cloned internally. This means that it is now possible to
 208 track the source of a method provided by a role, and even follow its
 209 history through intermediate roles.  This means that methods added by
 210 a role now show up when looking at a class's method list/map.
 211
 212 Parameter and Union args are now sorted, this makes Int|Str the same
 213 constraint as Str|Int. Also, incoming type constraint strings are
 214 normalized to remove all whitespace differences. This is mostly for
 215 internals and should not affect outside code.
 216
 217 L<Moose::Exporter> will no longer remove a subroutine that the
 218 exporting package re-exports. Moose re-exports the Carp::confess
 219 function, among others. The reasoning is that we cannot know whether
 220 you have also explicitly imported those functions for your own use, so
 221 we err on the safe side and always keep them.
 222
 223 =head1 Version 0.56
 224
 225 C<Moose::init_meta> should now be called as a method.
 226
 227 New modules for extension writers, L<Moose::Exporter> and
 228 L<Moose::Util::MetaRole>.
 229
 230 =head1 Version 0.55_01
 231
 232 Implemented metaclass traits (and wrote a recipe for it):
 233
 234   use Moose -traits => 'Foo'
 235
 236 This should make writing small Moose extensions a little
 237 easier.
 238
 239 =head1 Version 0.55
 240
 241 Fixed C<coerce> to accept anon types just like C<subtype> can.
 242 So that you can do:
 243
 244   coerce $some_anon_type => from 'Str' => via { ... };
 245
 246 =head1 Version 0.51
 247
 248 Added C<BUILDARGS>, a new step in C<< Moose::Object->new() >>.
 249
 250 =head1 Version 0.49
 251
 252 Fixed how the C<< is => (ro|rw) >> works with custom defined
 253 C<reader>, C<writer> and C<accessor> options. See the below table for
 254 details:
 255
 256   is => ro, writer => _foo    # turns into (reader => foo, writer => _foo)
 257   is => rw, writer => _foo    # turns into (reader => foo, writer => _foo)
 258   is => rw, accessor => _foo  # turns into (accessor => _foo)
 259   is => ro, accessor => _foo  # error, accesor is rw
 260
 261 =head1 Version 0.45
 262
 263 The C<before/around/after> method modifiers now support regexp
 264 matching of method names. NOTE: this only works for classes, it is
 265 currently not supported in roles, but, ... patches welcome.
 266
 267 The C<has> keyword for roles now accepts the same array ref form that
 268 L<Moose>.pm does for classes.
 269
 270 A trigger on a read-only attribute is no longer an error, as it's
 271 useful to trigger off of the constructor.
 272
 273 Subtypes of parameterizable types now are parameterizable types
 274 themselves.
 275
 276 =head1 Version 0.44
 277
 278 Fixed issue where C<DEMOLISHALL> was eating the value in C<$@>, and so
 279 not working correctly. It still kind of eats them, but so does vanilla
 280 perl.
 281
 282 =head1 Version 0.41
 283
 284 Inherited attributes may now be extended without restriction on the
 285 type ('isa', 'does').
 286
 287 The entire set of Moose::Meta::TypeConstraint::* classes were
 288 refactored in this release. If you were relying on their internals you
 289 should test your code carefully.
 290
 291 =head1 Version 0.40
 292
 293 Documenting the use of '+name' with attributes that come from recently
 294 composed roles. It makes sense, people are using it, and so why not
 295 just officially support it.
 296
 297 The C<< Moose::Meta::Class->create >> method now supports roles.
 298
 299 It is now possible to make anonymous enum types by passing C<enum> an
 300 array reference instead of the C<< enum $name => @values >>.
 301
 302 =head1 Version 0.37
 303
 304 Added the C<make_immutable> keyword as a shortcut to calling
 305 C<make_immutable> on the meta object. This eventually got removed!
 306
 307 Made C<< init_arg => undef >> work in Moose. This means "do not accept
 308 a constructor parameter for this attribute".
 309
 310 Type errors now use the provided message. Prior to this release they
 311 didn't.
 312
 313 =head1 Version 0.34
 314
 315 Moose is now a postmodern object system :)
 316
 317 The Role system was completely refactored. It is 100% backwards
 318 compat, but the internals were totally changed. If you relied on the
 319 internals then you are advised to test carefully.
 320
 321 Added method exclusion and aliasing for Roles in this release.
 322
 323 Added the L<Moose::Util::TypeConstraints::OptimizedConstraints>
 324 module.
 325
 326 Passing a list of values to an accessor (which is only expecting one
 327 value) used to be silently ignored, now it throws an error.
 328
 329 =head1 Version 0.26
 330
 331 Added parameterized types and did a pretty heavy refactoring of the
 332 type constraint system.
 333
 334 Better framework extendability and better support for "making your own
 335 Moose".
 336
 337 =head1 Version 0.25 or before
 338
 339 Honestly, you shouldn't be using versions of Moose that are this old,
 340 so many bug fixes and speed improvements have been made you would be
 341 crazy to not upgrade.
 342
 343 Also, I am tired of going through the Changelog so I am stopping here,
 344 if anyone would like to continue this please feel free.
 345
 346 =head1 AUTHOR
 347
 348 Stevan Little E<lt>stevan@iinteractive.comE<gt>
 349
 350 =head1 COPYRIGHT AND LICENSE
 351
 352 Copyright 2009 by Infinity Interactive, Inc.
 353
 354 L<http://www.iinteractive.com>
 355
 356 This library is free software; you can redistribute it and/or modify
 357 it under the same terms as Perl itself.
 358
 359 =cut