view release on metacpan or  search on metacpan

lib/Algorithm/Dependency/Source.pm  view on Meta::CPAN

package Algorithm::Dependency::Source;
# ABSTRACT: Implements a source of hierarchy items

#pod =pod
#pod
#pod =head1 DESCRIPTION
#pod
#pod The Algorithm::Dependency::Source class provides an abstract parent class for
#pod implementing sources for the hierarchy data the algorithm will use. For an
#pod example of an implementation of this, see
#pod L<Algorithm::Dependency::Source::File>, which is bundled with the main
#pod L<Algorithm::Dependency> package.
#pod
#pod =head1 METHODS
#pod
#pod =cut

use 5.005;
use strict;
use Algorithm::Dependency ();
use Params::Util qw{_SET};

our $VERSION = '1.112';


#####################################################################
# Constructor

#pod =pod
#pod
#pod =head2 new @arguments
#pod
#pod Although you cannot directly use the C<new> constructor for
#pod C<Algorithm::Dependency::Source>, it will work the same in all subclasses.
#pod
#pod The constructor takes zero or more subclass specific arguments to define the
#pod location of the source of the items, and returns a new object. Although it
#pod may check that the arguments you passed are valid, the source will usually
#pod NOT actually load the items from the source, instead deferring the loading
#pod until you need to use the items.
#pod
#pod Returns a new object on success, or C<undef> on error.
#pod
#pod =cut

sub new {
	my $class = shift;

	# This can't be created directly, it must be through
	# a SUPER::new call
	if ( $class eq __PACKAGE__ ) {
		die "Cannot directly instantiate Algorithm::Dependency::Source."
			. " You must use a subclass";
	}

	# Create the basic object
	my $self = bless {
		# Has the source been loaded
		loaded      => 0,

		# Indexes
		items_hash  => undef,
		items_array => undef,
		}, $class;

	$self;
}

#pod =pod
#pod
#pod =head2 load
#pod
#pod The C<load> method is the public method used to actually load the items from
#pod their storage location into the the source object. The method will
#pod automatically called, as needed, in most circumstances. You would generally
#pod only want to use C<load> manually if you think there may be some uncertainty
#pod that the source will load correctly, and want to check it will work.
#pod
#pod Returns true if the items are loaded successfully, or C<undef> on error.
#pod
#pod =cut

sub load {
	my $self = shift;

	# If this is a reload, clean up in preperation
	if ( $self->{loaded} ) {
		$self->{loaded}      = 0;
		$self->{items_hash}  = undef;
		$self->{items_array} = undef;
	}

	# Pass through to the real loader
	my $items = $self->_load_item_list;
	return $items unless $items;
	unless ( _SET($items, 'Algorithm::Dependency::Item') ) {
		die( ref($self) . "::_load_item_list did not return an Algorithm::Dependency::Item set" );
	}

	# Add the items
	foreach my $item ( @$items ) {
		# Have we added this one already?
		my $id = $item->id;
		if ( $self->{items_hash}->{ $id } ) {
			# Duplicate entry
			return undef;
		}

		# Add it
		push @{ $self->{items_array} }, $item;