view release on metacpan or  search on metacpan

README  view on Meta::CPAN

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

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

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;

DESCRIPTION
    This module uses 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

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

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

    *   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.

    That having all been said, 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 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.

METHODS
  new_or_matching(%params)
    Provided by 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 attribute that is not flagged as unique will be ignored
    in the case of an existing instance.

FUNCTIONS
  unique($attr)
    Sugar method that can be used instead of attribute labeling. Set $attr
    to the name of an attribute and it will be unique.

    This can be used in a role even if the attribute is not defined in the
    role.