NAME

Data::Tools provides set of basic functions for data manipulation.

SYNOPSIS

use Data::Tools qw( :all );  # import all functions
use Data::Tools;             # the same as :all :)
use Data::Tools qw( :none ); # do not import anything, use full package names

# --------------------------------------------------------------------------

# these set the encoding used by the file_text_* functions only:

data_tools_set_text_io_encoding( 'UTF-8' ); # file_text_* io will use UTF-8
data_tools_set_text_io_utf8();              # the same, shortcut
data_tools_set_text_io_bin();               # file_text_* io will use binary data

my $res  = file_save( $file_name, 'file content here' );
my $data = file_load( $file_name );

my $data_arrayref = file_load_ar( $file_name );

# for specific charset encoding and because of backward compatibility:

my $res  = file_save( { FILE_NAME => $file_name, ENCODING => 'UTF-8' }, 'data' );
my $data = file_load( { FILE_NAME => $file_name, ENCODING => 'UTF-8' } );

my $data_arrayref = file_load_ar( { FILE_NAME => $fname, ENCODING => 'UTF-8' } );

# ':RAW' => 1 reads/writes binary data:

my $res  = file_save( { FILE_NAME => $file_name, ':RAW' => 1 }, $binary_data );
my $data = file_load( { FILE_NAME => $file_name, ':RAW' => 1 } );

# --------------------------------------------------------------------------

my $file_modification_time_in_seconds = file_mtime( $file_name );
my $file_change_time_in_seconds       = file_ctime( $file_name );
my $file_last_access_time_in_seconds  = file_atime( $file_name );
my $file_size                         = file_size(  $file_name );

# --------------------------------------------------------------------------

my $res  = dir_path_make( '/path/to/somewhere' ); # create full path with 0700
my $res  = dir_path_make( '/new/path', MASK => 0755 ); # ...with mask 0755
my $path = dir_path_ensure( '/path/s/t/h' ); # ensure path exists, check+make

# --------------------------------------------------------------------------

my $path_with_trailing_slash = file_path( $full_path_or_file_name );

# file_name() and file_name_ext() return full name with leadeing
# dot for dot-files ( .filename )
my $file_name_including_ext  = file_name_ext( $full_path_or_file_name );
my $file_name_only_no_ext    = file_name( $full_path_or_file_name );

# file_ext() returns undef for dot-files ( .filename )
my $file_ext_only            = file_ext( $full_path_or_file_name );

# --------------------------------------------------------------------------

# uses simple backslash escaping of \n, = and \ itself
my $data_str = hash2str( $hash_ref ); # convert hash to string "key=value\n"
my $hash_ref = str2hash( $hash_str ); # convert str "key-value\n" to hash

# same as hash2str() but uses keys in certain order
my $data_str = hash2str_keys( \%hash, sort keys %hash );
my $data_str = hash2str_keys( \%hash, sort { $a <=> $b } keys %hash );

# same as hash2str() and str2hash() but uses URL-style escaping
my $data_str = hash2str_url( $hash_ref ); # convert hash to string "key=value\n"
my $hash_ref = str2hash_url( $hash_str ); # convert str "key-value\n" to hash

my $hash_ref = url2hash( 'key1=val1&key2=val2&testing=tralala);
# $hash_ref will be { key1 => 'val1', key2 => 'val2', testing => 'tralala' }

my $hash_ref_with_upper_case_keys = hash_uc( $hash_ref_with_lower_case_keys );
my $hash_ref_with_lower_case_keys = hash_lc( $hash_ref_with_upper_case_keys );

hash_uc_ipl( $hash_ref_to_be_converted_to_upper_case_keys );
hash_lc_ipl( $hash_ref_to_be_converted_to_lower_case_keys );

# save/load hash in str_url_escaped form to/from a file
my $res      = hash_save( $file_name, $hash_ref );
my $hash_ref = hash_load( $file_name );

# save hash with certain keys order, uses hash2str_keys()
my $res      = hash_save( $file_name, \%hash, sort keys %hash );

# same as hash_save() and hash_load() but uses hash2str_url() and str2hash_url()
my $res      = hash_save_url( $file_name, $hash_ref );
my $hash_ref = hash_load_url( $file_name );

# validate (nested) hash by example

# validation example nested hash
my $validate_hr = {
                  A => 'INT',
                  B => 'INT(-5,10)',
                  C => 'REAL',
                  D => {
                       E => 'RE:\d+[a-f]*',  # regexp match
                       F => 'REI:\d+[a-f]*', # case insensitive regexp match
                       },
                  DIR1  => '-d',   # must be existing directory
                  DIR2  => 'dir',  # must be existing directory
                  FILE1 => '-f',   # must be existing file
                  FILE2 => 'file', # must be existing file
                  };
# actual nested hash to be verified if looks like the example
my $data_hr     = {
                  A => '123',
                  B =>  '-1',
                  C =>  '1 234 567.89',
                  D => {
                       E => '123abc',
                       F => '456FFF',
                       },
                  }

my @invalid_keys = hash_validate( $data_hr, $validate_hr );
print "YES!" if hash_validate( $data_hr, $validate_hr );

# --------------------------------------------------------------------------

my $escaped   = str_url_escape( $plain_str ); # URL-style %XX escaping
my $plain_str = str_url_unescape( $escaped );

my $escaped   = str_html_escape( $plain_str ); # HTML-style &name; escaping
my $plain_str = str_html_unescape( $escaped );

my $hex_str   = str_hex( $plain_str ); # HEX-style XX string escaping
my $plain_str = str_unhex( $hex_str );

# --------------------------------------------------------------------------

# converts perl package names to file names, f.e: returns "Data/Tools.pm"
my $perl_pkg_fn = perl_package_to_file( 'Data::Tools' );

# --------------------------------------------------------------------------

# calculating hex digests
my $whirlpool_hex = wp_hex( $data );
my $sha1_hex      = sha1_hex( $data );
my $md5_hex       = md5_hex( $data );

# --------------------------------------------------------------------------

my $formatted_str = str_num_comma( 1234567.89 );   # returns "1'234'567.89"
my $formatted_str = str_num_comma( 4325678, '_' ); # returns "4_325_678"
my $padded_str    = str_pad( 'right', -12, '*' ); # returns "right*******"
my $str_c         = str_countable( $dc, 'day', 'days' );
                    # returns 'days' for $dc == 0
                    # returns 'day'  for $dc == 1
                    # returns 'days' for $dc >  1

my $num = str_kmg_to_num(   '1K' ); # returns 1024
my $num = str_kmg_to_num( '2.5M' ); # returns 2621440
my $num = str_kmg_to_num(   '1T' ); # returns 1099511627776

# --------------------------------------------------------------------------

# find all *.txt files in all subdirectories starting from /usr/local
# returned files are with full path names
my @files = glob_tree( '/usr/local/*.txt' );

# read directory entries names (without full paths)
my @files_and_dirs = read_dir_entries( '/tmp/secret/dir' );

# --------------------------------------------------------------------------

my $int   = bcd2int( $bcd_bytes ); # convert BCD byte data to integer
my $bytes = int2bcd( $int );       # convert integer to BCD bytes
my $str   = bcd2str( $bcd_bytes ); # convert BCD byte data to string

FUNCTIONS

hash_validate( $data_hr, $validate_hr );

Return value can be either scalar or array context. In scalar context return value is true (1) or false (0). In array context it returns list of the invalid keys (possibly key paths like 'KEY1/KEY2/KEY3'):

# array context
my @invalid_keys = hash_validate( $data_hr, $validate_hr );

# scalar context
print "YES!" if hash_validate( $data_hr, $validate_hr );

TODO

(more docs)

DATA::TOOLS SUB-MODULES

Data::Tools package includes several sub-modules:

* Data::Tools::Socket (socket I/O processing, TODO: docs)
* Data::Tools::Time   (time processing)

REQUIRED MODULES

Data::Tools is designed to be simple, compact and self sufficient. However it uses some 3rd party modules:

* Digest::Whirlpool
* Digest::MD5
* Digest::SHA1
* JSON

GITHUB REPOSITORY

git@github.com:cade-vs/perl-data-tools.git

git clone git://github.com/cade-vs/perl-data-tools.git

AUTHOR

Vladi Belperchinov-Shabanski "Cade"
      <cade@noxrun.com> <cade@bis.bg> <cade@cpan.org>
http://cade.noxrun.com/

NAME

Data::Tools::Socket provides set of socket I/O functions.

SYNOPSIS

use Data::Tools::Socket qw( :all );  # import all functions
use Data::Tools::Socket;             # the same as :all :)
use Data::Tools::Socket qw( :none ); # do not import anything, use full package names

# --------------------------------------------------------------------------

my $read_res_len  = socket_read(  $socket, $data_ref, $length, $timeout );
my $write_res_len = socket_write( $socket, $data,     $length, $timeout );
my $write_res_len = socket_print( $socket, $data, $timeout );

# --------------------------------------------------------------------------

my $read_data = socket_read_message(  $socket, $timeout );
my $write_res = socket_write_message( $socket, $data, $timeout );

# --------------------------------------------------------------------------

FUNCTIONS