File Coverage

blib/lib/LaTeX/Replicase.pm

Criterion	Covered	Total	%
statement	506	533	94.9
branch	364	434	83.8
condition	174	237	73.4
subroutine	21	21	100.0
pod	2	2	100.0
total	1067	1227	86.9

package LaTeX::Replicase;

use 5.010;
use strict;
use warnings;
use utf8;

use File::Basename qw(fileparse);
use File::Path qw(make_path);
use File::Compare;
use Carp;

require Exporter;

our @ISA = qw(Exporter);

our %EXPORT_TAGS = ('all' => [ qw(
		replication
		tex_escape
	) ],
);

our @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } );
our @EXPORT = qw( );

our $VERSION = '0.705';
our $DEBUG; $DEBUG = 0 unless defined $DEBUG;
our @logs;
our $nlo = 1; # Number Line Output, start of 1

sub tex_escape {
	return if ! $_[0] or $_[0] =~/^[a-zA-Z0-9,=:;!\.\s\+\-\*]+$/ or $_[0] =~s/^%%%://;

	for( $_[0] ) {
		s/\\/\\textbackslash\{\}/g;
		s/([%}{_&\$\#])/\\$1/g; # masking active symbols
		s/\^/\\$&\{\}/g; # ^ --> \^{}

		s/~/\\texttt\{\\~\{\}\}/g if $_[1] && $_[1] =~/~/; # tilde (~) --> \texttt{\~{}}
	}
}


sub replication {
	my( $source, $info, %op ) = @_;

	our $DEBUG; $DEBUG = $op{debug} if defined $op{debug};
	$DEBUG += 0;
	our @logs = ();

	if( defined( $source ) && length( $source ) ) {

		if(ref \$source eq 'SCALAR') {
			for( $source ) {
				s/^\s+//;
				s/\s+.*//s;

				$_ = (glob)[0] if $^O =~/(?:linux|bsd|darwin|solaris|sunos)/;
			}
		}
		elsif(ref $source ne 'ARRAY')  {
			$_ = "!!! ERROR#6: invalid FILE or ARRAY input!";
			$op{silent} or carp $_;

			push @logs, $_;
			return \@logs;
		}

	}
	else {
		$_ = "!!! ERROR#0: undefined input FILE or ARRAY!";
		$op{silent} or carp $_;

		push @logs, $_;
		return \@logs;
	}

push @logs, "--> Checking source data: '$source'" if $DEBUG;

	if((ref \$source eq 'SCALAR' and ! -s $source) or (ref $source eq 'ARRAY' and ! @$source)) {
		$_ = "!!! ERROR#1: source ('$source') does NOT exist or is EMPTY!";
		$op{silent} or carp $_;

		push @logs, $_;
		return \@logs;
	}

	# global data of TeX file
	unless( $info
		and (( ref $info eq 'HASH' and %$info ) or (ref $info eq 'ARRAY' and @$info ))
	) {
		$_= "!!! ERROR#2: EMPTY or WRONG data!";
		$op{silent} or carp $_;

		push @logs, $_;
		return \@logs;
	}

	# environments: global for %%%V:, %%%VAR: ; and local for %%%VAR:
	my $data = my $vardata = $info;

	my( $filename, $dir );
	if( ref \$source eq 'SCALAR') {
		( $filename, $dir, my($ext)) = fileparse( $source );
	}
	else { # for ARRAY input
		$filename = 'ready.tex';
		$dir = '.';
	}

	my( $fh, $ofile );
	if( defined( $_ = $op{ofile} ) && length ) {
		if(/::STDOUT$/) {
			$fh = $ofile = $_;
		}
		else {
			s/^\s+//;
			s/\s+.*//s;
			$ofile = ( $^O =~/(?:linux|bsd|darwin|solaris|sunos)/ ) ? (glob)[0] : $_;
		}
	}
	else {
		my $outdir = $op{outdir} // "$dir/$$"; # Target dir for ready TeX file
		if( length $outdir ) {
			for( $outdir ) {
				s/^\s+//;
				s/\s+.*//s;

				$_ = (glob)[0] if $^O =~/(?:linux|bsd|darwin|solaris|sunos)/;
			}
		}
		else { # for $outdir = ''
			$outdir = "./$$";
		}

		unless( -d $outdir ) {
			make_path( $outdir, {error => \my $err} );

			if ($err && @$err) {

				for my $diag (@$err) {
					my( $path, $message ) = %$diag;
					$_ = ( $path && length( $path ) ) ?
						"!!! ERROR#7: ('$path' creation problem) $message" :
						"!!! ERROR#8: (general error) $message";
					$op{silent} or carp $_;
					push @logs, $_;
				}

				return \@logs;
			}

		}

		$ofile = "$outdir/$filename";
	}

push @logs, "--> Using '$ofile' file as output" if $DEBUG;

	# new file must be different
	if( -s $ofile and ref \$source eq 'SCALAR'
		and (
			( $source eq $ofile and compare( $source, $ofile ) == 0 )
			or
			( join(',', stat $source) eq join(',', stat $ofile) )
		)
	) {
		$_= "!!! ERROR#3: Input (template) & output files match. Can't overwrite template file!";
		$op{silent} or carp $_;

		push @logs, $_;
		return \@logs;
	}

	my $TEMPLATE;
	if( ref \$source eq 'SCALAR') {
		my $mode = $op{utf8} ? ':utf8' : '';

push @logs, "--> Open '$source'" if $DEBUG;

		open $TEMPLATE, "<:raw$mode", $source or do{
			$_= "!!! ERROR#4: $!";
			$op{silent} or carp $_;

			push @logs, $_;
			return \@logs;
		};
	}

	unless( $fh ) { # it's not "::STDOUT"
		my $mode = $op{utf8} ? ':encoding(utf8)' : '';

push @logs, "--> Open '$ofile'" if $DEBUG;

		open $fh, ">$mode", $ofile or do{
			$_= "!!! ERROR#5: $!";
			$op{silent} or carp $_;

			push @logs, $_;
			return \@logs;
		};
	}

	$nlo = 1;
	my $chkVAR = 0; # check %%%VAR for ARRAY|HASH|SCALAR|REF->SCALAR type
	my $key;
	my $tdz; # flag of The Dead Zone
	my @columns;
	my $end = 0;

=for comment
=begin comment
@columns:
	[...]: -- table columns
	[...]{...} -- descriptions (properties) of table columns:
			{ki} -- name (key || index ) of a variable from $data->{ $key }
			{%} -- NO \par
			{v} -- to paste by default text (located in template) if variable =~/^\x{001}$/
			{p} -- to paste text on right
			{head}[...] -- TeX strings before %%%V:
			{tail}[...] -- TeX strings after %%%V:
			{eX}[...] -- indices of {head} that eXcept for the first and last elements and rows of %%%VAR:
=end comment
=cut

	if( $TEMPLATE )  {
		while( my $z = <$TEMPLATE> ) {

			$end = &_line_decryption( $fh, $info, \$z, \$data, \$vardata, \$chkVAR, \$key, \$tdz, \@columns, \%op );

			if( $end ) {
				print { $fh } <$TEMPLATE> if $end != 3; # NOT ( \endinput AND \end{document} )

				last; #--> Exit template
			}
			undef $z;

		}
		close $TEMPLATE;
	}
	else {
		for my $z ( @$source ) {

			if( $end ) {
				print { $fh } $z;
			}
			else {
				$end = &_line_decryption( $fh, $info, \$z, \$data, \$vardata, \$chkVAR, \$key, \$tdz, \@columns, \%op );

				last if $end == 3; # \endinput OR \end{document}
			}
		}
	}

	if( ! $end and defined( $key ) ) {
		&_var_output( $fh, $key, $vardata, \@columns, \%op );

		$_ = "~~> l.EOF. WARNING#1: Missing '%%%ENDx' tag for '$key'";
		$op{silent} or carp $_;
		push @logs, $_;
	}

	$ofile =~/::STDOUT$/ or close $fh;

	@logs or return;
	return \@logs;
}

#---------------------
# Internal function(s)

sub _line_decryption {
	my( $fh, $info, $z, $data, $vardata, $chkVAR, $key, $tdz, $columns, $op ) = @_;

	our $DEBUG;
	our @logs;
	our $nlo;

	if( defined $$key ) { # We are in VAR-structure

		return 0 unless $$z =~/%%%[AETV]\S*:/; # Nope control tags --> drop TeX line

		if( $$z =~/%%%(?:END(?[TZ]?)|TDZ|VAR):/) {
			my $t = $+{t};

			my $end = &_var_output( $fh, $$key, $$vardata, $columns, $op );

			# Clear the VAR-structure for the next external VARiable
			$$chkVAR = 0;
			undef $$key;
			@$columns = ();

			return $end if $end;

			return 1 if $t && $t eq 'T'; # END of Template area --> output everything to the end of template without substitution

			undef $$tdz if $t && $t eq 'Z';

			return 0 if $$z =~/%%%ENDZ?:/; # end of %%%VAR: tag

			if( $$z =~/%%%+TDZ:/) { # The Dead Zone
				$$tdz = 1;
				return 0;
			}

		}
		elsif( (ref $$vardata eq 'HASH' and (
					   ref $$vardata->{ $$key } eq 'HASH'
					or ref $$vardata->{ $$key } eq 'ARRAY'
					or ref \$$vardata->{ $$key } eq 'SCALAR'
					or ref $$vardata->{ $$key } eq 'SCALAR' # REF->SCALAR
				)
			)
			or (ref $$vardata eq 'ARRAY' and (
					   ref $$vardata->[ $$key ] eq 'HASH'
					or ref $$vardata->[ $$key ] eq 'ARRAY'
					or ref \$$vardata->[ $$key ] eq 'SCALAR'
					or ref $$vardata->[ $$key ] eq 'SCALAR' # REF->SCALAR
				)
			)
		) {
			my $vk = ref $$vardata eq 'HASH' ? $$vardata->{ $$key } : $$vardata->[ $$key ];
			my $sclr = (ref \$vk eq 'SCALAR' or ref $vk eq 'SCALAR') ? 1 : 0;

			# Index of column in target table
			my $j = ( @$columns && exists( $columns->[-1]{ki} ) ) ?
						@$columns :
						($#$columns // 0);
			$j = 0 if $j < 0 or $sclr;

			if( ! $sclr and $$z =~/^(.*?)\s?%%%+V:\s*([^\s:%#]+)(%?)\s?(.*)/) {
				# the non-SCALAR V-variable is nested in a VAR-structure
				my $dV = $1; # Value, by default
				my $ki = $2; # name (key or index) of V-variable
				my $Np = $3; # NO \par
				my $paste = $4; # on right

				if( $$chkVAR == 0b0001) { # V-variable is in {HASH|ARRAY}.ARRAY of VAR-structure

					if( $ki eq '@') {
						$ki = '0-'; # ALL elements
						$columns->[$j]{ki} = $ki; # starting index (unnamed meaning)
					}
					elsif( $ki =~/^\-*(\d+)$/ && ($1 < @$vk or ($ki < 0 && $1 == @$vk)) ) {
						# specific indices, e.g.: 0 or 3 or -1
						$columns->[$j]{ki} = $ki;
					}
					elsif( $ki =~/^[\d,\-]+$/) {
					# mixed indexes, e.g.: 1-3,6-7-9,-,4,-5,0,7- or 3- (i.e. 3..arr_end) or 0-5 (0..5) or -1- (-1,-2,..arr_start)
						for( $ki ) {
							s/\-+/-/g;
							s/,+/,/g;
						}
						$columns->[$j]{ki} = $ki;
					}
					else {
push @logs, "~~> l.$. WARNING#8: ARRAY index is not numeric in %%%V:". $ki if $DEBUG or ! $op->{ignore};
					}

				}
				elsif( $$chkVAR == 0b0010) { # V-variable is in ARRAY.HASH of VAR-structure

					for my $d ( @$vk ) {
						if( exists $d->{$ki} ) {
							$columns->[$j]{ki} = $ki; # save variable name in j-th column
							last;
						}
					}
				}
				elsif( $$chkVAR == 0b0100 or $$chkVAR == 0b01000 ) { # V-variable is SCALAR (or REF->SCALAR) in regular ARRAY of VAR-structure

					if( $ki eq '@') {
						$ki = '0-'; # ALL elements
						$columns->[$j]{ki} = $ki; # starting index (unnamed meaning)
					}
					elsif( $ki =~/^\-*(\d+)$/ && ($1 < @$vk or ($ki < 0 && $1 == @$vk)) ) {
						# specific indices, e.g.: 0 or 3 or -1
						$columns->[$j]{ki} = $ki;
					}
					elsif( $ki =~/^[\d,\-]+$/) {
					# mixed indexes, e.g.: 1-3,6-7-9,-,4,-5,0,7- or 3- (i.e. 3..arr_end) or 0-5 (0..5) or -1- (-1,-2,..arr_start)
						for( $ki ) {
							s/\-+/-/g;
							s/,+/,/g;
						}
						$columns->[$j]{ki} = $ki;
					}

				}
				elsif( ref $vk eq 'HASH'
						and exists( $vk->{$ki} )
						and ( ref \$vk->{$ki} eq 'SCALAR'
							or ref $vk->{$ki} eq 'SCALAR'
							or ( $ki eq '@'
								and ref $vk->{$ki} eq 'ARRAY'
							)
						)
				) {
					$columns->[$j]{ki} = $ki; # save variable key in j-th element
				}

				&_set_column( $dV, $Np, $paste, $columns->[$j] ) if exists $columns->[$j]{ki};
			}
			elsif( $$z =~/(?.+?)\s?%%%+ADD(?[AEX]?):(?%?)/
				or $$z =~/^\s*%%%+ADD(?[AEX]?):(?%?)\s?(?.*?)[\r\n]*$/
			) {
				my $s = $+{s};

				if( $+{p} ) {
					length($s) or return 0;
				}
				else {
					$s .= "\n";
				}

				if( $+{t} eq 'A') { # %%%ADDA:
					push @{ $columns->[$j]{head} }, $s;
					$columns->[$j]{ki} = '%%%ADDA'; # phantom
					$columns->[$j]{'%'} = 1;
				}
				elsif( $+{t} eq 'E') { # %%%ADDE:
					if( @$columns && ( $sclr or (exists( $columns->[-1]{ki} ) && ! $columns->[$j]) ) ) {
						push @{ $columns->[-1]{tail} }, $s;
					}
					else {
						push @{ $columns->[$j]{head} }, $s;
					}
				}
				else { # %%%ADD[X]:
					push @{ $columns->[$j]{head} }, $s;
					$columns->[$j]{eX}{ $#{ $columns->[$j]{head} } } = undef if ! $sclr and $+{t} eq 'X'; # $$chkVAR && ...  %%%ADDX:
				}
			}

			return 0;
		}
		else {
			return 0;
		}

	}
	elsif( $$z =~/%%%+END(?[TZ]?):/) { # end of template area

		# Clear the VAR-structure for the next external variable
		$$chkVAR = 0;
		undef $$key;
		@$columns = ();

		return 1 if $+{t} eq 'T'; # END of Template area --> output everything to the end of template without substitution

		undef $$tdz if $+{t} eq 'Z'; # End of TDZ
		return 0;
	}

	$$tdz = 1 if $$z =~s/^\s*%%%+TDZ:\s?[\r\n]*//; # The Dead Zone

	if( $$tdz ) { # The Dead Zone is ON
		if( length $$z ) {# Output TeX
			print { $fh } $$z;
			++$nlo;
		}
		return 0;
	}

	if( $$z =~/(.*?)\s?%%%+VAR:\s*([^\s:%#]+)(%?)\s?(.*)/) {
		my $before = $1;
		my $k = $2; # name (key)
		my $Np = $3; # NO \par
		my $paste = $4; # on right text for SCALAR only

		# root or global structure (environment)
		my $vd = ( $k =~s/^\/+//) ? $info : $$data;

		my $x; # for unknown/undefined sub-key

		# Search nested sub-keys
		for my $sk ( split '/', $k ) {
			$$vardata = $vd;
			length( $sk ) or next;

			if( $sk =~/^\d+$/ && ref $vd eq 'ARRAY' and defined( $vd->[$sk] )) {
				last if &_data_redef( $sk, $vd->[$sk], \$k, \$vd, \$x );
			}
			elsif( ref $vd eq 'HASH' and exists( $vd->{$sk} )) {
				last if &_data_redef( $sk, $vd->{$sk}, \$k, \$vd, \$x );
			}
			else {
				$x = $sk;
				last;
			}
		}

		# Clear the VAR-structure for a new variable
		$$chkVAR = 0;
		undef $$key;
		@$columns = ();

		if( $x ) {
push @logs, "~~> l.$. WARNING#2: unknown or undef ARRAY|HASH|SCALAR|REF.SCALAR of sub-key '$x' in %%%VAR:". $k if $DEBUG or ! $op->{ignore};

			$$vardata = $$data;
			print { $fh } $$z;
			++$nlo;
			return 0;
		}

		# key or sub-...sub-key is found
push @logs, "--> l.$. Found %%%VAR:". $k if $DEBUG;

		my $vk = ref $$vardata eq 'HASH' ? $$vardata->{$k} : $$vardata->[$k];

push @logs, "~~> l.$. NOT defined key in %%%VAR:". $k if ! defined($vk) && $DEBUG;

		return 0 if &_chk_var( $fh, $k, $vk, $Np, \$paste, \$before, $chkVAR, $columns, $z, $op );

# push @logs, "--> l.$. Remember key = '$k' (chkVAR=$$chkVAR), type: ".ref($vk) if $DEBUG; ###AG

		$$key = $k; # save key name
		return 0;

	}
	elsif( $$z =~/%%%+V:\s*=(def|esc|ignore|silent|debug)=\s*(\S*)/) { # setting up facultative options
		$op->{$1} = $2 || 0;
		$DEBUG = $2 || 0 if $1 eq 'debug';
		return 0;
	}
	elsif( $$z =~/^(?.*?)\s?%%%+V:\s*(?[^\s:%#]+)(?%?)\s?(?.*)/) {
		my $k = $+{k};

		my %el;
		&_set_column( $+{v}, $+{p}, $+{s}, \%el );

		my $inidata = $$data; # save initial environment

		if( $k =~s/^\/+//) {
			$$data = $info; # reset to root environment

			length($k) or return 0;
		}

		# Search nested sub-keys
		my $x = 0; # for unknown sub-key
		for my $sk ( split '/', $k ) {
			length( $sk ) or next;

			my $d;
			if( $sk =~/^\d+$/ && ref $$data eq 'ARRAY' && defined( $$data->[$sk] ) ) {
				$d = $$data->[$sk];
			}
			elsif( ref $$data eq 'HASH' && exists( $$data->{$sk} )) {
				$d = $$data->{$sk};
			}
			else {
push @logs, "~~> l.$. WARNING#3: unknown sub-key '$sk' in %%%V:". $k if $DEBUG or ! $op->{ignore};

				print { $fh } $$z;
				++$nlo;

				$x = 1;
				last;
			}

			# Check type
			if( (ref $d eq 'ARRAY' or ref $d eq 'HASH') ) {
				$$data = $d; #  sub-key (path) found: redefined
				next;
			}

			my $v;
			if( ref \$d eq 'SCALAR') {
				$v = $d;
			}
			elsif( ref $d eq 'SCALAR') { # REF->SCALAR
				$v = $$d;
			}
			else {
push @logs, "~~> l.$. WARNING#4: wrong type (not SCALAR|ARRAY|HASH) of '$sk' in %%%V:". $k if $DEBUG or ! $op->{ignore};

				print { $fh } $$z;
				++$nlo;

				$x = 1;
				last;
			}

			$_ = &_v_print( $fh, $k, $v, \%el, $op ) and return $_;

			$x = 1;
			last;
		}

		$$data = $inidata if $x; # value found or unknown sub-key: reset to initial environment

		return 0;
	}

	print { $fh } $$z;
	++$nlo;

	return 0;
}


sub _set_column {
	my( $dV, $Np, $paste, $column ) = @_;

	$column->{v} = $dV if length $dV;
	$column->{'%'} = 1 if $Np;
	$column->{p} = $paste if length $paste;
}


sub _data_redef {
	my( $sk, $d, $k, $data, $x ) = @_;

	if( ref $d eq 'ARRAY' or ref $d eq 'HASH') {
		$$data = $d; # redefined for %%%VAR:
		return 0;
	}

	if( ref \$d eq 'SCALAR' or ref $d eq 'SCALAR') {
		$$k = $sk;
	}
	else {
		$$x = $sk;
	}
	return 1;
}

sub _chk_var {
	my( $fh, $k, $vk, $Np, $paste, $before, $chkVAR, $columns, $z, $op ) = @_;

	our $DEBUG;
	our @logs;
	our $nlo;

	if( ref $vk eq 'ARRAY') {

		if( @{ $vk } ) {
		# Check ARRAY.{ARRAY|HASH|SCALAR[.REF]}

			for my $d ( @{ $vk } ) {
				if(ref $d eq 'ARRAY'){
					$$chkVAR |= 0b00001;
				}
				elsif(ref $d eq 'HASH') {
					$$chkVAR |= 0b00010;
				}
				elsif(ref \$d eq 'SCALAR') {
					$$chkVAR |= 0b00100;
				}
				elsif(ref $d eq 'SCALAR') { # REF->SCALAR
					$$chkVAR |= 0b01000;
				}
				else {
					$$chkVAR |= 0b10000;
				}
			}
		}
		else {
			$$chkVAR |= 0b00100; # by default, SCALAR
		}

		if( ! $$chkVAR or $$chkVAR > 0b01000 or ($$chkVAR & ($$chkVAR - 1)) ) {
push @logs, "~~> l.$. WARNING#6: mixed types (ARRAY with HASH with SCALAR or other) of %%%VAR:". $k if $DEBUG or ! $op->{ignore};

			print { $fh } $$z;
			++$nlo;
			return 1;
		}
	}
	elsif( ref \$vk eq 'SCALAR' or ref $vk eq 'SCALAR') {
		$columns->[0]{ki} = $k;
		&_set_column('', $Np, $$paste, $columns->[0] );
	}

	if( $$before ) {# Output prefix TeX
		print { $fh } $$before;
#		++$nlo;
	}

	return 0;
}

# VALUE output
sub _v_print {
	my( $fh, $k, $v, $el, $op ) = @_;
	$v = $$v if ref $v eq 'SCALAR';

	our $DEBUG;
	our @logs;
	our $nlo;

	unless( defined $v ) {
		if( $op->{def} ) {
push @logs, "~~> l.$.".' NOT defined %%%V[AR]:'. $k if $DEBUG;
			return 0;
		}
		$v = '';
	}

	if( $v =~/^\x{001}[\x{003}\x{004}]?$/) { # by default text from template
		if( exists $el->{v} ) {
			print { $fh } $el->{v};

push @logs, "--> l.$.>$nlo".' Insert text by default %%%V[AR]:'. $k .'= '. $el->{v} if $DEBUG;
		}
		$v =~s/^\x{001}//;
	}

	if( $v =~/^\x{003}$/) { # END of INPUT template, similar to \endinput
		say { $fh } '\endinput';
		++$nlo;
		return 3;
	}
	elsif( $v =~/^\x{004}$/) { # END of INPUT template, similar to \endinput
		say { $fh } '\end{document}';
		++$nlo;
		return 3;
	}
	elsif( length $v ) {
		tex_escape( $v, $op->{esc} ) if $op->{esc};

push @logs, "--> l.$.>$nlo".' Insert %%%V[AR]:'. $k .'= '. $v if $DEBUG;

		print { $fh } $v;
		++$nlo while $v =~/\n/g;

		print { $fh } $el->{p} if exists $el->{p};
	}

	unless( $el->{'%'} ) {
		print { $fh } "\n"; # NO:YES \par
		++$nlo;
	}

	return 0;
}

# HEAD-TAIL output
sub _ht_print {
	my( $fh, $el, $ht, $border ) = @_;

	$el->{$ht} or return;

	our $DEBUG;
	our @logs;
	our $nlo;

	my $i = 0;
	foreach( @{ $el->{$ht} } ) {
		next if $ht eq 'head' and $border && exists( $el->{eX} ) && exists( $el->{eX}{$i} );

push @logs, "-->\tl.$.>$nlo Insert $ht: ". $_ if $DEBUG;

		print { $fh } $_;
		++$nlo;
	}
	continue {
		++$i;
	}

}

# HEAD-VALUE-TAIL output
sub _hvt_print {
	my( $fh, $ki, $val, $el, $op, $border ) = @_;

	our $DEBUG;
	our @logs;
	our $nlo;

	if( length($ki) and ! defined $val ) {
		if( $op->{def} ) {
			push @logs, "~~> l.$.".' NOT defined %%%V:'. $ki if $DEBUG;
			return 0;
		}

		$val = '';
	}

	# output head of variable
	&_ht_print( $fh, $el, 'head', $border );

	# output value of variable ( $fh, $ki, $val, $el, $op )
	$_ = &_v_print and return $_;

	# output tail of variable
	&_ht_print( $fh, $el, 'tail', 0);

	return 0;
}


sub _s_a_prn {
	my( $fh, $i, $values, $el, $op, $border, $col ) = @_;

	my $val = $values->[$i];
	$val = $$val if ref $val eq 'SCALAR';

	my $end = 0;

	if( ref \$val eq 'SCALAR') {
		$end = &_hvt_print( $fh, $i, $val, $el, $op, $$border );

		++$$col;
		$$border = 0;
	}
	elsif( ref $val eq 'ARRAY') { # [...].ARRAY.ARRAY

		for( @$val ) {
			next if ref \$_ ne 'SCALAR';

			$end = &_hvt_print( $fh, $i, $_, $el, $op, $$border );

			++$$col;
			$$border = 0;

			last if $end;
		}

	}

	return $end;
}


sub _mixed_indices {
	my( $fh, $ki, $values, $el, $op, $border ) = @_;

	my $nd = @$values;
	my $col = my $end = 0;

	for my $ii ( split ',', $ki ) { # e.g. -1-,1-3,6-7-9,-,4,-5,0,7-
		next if $ii eq '-';

		if( $ii =~/^(\-[1-9]\d*)\-(\d*)$/) { # -1- i.e. reverse: -1,-2,..-@arr (i.e. arr_start)
			my $s = $1;
			my $e = -1*($2 || $nd);
			$s = -1*$nd if abs($s) > $nd;
			$e = -1*$nd if abs($e) > $nd;
			($s, $e) = ($e, $s) if $e > $s;

			for( my $i = $s; $i >= $e; --$i ) {
				$end = &_s_a_prn( $fh, $i, $values, $el, $op, \$border, \$col ) and last;
			}

			$end ? last : next;
		}

		if( $ii =~/^\-[0-9]+$/ ) { # -5
			my $i = $ii+0;

			if( abs($i) <= $nd ) {
				$end = &_s_a_prn( $fh, $i, $values, $el, $op, \$border, \$col ) and last;
			}

			next;
		}

		my @n = grep{length} sort{$a <=> $b} split '-', $ii;

		if( @n < 2 and $n[0] < $nd ) { # e.g. 4 || 0 || 7(-)
			if( $ii =~/\-$/) { # 7(-)

				for( my $i = $n[0]; $i < $nd; ++$i ) {
					$end = &_s_a_prn( $fh, $i, $values, $el, $op, \$border, \$col ) and last;
				}

			}
			else { # 4 || 0
				$end = &_s_a_prn( $fh, $n[0], $values, $el, $op, \$border, \$col ) and last;
			}

		}
		else { # 1-3 ->(1..3) || 6-7-9 ->(6..9)
			for( my $i = $n[0]; $i <= $n[-1]; ++$i ) {
				$end = &_s_a_prn( $fh, $i, $values, $el, $op, \$border, \$col ) and last;
			}
		}

		last if $end;
	}

	return( $col, $end );
}


sub _var_output {
	my( $fh, $key, $vardata, $columns, $op ) = @_;
	my $values =  (ref $vardata eq 'HASH') ? $vardata->{ $key } : $vardata->[ $key ];

	@$columns or return;

	our $DEBUG;
	our @logs;
	our $nlo;

	my $end = 0;

	if( ref \$values eq 'SCALAR' or ref $values eq 'SCALAR') { # key => SCALAR
		return &_hvt_print( $fh, $key, $values, $columns->[0], $op );
	}

	if( ref $values eq 'ARRAY') { # key => ARRAY

		unless( @$values ) {
push @logs, "~~> l.$. WARNING#7: empty ARRAY of %%%VAR:". $key if $DEBUG or ! $op->{ignore};
			return 0;
		}

		# Forming a table
		my $row = 0;
		my $nd = @$values;

_var_output_M0:
		foreach my $d ( @$values ) { # loop through table rows

push @logs, '--> Table row = '. $row if $DEBUG;

			my $col = 0;
			foreach my $el ( @$columns ) { # loop through table columns (for ARRAY.HASH) or rows (for ARRAY.SCALAR)

				my $ki = $el->{ki};
				my $border = ((! $row and ! $col) or ($row >= $#{ $values } and (!defined( $ki ) or !length( $ki )) ) ) ? 1 : 0;

				my $val;
				if( defined $ki ) {
					if( $ki eq '%%%ADDA') {
						$val = '';
					}
					elsif( ref \$d eq 'SCALAR' or ref $d eq 'SCALAR') { # (ARRAY.SCALAR or ARRAY.REF->SCALAR) in regular vector

						if( $ki =~/^[\d,\-]+$/) {
						# mixed indices, e.g.: 1-3,6-7-9,-,4,-5,0,7- or 3- (i.e. 3..arr_end) or 0-5 (0..5) or -1- (-1,-2,..arr_start)
							last _var_output_M0 if $row;

							($_, $end) = &_mixed_indices( $fh, $ki, $values, $el, $op, $border );
							$col += $_ - 1 if $_;
						}

						$end ? last _var_output_M0 : next;
					}
					elsif( ref $d eq 'HASH') { # ARRAY.HASH
						$val = $d->{$ki};

						if( defined( $val ) && ref $val eq 'ARRAY') { # ARRAY.HASH.ARRAY
							for my $vv ( @$val ) {
								next unless ref \$vv eq 'SCALAR';

								$end = &_hvt_print( $fh, $ki, $vv, $el, $op, $border ) and last _var_output_M0;
								++$col;
							}

							$end ? last _var_output_M0 : next;
						}
						elsif( ref \$val ne 'SCALAR' and ref $val ne 'SCALAR') {
							next;
						}
					}
					elsif( ref $d eq 'ARRAY') { # ARRAY.ARRAY

						if( $ki =~/^[\d,\-]+$/) {
						# mixed indices, e.g.: 1-3,6-7-9,-,4,-5,0,7- or 3- (i.e. 3..arr_end) or 0-5 (0..5) or -1- (-1,-2,..arr_start)
							($_, $end) = &_mixed_indices( $fh, $ki, $d, $el, $op, $border );
							$col += $_ - 1 if $_;
						}

						$end ? last _var_output_M0 : next;
					}
					elsif( $op->{def} ) {

push @logs, "~~> l.$. NOT defined %%%V:". $ki if $DEBUG;

						next;
					}
				}
				else {
				# empty parameter -- at the very end of the columns (parameters)
					$ki = '';
				}

				$end = &_hvt_print( $fh, $ki, $val, $el, $op, $border ) and last _var_output_M0;
			}
			continue {
				++$col;
			}

			last if $end;
		}
		continue {
			++$row;
		}

	}
	elsif( ref $values eq 'HASH') {

		my $col = 0;
		foreach my $el ( @$columns ) { # loop through parameters of %%%VAR-structure

			my $ki = $el->{ki};
			my $border = ( ! $col or ($col >= $#{ $columns } and (!defined( $ki ) or !length( $ki )) )) ? 1 : 0;

			my $val;
			if( defined $ki ) {
				if( $ki eq '%%%ADDA') {
					$val = '';
				}
				elsif( ref \$values->{$ki} eq 'SCALAR' and ( !$op->{def} or defined( $values->{$ki} ) ) ) { # HASH.SCALAR
					$val = $values->{$ki};
				}
				elsif( ref $values->{$ki} eq 'SCALAR' and ( !$op->{def} or defined( ${ $values->{$ki} } ) ) ) { # HASH.REF->SCALAR
					$val = ${ $values->{$ki} };
				}
				elsif( $ki eq '@' and ref $values->{'@'} eq 'ARRAY') {
					for my $k ( @{ $values->{'@'} } ) {
						next unless defined($k) && exists( $values->{$k} );

						my $v;
						if( ref \$values->{$k} eq 'SCALAR') {
							$v = $values->{$k};
						}
						elsif( ref $values->{$k} eq 'SCALAR') {
							$v = ${ $values->{$k} };
						}
						elsif( $op->{def} ) {
push @logs, "-->\tl.$. ". 'NOT HASH.ARRAY.SCALAR %%%V:@->{'.$k."} in %%%VAR:". $key if $DEBUG;

							next;
						}

						$end = &_hvt_print( $fh, $k, $v, $el, $op, $border ) and last _var_output_M0;
						$border = 0;
					}

					$end ? last : next;
				}
				elsif( $op->{def} ) {
push @logs, "~~> l.$. NOT HASH.SCALAR or NOT defined %%%V:". $ki if $DEBUG;

					next;
				}
			}
			else {
			# empty parameter -- at the very end of the columns (parameters)
				$ki = '';
			}

			$end = &_hvt_print( $fh, $ki, $val, $el, $op, $border ) and last;
		}
		continue {
			++$col;
		}
	}

	return $end;
}

1;

__END__