# Array.pm: Class Used for Managing Array Structures

package RDA::Value::Array;

# $Id: Array.pm,v 1.8 2014/05/11 18:38:22 RDA Exp $
# ARCS: $Header: /home/cvs/cvs/RDA_8/src/scripting/lib/RDA/Value/Array.pm,v 1.8 2014/05/11 18:38:22 RDA Exp $
#
# Change History
# 20140511  MSC  Extend the as_data method.

=head1 NAME

RDA::Value::Array - Class Used for Managing Array Structures

=head1 SYNOPSIS

 require RDA::Value::Array;

=head1 DESCRIPTION

The objects of the C<RDA::Value::Array> class are be used for storing array
structures.

The following methods are available:

=cut

use strict;

BEGIN
{ use Exporter;
  use RDA::Text qw(get_string);
  use RDA::SDCL::Value;
  use RDA::Value::Scalar qw(:value);
}

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

# Define the global private constants

# Define the global private variables

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

=head2 S<$h = RDA::Value::Array-E<gt>new(...)>

The object constructor. You can specify some initial content as arguments.

C<RDA::Value::Array> is represented by a blessed array reference.

=cut

sub new
{ my $cls = shift;

  return bless [@_], ref($cls) || $cls;
}

=head2 S<$h = RDA::Value::Array::new_from_data(@array)>

Alternative object constructor, populating the array from a Perl list.

=cut

sub new_from_data
{ return bless [map {RDA::Value::Scalar::new_from_data($_)} @_], __PACKAGE__;
}

=head2 S<$h = RDA::Value::Array::new_from_list($ref)>

Alternative object constructor, populating the array from a RDA list.

=cut

sub new_from_list
{ my ($tbl) = @_;

  return bless [@{$tbl}], __PACKAGE__;
}

=head2 S<$h-E<gt>dump([$level[,$text[,$trace]]])>

This method returns a string containing the value dump. You can provide an
indentation level, a prefix text, and a trace indicator as extra parameters.

=cut

sub dump  ## no critic (Builtin)
{ my ($slf, $lvl, $txt, $trc) = @_;

  $lvl = 0   unless defined($lvl);
  $txt = q{} unless defined($txt);

  return dump_object($slf, {$slf => 'Array()'}, $lvl, $txt, $trc, 'Array(');
}

sub dump_object
{ my ($slf, $tbl, $lvl, $txt, $trc, $arg) = @_;
  my ($buf, $cnt, $pre);

  $pre = q{  } x $lvl++;
  $buf = $pre.$txt.'Array=[';
  $cnt = 0;
  foreach my $itm (@{$slf})
  { $buf .= qq{\n};
    if (!defined($itm))
    { $buf .= $pre.'  <undef>';
    }
    elsif (exists($tbl->{$itm}))
    { $buf .= $pre.q{  }.$tbl->{$itm};
    }
    elsif ($arg)
    { $tbl->{$itm} = "$arg$cnt)";
      $buf .= $itm->dump_object($tbl, $lvl, q{}, $trc, "$arg$cnt,");
    }
    else
    { $buf .= $itm->dump_object($tbl, $lvl, q{}, $trc);
    }
    ++$cnt;
  }
  return $cnt ? $buf.qq{\n}.$pre.q{]} : $buf.q{]};
}

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

This method indicates whether the value is a list or an array.

=cut

sub is_array
{ return 1;
}

=head1 ASSIGN AND EVAL METHODS

=head2 S<$h-E<gt>copy_value([$flag])>

This method returns a copy of the data structure.

=cut

sub copy_value
{ my ($src, $flg) = @_;

  return RDA::SDCL::Value::copy_array($src->new, $src, {}, $flg);
}

=head1 CONVERSION METHODS

=head2 S<$h-E<gt>as_data([$flag])>

This method converts the value as a list of Perl data structures. When the flag
is set, it executes code blocks.

=cut

sub as_data
{ my ($slf, $flg) = @_;

  return (RDA::SDCL::Value::conv_array([], $slf, {}, $flg));
}

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

This method converts the value as a Perl scalar.

=cut

sub as_scalar
{ return shift;
}

1;

__END__

=head1 SEE ALSO

L<RDA::Agent|RDA::Agent>,
L<RDA::SDCL::Block|RDA::SDCL::Block>,
L<RDA::SDCL::Value|RDA::SDCL::Value>,
L<RDA::Text|RDA::Text>,
L<RDA::Value::List|RDA::Value::List>,
L<RDA::Value::Scalar|RDA::Value::Scalar>

=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