view release on metacpan or  search on metacpan

lib/MooseX/Unique.pm  view on Meta::CPAN

            ['MooseX::Unique::Meta::Trait::Role::ApplicationToRole'],
    },
    base_class_roles => ['MooseX::Unique::Meta::Trait::Object'],
    with_meta        => ['unique', 'required_matches'],

);

sub unique {
    my ( $meta, @att ) = @_;
    if ( ref $att[0] ) {
        @att = @{ $att[0] };
    }
    $meta->add_match_attribute( @att );
}

sub required_matches {
    my ( $meta, $val) = @_;
    $meta->add_match_requires( $val );
}


1;


=pod

=for :stopwords Edward Allen J. III cpan testmatrix url annocpan anno bugtracker rt cpants
kwalitee diff irc mailto metadata placeholders BUILDARGS params readonly
MetaRole metaroles metaclass doy Luehrs sartak UniqueIdentity

=encoding utf-8

=head1 NAME

MooseX::Unique - Make your Moose instances as unique as you are

=head1 VERSION

  This document describes v0.005 of MooseX::Unique - released June 22, 2011 as part of MooseX-Unique.

=head1 SYNOPSIS

    package MyApp;
    use Moose;
    use MooseX::Unique;

    has identity => (
        is  => 'ro',
        isa => 'Str',
        required => 1,
        unique => 1,
    );

    has number =>  ( 
        is => 'rw',
        isa => 'Int'
    );


    package main;
    use Modern::Perl;


    my $objecta = MyApp->new_or_matching(identity => 'Mine');
    my $objectb = MyApp->new_or_matching(identity => 'Mine');

    $objecta->number(40);

    # prints:  Num: 40
    say "Num: ", $objectb->number;

=head1 DESCRIPTION

This module uses L<MooseX::InstanceTracking> to keep track of your
instances.  If an attribute has a unique flag set, and a new attribute is
requested with the same value, the original will be returned.

This is useful if

=over

=item *

If you are creating several attributes from data, which may have 
duplicates that you would rather merge than replace.

=item *

If you want to create a new or modify and are too lazy to look up the data
yourself. 

=item *

You have a complicated network of data, with several cross references.
For example, a song could have an album and an artist.  That album could
have the same artist, or a different artist.  That artist can have
multiple albums.  That album, of course, has multiple songs.  When
importing song by song, this web would be lost without some sort of
instance tracking.  This module lets Moose do the work for you.

=back

That having all been said, B<think twice> before using this module.  It 
can cause spooky action at a distance.  Be sure to use it only on immutable
objects. The synopsis should indicate how this can be troubling, confusing, 
and a great source of bizarre bugs if you are not paying attention.

In addition to the spooky action at a distance, please keep in mind that the
instance tracking is performed using B<weak references>.  If you let an object
fall out of scope, it is gone, so a new object with the same unique attribute
will be new.

=head1 METHODS

=head2 new_or_matching(%params)

Provided by L<MooseX::Unique::Object|MooseX::Unique::Object>.

This is a wrapper around your new method that looks up the attribute for you.  
Please note that this module does not process your BUILDARGS before looking for 
an instance.  So, values must be passed as a hash or hash reference. Any