# Internal.pm: Class Used for Managing Internal Variables

package RDA::Value::Internal;

# $Id: Internal.pm,v 1.6 2013/11/22 11:35:03 RDA Exp $
# ARCS: $Header: /home/cvs/cvs/RDA_8/src/scripting/lib/RDA/Value/Internal.pm,v 1.6 2013/11/22 11:35:03 RDA Exp $
#
# Change History
# 20131021  MSC  Make code more strict.

=head1 NAME

RDA::Value::Internal - Class Used for Managing Internal Variables

=head1 SYNOPSIS

 require RDA::Value::Internal;

=head1 DESCRIPTION

The objects of the C<RDA::Value::Internal> class are used to manage internal
variables.

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;
}

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

# Define the global private constants

# Define the global private variables
my %tb_key = (
  'error'   => 'err',
  'last'    => 'val',
  'line'    => 'lin',
  'matches' => 'hit',
  'self'    => 'slf',
  );
my %tb_lft = (
  'error'   => q{},
  'last'    => q{},
  'line'    => q{},
  'matches' => q{},
  'self'    => q{$},
  );
my %tb_var = (
  'error'   => q{@},
  'last'    => undef,
  'line'    => q{$},
  'matches' => q{@},
  'self'    => q{$},
  );

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

=head2 S<$h = RDA::Value::Internal-E<gt>new($ctx,$nam)>

The object constructor. It takes the execution context reference and the
variable name as extra arguments.

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

=over 12

=item S<    B<'ctx' > > Reference to the execution context

=item S<    B<'key' > > Variable key

=item S<    B<'nam' > > Variable name

=item S<    B<'var' > > Variable type

=back

=cut

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

  die get_string('BAD_INTERNAL', $nam) unless exists($tb_key{$nam});

  # Create the variable value object and return its reference
  return bless {
    ctx => $ctx,
    key => $tb_key{$nam},
    nam => $nam,
    var => $tb_var{$nam},
    }, ref($cls) || $cls;
}

=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) = @_;

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

  return dump_object($slf, {}, $lvl, $txt);
}

sub dump_object
{ my ($slf, $tbl, $lvl, $txt) = @_;

  return q{  } x $lvl.$txt.q{Internal=}.$slf->{'nam'};
}

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

This method indicates whether the value can be used as a left value.

=cut

sub is_lvalue
{ return $tb_lft{shift->{'nam'}};
}

=head1 ASSIGN AND EVAL METHODS

=head2 S<$h-E<gt>eval_value([$flg])>

This method resolves a variable. When the flag is set, it executes code values.

=cut

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

  return $slf->{'ctx'}->get_internal($slf->{'key'})->eval_value($flg);
}

# --- Find object mechanim ----------------------------------------------------

sub find_object
{ my ($slf, $typ) = @_;
  my $val;

  # Treat a request without creating the variable
  return ($slf->{'ctx'}->get_internal($slf->{'key'}))
    unless $typ;

  # Get the variable value, creating the variable when needed
  die get_string('INCOMPATIBLE')
    unless !defined($slf->{'var'})  ## no critic (Unless)
        || $slf->{'var'} eq $typ
        || $slf->{'var'} eq q{$};
  $val = $slf->{'ctx'}->get_internal($slf->{'key'}, 1, ".$typ");
  return ($val, [$slf->{'ctx'}, $slf->{'nam'}, $val]);
}

1;

__END__

=head1 SEE ALSO

L<RDA::Agent|RDA::Agent>,
L<RDA::SDCL::Block|RDA::SDCL::Block>,
L<RDA::SDCL::Context|RDA::SDCL::Context>,
L<RDA::SDCL::Value|RDA::SDCL::Value>,
L<RDA::Text|RDA::Text>,
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