# Results.pm: Class Used to Manage RDA Results

package RDA::Driver::Results;

# $Id: Results.pm,v 1.11 2014/07/21 18:51:19 RDA Exp $
# ARCS: $Header: /home/cvs/cvs/RDA_8/src/scripting/lib/RDA/Driver/Results.pm,v 1.11 2014/07/21 18:51:19 RDA Exp $
#
# Change History
# 20140721  MSC  Skip CVS directories in scans.

=head1 NAME

RDA::Driver::Results - Class Used to Manage RDA Results

=head1 SYNOPSIS

 require RDA::Driver::Results;

=head1 DESCRIPTION

The objects of the C<RDA::Driver::Results> class are used to manage RDA
results.

The following methods are available:

=cut

use strict;

BEGIN
{ use Exporter;
  use IO::File;
  use RDA::Text qw(get_string);
  use RDA::Object::Rda;
}

# Define the global public variables
use vars qw($STRINGS $VERSION @ISA);
$VERSION = sprintf('%d.%02d', q$Revision: 1.11 $ =~ /(\d+)\.(\d+)/);
@ISA     = qw(Exporter);

# Define the global private constants

# Define the global private variables

# Report the package version
sub Version
{ return $VERSION;
}

=head2 S<$h = RDA::Driver::Results-E<gt>new($pth)>

The object constructor. This method takes the result path as an argument.

C<RDA::Driver::Results> is represented by a blessed hash reference. The
following special keys are used:

=over 12

=item S<    B<'top' > > Results top directory

=item S<    B<'_pth'> > Path to the current file.

=back

Internal keys are prefixed by an underscore.

=cut

sub new
{ my ($cls, $pth) = @_;

  # Create the object and return its reference
  return bless {
    top  => RDA::Object::Rda->cat_dir($pth),
    }, ref($cls) || $cls;
}

=head2 S<$h-E<gt>delete_object>

This method deletes the result control object.

=cut

sub delete_object
{ # Delete the object
  undef %{$_[0]};
  undef $_[0];
  return;
}

=head2 S<$h-E<gt>find_handle($sig)>

This method returns a file handle to the specified result.

=cut

sub find_handle
{ my (undef, $sig) = @_;
  my ($ifh);

  $ifh = IO::File->new;
  return $ifh->open("<$sig") ? $ifh : undef;
}

=head2 S<$h-E<gt>scan($fct[,@arg])>

This method scans the result directory structure. For each file found inside
the archive, it calls the specified function with the following arguments: the
file name, a reference to the result control object, and the specified function
arguments. It stops the processing when the function returns a true value.

=cut

sub scan
{ my ($slf, $fct, @arg) = @_;

  # Analyze the archive
  return -2 unless opendir(RES, $slf->{'top'});
  _scan($slf, $slf->{'top'}, undef, $fct, @arg);

  # Return the completion status
  return 0;
}

sub _scan
{ my ($slf, $bas, $dir, $fct, @arg) = @_;
  my ($pth, $rel, $ret, @sub);

  # Scan the directory
  foreach my $nam (readdir(RES))
  { $rel = defined($dir) ? join(q{/},$dir, $nam) : $nam;
    $pth = RDA::Object::Rda->cat_file($bas, $rel);
    push(@sub, $rel) if -d $pth && -r $pth && $nam !~ m/^(?:\.+|CVS)$/;
    $slf->{'_pth'} = $pth;
    last if -f $pth && ($ret = &$fct($rel, $slf, @arg));
  }
  closedir(RES);

  # Explore subdirectories
  unless ($ret) #++$lvl > $max)
  { foreach my $sub (@sub)
    { next unless opendir(RES, RDA::Object::Rda->cat_dir($bas, $sub));
      return 1 if _scan($slf, $bas, $sub, $fct, @arg);
    }
  }

  # Propagate abort
  return $ret;
}

=head1 HEADER EMULATION METHODS

=head2 S<$h-E<gt>get_handle>

This method returns a file handle to the corresponding file or an undefined
value in case of problems.

=cut

sub get_handle
{ my ($ifh);

  $ifh = IO::File->new;
  return $ifh->open('<'.shift->{'_pth'}) ? $ifh : undef;
}

=head2 S<$h-E<gt>get_info($name)>

This method is provided for compatibility.

=cut

sub get_info
{ return q{};
}

=head2 S<$h-E<gt>get_position>

This method is provided for compatibility.

=cut

sub get_position
{ return q{};
}

=head2 S<$h-E<gt>get_signature>

This method returns the path to the result file.

=cut

sub get_signature
{ return shift->{'_pth'};
}

1;

=head1 SEE ALSO

L<RDA::Agent|RDA::Agent>,
L<RDA::Object|RDA::Object>,
L<RDA::Object::Rda|RDA::Object::Rda>,
L<RDA::Text|RDA::Text>

=head1 COPYRIGHT NOTICE

Copyright (c) 2002, 2016, Oracle and/or its affiliates. All rights reserved.

=head1 TRADEMARK NOTICE

Oracle and Java are registered trademarks of Oracle and/or its
affiliates. Other names may be trademarks of their respective owners.

=cut