Add [DEPRECATED] and MigrationGuide

[gitmo/MooseX-AttributeHelpers.git] / lib / MooseX / AttributeHelpers / MigrationGuide.pod

=head1 MIGRATION GUIDE

So you want to migrate your wonderful MooseX::AttributeHelpers code to the
new and shiny L<Moose::Meta::Attribute::Native>? Then you've come to the 
right place at least :)

=head2 DIFFERENCES

There are some subtle differences between the two, and we will try to hilight
them with small code snipptes

First a MX::AH example:

    use Moose;
    use MooseX::AttributeHelpers;
    
    has 'items' => (
        metaclass => 'Collection::List',
        is => 'ro',
        isa => 'ArrayRef',
        provides => {
            'grep' => 'filter_items',
        }
    );
    
And now the updated way using the Native traits from Moose it self

    use Moose;
    
    has 'items' => (
        traits => ['Array'],
        is => 'ro',
        isa => 'ArrayRef',
        handles => {
            'filter_items' => 'grep',
        },
    );
    
There are basicly three diffrences in the simple cases. 

=over

=item metaclass becomes trait

In the native way of doing things, we add a trait to our attribute, where
we in AttributeHelpers assigned a metaclass.

=item provides is removed in favour of the standard handles

Where we used to have a special syntax for method provides in the old way
of doing things, we now use the standard handles in the native way. There is
one noteable exception to the usual handles in has (), which is that for 
the Native traits, we only accept a hashref. 

This leads us over to the last difference of the day

=item the order of handles is the reversed order of provides

You might have spotted this already, you clever you? This is done
to conform to the standard way handles works, and should make it easier
and clearer in the long run.