view release on metacpan or  search on metacpan

lib/Banal/Utils/Data.pm  view on Meta::CPAN

#===============================================
package Banal::Utils::Data;

use 5.006;
use utf8;
use strict;
use warnings;
no  warnings qw(uninitialized);

require Exporter;

our @ISA 		= qw(Exporter);
our @EXPORT_OK 	= qw(   banal_get_data 
						flatten_complex_data_to_list 
						flatten_complex_data_to_list_with_options
					);
use Carp;
use Data::Dumper;
use Banal::Utils::String 	qw(trim);
use Banal::Utils::Array 	qw(array1_starts_with_array2);




##############################################################################"
# PUBLIC (exportable) FUNCTIONS
##############################################################################"


#----------------------------------
# Function, not a method!
#----------------------------------
sub banal_get_data {
	my $args								= {@_};
	my $opts								= $args->{options} || {};
	my $search_upwards_while_not_defined	= $opts->{search_upwards_while_not_defined};

	
	
	# This is where the MAGIC happens. For a full list of options, see the function "normalize_data_root_and_keys()".
	my ($root, @keys) 						= _normalize_data_root_and_keys (@_);		
			
	# The data root should have been defined by now. 
	return unless ($root); 
	
	# All this for nothing? 	
	return $root if (scalar(@keys)  < 1);

	# The reason for the below loop is to allow outer level 'variables' to be used when the variable is not defined at the proper (inner) level.
	# Very handy for CONFIGURATION handling scenarios.
	my $key		= pop @keys;
	while (scalar(@keys) >= 0) {
		my $value= _banal_basic_get_data_via_key_list(data=>$root, keys=>[@keys, $key]);	
		return $value if defined($value);	
		
		# Continue searching upwards if we are allowed to do so. Return otherwise.
		return unless $search_upwards_while_not_defined;
			
		pop @keys;
	}
	return;
}



#-----------------------------------------------
# FUNCTION (not a method).
#-----------------------------------------------
sub flatten_complex_data_to_list {
	return flatten_complex_data_to_list_with_options (data=>[@_], on_ArrayRef=>'flatten',  on_HashRef=>'flatten', on_ScalarRef=>'flatten');
}


#-----------------------------------------------
# FUNCTION (not a method).
#-----------------------------------------------
sub flatten_complex_data_to_list_with_options {
	my $opts 			= {@_};
	my $data			= $opts->{data};
	my $on_ArrayRef		= $opts->{on_ArrayRef}	|| 'flatten';
	my $on_HashRef		= $opts->{on_HashRef}	|| 'flatten';
	my $on_ScalarRef	= $opts->{on_ScalarRef}	|| 'flatten';
	my @list			= ();
	
	foreach my $datum (@$data) {
		if 		((reftype($datum) eq 'ARRAY') 	&& ($on_ArrayRef 	=~ /^flatten|dereference$/io)){
				push @list, flatten_complex_data_to_list_with_options(data=>$datum);
				next;
		}elsif ((reftype($datum) eq 'HASH') 	&& ($on_HashRef 	=~ /^flatten|dereference$/io)){
				push @list, flatten_complex_data_to_list_with_options(data=>[%$datum]);
				next;
		}elsif 	((reftype($datum) eq 'SCALAR') 	&& ($on_ScalarRef 	=~ /^flatten|dereference$/io)){
				push @list, flatten_complex_data_to_list_with_options(data=>[$$datum]);;
				next;

		}else {
				push @list, $datum;
				next;			
		}
		
	}
	return @list;
}


#*******************************************************************
# PRIVATE (non-exported) FUNCTIONS
#*******************************************************************
 
#----------------------------------
sub _is_absolute_data_key_reference {
	return ((scalar(@_)  > 0) && !$_[0]);		
}

#----------------------------------
sub _normalize_data_root_and_keys {
	my $args								= {@_};