NAME
    Mail::Action::Role::Purge - purge expired objects from
    Mail::Action::Storage collections.

SYNOPSIS
     use Mail::TempAddress::Addresses;
     use Mail::Action::Role::Purge;
     use Class::Roles
        apply => {
            role => 'Purge',
            to   => 'Mail::TempAddress::Addresses',
        };
     my $addrs = Mail::TempAddress::Addresses->new( '/foo' );
     for my $addr( $addrs->object_names ) {
         print "the address for ", $addr->owner, " expires at ",
               scalar localtime($addr->expires), "\n";
         if( $addr->expires < time() ) {
             $addrs->delete_from_storage($addr);
         }
     }

DESCRIPTION
    Mail::Action::Role::Purge provides a role to allow subclasses of
    Mail::Action::Storage to retrieve the names of all object in the
    collection and remove the file on disk underlying a named object.

ROLES
  Purge
    This role should be applied to a subclass of Mail::Action::Storage. It
    allows an object of the class to iterate over all objects in the
    collection and remove named object from the collection.

    It adds several methods to the class to which it is applied:

    object_names()
        This method returns all a list of names of the objects in the
        collection. The objects are returned as a list in list context or a
        list reference in scalar context.

    num_objects()
        This method returns the number of objects in the collection. Similar
        to using

         scalar @{ $storage->object_names }

        But a bit quicker since the names themselves don't have to be passed
        from the method back to the caller.

    delete_from_storage($name)
        This method removes the file on disk that represents the named
        object. A true value is returned upon success and undef upon error.
        Inspect $! for details as to what went wrong.

    purge($min_age)
        This method is a frontend to num_objects() and
        delete_from_storage(). It gets the names of all objects in the
        collection, then in turn fetches each object and checks if it has
        expired. If it has, it deletes that object from the storage. The
        method returns the number of purged objects.

        By default each object need only be expired. Passing the
        $min_expired_age requires that the object have been expired for at
        least that many seconds. The minimum age may also be passed using a
        freeform expression like '1h30m' or '2m1w'. See "address_expires" in
        Mail::Action::Address for more details.

        For example, if an address object is set to expire at "Mon Oct 27
        19:31:39 2003" and the purge() routine is run at "19:33" with an
        argument of 300, then the data file for the object will not be
        deleted. If the purge method were to be called at "19:36:40" or any
        time thereafter then the data file will be deleted.

BACKGROUND
    This module began life as Mail::TempAddress::Addresses::Purgeable, which
    was a simple subclass of Mail::TempAddress::Addresses designed to add
    purging functionality. At the time I wasn't aware of Mail::SimpleList.

    After a few mails back and forth with chromatic, the topic of
    refactoring the common parts of Mail::TempAddress::Addresses and
    Mail::SimpleList came up, at which point the functionality provided by
    the original module made more sense to implement as a mixin.

    About a week later chromatic re-factored those common parts out into
    Mail::Action. A couple of weeks after that he re-factored the common
    parts out into roles using his new Class::Roles module and suggested
    that I implement my module as a role rather than a mixin.

ACKNOWLEDGEMENTS
    chromatic for providing tons of feedback and for developing Mail::Action
    and Class::Roles.

AUTHOR
    James FitzGibbon <jfitz@CPAN.ORG>

COPYRIGHT
    Copyright (c) 2003, James FitzGibbon. All rights reserved. This module
    is distributed under the same terms as Perl itself.

