##========================================================================
## POD DOCUMENTATION, auto-generated by podextract.perl

##========================================================================
## NAME
=pod

=head1 NAME

DiaColloDB::Utils - diachronic collocation database, generic utilities

=cut

##========================================================================
## SYNOPSIS
=pod

=head1 SYNOPSIS

 ##========================================================================
 ## PRELIMINARIES
 
 use DiaColloDB::Utils;
 
 ##========================================================================
 ## Functions: Fcntl
 
 $flags = PACKAGE::fcflags($flags);
 $bool = fcread($flags);
 $bool = fcwrite($flags);
 $bool = fctrunc($flags);
 $bool = fccreat($flags);
 $fh_or_undef = fcopen($file,$flags);
 
 ##========================================================================
 ## JSON: load
 
 $data = PACKAGE::loadJsonString( $string,%opts);
 $data = PACKAGE::loadJsonFile($filename_or_handle,%opts);
 
 ##========================================================================
 ## JSON: save
 
 $str = PACKAGE::saveJsonString($data);
 $bool = PACKAGE::saveJsonFile($data,$filename_or_handle,%opts);
 
 ##========================================================================
 ## Functions: env
 
 \%setenv = PACKAGE::env_set(%setenv);
 \%restored = PACKAGE::env_pop(%setenv);
 
 ##========================================================================
 ## Functions: run
 
 $fh_or_undef = PACKAGE::opencmd($cmd);
 $bool = crun(@IPC_Run_args);
 $bool = csort_to(\@sortargs, \&catcher);
 $bool = csortuc_to(\@sortargs, \&catcher);
 
 ##========================================================================
 ## Functions: pack filters
 
 $len = PACKAGE::packsize($packfmt);
 \&filter_sub = PACKAGE::packFilterStore($pack_template);
 \&filter_sub = PACKAGE::packFilterFetch($pack_template);
 
 ##========================================================================
 ## Math stuff
 
 $log2 = log2($x);
 $max2 = max2($x,$y);
 $min2 = min2($x,$y);
 
 ##========================================================================
 ## Functions: lists
 
 \@l_uniq = luniq(\@l);
 
 ##========================================================================
 ## Functions: regexes
 
 $re = regex($re_str);
 
 ##========================================================================
 ## Functions: html
 
 $escaped = htmlesc($str);
 
 ##========================================================================
 ## Functions: time
 
 $hms       = PACKAGE::s2hms($seconds,$sfmt="%06.3f");
 $timestr = PACKAGE::s2timestr($seconds,$sfmt="%f");
 $rfc_timestamp = PACAKGE->timestamp();
 
 ##========================================================================
 ## Functions: file
 
 $mtime = PACKAGE->file_mtime($file_or_fh);
 $timestamp = PACKAGE->file_timestamp($file_or_fh);
 $nbytes = du_file(@filenames_or_fh);
 $nbytes = du_glob(@globs);
 
 ##========================================================================
 ## Utils: SI
 
 $str = si_str($float);
 

=cut

##========================================================================
## DESCRIPTION
=pod

=head1 DESCRIPTION

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::Utils: Globals
=pod

=head2 Globals

=over 4

=item Variable: @ISA

DiaColloDB::Utils
inherits from
L<Exporter|Exporter>
and
L<DiaColloDB::Logger|DiaColloDB::Logger>.

=item Variable: %EXPORT_TAGS

Exportable tags:

 fcntl => [qw(fcflags fcread fcwrite fctrunc fccreat fcperl fcopen)],
 json  => [qw(loadJsonString loadJsonFile saveJsonString saveJsonFile)],
 sort  => [qw(csort_to csortuc_to)],
 run   => [qw(crun opencmd)],
 env   => [qw(env_set env_push env_pop)],
 pack  => [qw(packsize packFilterFetch packFilterStore)],
 math  => [qw($LOG2 log2 min2 max2)],
 list  => [qw(luniq)],
 regex => [qw(regex)],
 html  => [qw(htmlesc)],
 time  => [qw(s2hms s2timestr timestamp)],
 file  => [qw(file_mtime file_timestamp du_file du_glob)],
 si    => [qw(si_str)],

=item Variable: @EXPORT_OK

All symbols in %EXPORT_TAGS are exportable

=item Variable: @EXPORT

All symbols in %EXPORT_TAGS are exported by default.

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::Utils: Functions: Fcntl
=pod

=head2 Functions: Fcntl

=over 4

=item fcflags

 $flags = PACKAGE::fcflags($flags);

returns L<Fcntl|Fcntl> flags for symbolic string $flags

=item fcread

 $bool = fcread($flags);

returns true if any read-bits are set for $flags

=item fcwrite

 $bool = fcwrite($flags);

returns true if any write-bits are set for $flags

=item fctrunc

 $bool = fctrunc($flags);

returns true if truncate-bits are set for $flags

=item fccreat

 $bool = fccreat($flags);

returns true iff creation flag is set for $flags.

=item fcperl

 $str = fcperl($flags);

returns perl mode-string corresponding to $flags.

=item fcopen

 $fh_or_undef = fcopen($file,$flags);
 $fh_or_undef = fcopen($file,$flags,$mode,$perms)

opens $file with L<Fcntl|Fcntl>-style flags $flags.

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::Utils: JSON: load
=pod

=head2 JSON: load

=over 4

=item loadJsonString

 $data = PACKAGE::loadJsonString( $string,%opts);
 $data = PACKAGE::loadJsonString(\$string,%opts)

decodes JSON string.
%opts are passed to L<JSON::from_json()|JSON/from_json>.

=item loadJsonFile

 $data = PACKAGE::loadJsonFile($filename_or_handle,%opts);

loads JSON data from a file or filehandle.
%opts are passed to loadJsonString().

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::Utils: JSON: save
=pod

=head2 JSON: save

=over 4

=item saveJsonString

 $str = PACKAGE::saveJsonString($data);
 $str = PACKAGE::saveJsonString($data,%opts);

Encode data as a JSON string.
%opts are passed to L<JSON::to_json()|JSON/to_json>, e.g. (pretty=E<gt>0, canonical=E<gt>0)'.

=item saveJsonFile

 $bool = PACKAGE::saveJsonFile($data,$filename_or_handle,%opts);

Save JSON data to a file.
%opts are passed to saveJsonString().

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::Utils: Functions: env
=pod

=head2 Functions: env

=over 4

=item Variable: @env_stack

Stack of temporary environment variables.

=item env_set

 \%setenv = PACKAGE::env_set(%setenv);

Set or clear environment variables.

=item env_push

 \%oldvals = PACKAGE::env_push(%setenv);

Push old values for keys(%setenv) to @env_stack
and calls env_set(%setenv).

=item env_pop

 \%restored = PACKAGE::env_pop(%setenv);

Pops the most recent variable bindings from @env_stack
and restores them to the environment.

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::Utils: Functions: run
=pod

=head2 Functions: run

=over 4

=item opencmd

 $fh_or_undef = PACKAGE::opencmd($cmd);
 $fh_or_undef = PACKAGE::opencmd($mode,@argv);

does log trace at level $TRACE_RUNCMD

=item crun

 $bool = crun(@IPC_Run_args);

wrapper for IPC::Run::run(@IPC_Run_args) with $ENV{LC_ALL}='C'

=item csort_to

 $bool = csort_to(\@sortargs, \&catcher);

runs system sort and feeds resulting lines to \&catcher

=item csortuc_to

 $bool = csortuc_to(\@sortargs, \&catcher);

runs system sort | uniq -c and feeds resulting lines to \&catcher

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::Utils: Functions: pack filters
=pod

=head2 Functions: pack filters

=over 4

=item packsize

 $len = PACKAGE::packsize($packfmt);
 $len = PACKAGE::packsize($packfmt,@args);

get pack-size for $packfmt with args @args

=item packFilterStore

 \&filter_sub = PACKAGE::packFilterStore($pack_template);
 \&filter_sub = PACKAGE::packFilterStore([$pack_template_store, $pack_template_fetch]);
 \&filter_sub = PACKAGE::packFilterStore([\&pack_code_store,   \&pack_code_fetch]);

returns a L<DB_File|DB_File>-style STORE-filter sub for transparent packing of data to $pack_template

=item packFilterFetch

 \&filter_sub = PACKAGE::packFilterFetch($pack_template);
 \&filter_sub = PACKAGE::packFilterFetch([$pack_template_store, $pack_template_fetch]);
 \&filter_sub = PACKAGE::packFilterFetch([\&pack_code_store,   \&pack_code_fetch]);

returns a L<DB_File|DB_File>-style FETCH-filter sub for transparent unpacking of data from $pack_template.

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::Utils: Math stuff
=pod

=head2 Math stuff

=over 4

=item Variable: $LOG2

constant: C<log(2)> for binary logarithms.

=item log2

 $log2 = log2($x);

binary logarithm function.

=item max2

 $max2 = max2($x,$y);

maximum

=item min2

 $min2 = min2($x,$y);

minimum

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::Utils: Functions: lists
=pod

=head2 Functions: lists

=over 4

=item luniq

 \@l_uniq = luniq(\@l);

returns unique defined elements of @l

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::Utils: Functions: regexes
=pod

=head2 Functions: regexes

=over 4

=item regex

 $re = regex($re_str);


parses regex $re_str, which can optionally be "/"-quoted.
parses modifiers /[gimsadlu].
/g modifier is parsed a la ddc (match whole word).

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::Utils: Functions: html
=pod

=head2 Functions: html

=over 4

=item htmlesc

 $escaped = htmlesc($str);

escape an HTML string.

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::Utils: Functions: time
=pod

=head2 Functions: time

=over 4

=item s2hms

 $hms       = PACKAGE::s2hms($seconds,$sfmt="%06.3f");
 ($h,$m,$s) = PACKAGE::s2hms($seconds,$sfmt="%06.3f");

convert a time value in seconds to HH:MM:SS.SSSS format

=item s2timestr

 $timestr = PACKAGE::s2timestr($seconds,$sfmt="%f");

convert a time value in seconds to H?M?S.SSSS format

=item timestamp

 $rfc_timestamp = PACAKGE->timestamp();
 $rfc_timestamp = PACAKGE->timestamp($time);

Return a UTC ISO-8601 timestamp format "%Y-%m-%dT%H:%M%SZ" for the UNIX time $time.

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::Utils: Functions: file
=pod

=head2 Functions: file

=over 4

=item file_mtime

 $mtime = PACKAGE->file_mtime($file_or_fh);

get mtime (last modification time) for $file_or_fh.

=item file_timestamp

 $timestamp = PACKAGE->file_timestamp($file_or_fh);

get an ISO-8601 timestamp for mtime of $file_or_fh.

=item du_file

 $nbytes = du_file(@filenames_or_fhs);

return number of bytes used by @filesnames_or_fhs

=item du_glob

 $nbytes = du_glob(@globs);

return number of bytes used by files matching and $glob in @globs

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::Utils: Utils: SI
=pod

=head2 Utils: SI

=over 4

=item si_str

 $str = si_str($float);

returns an SI string for $float.

=back

=cut

##========================================================================
## END POD DOCUMENTATION, auto-generated by podextract.perl

##======================================================================
## Footer
##======================================================================
=pod

=head1 AUTHOR

Bryan Jurish E<lt>moocow@cpan.orgE<gt>

=head1 COPYRIGHT AND LICENSE

Copyright (C) 2015-2016 by Bryan Jurish

This package is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.14.2 or,
at your option, any later version of Perl 5 you may have available.

=head1 SEE ALSO

L<dcdb-create.per(1)|dcdb-create.perl>,
L<dcdb-query.perl(1)|dcdb-query.perl>,
L<dcdb-info.perl(1)|dcdb-info.perl>,
L<dcdb-export.perl(1)|dcdb-export.perl>,
L<dcdb-dump.perl(1)|dcdb-dump.perl>,
L<DiaColloDB(3pm)|DiaColloDB>,
L<perl(1)|perl>,
...



=cut
