.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Bio::Root::Utilities 3pm" .TH Bio::Root::Utilities 3pm "2021-08-15" "perl v5.32.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Bio::Root::Utilities \- general\-purpose utilities .SH "SYNOPSIS" .IX Header "SYNOPSIS" .SS "Object Creation" .IX Subsection "Object Creation" .Vb 3 \& # Using the supplied singleton object: \& use Bio::Root::Utilities qw(:obj); \& $Util\->some_method(); \& \& # Create an object manually: \& use Bio::Root::Utilities; \& my $util = Bio::Root::Utilities\->new(); \& $util\->some_method(); \& \& $date_stamp = $Util\->date_format(\*(Aqyyy\-mm\-dd\*(Aq); \& \& $clean = $Util\->untaint($dirty); \& \& $compressed = $Util\->compress(\*(Aq/home/me/myfile.txt\*(Aq) \& \& my ($mean, $stdev) = $Util\->mean_stdev( @data ); \& \& $Util\->authority("me@example.com"); \& $Util\->mail_authority("Something you should know about..."); \& \& ...and a host of other methods. See below. .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" Provides general-purpose utilities of potential interest to any Perl script. .PP The \f(CW\*(C`:obj\*(C'\fR tag is a convenience that imports a \f(CW$Util\fR symbol into your namespace representing a Bio::Root::Utilities object. This saves you from creating your own Bio::Root::Utilities object via \&\f(CW\*(C`Bio::Root::Utilities\->new()\*(C'\fR or from prefixing all method calls with \&\f(CW\*(C`Bio::Root::Utilities\*(C'\fR, though feel free to do these things if desired. Since there should normally not be a need for a script to have more than one Bio::Root::Utilities object, this module thus comes with it's own singleton. .SH "INSTALLATION" .IX Header "INSTALLATION" This module is included with the central Bioperl distribution: .PP .Vb 2 \& http://www.bioperl.org/wiki/Getting_BioPerl \& ftp://bio.perl.org/pub/DIST .Ve .PP Follow the installation instructions included in the \s-1README\s0 file. .SH "DEPENDENCIES" .IX Header "DEPENDENCIES" Inherits from Bio::Root::Root, and uses Bio::Root::IO and Bio::Root::Exception. .PP Relies on external executables for file compression/uncompression and sending mail. No paths to these are hard coded but are located as needed. .SH "SEE ALSO" .IX Header "SEE ALSO" .Vb 1 \& http://bioperl.org \- Bioperl Project Homepage .Ve .SH "ACKNOWLEDGEMENTS" .IX Header "ACKNOWLEDGEMENTS" This module was originally developed under the auspices of the Saccharomyces Genome Database: http://www.yeastgenome.org/ .SH "AUTHOR Steve Chervitz" .IX Header "AUTHOR Steve Chervitz" .SS "date_format" .IX Subsection "date_format" .Vb 10 \& Title : date_format \& Usage : $Util\->date_format( [FMT], [DATE]) \& Purpose : \-\- Get a string containing the formatted date or time \& : taken when this routine is invoked. \& : \-\- Provides a way to avoid using \`date\`. \& : \-\- Provides an interface to localtime(). \& : \-\- Interconverts some date formats. \& : \& : (For additional functionality, use Date::Manip or \& : Date::DateCalc available from CPAN). \& Example : $Util\->date_format(); \& : $date = $Util\->date_format(\*(Aqyyyy\-mmm\-dd\*(Aq, \*(Aq11/22/92\*(Aq); \& Returns : String (unless \*(Aqlist\*(Aq is provided as argument, see below) \& : \& : \*(Aqyyyy\-mm\-dd\*(Aq = 1996\-05\-03 # default format. \& : \*(Aqyyyy\-dd\-mm\*(Aq = 1996\-03\-05 \& : \*(Aqyyyy\-mmm\-dd\*(Aq = 1996\-May\-03 \& : \*(Aqd\-m\-y\*(Aq = 3\-May\-1996 \& : \*(Aqd m y\*(Aq = 3 May 1996 \& : \*(Aqdmy\*(Aq = 3may96 \& : \*(Aqmdy\*(Aq = May 3, 1996 \& : \*(Aqymd\*(Aq = 96may3 \& : \*(Aqmd\*(Aq = may3 \& : \*(Aqyear\*(Aq = 1996 \& : \*(Aqhms\*(Aq = 23:01:59 # when not converting a format, \*(Aqhms\*(Aq can be \& : # tacked on to any of the above options \& : # to add the time stamp: eg \*(Aqdmyhms\*(Aq \& : \*(Aqfull\*(Aq | \*(Aqunix\*(Aq = UNIX\-style date: Tue May 5 22:00:00 1998 \& : \*(Aqlist\*(Aq = the contents of localtime(time) in an array. \& Argument : (all are optional) \& : FMT = yyyy\-mm\-dd | yyyy\-dd\-mm | yyyy\-mmm\-dd | \& : mdy | ymd | md | d\-m\-y | hms | hm \& : (\*(Aqhms\*(Aq may be appended to any of these to \& : add a time stamp) \& : \& : DATE = String containing date to be converted. \& : Acceptable input formats: \& : 12/1/97 (for 1 December 1997) \& : 1997\-12\-01 \& : 1997\-Dec\-01 \& Throws : \& Comments : If you don\*(Aqt care about formatting or using backticks, you can \& : always use: $date = \`date\`; \& : \& : For more features, use Date::Manip.pm, (which I should \& : probably switch to...) .Ve .PP See Also : \fBfile_date()\fR, \fBmonth2num()\fR .SS "month2num" .IX Subsection "month2num" .Vb 7 \& Title : month2num \& Purpose : Converts a string containing a name of a month to integer \& : representing the number of the month in the year. \& Example : $Util\->month2num("march"); # returns 3 \& Argument : The string argument must contain at least the first \& : three characters of the month\*(Aqs name. Case insensitive. \& Throws : Exception if the conversion fails. .Ve .SS "num2month" .IX Subsection "num2month" .Vb 5 \& Title : num2month \& Purpose : Does the opposite of month2num. \& : Converts a number into a string containing a name of a month. \& Example : $Util\->num2month(3); # returns \*(AqMar\*(Aq \& Throws : Exception if supplied number is out of range. .Ve .SS "compress" .IX Subsection "compress" .Vb 10 \& Title : compress \& Usage : $Util\->compress(full\-path\-filename); \& : $Util\->compress(); \& Purpose : Compress a file. \& Example : $Util\->compress("/usr/people/me/data.txt"); \& : $Util\->compress(\-file=>"/usr/people/me/data.txt", \& : \-tmp=>1, \& : \-outfile=>"/usr/people/share/data.txt.gz", \& : \-exe=>"/usr/local/bin/fancyzip"); \& Returns : String containing full, absolute path to compressed file \& Argument : Named parameters (case\-insensitive): \& : \-FILE => String (name of file to be compressed, full path). \& : If the supplied filename ends with \*(Aq.gz\*(Aq or \*(Aq.Z\*(Aq, \& : that extension will be removed before attempting to compress. \& : Optional: \& : \-TMP => boolean. If true, (or if user is not the owner of the file) \& : the file is compressed to a temp file. If false, file may be \& : clobbered with the compressed version (if using a utility like \& : gzip, which is the default) \& : \-OUTFILE => String (name of the output compressed file, full path). \& : \-EXE => Name of executable for compression utility to use. \& : Will supersede those in @COMPRESSION_UTILS defined by \& : this module. If the absolute path to the executable is not provided, \& : it will be searched in the PATH env variable. \& Throws : Exception if file cannot be compressed. \& : If user is not owner of the file, generates a warning and compresses to \& : a tmp file. To avoid this warning, use the \-o file test operator \& : and call this function with \-TMP=>1. \& Comments : Attempts to compress using utilities defined in the @COMPRESSION_UTILS \& : defined by this module, in the order defined. The first utility that is \& : found to be executable will be used. Any utility defined in optional \-EXE param \& : will be tested for executability first. \& : To minimize security risks, the \-EXE parameter value is untained using \& : the untaint() method of this module (in \*(Aqrelaxed\*(Aq mode to permit path separators). .Ve .PP See Also : \fBuncompress()\fR .SS "uncompress" .IX Subsection "uncompress" .Vb 10 \& Title : uncompress \& Usage : $Util\->uncompress(full\-path\-filename); \& : $Util\->uncompress(); \& Purpose : Uncompress a file. \& Example : $Util\->uncompress("/usr/people/me/data.txt"); \& : $Util\->uncompress(\-file=>"/usr/people/me/data.txt.gz", \& : \-tmp=>1, \& : \-outfile=>"/usr/people/share/data.txt", \& : \-exe=>"/usr/local/bin/fancyzip"); \& Returns : String containing full, absolute path to uncompressed file \& Argument : Named parameters (case\-insensitive): \& : \-FILE => String (name of file to be uncompressed, full path). \& : If the supplied filename ends with \*(Aq.gz\*(Aq or \*(Aq.Z\*(Aq, \& : that extension will be removed before attempting to uncompress. \& : Optional: \& : \-TMP => boolean. If true, (or if user is not the owner of the file) \& : the file is uncompressed to a temp file. If false, file may be \& : clobbered with the uncompressed version (if using a utility like \& : gzip, which is the default) \& : \-OUTFILE => String (name of the output uncompressed file, full path). \& : \-EXE => Name of executable for uncompression utility to use. \& : Will supersede those in @UNCOMPRESSION_UTILS defined by \& : this module. If the absolute path to the executable is not provided, \& : it will be searched in the PATH env variable. \& Throws : Exception if file cannot be uncompressed. \& : If user is not owner of the file, generates a warning and uncompresses to \& : a tmp file. To avoid this warning, use the \-o file test operator \& : and call this function with \-TMP=>1. \& Comments : Attempts to uncompress using utilities defined in the @UNCOMPRESSION_UTILS \& : defined by this module, in the order defined. The first utility that is \& : found to be executable will be used. Any utility defined in optional \-EXE param \& : will be tested for executability first. \& : To minimize security risks, the \-EXE parameter value is untained using \& : the untaint() method of this module (in \*(Aqrelaxed\*(Aq mode to permit path separators). .Ve .PP See Also : \fBcompress()\fR .SS "file_date" .IX Subsection "file_date" .Vb 10 \& Title : file_date \& Usage : $Util\->file_date( filename [,date_format]) \& Purpose : Obtains the date of a given file. \& : Provides flexible formatting via date_format(). \& Returns : String = date of the file as: yyyy\-mm\-dd (e.g., 1997\-10\-15) \& Argument : filename = string, full path name for file \& : date_format = string, desired format for date (see date_format()). \& : Default = yyyy\-mm\-dd \& Thows : Exception if no file is provided or does not exist. \& Comments : Uses the mtime field as obtained by stat(). .Ve .SS "untaint" .IX Subsection "untaint" .Vb 10 \& Title : untaint \& Purpose : To remove nasty shell characters from untrusted data \& : and allow a script to run with the \-T switch. \& : Potentially dangerous shell meta characters: &;\`\*(Aq\e"|*?!~<>^()[]{}$\en\er \& : Accept only the first block of contiguous characters: \& : Default allowed chars = "\-\ew.\*(Aq, ()" \& : If $relax is true = "\-\ew.\*(Aq, ()\e/=%:^<>*" \& Usage : $Util\->untaint($value, $relax) \& Returns : String containing the untained data. \& Argument: $value = string \& : $relax = boolean \& Comments: \& This general untaint() function may not be appropriate for every situation. \& To allow only a more restricted subset of special characters \& (for example, untainting a regular expression), then using a custom \& untainting mechanism would permit more control. \& \& Note that special trusted vars (like $0) require untainting. .Ve .SS "mean_stdev" .IX Subsection "mean_stdev" .Vb 6 \& Title : mean_stdev \& Usage : ($mean, $stdev) = $Util\->mean_stdev( @data ) \& Purpose : Calculates the mean and standard deviation given a list of numbers. \& Returns : 2\-element list (mean, stdev) \& Argument : list of numbers (ints or floats) \& Thows : n/a .Ve .SS "count_files" .IX Subsection "count_files" .Vb 10 \& Title : count_files \& Purpose : Counts the number of files/directories within a given directory. \& : Also reports the number of text and binary files in the dir \& : as well as names of these files and directories. \& Usage : count_files(\e%data) \& : $data{\-DIR} is the directory to be analyzed. Default is ./ \& : $data{\-PRINT} = 0|1; if 1, prints results to STDOUT, (default=0). \& Argument : Hash reference (empty) \& Returns : n/a; \& : Modifies the hash ref passed in as the sole argument. \& : $$href{\-TOTAL} scalar \& : $$href{\-NUM_TEXT_FILES} scalar \& : $$href{\-NUM_BINARY_FILES} scalar \& : $$href{\-NUM_DIRS} scalar \& : $$href{\-T_FILE_NAMES} array ref \& : $$href{\-B_FILE_NAMES} array ref \& : $$href{\-DIRNAMES} array ref .Ve .SS "file_info" .IX Subsection "file_info" .Vb 4 \& Title : file_info \& Purpose : Obtains a variety of date for a given file. \& : Provides an interface to Perl\*(Aqs stat(). \& Status : Under development. Not ready. Don\*(Aqt use! .Ve .SS "delete" .IX Subsection "delete" .Vb 2 \& Title : delete \& Purpose : .Ve .SS "create_filehandle" .IX Subsection "create_filehandle" .Vb 10 \& Usage : $object\->create_filehandle(); \& Purpose : Create a FileHandle object from a file or STDIN. \& : Mainly used as a helper method by read() and get_newline(). \& Example : $data = $object\->create_filehandle(\-FILE =>\*(Aqusr/people/me/data.txt\*(Aq) \& Argument : Named parameters (case\-insensitive): \& : (all optional) \& : \-CLIENT => object reference for the object submitting \& : the request. Default = $Util. \& : \-FILE => string (full path to file) or a reference \& : to a FileHandle object or typeglob. This is an \& : optional parameter (if not defined, STDIN is used). \& Returns : Reference to a FileHandle object. \& Throws : Exception if cannot open a supplied file or if supplied with a \& : reference that is not a FileHandle ref. \& Comments : If given a FileHandle reference, this method simply returns it. \& : This method assumes the user wants to read ascii data. So, if \& : the file is binary, it will be treated as a compressed (gzipped) \& : file and access it using gzip \-ce. The problem here is that not \& : all binary files are necessarily compressed. Therefore, \& : this method should probably have a \-mode parameter to \& : specify ascii or binary. .Ve .PP See Also : \fBget_newline()\fR .SS "get_newline" .IX Subsection "get_newline" .Vb 8 \& Usage : $object\->get_newline(); \& Purpose : Determine the character(s) used for newlines in a given file or \& : input stream. Delegates to Bio::Root::Utilities::get_newline() \& Example : $data = $object\->get_newline(\-CLIENT => $anObj, \& : \-FILE =>\*(Aqusr/people/me/data.txt\*(Aq) \& Argument : Same arguemnts as for create_filehandle(). \& Returns : Reference to a FileHandle object. \& Throws : Propagates any exceptions thrown by Bio::Root::Utilities::get_newline(). .Ve .PP See Also : \fBtaste_file()\fR, \fBcreate_filehandle()\fR .SS "taste_file" .IX Subsection "taste_file" .Vb 10 \& Usage : $object\->taste_file( ); \& : Mainly a utility method for get_newline(). \& Purpose : Sample a filehandle to determine the character(s) used for a newline. \& Example : $char = $Util\->taste_file($FH) \& Argument : Reference to a FileHandle object. \& Returns : String containing an octal represenation of the newline character string. \& : Unix = "\e012" ("\en") \& : Win32 = "\e012\e015" ("\er\en") \& : Mac = "\e015" ("\er") \& Throws : Exception if no input is read within $TIMEOUT_SECS seconds. \& : Exception if argument is not FileHandle object reference. \& : Warning if cannot determine neewline char(s). \& Comments : Based on code submitted by Vicki Brown (vlb@deltagen.com). .Ve .PP See Also : \fBget_newline()\fR .SS "file_flavor" .IX Subsection "file_flavor" .Vb 12 \& Usage : $object\->file_flavor( ); \& Purpose : Returns the \*(Aqflavor\*(Aq of a given file (unix, dos, mac) \& Example : print "$file has flavor: ", $Util\->file_flavor($file); \& Argument : filename = string, full path name for file \& Returns : String describing flavor of file and handy info about line endings. \& : One of these is returned: \& : unix (\en or 012 or ^J) \& : dos (\er\en or 015,012 or ^M^J) \& : mac (\er or 015 or ^M) \& : unknown \& Throws : Exception if argument is not a file \& : Propagates any exceptions thrown by Bio::Root::Utilities::get_newline(). .Ve .PP See Also : \fBget_newline()\fR, \fBtaste_file()\fR .SS "mail_authority" .IX Subsection "mail_authority" .Vb 3 \& Title : mail_authority \& Usage : $Util\->mail_authority( $message ) \& Purpose : Syntactic sugar to send email to $Bio::Root::Global::AUTHORITY .Ve .PP See Also : \fBsend_mail()\fR .SS "authority" .IX Subsection "authority" .Vb 3 \& Title : authority \& Usage : $Util\->authority(\*(Aqadmin@example.com\*(Aq); \& Purpose : Set/get the email address that should be notified by mail_authority() .Ve .PP See Also : \fBmail_authority()\fR .SS "send_mail" .IX Subsection "send_mail" .Vb 10 \& Title : send_mail \& Usage : $Util\->send_mail( named_parameters ) \& Purpose : Provides an interface to mail or sendmail, if available \& Returns : n/a \& Argument : Named parameters: (case\-insensitive) \& : \-TO => e\-mail address to send to \& : \-SUBJ => subject for message (optional) \& : \-MSG => message to be sent (optional) \& : \-CC => cc: e\-mail address (optional) \& Thows : Exception if TO: address appears bad or is missing. \& : Exception if mail cannot be sent. \& Comments : Based on TomC\*(Aqs tip at: \& : http://www.perl.com/CPAN/doc/FMTEYEWTK/safe_shellings \& : \& : Using default \*(AqFrom:\*(Aq information. \& : sendmail options used: \& : \-t: ignore the address given on the command line and \& : get To:address from the e\-mail header. \& : \-oi: prevents send_mail from ending the message if it \& : finds a period at the start of a line. .Ve .PP See Also : \fBmail_authority()\fR .SS "find_exe" .IX Subsection "find_exe" .Vb 10 \& Title : find_exe \& Usage : $Util\->find_exe(name); \& Purpose : Locate an executable (for use in a system() call, e.g.)) \& Example : $Util\->find_exe("gzip"); \& Returns : String containing executable that passes the \-x test. \& Returns undef if an executable of the supplied name cannot be found. \& Argument : Name of executable to be found. \& : Can be a full path. If supplied name is not executable, an executable \& : of that name will be searched in all directories in the currently \& : defined PATH environment variable. \& Throws : No exceptions, but issues a warning if multiple paths are found \& : for a given name. The first one is used. \& Comments : TODO: Confirm functionality on all bioperl\-supported platforms. \& May get tripped up by variation in path separator character used \& for splitting ENV{PATH}. \&See Also : .Ve .SS "yes_reply" .IX Subsection "yes_reply" .Vb 9 \& Title : yes_reply() \& Usage : $Util\->yes_reply( [query_string]); \& Purpose : To test an STDIN input value for affirmation. \& Example : print +( $Util\->yes_reply(\*(AqAre you ok\*(Aq) ? "great!\en" : "sorry.\en" ); \& : $Util\->yes_reply(\*(AqContinue\*(Aq) || die; \& Returns : Boolean, true (1) if input string begins with \*(Aqy\*(Aq or \*(AqY\*(Aq \& Argument: query_string = string to be used to prompt user (optional) \& : If not provided, \*(AqYes or no\*(Aq will be used. \& : Question mark is automatically appended. .Ve .SS "request_data" .IX Subsection "request_data" .Vb 9 \& Title : request_data() \& Usage : $Util\->request_data( [value_name]); \& Purpose : To request data from a user to be entered via keyboard (STDIN). \& Example : $name = $Util\->request_data(\*(AqName\*(Aq); \& : # User will see: % Enter Name: \& Returns : String, (data entered from keyboard, sans terminal newline.) \& Argument: value_name = string to be used to prompt user. \& : If not provided, \*(Aqdata\*(Aq will be used, (not very helpful). \& : Question mark is automatically appended. .Ve .SS "quit_reply" .IX Subsection "quit_reply" .Vb 3 \& Title : quit_reply \& Usage : \& Purpose : .Ve .SS "verify_version" .IX Subsection "verify_version" .Vb 3 \& Purpose : Checks the version of Perl used to invoke the script. \& : Aborts program if version is less than the given argument. \& Usage : verify_version(\*(Aq5.000\*(Aq) .Ve