Array::Tour::RandomWalk - Return coordinates to take a random path.

      use Array::Tour::RandomWalk qw(:directions);

      my $rndwalk = Array::Tour::RandomWalk->new(
          dimensions => [13, 7, 1],
	  start => [0, 0, 0]
	  backtrack => "queue",
	  );

  $self->_set(%attributes);

  @directions = $obj->_collect_dirs($c, $r, $l);

package Array::Tour::RandomWalk;
use 5.008;
use strict;
use warnings;
use integer;
use base q(Array::Tour);
use Array::Tour qw(:directions :status);

our $VERSION = '0.06';

sub direction()
{
	my $self = shift;
	return ($self->{tourstatus} == STOP)? NoDirection: $self->{direction};
}

sub next
{
	my $self = shift;

	return undef unless ($self->has_next());

	my @dir = $self->_collect_dirs();

#	print "Position => [", join(", ", @{$self->get_position()}), "]\n",
#		"Can go (", join(", ", (map{$self->direction_name($_)} @dir)), ")\n";
	#
	# There is a cell to break into.
	#
	if (@dir > 0)
	{
		my $p = $self->{position};

		#
		# If there were multiple choices, save it
		# for future reference.
		#
		push @{ $self->{plist} }, $p if (@dir > 1);

		#
		# Choose a wall at random and break into the next cell.
		#
		$self->{direction} = $self->{wander}->(\@dir, $p);
		$self->_break_through();
		++$self->{odometer};
	}
	else	# No place to go, back up.
	{
		if (@{ $self->{plist} } == 0)	# No place to back up, quit.
		{
			$self->{tourstatus} = STOP;
			return undef;
		}

		$self->{direction} = SetPosition;
		if ($self->{backtrack} eq 'stack')
		{
			$self->{position} = pop @{ $self->{plist} };
		}
		elsif ($self->{backtrack} eq 'random')
		{
			$self->{position} = splice @{ $self->{plist} }, rand @{ $self->{plist} }, 1;
		}
		else
		{
			$self->{position} = shift @{ $self->{plist} };
		}
	}

#	print "\n********\n", $self->dump_array(), "\n********\n";

	return $self->adjusted_position();
}

sub _set
{
	my $self = shift;
	my(%params) = @_;

	#
	# Parameter checks.
	#
	warn "Unknown paramter $_" foreach (grep{$_ !~ /backtrack|wander|start/} (keys %params));
	$params{start} ||= [0, 0, 0];
	$params{backtrack} ||= "queue";

	#
	# We've got the dimensions, now set up an array.
	#
	$self->_make_array();

	$self->{position} = $self->{start} = $params{start};
	$self->{wander} = $params{wander} || \&_random_dir;
	$self->{backtrack} = $params{backtrack};

	$self->{plist} = ();

	return $self;
}

sub _random_dir
{
	return ${$_[0]}[int(rand(@{$_[0]}))];
}

sub _collect_dirs
{
	my $self = shift;
	my($c, $r, $l) = @{ $self->{position} };
	my $m = $self->get_array();
	my($c_siz, $r_siz, $l_siz) = map {$_ - 1} $self->get_dimensions();
	my @dir;

	#
	# Search for enclosed cells in a partially sorted order,
	# starting from North and going counter-clockwise (Ceiling
	# and Floor will always be pushed last).
	#
	push(@dir, North)    if ($r > 0 and $$m[$l][$r - 1][$c] == 0);
	push(@dir, West)     if ($c > 0 and $$m[$l][$r][$c - 1] == 0);
	push(@dir, South)    if ($r < $r_siz and $$m[$l][$r + 1][$c] == 0);
	push(@dir, East)     if ($c < $c_siz and $$m[$l][$r][$c + 1] == 0);
	push(@dir, Ceiling)  if ($l > 0 and $$m[$l - 1][$r][$c] == 0);
	push(@dir, Floor)    if ($l < $l_siz and $$m[$l + 1][$r][$c] == 0);
	return @dir;
}

sub _break_through
{
	my $self = shift;
	my $dir = $self->{direction};
	my($c, $r, $l) = @{$self->{position}};
	my $m = $self->get_array();

	$$m[$l][$r][$c] |= $dir;
	($c, $r, $l) = @{$self->_move_to($dir)};
	$$m[$l][$r][$c] |= $self->opposite_direction($dir);
	$self->{position} = [$c, $r, $l];
}

1;
__END__