NAME

DTA::TokWrap::Utils - DTA tokenizer wrappers: generic utilities

SYNOPSIS

 use DTA::TokWrap::Utils qw(:files :slurp :progs :libxml :libxslt :time :si);
 
 ##========================================================================
 ## Utils: external programs
 
 $progpath_or_undef = path_prog($progname,%opts);
 $exitval = runcmd(@cmd);
 
 ##========================================================================
 ## Utils: XML::LibXML
 
 $parser = libxml_parser(%opts);
 
 ##========================================================================
 ## Utils: XML::LibXSLT
 
 $xslt = xsl_xslt();
 $stylesheet = xsl_stylesheet(file=>$xsl_file);
 
 ##========================================================================
 ## Utils: I/O: slurp
 
 \$txtbuf = slurp_file($filename_or_fh);
 
 ##========================================================================
 ## Utils: Files
 
 $mtime_in_floating_seconds = file_mtime($filename_or_fh);
 $bool = file_is_newer($dstFile, \@depFiles, $requireMissingDeps);
 $bool = file_try_open($filename);
 $abs_path_to_file = abs_path($file);
 $bool = str2file($string,$filename_or_fh,\%opts);
 $bool = ref2file($stringRef,$filename_or_fh,\%opts);
 
 ##========================================================================
 ## Utils: Time
 
 $stamp = timestamp();
 
 ##========================================================================
 ## Utils: SI
 
 $si_str = sistr($val, $printfFormatChar, $printfFormatPrecision);

DESCRIPTION

DTA::TokWrap::Utils provides diverse assorted miscellaneous utilities which don't fit well anywhere else and which don't on their own justify the creation of a new package.

Constants

@ISA

DTA::TokWrap::Utils inherits from DTA::TokWrap::Logger.

$TRACE_RUNCMD

Log-level for tracing runcmd() calls. Default='trace'. See DTA::TokWrap::Logger for details.

Exported under the :progs tag.

Utils: external programs

The following are exported under the :progs tag:

path_prog

 $progpath_or_undef = DTA::TokWrap::Utils::path_prog($progname,%opts);

Attempt to find an executable program $progname in $ENV{PATH}.

Known %opts:

 prepend => \@paths,  ##-- prepend @paths to Env::Path->PATH->List
 append  => \@paths,  ##-- append @paths to Env::Path->PATH->List
 warnsub => \&sub,    ##-- warn subroutine if program not found (undef for no warnings)

runcmd

 $exitval = DTA::TokWrap::Utils::runcmd(@cmd);

Just a wrapper for system() with optional logging via DTA::TokWrap::Logger.

Utils: XML::LibXML

The following are exported by the :libxml tag:

Variable: %LIBXML_PARSERS

%LIBXML_PARSERS

XML::LibXML parsers, keyed by parser attribute strings (see libxml_parser())

libxml_parser

 $parser = libxml_parser(%opts);

Known %opts (see XML::LibXML(3pm) for details):

 line_numbers    => $bool,  ##-- default: 1
 load_ext_dtd    => $bool,  ##-- default: 0
 validation      => $bool,  ##-- default: 0
 keep_blanks     => $bool,  ##-- default: 1
 expand_entities => $bool,  ##-- default: 1
 recover         => $bool,  ##-- default: 1

Utils: XML::LibXSLT

The following are exported by the :libxslt tag:

Variable: $XSLT

Package-global shared XML::LibXSLT object (or undef)

xsl_xslt

 $xslt = DTA::TokWrap::Utils::xsl_xslt();

Returns XML::LibXSLT object ($XSLT).

xsl_stylesheet

 $stylesheet = DTA::TokWrap::Utils::xsl_stylesheet(file=>$xsl_file);
 $stylesheet = DTA::TokWrap::Utils::xsl_stylesheet(fh=>$xsl_fh)
 $stylesheet = DTA::TokWrap::Utils::xsl_stylesheet(doc=>$xsl_doc)
 $stylesheet = DTA::TokWrap::Utils::xsl_stylesheet(string=>$xsl_string)

Compile an XSL stylesheet from specified source.

Utils: I/O: slurp

The following are exported by the :slurp tag:

slurp_file

 \$txtbuf = DTA::TokWrap::Utils::slurp_file($filename_or_fh);
 \$txtbuf = DTA::TokWrap::Utils::slurp_file($filename_or_fh,\$txtbuf)

Slurp an entire file into a string.

Utils: Files

The following are exported by the :files tag:

file_mtime

 $mtime_in_floating_seconds = file_mtime($filename_or_fh);

Get file modification time. De-references symlinks. Uses Time::HiRes::stat() if available, otherwise perl core function stat().

file_is_newer

 $bool = DTA::TokWrap::Utils::file_is_newer($dstFile, \@depFiles, $requireMissingDeps);

Returns true if $dstFile is newer than all existing @depFiles. If $requireMissingDeps is true, non-existent @depFiles will cause this function to return false.

file_try_open

 $bool = file_try_open($filename);

Tries to open() $filename; returns true if successful, otherwise populates $! with the relevant OS error message.

abs_path

 $abs_path_to_file = abs_path($file);

Get absolute path for a file or directory. De-references symlinks.

Imported from the Cwd module.

str2file

 $bool = str2file($string,$filename_or_fh,\%opts);

Dumps a string $string to a file $filename_or_fh. Opposite of slurp_file().

%opts: see ref2file().

ref2file

 $bool = ref2file($stringRef,$filename_or_fh,\%opts);

Dumps $$stringRef to $filename_or_fh. Opposite of slurp_file().

%opts:

 binmode => $layer,  ##-- binmode layer (e.g. ':raw') for $filename_or_fh? (default=none)

The following are exported by the :time tag:

Utils: Time

time

 $floating_seconds_since_epoch = PACAKGE::timestamp()

Just a wrapper for Time::HiRes::time().

Utils: SI

The following are exported by the :si tag:

sistr

 $si_str = sistr($val, $printfFormatChar, $printfFormatPrecision);

Returns an SI string for numeric value $val.

AUTHOR

Bryan Jurish <jurish@bbaw.de>

COPYRIGHT AND LICENSE

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.