# MRC.pm: Multi-Run Collection Command Library

package RDA::Request::MRC;

# $Id: MRC.pm,v 1.9 2015/04/29 13:52:05 RDA Exp $
# ARCS: $Header: /home/cvs/cvs/RDA_8/src/scripting/lib/RDA/Request/MRC.pm,v 1.9 2015/04/29 13:52:05 RDA Exp $
#
# Change History
# 20150424  MSC  Introduce the control agent concept.

=head1 NAME

RDA::Request::MRC - Multi-Run Collection Command Library

=head1 SYNOPSIS

 require RDA::Request::RDA;

=head1 DESCRIPTION

The objects of the C<RDA::Request::MRC> class are used to interface with
multi-run collections.

The following methods are available:

=cut

use strict;

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

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

# Define the global private constants

# Define the global private variables
my %tb_cmd = (
  'MRC.CHECK'   => \&_do_check,
  'MRC.DISPLAY' => \&_do_display,
  'MRC.LIST'    => \&_do_list,
  'MRC.XREF'    => \&_do_xref,
  );

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

=head2 S<$h = RDA::Request::RDA-E<gt>new($agt)>

The object constructor. This method enables you to specify the agent reference
as an argument.

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

=over 10

=item S<  B<'_agt'> > Reference to the agent object

=item S<  B<'_cfg'> > Reference to the RDA software configuration

=item S<  B<'_ctl'> > Reference to the control object

=item S<  B<'_dir'> > Collect directory structure

=back

Internal keys are prefixed by an underscore.

=cut

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

  # Create the library object and return the object reference
  $cfg = $agt->get_config;
  return bless {
    _agt => $agt,
    _cfg => $cfg,
    _ctl => $agt->get_collector->get_mrc,
    _dir => $cfg->get_group('D_RDA_COL'),
    }, ref($cls) || $cls;
}

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

This method deletes the library object.

=cut

sub delete_object
{ RDA::Object::dump_caller($_[0], 'Commands') if $RDA::Object::DELETE;
  undef %{$_[0]};
  undef $_[0];
  return;
}

=head2 S<$h-E<gt>exec_command($req)>

This method executes the command specified in the message.

=cut

sub exec_command
{ my ($slf, $req) = @_;

  my $cmd = $req->{'msg'};
  return exists($tb_cmd{$cmd})
    ? &{$tb_cmd{$cmd}}($slf, $req)
    : $req->error('NotImplemented', get_string('BAD_COMMAND', $cmd));
}

=head1 MRC COMMANDS

=head2 MRC.CHECK - Check command

This command checks a multi-run collection definition file. It supports the
following attribute:

=over 14

=item B<  definition>

Specifies the file to check.

=back

=cut

sub _do_check
{ my ($slf, $req) = @_;
  my ($pth);

  # Validate the attribute
  return $req->error('NoDefinition')
    unless defined($pth = $req->get_first('definition'));

  # Check the requested file
  eval {$slf->{'_ctl'}->load($pth, _get_group($pth))};

  # Return the completion status
  return $req->reply($@, 'Check');
}

=head2 MRC.DISPLAY - Display command

This command displays the manual page of the specified multi-run collection. It
supports the following attributes:

=over 12

=item B<  groups>

When present, restricts the definition search to the specified groups, the
C<RDA> group, and the content of the file referenced by the C<RDA_MRC>
environment variable.

=item B<  name>

Specifies the multi-run collection name.

=item B<  settings>

When the true, it includes the settings (false by default).

=back

=cut

sub _do_display
{ my ($slf, $req) = @_;
  my ($buf, $col, $def, $grp, $nam);

  # Validate the attribute
  return $req->error('NoName')
    unless defined($col = $req->get_first('name'));

  # Generate the manual page
  eval {
    $grp = $req->get_value('groups');
    ($def, $nam) = $slf->{'_ctl'}->get_collection($col, $grp);
    die get_string('NO_COLLECTION', $col) unless ref($def);
    $buf = $def->display($nam, $req->get_first('settings'));
    };
  $req->add_error($@) if $@;

  # Display the manual page
  return $req->has_errors
    ? $req->error('Display')
    : _display($slf, $req, 'OK.Display', $buf);
}

=head2 PROFILE.LIST - List command

This command lists all corresponding multi-run collections. It supports the
following attributes:

=over 15

=item B<  description>

When true, includes the description as data.

=item B<  groups>

When present, restricts the definition search to the specified groups, the
C<RDA> group, and the content of the file referenced by the C<RDA_MRC>
environment variable.

=item B<  set>

When present, restricts the definition search to the specified set.

=back

=cut

sub _do_list
{ my ($slf, $req) = @_;
  my ($buf, $def, $grp, $set, @tbl);

  # Get the list of multi-run collections
  eval {
    # Select the multi-run collection definition files
    $grp = $req->get_value('groups');
    $set = $slf->find_set($grp, $set)
      if defined($set = $req->get_first('set'));
    $def = $slf->{'_ctl'}->get_collections($set);
    @tbl = sort keys(%{$def});

    # Get the descriptions when requested
    $buf = join(q{},
      map {$_.q{|}.$def->{$_}->get_title($_, q{}).qq{\n}} @tbl)
      if $req->get_first('description');
  };
  $req->add_error($@) if $@;

  # Return the completion status
  return $req->has_errors
    ? $req->error('List')
    : $req->new('OK.List', mrc => [@tbl])->add_data($buf);
}

=head2 MRC.XREF - Cross-reference command

This command produces a cross-reference of existing multi-run collection
definitions. It supports the following attributes:

=over 14

=item B<  all>

When true, includes all entries in the cross-reference. By default, it
considers the entries with a title only.

=item B<  definition>

When present, restricts the cross-reference to the specified definition file.

=item B<  groups>

When present, restricts the definition search to the specified groups, the
C<RDA> group, and the content of the file referenced by the C<RDA_MRC>
environment variable.

=back

=cut

sub _do_xref
{ my ($slf, $req) = @_;
  my ($buf, $ctl, $grp, $pth);

  # Generate the cross-reference
  eval {
    $ctl = $slf->{'_ctl'};
    $buf = $ctl->xref(
      !defined($pth = $req->get_first('definition'))
        ? $ctl->select($grp = $req->get_value('groups')) :
      defined($grp = _get_group($pth))
        ? {$grp => $ctl->load($pth, $grp)} :
      {'<GRP>' => $ctl->load($pth)}, $req->get_first('all'));
    };
  $req->add_error($@) if $@;

  # Display the cross-reference
  return $req->has_errors
    ? $req->error('Xref')
    : _display($slf, $req, 'OK.Xref', $buf);
}

# --- Internal routines -------------------------------------------------------

# Display the result
sub _display
{ my ($slf, $req, $sta, $buf) = @_;
  my ($err, $msg);

  $msg = RDA::Object::Message->new('DISPLAY.DSP_REPORT',
    page => 1)->add_data($buf);
  return ($err = $slf->{'_agt'}->submit(q{.}, $msg)->is_error($req))
    ? $req->error($err)
    : $req->new($sta);
}

# Determine the group name
sub _get_group
{ my ($pth) = @_;
  my ($grp, $ifh);

  $ifh = IO::File->new;
  if ($ifh->open('<'.RDA::Object::Rda->cat_file(RDA::Object::Rda->dirname($pth),
    'group.cfg')))
  { while (<$ifh>)
    { if (m/^\[([A-Z][A-Z\d]*)\]/)
      { $grp = $1;
        last;
      }
    }
    $ifh->close;
  }
  return $grp;
}

1;

__END__

=head1 SEE ALSO

L<RDA::Agent|RDA::Agent>,
L<RDA::Error|RDA::Error>,
L<RDA::Object|RDA::Object>,
L<RDA::Object::Message|RDA::Object::Message>,
L<RDA::Object::Rda|RDA::Object::Rda>,
L<RDA::Request::DISPLAY|RDA::Request::DISPLAY>,
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