# Extra.pm: Extra Collection Command Package

package RDA::UI::Extra;

# $Id: Extra.pm,v 1.10 2015/05/08 18:17:03 RDA Exp $
# ARCS: $Header: /home/cvs/cvs/RDA_8/src/scripting/lib/RDA/UI/Extra.pm,v 1.10 2015/05/08 18:17:03 RDA Exp $
#
# Change History
# 20150424  MSC  Introduce the control agent concept.

=head1 NAME

RDA::UI::Extra - Extra Collection Command Package

=head1 SYNOPSIS

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

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

=head1 DESCRIPTION

This package regroups additional commands to manage the collection of
additional information.

The following commands are available:

=cut

use strict;

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

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

# Define the global private constants

# Define the global private variables
my %tb_del = map {$_=> 1}
  qw(del_cmd del_data del_dir del_extra del_file del_files del_smpl);

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

=head2 S<add command title path [arg...]>

This command adds an operating system command to collect information. It
supports the following arguments:

=over 9

=item B<  title>

Specifies the report title.

=item B<  path>

Specifies the path of the operating system command to execute.

=item B<  arg>

Lists the command arguments.

=back

=head2 S<add data path...>

This command adds the specified binary files to the list of extra elements to
collect.

=head2 S<add directory path [pattern [options]]>

This command adds a directory to analyze. RDA will collect from it all files
matching the associated pattern and search options. It support the following
arguments:

=over 11

=item B<  options>

Specifies the search options.

=item B<  path>

Specifies the path of the directory to analyze.

=item B<  pattern>

Specifies a Perl regular expression used for selecting or rejecting files.

=back

The valid options are:

=over 7

=item B<  'i' >

Ignores case distinctions in both the pattern and the results.

=item B<  'p' >

Converts the paths to a full path (implied).

=item B<  'r' >

Searches files recursively under each subdirectory. To avoid loops in the
directory structure, the recursion level is limited to 8.

=item B<  'v' >

Inverts the sense of matching to select non-matching files.

=back

=head2 S<add files path...>

This command adds the specified files to the list of extra elements to collect.

=head2 S<add sample name path [arg...]>

This command adds an operating system command to sample. It supports the
following arguments:

=over 8

=item B<  name>

Specifies the name of the report used to accumulate the corresponding
samples. It must start with a letter.

=item B<  path>

Specifies the path of the operating system command to execute.

=item B<  arg>

Lists the command arguments.

=back

=cut

sub add
{ my ($agt, @arg) = @_;
  my ($cmd, $nam, $opt, $pat, $pth);

  RDA::Options::getopts(q{}, \@arg);
  if (defined($cmd = shift(@arg)))
  { @arg = map {RDA::Object::decode($_)} @arg;
    if ($cmd =~ m/^(cmd|command)$/i)  ## no critic (Fixed)
    { die get_string('NO_TITLE')   unless defined($nam = shift(@arg));
      die get_string('NO_COMMAND') unless @arg;
      return $agt->submit(q{.}, 'EXTRA.ADD_CMD',
        command => [@arg],
        save    => 1,
        title   => $nam);
    }
    if ($cmd eq 'data')
    { return $agt->submit(q{.}, 'EXTRA.ADD_DAT',
        files => [@arg],
        save  => 1);
    }
    if ($cmd =~ m/^dir(ectory)?$/i)
    { die get_string('NO_DIRECTORY') unless defined($pth = shift(@arg));
      $pat = shift(@arg);
      $opt = shift(@arg);
      return $agt->submit(q{.}, 'EXTRA.ADD_DIR',
        directory => $pth,
        pattern   => $pat,
        options   => $opt,
        save      => 1);
    }
    if ($cmd =~ m/^files?/i)
    { return $agt->submit(q{.}, 'EXTRA.ADD_FIL',
        files => [@arg],
        save  => 1);
    }
    if ($cmd =~ m/^sa?mple?$/i)
    { die get_string('NO_NAME')
        unless defined($nam = shift(@arg)) && $nam =~ m/^[A-Za-z]/;
      die get_string('NO_COMMAND')
        unless defined($cmd = shift(@arg));
      return $agt->submit(q{.}, 'EXTRA.ADD_SMP',
        command => [$cmd, @arg],
        name    => $nam,
        save    => 1);
    }
    die get_string('ERR_ADD', $cmd);
  }
  return 0;
}

=head2 S<delete [-a|pos[-pos]...]>

This command deletes files or directories from the list of extra elements to
collect. It supports the following switches and arguments:

=over 8

=item B<  -a>

Deletes all elements.

=item B<  pos>

Deletes specific elements, which are referenced by their position in the report
produced by the C<list> command. RDA discards any offset that is not integer
number greater than zero or that is not an offset range, where two offsets are
separated by a dash.


=back

=cut

sub delete  ## no critic (Builtin)
{ my ($agt, @arg) = @_;
  my ($opt);

  $opt = RDA::Options::getopts('a', \@arg);
  return $agt->submit(q{.}, 'EXTRA.DELETE',
    all     => $opt->{'a'},
    offsets => @arg ? [@arg] : undef,
    save    => 1)
}

=head2 S<export>

This command exports the extra collection settings. It generates commands to
re-create them.

=cut

sub export
{ return shift->submit(q{.}, 'EXTRA.EXPORT');
}

=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>

This command lists the extra elements to collect.

=cut

sub list
{ return shift->submit(q{.}, 'EXTRA.LIST');
}

# --- Command execution routines ----------------------------------------------

sub exec  ## no critic (Builtin)
{ my ($agt, $cmd, @arg) = @_;

  RDA::Options::getopts(q{}, \@arg);
  ## no critic (Ampersand)
  return 0                    if $cmd =~ m/^(add|del)_env$/;
  return &add($agt, $1, @arg) if $cmd =~ m/^add_(\w+)$/;
  return &delete($agt, @arg)  if exists($tb_del{$cmd});
  die get_string('ERR_COMMAND', $cmd);
}

1;

__END__

=head1 NOTE

Any deletion operation causes the removal of the data previously collected by
the C<RDA.EXTRA> and C<SAMPLE.EXTRA> modules.

=head1 SEE ALSO

L<RDA::Agent|RDA::Agent>,
L<RDA::Object|RDA::Object>,
L<RDA::Object::Item|RDA::Object::Item>,
L<RDA::Object::Message|RDA::Object::Message>,
L<RDA::Options|RDA::Options>,
L<RDA::Request::DISPLAY|RDA::Request::DISPLAY>
L<RDA::Request::EXTRA|RDA::Request::EXTRA>
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