package RDA::Macro::Data; # $Id: Data.pm,v 1.16 2009/02/19 08:18:46 mschenke Exp $ # ARCS: $Header: /u02/webapps/workbench/cvs/RDA_4/src/scripting/lib/RDA/Macro/Data.pm,v 1.16 2009/02/19 08:18:46 mschenke Exp $ # # Change History # 20090219 MSC Add the 'call' method. =head1 NAME RDA::Macro::Data - Class Used for Complex Data Structure Manipulation Macros =head1 SYNOPSIS require RDA::Macro::Data; =head1 DESCRIPTION The objects of the C class are used to interface with macros for manipulating complex data structure. The following methods are available: =cut use strict; BEGIN { use Exporter; use RDA::Object::Data; use RDA::Value; } # Define the global public variables use vars qw($VERSION); $VERSION = sprintf("%d.%02d", q$Revision: 1.16 $ =~ /(\d+)\.(\d+)/); # Define the global private variables my $DATA = 'RDA::Object::Data'; my $OBJECT = qr/^RDA::Object::/; my $VALUE = 'RDA::Value'; my %tb_alt = ( 'list' => \&_list, ); my %tb_fct = ( 'addDataValue' => \&_m_add_value, 'clearData' => \&_m_clear, 'copyData' => \&_m_copy, 'createData' => \&_m_create, 'deleteData' => \&_m_delete, 'decrDataValue' => \&_m_decr_value, 'evalData' => \&_m_eval, 'existsData' => \&_m_exists, 'extern' => \&_m_extern, 'getData' => \&_m_get_data, 'getDataError' => \&_m_get_error, 'getDataIndex' => \&_m_get_index, 'getDataKeys' => \&_m_get_keys, 'getDataValue' => \&_m_get_value, 'incrDataValue' => \&_m_incr_value, 'missingData' => \&_m_missing, 'refData' => \&_m_ref, 'renameData' => \&_m_rename, 'resolveData' => \&_m_resolve, 'setDataValue' => \&_m_set_value, ); my %tb_stl = ( '*' => '**', "'" => "''", '`' => '``', ); # Report the module version number sub Version { $VERSION; } =head2 S<$h = RDA::Macro::Data-Enew($agt)> The object constructor. It takes the agent object reference as an argument. C is represented by a blessed hash reference. The following special keys are used: =over 12 =item S< B<'_agt'> > Reference to the agent object =item S< B<'_dat'> > Library data structure =item S< B<'_err'> > Error message for last external macro execution =back =cut sub new { my $slf = shift; my $class = ref($slf) || $slf; my $agt = shift; # Create the macro object $slf = bless {_agt => $agt, _err => ''}, $class; # Clear the library hash $slf->_reset_data; # Register the macros $agt->register($slf, [keys(%tb_fct)], qw(stat)); # Return the object reference $slf; } # Clear the library hash for each module sub clr_stats { shift->_reset_data; } sub get_stats { shift->_reset_data; } =head2 S<$h-Ecall($name,...)> This method executes the macro code. =cut sub call { my ($slf, $nam, @arg) = @_; &{$tb_fct{$nam}}($slf, @arg); } =head2 S<$h-Erun($name,$arg,$ctx)> This method executes the macro with the specified argument list in a given context. =cut sub run { my ($slf, $nam, $arg, $ctx) = @_; return &{$tb_fct{$nam} || $tb_alt{$nam}}($slf, $ctx, $arg); } =head1 INTERFACE MACROS =head2 S This macro calls an external Perl macro and provides a return value. It evaluates the Perl code in a scalar context. When it returns an array reference, the array should contain values that can be converted into RDA values only. =cut sub _m_extern { my ($slf, $ctx, $arg) = @_; my ($cls, $fct, $ref, $ret, @arg); ($cls, $fct, @arg) = $arg->eval_as_array; $slf->{'_err'} = ''; if ($cls && $fct) { eval "require RDA::Extern::$cls"; if ($@) { eval "require $cls"; } else { $cls = "RDA::Extern::$cls"; } unless ($slf->{'_err'} = $@) { $ret = eval "$cls\:\:$fct(\$ctx, \@arg)"; return _conv_value($ret, 1) unless ($slf->{'_err'} = $@); } } $VAL_UNDEF; } =head2 S This macro returns the error message from the last external macro call. If no errors are encountered, then it returns an empty string. =cut sub _m_get_error { RDA::Value->new('T', shift->{'_err'}); } =head1 MACROS FOR MANIPULATING COMPLEX DATA STRUCTURES This macro library also provides macros to manage complex data structures using C objects. A data structure is associated to this macro library and is shared between all execution contexts of a module. =head2 S This macro pushes a new value in the array associated to the specified key chain. It evaluates the value without executing code values. When required, it converts a previously stored value to an array. It returns the new number of elements in the array. In the case of problems, it returns an undefined value. =cut sub _m_add_value { my ($slf, $ctx, $arg) = @_; my ($dat, $flg, $key, $lst, $tbl, $val); ($dat, $val, $lst) = _parse_arg($slf, $arg, 1); return $VAL_UNDEF unless ref($val); ($dat, $key, $flg) = _find_item($dat, $lst); return $VAL_UNDEF unless defined($key); if ($flg) { if (defined($dat->[$key])) { $dat->[$key] = $tbl = [$tbl] unless ref($tbl = $dat->[$key]) eq 'ARRAY'; } else { $dat->[$key] = $tbl = []; } } else { if (exists($dat->{$key})) { $dat->{$key} = $tbl = [$tbl] unless ref($tbl = $dat->{$key}) eq 'ARRAY'; } else { $dat->{$key} = $tbl = []; } } RDA::Value->new('N', push(@$tbl, $val->eval_value)); } =head2 S This macro clears the specified sub hash. When you do not specify any keys, the whole hash is cleared. It returns zero on successful completion. Otherwise, it returns a non-zero value. =cut sub _m_clear { my ($slf, $ctx, $arg) = @_; my ($dat, $flg, $key); ($dat, $key, $flg) = _find_item(_parse_arg($slf, $arg)); return $VAL_ONE unless defined($dat); if ($flg) { $dat->[$key] = {}; } elsif (defined($key)) { $dat->{$key} = {}; } else { foreach $key (keys(%$dat)) { delete($dat->{$key}); } } $VAL_ZERO; } =head2 S This macro returns a copy of a data structure. =cut sub _m_copy { my ($slf, $ctx, $arg) = @_; my $dat; ($dat) = _parse_arg($slf, $arg); RDA::Value->new('O', $dat->copy); } =head2 Sval,...])> This macro creates a new data structure and returns an object reference. Array and hash variables are converted respectively in arrays or hashes. You can also use a C macro to create sub arrays. It evaluates other arguments in a scalar context. =cut sub _m_create { my ($slf, $ctx, $arg) = @_; my ($key, $val, @arg, @tbl); @arg = @{$arg->get_items}; while (($key, $val) = splice(@arg, 0, 2)) { next unless ref($key) && ref($val); $val = $val->eval_macro({list => $slf}) if $val->is_macro; push(@tbl, $key->eval_as_string, $val->is_list ? _create_array($slf, @{$val->get_items}) : ($val->is_var eq '@') ? _create_vec($val) : ($val->is_var eq '%') ? _create_hash($val) : _create_scalar($val)); } RDA::Value->new('O', RDA::Object::Data->new(@tbl)); } sub _create_array { my $slf = shift; my $tbl = []; foreach my $val (@_) { next unless ref($val); $val = $val->eval_macro({list => $slf}) if $val->is_macro; push(@$tbl, $val->is_list ? _create_array($slf, @{$val->get_items}) : ($val->is_var eq '@') ? _create_vec($val) : ($val->is_var eq '%') ? _create_hash($val) : _create_scalar($val)); } return $tbl; } sub _create_hash { my $val = shift; my ($dic, $nam); $dic = $val->get_info('ctx')->get_dict; $nam = $val->get_info('nam'); exists($dic->{$nam}) ? {%{$dic->{$nam}->{'ref'}}} : undef; } sub _create_scalar { my $val = shift; $val = $val->eval_value unless $val->is_pointer; ($val->is_code || $val->is_pointer) ? $val : $val->eval_as_scalar; } sub _create_vec { my $val = shift; my ($dic, $nam); $dic = $val->get_info('ctx')->get_dict; $nam = $val->get_info('nam'); exists($dic->{$nam}) ? [@{$dic->{$nam}->{'ref'}->{'val'}}] : undef; } sub _list { my ($slf, $ctx, $arg) = @_; RDA::Value->new('L', [@{$arg->get_items}]); } =head2 S This macro decrements by one the value associated with the specific key chain. It returns the new value. If the key is not defined or is associated with a sub hash or an array, it returns an undefined value. =cut sub _m_decr_value { _incr_value(-1, @_); } =head2 S This macro deletes a data element from the data structure. It returns zero on successful completion. Otherwise, it returns a non-zero value. =cut sub _m_delete { my ($slf, $ctx, $arg) = @_; my ($dat, $flg, $key); ($dat, $key, $flg) = _find_item(_parse_arg($slf, $arg)); return $VAL_ONE unless defined($key); if ($flg) { $dat->[$key] = undef; } else { delete($dat->{$key}); } $VAL_ZERO; } =head2 S This macro evaluates a data structure. It returns a new data structure that can be used by external Perl modules. =cut sub _m_eval { my ($slf, $ctx, $arg) = @_; my $dat; ($dat) = _parse_arg($slf, $arg); RDA::Value->new('O', $dat->eval); } =head2 S This macro indicates if the key chain exists in a hash. The macro does not modify the data structure. =cut sub _m_exists { _exists(@_) ? $VAL_ONE : $VAL_ZERO; } sub _exists { my ($slf, $ctx, $arg) = @_; my ($dat, $flg, $key, $lst); ($dat, $lst) = _parse_arg($slf, $arg); foreach my $itm ($lst->eval_as_array) { next unless defined($itm); if (defined($key)) { if ($flg) { return 0 unless defined($dat->[$key]); $dat = $dat->[$key]; } else { return 0 unless exists($dat->{$key}); $dat = $dat->{$key}; } return 0 unless ref($dat) eq 'HASH' || ref($dat) eq $DATA; } $flg = ref($dat) eq 'ARRAY'; $key = $itm; } (!$flg && defined($key) && exists($dat->{$key})) ? 1 : 0; } =head2 S This macro returns a reference to the library data structure. =cut sub _m_get_data { RDA::Value->new('O', shift->{'_dat'}) } =head2 S This macro returns the list of all keys of the specified sub hash, sorted numericly. =cut sub _m_get_index { my ($slf, $ctx, $arg) = @_; my ($dat, $flg, $key, $ref); ($dat, $key, $flg) = _find_item(_parse_arg($slf, $arg)); if (defined($key)) { return $VAL_EMPTY unless exists($dat->{$key}); $ref = ref($dat = $dat->{$key}); return $VAL_EMPTY unless $ref eq 'HASH' || $ref eq $DATA; } defined($dat) ? RDA::Value::new_list(sort {$a <=> $b} keys(%$dat)) : $VAL_EMPTY; } =head2 S This macro returns the list of all keys of the specified sub hash, sorted alphabeticly. =cut sub _m_get_keys { my ($slf, $ctx, $arg) = @_; my ($dat, $flg, $key, $ref); ($dat, $key, $flg) = _find_item(_parse_arg($slf, $arg)); if (defined($key)) { return $VAL_EMPTY unless exists($dat->{$key}); $ref = ref($dat = $dat->{$key}); return $VAL_EMPTY unless $ref eq 'HASH' || $ref eq $DATA; } defined($dat) ? RDA::Value::new_list(sort keys(%$dat)) : $VAL_EMPTY; } =head2 S This macro returns the value associated with the specified key chain. If the key is not defined or if the key chain is invalid, it returns an undefined value. Arrays are converted in lists but sub arrays are not included. =cut sub _m_get_value { my ($slf, $ctx, $arg) = @_; my ($dat, $flg, $key, $ref, $val); ($dat, $key, $flg) = _find_item(_parse_arg($slf, $arg)); defined($key) ? _conv_value($flg ? $dat->[$key] : exists($dat->{$key}) ? $dat->{$key} : undef, 1) : $VAL_UNDEF; } =head2 S This macro increments by one the value associated with the specific key chain. It returns the new value. If the key is not defined or is associated with a sub hash or an array, it returns an undefined value. =cut sub _m_incr_value { _incr_value(1, @_); } sub _incr_value { my ($val, $slf, $ctx, $arg) = @_; my ($dat, $flg, $key, $old, $ref); ($dat, $key, $flg) = _find_item(_parse_arg($slf, $arg)); return $VAL_UNDEF unless defined($key); $old = $flg ? $dat->[$key] : $dat->{$key}; if (defined($old)) { return $VAL_UNDEF if ($ref = ref($old)) && $ref ne $VALUE; $val += $ref ? $old->eval_as_number : $old; } $val = RDA::Value->new('N', $val); $flg ? $dat->[$key] = $val : $dat->{$key} = $val; } =head2 S This macro indicates whether the key chain is missing in a hash. The macro does not modify the data structure. =cut sub _m_missing { _exists(@_) ? $VAL_ZERO : $VAL_ONE; } =head2 S This macro returns a non-empty string if the specified key chain is associated with a reference. Otherwise, it returns an empty string. =cut sub _m_ref { my ($slf, $ctx, $arg) = @_; my ($dat, $flg, $key); ($dat, $key, $flg) = _find_item(_parse_arg($slf, $arg)); (!defined($key)) ? $VAL_NONE : $flg ? _ref_value($dat->[$key]) : exists($dat->{$key}) ? _ref_value($dat->{$key}) : $VAL_NONE; } sub _ref_value { my $ref = ref(shift); ($ref eq $VALUE) ? $VAL_NONE : RDA::Value->new('T', $ref); } =head2 S This macro renames a hash key. It returns zero on successful completion. Otherwise, it returns a non-zero value. =cut sub _m_rename { my ($slf, $ctx, $arg) = @_; my ($dat, $flg, $lst, $old, $new); ($dat, $new, $lst) = _parse_arg($slf, $arg, 1); return $VAL_ONE unless ref($new) && ($new = $new->eval_as_string); ($dat, $old, $flg) = _find_item($dat, $lst); return $VAL_ONE unless !$flg && defined($old) && exists($dat->{$old}); $dat->{$new} = delete($dat->{$old}); $VAL_ZERO; } =head2 S This macro resolves hash key references from the string, using the specified sub hash. It supports nested references. The following reference formats are supported: =over 20 =item B< ${key}> Replaces the reference with the hash key values. When the key is not defined, it replaces the reference with an empty string. =item B< ${key:dft}> Replaces the reference with the hash key values. When the key is not defined, it replaces the reference with the default text. =item B< ${key?txt:dft}> Replaces the reference with the specified text when the hash key exists. Otherwise, it replaces the reference with the default text. =back You can prefix the key by a character indicating how the key value must be emphasized. It is not used for other replacement texts. The valid style characters are as follows: =over 6 =item S< *> for bold =item S< '> (single quote) for italic =item S< `> (back quote) for code =back It returns the resulting value. =cut sub _m_resolve { my ($slf, $ctx, $arg) = @_; my ($dat, $flg, $key, $lst, $str); ($dat, $str, $lst) = _parse_arg($slf, $arg, 1); return $VAL_UNDEF unless ref($str); ($dat, $key, $flg) = _find_item($dat, $lst); $dat = $flg ? $dat->[$key] : $dat->{$key} if defined($key); $dat = {} unless ref($dat) eq 'HASH' || ref($dat) eq $DATA; $str = $str->eval_as_string; 1 while $str =~ s/\$\{([\*\'\`])?(\w+)((\?)([^\{\}]*?))?(\:([^\{\}]*?))?\}/ _resolve($dat, $1, $2, $4, $5, $7)/eg; RDA::Value->new('T', $str); } sub _resolve { my ($hsh, $stl, $key, $tst, $txt, $dft) = @_; my $str; if (exists($hsh->{$key})) { return defined($txt) ? $txt : '' if $tst; $str = $hsh->{$key}; $stl = ($stl && exists($tb_stl{$stl})) ? $tb_stl{$stl} : ''; return $stl.$str->eval_as_string.$stl if ref($str) eq $VALUE; return $stl.$str.$stl unless ref($str); } defined($dft) ? $dft : ''; } =head2 S This macro assigns a new value to the specified key chain. You can insert array structures as value, by using array variables or C macros. By analogy, a hash variable is converted into a hash structure. Otherwise, it evaluates the value in a scalar context without executing code values. It returns the assigned value. =cut sub _m_set_value { my ($slf, $ctx, $arg) = @_; my ($dat, $flg, $key, $lst, $val, @tbl); ($dat, $val, $lst) = _parse_arg($slf, $arg, 1); return $VAL_UNDEF unless ref($val); ($dat, $key, $flg) = _find_item($dat, $lst); return $VAL_UNDEF unless defined($key); $val = $val->eval_macro({list => $slf}) if $val->is_macro; $val = $val->is_list ? _create_array($slf, @{$val->get_items}) : ($val->is_var eq '@') ? _create_vec($val) : ($val->is_var eq '%') ? _create_hash($val) : _create_scalar($val); _conv_value($flg ? $dat->[$key] = $val : $dat->{$key} = $val, 1); } # --- Internal data structure functions --------------------------------------- # Convert a Perl array sub _conv_array { my ($val) = @_; RDA::Value->new('L', [map {_conv_value($_)} @$val]); } # Convert a Perl hash sub _conv_hash { my ($val) = @_; RDA::Value->new('O', RDA::Object::Data->new(%$val)); } # Convert a value sub _conv_value { my ($val, $flg) = @_; my $ref; $ref = ref($val); ($ref eq $VALUE) ? $val : ($ref eq 'ARRAY' && $flg) ? _conv_array($val) : ($ref eq 'HASH') ? _conv_hash($val) : ($ref =~ $OBJECT) ? RDA::Value->new('O', $val) : $ref ? $VAL_UNDEF : defined($val) ? RDA::Value->new('T', $val) : $VAL_UNDEF; } # Find data item sub _find_item { my ($dat, $arg) = @_; my ($flg, $key, $ref, @key); @key = ('[data]'); foreach my $itm ($arg->eval_as_array) { next unless defined($itm); if (defined($key)) { if ($flg) { $dat->[$key] = {} unless defined($dat->[$key]); $dat = $dat->[$key]; } else { $dat->{$key} = {} unless exists($dat->{$key}); $dat = $dat->{$key}; } $ref = ref($dat); return () unless $ref eq 'HASH' || $ref eq $DATA || $ref eq 'ARRAY'; push(@key, $key) } $flg = ref($dat) eq 'ARRAY'; $key = $itm; } ($dat, $key, $flg, join('->', @key)); } # Parse the argument list sub _parse_arg { my ($slf, $arg, $flg) = @_; my ($dat, $obj, $val, @arg); # Take a copy of the argument list @arg = @{$arg->get_items}; # Determine the data structure object if (ref($obj = shift(@arg))) { $dat = $obj->eval_as_scalar; unless (ref($dat) eq $DATA) { $dat = $slf->{'_dat'}; unshift(@arg, $obj); } } else { $dat = $slf->{'_dat'}; } # Return the arguments if ($flg) { $val = pop(@arg); return ($dat, $val, RDA::Value->new('L', [@arg])); } return ($dat, RDA::Value->new('L', [@arg])); } # Reset the library hash sub _reset_data { shift->{'_dat'} = RDA::Object::Data->new; } 1; __END__ =head1 SEE ALSO L, L, L, L =head1 COPYRIGHT NOTICE Copyright (c) 2002-2009, Oracle. All rights reserved. =head1 TRADEMARK NOTICE Oracle, JD Edwards, PeopleSoft, and Siebel are registered trademarks of Oracle Corporation and/or its affiliates. Other names may be trademarks of their respective owners. =cut