# Explorer.pm: Oracle Explorer Command Package

package RDA::UI::Explorer;

# $Id: Explorer.pm,v 1.18 2015/05/08 18:17:03 RDA Exp $
# ARCS: $Header: /home/cvs/cvs/RDA_8/src/scripting/lib/RDA/UI/Explorer.pm,v 1.18 2015/05/08 18:17:03 RDA Exp $
#
# Change History
# 20150508  MSC  Improve the documentation.

=head1 NAME

RDA::UI::Explorer - Oracle Explorer Command Package

=head1 SYNOPSIS

 <rda> <options> -XExplorer <command> <switches> <arg> ...

 <sdci> <options> -XExplorer <command> <switches> <arg> ...

=head1 DESCRIPTION

The following commands are available:

=cut

use strict;

BEGIN
{ use Exporter;
  use RDA::Text qw(get_string);
  use RDA::Object::Message;
  use RDA::Object::Rda;
  use RDA::Object::View;
  use RDA::Options;
}

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

# Define the global private constants
my $TARGET = 'explorer';

# Define the global private variables
my %tb_can = (
  NoGroup => 2,
  BadMember => 3,
  );
my %tb_lst = (
  alias       => 'A',
  aliases     => 'A',
  collect     => 'C',
  collection  => 'C',
  collections => 'C',
  group       => 'G',
  groups      => 'G',
  map         => 'M',
  mapping     => 'M',
  mappings    => 'M',
  module      => 'N',
  modules     => 'N',
  name        => 'N',
  names       => 'N',
  result      => 'C',
  results     => 'C',
  run         => 'C',
  tool        => 'N',
  tools       => 'N',
  );
my %tb_typ = (
  A => 'aliases',   # Text:TtlA Text:NoA
  G => 'groups',    # Text:TtlG Text:NoG
  M => 'mappings',  # Text:TtlM Text:NoM
  N => 'names',     # Text:TtlN Text:NoN
  );

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

=head2 S<can [name...]>

This command indicates whether RDA covers all Oracle Explorer tools that are
specified as arguments.

Without arguments, it lists the Oracle Explorer collections that can be
performed by RDA.

=cut

sub can
{ my ($agt, @arg) = @_;
  my ($rsp, $val);

  # Treat the switches
  RDA::Options::getopts(q{}, \@arg);

  # Treat the arguments
  $agt->get_config->set_info('B_SUB', 1);
  $rsp = $agt->submit(q{.}, 'EXPLORER.CAN',
    beta  => (scalar $agt->get_env('XPL_EXP')),
    set   => $agt->get_collector->get_first('DEFAULT.K_FORCE_SET'),
    tools => (scalar @arg) ? [@arg] : undef);

  # Indicate the completion status
  return exists($tb_can{$val}) ? $tb_can{$val} : 1 if ($val= $rsp->is_error);
  if (ref($val = $rsp->get_value('tools')))
  { $val = join(q{ }, @{$val}).qq{\n};
    syswrite(STDOUT, $val, length($val));
  }
  return 0;
}

=head2 S<convert [-d dir] [-l lvl] [-n] [-r dir] [set...]>

This command extracts Oracle Explorer results from RDA reports using the
Oracle Explorer catalog. When you do not specify any Oracle Explorer collection
sets as arguments, all files are extracted.

The command supports the following switches:

=over 10

=item B<  -d dir>

Specifies the Oracle Explorer result directory (F<explorer> by default).

=item B<  -l lvl>

Specifies the maximum customer file management level to accept.

=item B<  -n>

Do not adjust file attributes.

=item B<  -r dir>

Specifies the RDA work directory (by default derived from the default RDA
collector).

=back

=cut

sub convert
{ my ($agt, @arg) = @_;
  my ($cfg, $dir, $opt);

  # Treat the switches
  $opt = RDA::Options::getopts('d:l:nr:', \@arg);
  $cfg = $agt->get_config;
  $opt->{'d'} = $cfg->clean_path([$cfg->get_work, $opt->{'d'}, q{}], 1)
    if exists($opt->{'d'}) && !$cfg->is_absolute($opt->{'d'});

  # Set the collector
  if (exists($opt->{'r'}))
  { die get_string('BAD_DIR', $opt->{'r'})
      unless defined($dir = $agt->get_system->test_dir('d', $opt->{'r'}, 1));
    _set_collector($agt, $dir);
  }
  else
  { _set_collector($agt,
      defined($dir = $agt->get_system->test_dir('d', $agt->get_info('zip')))
      ? $dir
      : RDA::Object::Rda->current_dir);
  }

  # Perform the conversion
  return $agt->submit(q{.}, 'EXPLORER.CONVERT',
    directory => $opt->{'d'},
    maximum   => $opt->{'l'},
    native    => $opt->{'n'},
    sets      => (scalar@arg) ? [@arg] : undef);
}

=head2 S<help>

This command displays the command syntax and the related explanations.

=cut

sub help
{ return shift->submit(q{.}, 'DISPLAY.DSP_POD', package => __PACKAGE__);
}

=head2 S<list [-ACGMN] [set...]>

This command lists the available Oracle Explorer tools or the Oracle Explorer
collections that can be extracted from the RDA reports.

You can restrict the list by specifying following switches:

=over 7

=item B<  -A > Lists the Oracle Explorer tool aliases.

=item B<  -C > Lists the Oracle Explorer collections available in RDA reports.

=item B<  -G > Lists the Oracle Explorer tool groups.

=item B<  -M > Lists how the Oracle Explorer tools are implemented.

=item B<  -N > Lists the Oracle Explorer tool names.

=back

or following keywords:

=over 15

=item B<  aliases>

Lists the Oracle Explorer tool aliases.

=item B<  collections>

Lists the Oracle Explorer collections that can be extracted from the RDA
reports (the default set).

=item B<  groups>

Lists the Oracle Explorer tool groups.

=item B<  mappings>

Lists how the Oracle Explorer tools are implemented.

=item B<  names>

Lists the Oracle Explorer tool names.

=back

=cut

sub list
{ my ($agt, @arg) = @_;
  my ($buf, $opt, $sep);

  # Determine the list types
  $opt = RDA::Options::getopts('ACGMN', \@arg);
  foreach my $typ (@arg)
  { $typ = lc($typ);
    die get_string('BAD_LIST', $typ) unless exists($tb_lst{$typ});
    $opt->{$tb_lst{$typ}} = 1;
  }

  # Produce requested lists
  $agt->get_config->set_info('B_SUB', 1);
  $buf = q{};
  $sep = qq{.N1\n};
  $buf .= _get_list($agt, 'N', $buf ? $sep : q{}) if exists($opt->{'N'});
  $buf .= _get_list($agt, 'A', $buf ? $sep : q{}) if exists($opt->{'A'});
  $buf .= _get_list($agt, 'G', $buf ? $sep : q{}) if exists($opt->{'G'});
  $buf .= _get_list($agt, 'M', $buf ? $sep : q{}) if exists($opt->{'M'});
  $buf .= _get_report($agt,    $buf ? $sep : q{}) if exists($opt->{'C'});

  # Produce default lists
  $buf = _get_report($agt, q{}) unless $buf;

  # Display the report and indicate the completion status
  return $agt->submit(q{.}, RDA::Object::Message->new('DISPLAY.DSP_REPORT',
    page => 1)->add_data($buf));
}

# Produce a tool report
sub _get_list
{ my ($agt, $typ, $sep) = @_;
  my ($buf, $rsp);

  # Get the multi-run collection list
  $rsp = $agt->submit(q{.}, 'EXPLORER.LIST',
    beta        => (scalar $agt->get_env('XPL_EXP')),
    description => 1,
    set         => $agt->get_collector->get_first('DEFAULT.K_FORCE_SET'),
    type        => $tb_typ{$typ});
  $agt->abort if $rsp->is_error($agt, get_string('ERR_LIST'));

  # Produce the report
  return ($buf = $rsp->get_data)
    ? $sep.q{.M 2 '}.get_string('Ttl'.$typ).qq{'\n}.$buf.qq{\n}
    : $sep._no_list('No'.$typ);
}

# Produce a collection report
sub _get_report
{ my ($agt, $sep) = @_;
  my ($dir, $rsp, @tbl);

  # Set the collector
  eval {_set_collector($agt,
    defined($dir = $agt->get_system->test_dir('d', $agt->get_info('zip')))
    ? $dir
    : RDA::Object::Rda->current_dir)};

  # Get and report the collections
  unless ($@)
  { # Request the list
    $rsp = $agt->submit(q{.}, 'EXPLORER.REPORT');
    $agt->abort if $rsp->is_error($agt, get_string('ERR_REPORT'));

    # Produce the report
    return $sep.q{.M 2 '}.get_string('TtlC').qq{'\n}
      .join(q{}, map {qq{$_|\\040\n}} sort @tbl).qq{\n}
      if (@tbl = $rsp->get_value('collections'));
  }

  # Indicate that no collections have been found
  return $sep._no_list('NoC');
}

# Report an empty list
sub _no_list
{ my ($txt) = @_;

  return q{.T'}.get_string($txt).qq{'\n};
}

=head2 S<man name...>

This command displays the man pages associated with the specified tools. The
operating system "pager" mechanism must be configured to pause at the end of
the page to support multiple arguments in interactive mode.

=cut

sub man
{ my ($agt, @arg) = @_;
  my ($cfg, $dir, $rsp, %mod);

  # Treat the switches
  RDA::Options::getopts(q{}, \@arg);

  # Get the name/module mapping
  $rsp = $agt->submit(q{.}, 'EXPLORER.LIST',
    beta => (scalar $agt->get_env('XPL_EXP')),
    set  => $agt->get_collector->get_first('DEFAULT.K_FORCE_SET'),
    type => 'mappings');
  $agt->abort if $rsp->is_error($agt, get_string('ERR_LIST'));
  %mod = $rsp->get_value('list');

  # Treat the arguments
  $cfg = $agt->get_config;
  $dir = $cfg->get_group('D_RDA_COL');
  foreach my $arg (@arg)
  { $agt->submit(q{.}, 'DISPLAY.DSP_POD',
      file => $cfg->cat_file($dir, split(/:/, $mod{$arg}.'.ctl')),
      page => 1)->is_error($agt) if exists($mod{$arg});
  }

  # Indicate a successful completion
  return 0;
}

=head2 S<render [-d dir] [-f] [-t theme]>

This command renders the RDA reports contained in the Oracle Explorer result
directory structure.

The command supports the following switches:

=over 12

=item B<  -d dir>

Specifies the Oracle Explorer result directory (the current directory by
default).

=item B<  -f>

Generates all reports.

=item B<  -t theme>

Uses the specified theme for rendering the reports.

=back

=cut

sub render
{ my ($agt, @arg) = @_;
  my ($dir, $opt);

  # Treat the switches
  $opt = RDA::Options::getopts('d:ft:', \@arg);

  # Set the collector
  if (exists($opt->{'d'}))
  { die get_string('BAD_DIR', $opt->{'d'})
      unless defined($dir = $agt->get_system->test_dir('d', $opt->{'d'}));
    _set_collector($agt, $dir);
  }
  else
  { _set_collector($agt,
      defined($dir = $agt->get_system->test_dir('d', $agt->get_info('zip')))
      ? $dir
      : RDA::Object::Rda->current_dir);
  }

  # Render the RDA reports
  return $agt->submit(q{.}, 'RENDER.GEN_HTML',
    force => $opt->{'f'},
    start => 'RDA_END_report.htm',
    theme => $opt->{'t'});
}

=for stopwords cnrst

=head2 S<run [-cnrst] -d dir [name...]>

This command performs data collection for Oracle explorer. It accepts a
comma-separated list of tool names as arguments.

The command supports the following switches:

=over 10

=item B<  -c>

Converts the RDA reports in Oracle Explorer results.

=item B<  -d dir>

Specifies the Oracle Explorer result directory.

=item B<  -n>

Do not adjust file attributes.

=item B<  -r>

Renders the RDA reports.

=item B<  -s>

Saves the setup information.

=item B<  -t>

Activates the trace mode for the Oracle Explorer collections.

=back

=cut

sub run
{ my ($agt, @arg) = @_;
  my ($opt);

  # Treat the switches
  $opt = RDA::Options::getopts('cd:rts', \@arg);

  # Perform the data collection
  $agt->get_config->set_info('B_SUB', 1);
  $agt->submit(q{.}, 'EXPLORER.RUN',
    beta  => (scalar $agt->get_env('XPL_EXP')),
    tools => (scalar @arg) ? [@arg] : undef,
    save  => $opt->{'s'},
    set   => $agt->get_collector->get_first('DEFAULT.K_FORCE_SET'),
    trace => $opt->{'t'})->is_error($agt);

  # When requested, convert the results
  $agt->submit(q{.}, 'EXPLORER.CONVERT',
    directory => $opt->{'d'},
    native    => $opt->{'n'})->is_error($agt) if $opt->{'c'};

  # When requested, render the results
  $agt->submit(q{.}, 'RENDER.GEN_HTML')->is_error($agt) if $opt->{'r'};

  # Indicate a successful completion
  return 0;
}

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

# Set the collector
sub _set_collector
{ my ($agt, $dir) = @_;
  my ($cfg, $top);

  # Detect the RDA results
  $cfg = $agt->get_config;
  die get_string('NO_RDA')
    unless -f $cfg->cat_file($top = $cfg->cat_dir($dir, 'rda'), 'RDA.log') ||
           -f $cfg->cat_file($top = $dir, 'RDA.log') ||
           -f $cfg->cat_file($top = $cfg->up_dir, 'RDA.log');
  $top = $cfg->clean_path([$cfg->get_work, $top, q{}], 1)
    unless $cfg->is_absolute($top);
  die get_string('NO_COLLECT')
    unless -d $cfg->cat_dir($top, 'collect');
  chdir($top) or die get_string('ERR_CD', $top, $!);

  # Create the corresponding collector
  $cfg->set_info('B_CURRENT', 1);
  $cfg->set_info('D_CWD',     $top);
  $agt->get_collector(1)->set_value('OUTPUT.B_CLEAN', 0);
  return;
}

1;

__END__

=head1 SEE ALSO

L<RDA::Agent|RDA::Agent>,
L<RDA::Object|RDA::Object>,
L<RDA::Object::Collect|RDA::Object::Collect>,
L<RDA::Object::Content|RDA::Object::Content>,
L<RDA::Object::Message|RDA::Object::Message>,
L<RDA::Object::Rda|RDA::Object::Rda>,
L<RDA::Object::View|RDA::Object::View>,
L<RDA::Options|RDA::Options>,
L<RDA::Request::DISPLAY|RDA::Request::DISPLAY>,
L<RDA::Request::EXPLORER|RDA::Request::EXPLORER>,
L<RDA::Request::RDA|RDA::Request::RDA>,
L<RDA::Text|RDA::Text>

=head1 COPYRIGHT NOTICE

Copyright (c) 2002, 2016, Oracle. All rights reserved.

=head1 TRADEMARK NOTICE

Oracle is a registered trademark of Oracle Corporation and/or its
affiliates. Other names may be trademarks of their respective owners.

=cut