From: Dave Rolsky Date: Sat, 21 Mar 2009 02:15:18 +0000 (-0500) Subject: Took a revision pass through this document. X-Git-Tag: 0.72_01~59 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=0f13f53c97590701c6f9b3683de4f54ae1264ece;p=gitmo%2FMoose.git Took a revision pass through this document. --- diff --git a/lib/Moose/Manual/Delta.pod b/lib/Moose/Manual/Delta.pod index 97fedc5..2450b7d 100644 --- a/lib/Moose/Manual/Delta.pod +++ b/lib/Moose/Manual/Delta.pod @@ -6,176 +6,176 @@ Moose::Manual::Delta - Important Changes in Moose =head1 DESCRIPTION -This attempts to document any important or noteworthy changes -in Moose both good or bad. While this does duplicate data from -the F file it aims to provide more details and when -possible fixes or workarounds as well. - -This document is a good way to keep up with important changes, -but it can also be useful in doing things like finding the lowest -version of Moose that supported a given feature, or as a helper -for people upgrading Moose versions and encountering issues. -So if you encounter a problem and have a solution but don't see -it documented here, or think I missed an important feature, then -please send us a patch. +This documents any important or noteworthy changes in Moose, with a +focus on backwards. This does duplicate data from the F file, +but aims to provide more details and when possible workarounds. + +Besides helping keep up with changes, you can also use this document +for finding the lowest version of Moose that supported a given +feature. If you encounter a problem and have a solution but don't see +it documented here, or think we missed an important feature, please +send us a patch. =head1 Version 0.73 -Calling subtype with a name as the only argument is now an +Calling C with a name as the only argument now throws an exception. If you want an anonymous subtype do: my $subtype = subtype as 'Foo'; -This is related to the changes in L. +This is related to the changes in version 0.71_01. =head1 Version 0.72 -A mutable class accepted Foo->new(undef) without complaint, -while an immutable class would blow up with an unhelpful -error. Now, in both cases we throw a helpful error -instead. +A mutable class accepted C<< Foo->new(undef) >> without complaint, +while an immutable class would blow up with an unhelpful error. Now, +in both cases we throw a helpful error instead. -This "feature" was originally added to allow for cases such -as this: +This "feature" was originally added to allow for cases such as this: my $args; - if (something()) { - $args = { ... }; + + if ( something() ) { + $args = {...}; } + return My::Class->new($args); -But it has been decided that this is bad form and you should -do what you mean more and not have Moose clean up for you. +But we decided this is a bad idea and a little too magical, because it +can easily mask real errors. =head1 Version 0.71_01 -Calling type or subtype without the sugar helpers (as, where, -message) is now deprecated. This means that code like this -will no longer work: +Calling C or C without the sugar helpers (C, +C, C) is now deprecated. + +As a side effect, this meant we ended up using Perl prototypes on +C, and code like this will no longer work: use Moose::Util::TypeConstraints; use Declare::Constraints::Simple -All; - - subtype 'ArrayOfInts' + + subtype 'ArrayOfInts' => as 'ArrayRef' => IsArrayRef(IsInt); Instead it must be changed to this: - subtype('ArrayOfInts' => { - as => 'ArrayRef', - where => IsArrayRef(IsInt) - } + subtype( + 'ArrayOfInts' => { + as => 'ArrayRef', + where => IsArrayRef(IsInt) + } ); -If you want to maintain backwards compat in your module then -you can just wrap it within a version test like so: +If you want to maintain backwards compat with older versions of Moose, +you must explicitly test Moose's C: - if ($Moose::VERSION < 0.72) { - subtype 'ArrayOfInts' + if ( Moose->VERSION < 0.71_01 ) { + subtype 'ArrayOfInts' => as 'ArrayRef' => IsArrayRef(IsInt); } else { - subtype('ArrayOfInts' => { - as => 'ArrayRef', - where => IsArrayRef(IsInt) - } + subtype( + 'ArrayOfInts' => { + as => 'ArrayRef', + where => IsArrayRef(IsInt) + } ); } =head1 Version 0.70 -We no longer pass the meta-attribute object as a final -argument to triggers. This actually changed for inlined code a -while back, but the non-inlined version and the docs were -still out of date. - -Not sure how many people actually used this feature, but if -you did, the workaround is pretty simple. You just fetch the -attribute object from out of the C<$self> that is passed as -the first argument to trigger, like so: - -has 'foo' => ( - is => 'ro', - isa => 'Any', - trigger => sub { - my ($self, $value) = @_; - my $attr = $self->meta->find_attribute_by_name('foo'); - # ... - } -); +We no longer pass the meta-attribute object as a final argument to +triggers. This actually changed for inlined code a while back, but the +non-inlined version and the docs were still out of date. + +If by some chance you actually used this feature, the workaround is +simple. You fetch the attribute object from out of the C<$self> +that is passed as the first argument to trigger, like so: + + has 'foo' => ( + is => 'ro', + isa => 'Any', + trigger => sub { + my ( $self, $value ) = @_; + my $attr = $self->meta->find_attribute_by_name('foo'); + + # ... + } + ); =head1 Version 0.66 -If you created a subtype and passed a parent that Moose didn't -know about, it simply ignored the parent. Now it automatically -creates the parent as a class type. This may not be what you -want, but is less broken than before. +If you created a subtype and passed a parent that Moose didn't know +about, it simply ignored the parent. Now it automatically creates the +parent as a class type. This may not be what you want, but is less +broken than before. -You could declare a name with subtype such as "Foo!Bar" that -would be allowed, but if you used it in a parameterized type -such as "ArrayRef[Foo!Bar]" it wouldn't work. We now do some -vetting on names created via the sugar functions, so that they -can only contain alphanumerics, ":", and ".". +You could declare a name with subtype such as "Foo!Bar". Moose would +accept this allowed, but if you used it in a parameterized type such +as "ArrayRef[Foo!Bar]" it wouldn't work. We now do some vetting on +names created via the sugar functions, so that they can only contain +alphanumerics, ":", and ".". =head1 Version 0.65 Methods created via an attribute can now fulfill a C -declaration for a role. Honestly I don't know why I didn't make -this work originally, I was just insane or something. +declaration for a role. Honestly we don't know why Stevan didn't make +this work originally, he was just insane or something. -Stack traces from inlined code will now report its line and -file as being in your class, as opposed to in Moose guts. +Stack traces from inlined code will now report the line and file as +being in your class, as opposed to in Moose guts. =head1 Version 0.62_02 -When a class does not provide all of a role's required -methods, the error thrown now mentions all of the missing -methods, as opposed to just the first one found. +When a class does not provide all of a role's required methods, the +error thrown now mentions all of the missing methods, as opposed to +just the first missing method. -Moose will no longer inline a constructor for your class -unless it inherits its constructor from Moose::Object, and -will warn when it doesn't inline. If you want to force -inlining anyway, pass "replace_constructor => 1" to -make_immutable. +Moose will no longer inline a constructor for your class unless it +inherits its constructor is inherited from Moose::Object, and will +warn when it doesn't inline. If you want to force inlining anyway, +pass C<< "replace_constructor => 1 >> to C. + +If you want to get rid of the warning, pass C<< inline_constructor => +1 >>. =head1 Version 0.62 -Removed the (deprecated) make_immutable keyword. +Removed the (deprecated) C keyword. Removing an attribute from a class now also removes delegation -(handles) methods installed for that attribute. This is correct +(C) methods installed for that attribute. This is correct behavior, but if you were wrongly relying on it you might get bit. =head1 Version 0.58 -Roles now add methods by calling add_method, not -alias_method. They make sure to always provide a method -object, which will be cloned internally. This means that it is -now possible to track the source of a method provided by a -role, and even follow its history through intermediate roles. -This means that methods added by a role now show up when -looking at a class's method list/map. - -Parameter and Union args are now sorted, this makes Int|Str -the same constraint as Str|Int. Incoming type constraint strings -also are normalized to remove all whitespace differences. This is -all mostly just for internals and should not affect outside code. - -Moose::Exporter will no longer remove a subroutine that the -exporting package re-exports. Moose re-exports the -Carp::confess function, among others. The reasoning is that we -cannot know whether you have also explicitly imported those -functions for your own use, so we err on the safe side and -always keep them. +Roles now add methods by calling C, not +C. They make sure to always provide a method object, +which will be cloned internally. This means that it is now possible to +track the source of a method provided by a role, and even follow its +history through intermediate roles. This means that methods added by +a role now show up when looking at a class's method list/map. + +Parameter and Union args are now sorted, this makes Int|Str the same +constraint as Str|Int. Also, incoming type constraint strings are +normalized to remove all whitespace differences. This is mostly for +internals and should not affect outside code. + +L will no longer remove a subroutine that the +exporting package re-exports. Moose re-exports the Carp::confess +function, among others. The reasoning is that we cannot know whether +you have also explicitly imported those functions for your own use, so +we err on the safe side and always keep them. =head1 Version 0.56 -Moose::init_meta should now be called as a method. +C should now be called as a method. -New modules for extension writers, Moose::Exporter and -Moose::Util::MetaRole. +New modules for extension writers, L and +L. =head1 Version 0.55_01 @@ -195,12 +195,12 @@ So that you can do: =head1 Version 0.51 -Added BUILDARGS, a new step in Moose::Object::new(). +Added C, a new step in C<< Moose::Object->new() >. =head1 Version 0.49 -Fixed how the C (ro|rw)> works with custom defined -reader, writer and accessor options. See the below table for +Fixed how the C<< is => (ro|rw) >> works with custom defined +C, C and C options. See the below table for details: is => ro, writer => _foo # turns into (reader => foo, writer => _foo) @@ -210,85 +210,88 @@ details: =head1 Version 0.45 -The C method modifiers now support regexp matching -of method names. NOTE: this only works for classes, it is currently not -supported in roles, but, ... patches welcome. +The C method modifiers now support regexp +matching of method names. NOTE: this only works for classes, it is +currently not supported in roles, but, ... patches welcome. -The C keyword for roles now accepts the same array ref form that -Moose.pm does for classes. +The C keyword for roles now accepts the same array ref form that +L.pm does for classes. -A trigger on a ro-attribute is no longer an error, as it's useful to -trigger off of the constructor. +A trigger on a read-only attribute is no longer an error, as it's +useful to trigger off of the constructor. -Subtypes of parameterizable types now are themselves parameterizable -types. +Subtypes of parameterizable types now are parameterizable types +themselves. =head1 Version 0.44 -Fixed issue where DEMOLISHALL was eating the C<$@> values, and so not -working correctly, it still kind of eats them, but so does vanilla perl. +Fixed issue where C was eating the value in C<$@>, and so +not working correctly. It still kind of eats them, but so does vanilla +perl. =head1 Version 0.41 -Inherited attributes may now be extended without restriction on the +Inherited attributes may now be extended without restriction on the type ('isa', 'does'). -The entire set of Moose::Meta::TypeConstraint::* classes got refactored in -this release, chances are if you were relying on their internals you might -want to check on them. +The entire set of Moose::Meta::TypeConstraint::* classes were +refactored in this release. If you were relying on their internals you +should test your code carefully. =head1 Version 0.40 -Documenting the use of '+name' with attributes that come from recently -composed roles. It makes sense, people are using it, and so why not just -officially support it. +Documenting the use of '+name' with attributes that come from recently +composed roles. It makes sense, people are using it, and so why not +just officially support it. -The C method which now supports roles too. +The C<< Moose::Meta::Class->create >> method now supports roles. -It is now possible to make anon-enums by passing 'enum' an ARRAY ref instead -of the $name => @values. +It is now possible to make anononymous enum types by passing C +an array reference instead of the C<< enum $name => @values >>. =head1 Version 0.37 -Added the 'make_immutable' keyword as a shortcut to calling make_immutable on -the meta object. However, this eventually gets removed again, but this is where -the trouble began. +Added the C keyword as a shortcut to calling +C on the meta object. This eventually got removed! -Making (init_arg => undef) work in Moose. This basically means "do not accept +Made C<< init_arg => undef >> work in Moose. This means "do not accept a constructor parameter for this attribute". -Making type errors use the assigned message, prior to this they didn't. +Type errors now use the provided message. Prior to this release they +didn't. =head1 Version 0.34 Moose is now a postmodern object system :) -The Role system was completely refactored. It is 100% backwards compat, but the -internals are totally changed. So if you relied on the internals then you might -want to check this one out. +The Role system was completely refactored. It is 100% backwards +compat, but the internals were totally changed. If you relied on the +internals then you are advised to test carefully. Added method exclusion and aliasing for Roles in this release. -Added the L module. +Added the L +module. -Passing a list of values to an accessor (which is only expecting one value) used -to be silently ignored, now it throws an error. +Passing a list of values to an accessor (which is only expecting one +value) used to be silently ignored, now it throws an error. =head1 Version 0.26 -Added parameterized types and so did a pretty heavy refactoring of the type -constraint system. +Added parameterized types and did a pretty heavy refactoring of the +type constraint system. -Better framework extendability and better support for "making your own Moose". +Better framework extendability and better support for "making your own +Moose". =head1 Version 0.25 or before -Honestly, you shouldn't be using versions of Moose that are this old, so many -bug fixes and speed improvements have been made you would be crazy to not -upgrade. +Honestly, you shouldn't be using versions of Moose that are this old, +so many bug fixes and speed improvements have been made you would be +crazy to not upgrade. -Also, I am tired of going through the Changelog so I am stopping here, if -anyone would like to continue this please feel free. +Also, I am tired of going through the Changelog so I am stopping here, +if anyone would like to continue this please feel free. =head1 AUTHOR @@ -303,4 +306,4 @@ L This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. -=cut \ No newline at end of file +=cut