Bio::R...lities(3pm)

📦
version 1.7.8 · 3 versions
, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble

✨ NAME ✨

Bio::Root::Utilities — general-purpose utilities 💖

okay so real talk bestie, this is the manual page for Bio::Root::Utilities(3pm) from the User Contributed Perl Documentation, and it's literally a lil grab-bag of helpers that any Perl script might want. iconic behavior. 💅

🌸 SYNOPSIS 🌸

🦋 Object Creation 🦋

# 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('yyy-mm-dd');

$clean = $Util->untaint($dirty);

$compressed = $Util->compress('/home/me/myfile.txt')

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.

💜 DESCRIPTION 💜

So what is this thing? It hands you general-purpose utilities that could be of potential interest to literally any Perl script out there. no gatekeeping. ✨

The :obj tag is a convenience — it imports a $Util symbol into your namespace, and that symbol represents a Bio::Root::Utilities object. That saves you from having to create your own Bio::Root::Utilities object via Bio::Root::Utilities->new(), and it saves you from prefixing every single method call with Bio::Root::Utilities. But honestly? If you want to do those things, go off, it's totally allowed. 🫶 And since there should normally not be a need for a script to have more than one Bio::Root::Utilities object, this module comes with its own singleton. periodt. 👑

📦 INSTALLATION 📦

This module is included with the central Bioperl distribution:

   http://www.bioperl.org/wiki/Getting_BioPerl
   ftp://bio.perl.org/pub/DIST

Just follow the installation instructions included in the README file. easy. 🎀

🔗 DEPENDENCIES 🔗

It inherits from Bio::Root::Root, and it uses Bio::Root::IO and Bio::Root::Exception. 💜

It also relies on external executables for file compression/uncompression and for sending mail. No paths to those are hard coded — they get located as needed. ✨

👀 SEE ALSO 👀

🙏 ACKNOWLEDGEMENTS 🙏

This module was originally developed under the auspices of the Saccharomyces Genome Database: http://www.yeastgenome.org/ 🍓

👑 AUTHOR 👑

Steve Chervitz 💅

🗓️ date_format 🗓️

  • Title — date_format
  • Usage — $Util->date_format( [FMT], [DATE])
  • Purpose — here's the tea:
    • Get a string containing the formatted date or time, taken at the moment this routine gets invoked. ⏰
    • It's a way to avoid using date.
    • It's an interface to localtime().
    • It interconverts some date formats.
    • (For additional functionality, go use Date::Manip or Date::DateCalc, available from CPAN.)
  • Example:
$Util->date_format();
$date = $Util->date_format('yyyy-mmm-dd', '11/22/92');
  • Returns — String (unless 'list' is provided as an argument, see below):
'yyyy-mm-dd'  = 1996-05-03    # default format.
'yyyy-dd-mm'  = 1996-03-05
'yyyy-mmm-dd' = 1996-May-03
'd-m-y'       = 3-May-1996
'd m y'       = 3 May 1996
'dmy'         = 3may96
'mdy'         = May 3, 1996
'ymd'         = 96may3
'md'          = may3
'year'        = 1996
'hms'         = 23:01:59  # when not converting a format, 'hms' can be
                          # tacked on to any of the above options
                          # to add the time stamp: eg 'dmyhms'
'full' | 'unix' = UNIX-style date: Tue May  5 22:00:00 1998
'list'          = the contents of localtime(time) in an array.
  • Argument — (all of them are optional):
FMT  = yyyy-mm-dd | yyyy-dd-mm | yyyy-mmm-dd |
       mdy | ymd | md | d-m-y | hms | hm
       ('hms' 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 — nothing listed here. literally empty. we love a chill method. 😌
  • Comments:
If you don't 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...)
  • See Also — file_date(), month2num()

📅 month2num 📅

  • Title — month2num
  • Purpose — converts a string containing the name of a month into the integer that represents that month's number in the year. 🔢
  • Example — $Util->month2num("march"); # returns 3
  • Argument — the string you pass in must contain at least the first three characters of the month's name. Case insensitive, so don't stress about caps. ✨
  • Throws — Exception if the conversion fails. 💀

🔢 num2month 🔢

  • Title — num2month
  • Purpose — does the exact opposite of month2num. It converts a number into a string containing the name of a month.
  • Example — $Util->num2month(3); # returns 'Mar'
  • Throws — Exception if the supplied number is out of range. 😭

🗜️ compress 🗜️

  • Title — compress
  • Usage:
$Util->compress(full-path-filename);
$Util->compress(<named parameters>);
  • 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 the full, absolute path to the compressed file. 💖
  • Argument — Named parameters (case-insensitive):
    • -FILE — String (name of the file to be compressed, full path). If the supplied filename ends with '.gz' or '.Z', that extension will be removed before attempting to compress.
    • Optional:
    • -TMP — boolean. If true, (or if the user is not the owner of the file) the file is compressed to a temp file. If false, the file may be clobbered with the compressed version (that's if you're using a utility like gzip, which is the default). ⚠️ careful bestie
    • -OUTFILE — String (name of the output compressed file, full path).
    • -EXE — name of the executable for the compression utility to use. It will supersede those in @COMPRESSION_UTILS defined by this module. If the absolute path to the executable is not provided, it will be searched for in the PATH env variable.
  • Throws — Exception if the file cannot be compressed. Also, if the user is not the owner of the file, it generates a warning and compresses to a tmp file. Wanna dodge that warning? Use the -o file test operator and call this function with -TMP=>1. 💅
  • Comments — It attempts to compress using the utilities defined in the @COMPRESSION_UTILS defined by this module, in the order defined. The first utility found to be executable is the one that gets used. Any utility defined in the optional -EXE param gets tested for executability first. And to minimize security risks, the -EXE parameter value is untained using the untaint() method of this module (in 'relaxed' mode, to permit path separators).
  • See Also — uncompress()

📂 uncompress 📂

  • Title — uncompress
  • Usage:
$Util->uncompress(full-path-filename);
$Util->uncompress(<named parameters>);
  • 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 the full, absolute path to the uncompressed file. 💖
  • Argument — Named parameters (case-insensitive):
    • -FILE — String (name of the file to be uncompressed, full path). If the supplied filename ends with '.gz' or '.Z', that extension will be removed before attempting to uncompress.
    • Optional:
    • -TMP — boolean. If true, (or if the user is not the owner of the file) the file is uncompressed to a temp file. If false, the file may be clobbered with the uncompressed version (that's if you're using a utility like gzip, which is the default). ⚠️
    • -OUTFILE — String (name of the output uncompressed file, full path).
    • -EXE — name of the executable for the uncompression utility to use. It will supersede those in @UNCOMPRESSION_UTILS defined by this module. If the absolute path to the executable is not provided, it will be searched for in the PATH env variable.
  • Throws — Exception if the file cannot be uncompressed. Also, if the user is not the owner of the file, it generates a warning and uncompresses to a tmp file. To avoid that warning, use the -o file test operator and call this function with -TMP=>1. 💅
  • Comments — It attempts to uncompress using the utilities defined in the @UNCOMPRESSION_UTILS defined by this module, in the order defined. The first utility found to be executable is the one that gets used. Any utility defined in the optional -EXE param gets tested for executability first. And to minimize security risks, the -EXE parameter value is untained using the untaint() method of this module (in 'relaxed' mode, to permit path separators).
  • See Also — compress()

🕰️ file_date 🕰️

  • Title — file_date
  • Usage — $Util->file_date( filename [,date_format])
  • Purpose — obtains the date of a given file. It gives you 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 the file. date_format = string, desired format for the date (see date_format()). Default = yyyy-mm-dd
  • Thows — Exception if no file is provided or the file does not exist. (yep, the field is spelled "Thows" in the original, we keep it 💀)
  • Comments — It uses the mtime field as obtained by stat().

untaint 💅

  • 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:
&;`'\"|*?!~<>^()[]{}$\n\r
  • Accept only the first block of contiguous characters:
  • Default allowed chars = "-\w.', ()"
  • If $relax is true = "-\w.', ()\/=%:^<>*"
  • 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.

mean_stdev ✨

  • 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 (yes, it's a typo, but we keep it exactly 💀)

count_files 🗂️

  • 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(\%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

file_info 🚧

  • Title: file_info
  • Purpose: Obtains a variety of date for a given file.
    • Provides an interface to Perl's stat().
  • Status: Under development. Not ready. Don't use!
⚠️ Bestie, this one is literally not ready. Do not use it, periodt.

delete 🗑️

  • Title: delete
  • Purpose: (empty, bestie, it's literally blank 😶)

create_filehandle 📂

  • Usage: $object->create_filehandle(<named parameters>);
  • 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 =>'usr/people/me/data.txt')
  • 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.
  • See Also: get_newline()

get_newline 📝

  • Usage: $object->get_newline(<named parameters>);
  • 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 =>'usr/people/me/data.txt')
  • Argument: Same arguemnts as for create_filehandle().
  • Returns: Reference to a FileHandle object.
  • Throws: Propagates any exceptions thrown by Bio::Root::Utilities::get_newline().
  • See Also: taste_file(), create_filehandle()

taste_file 😋

  • Usage:
    • $object->taste_file( <FileHandle> );
    • 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 = "\012" ("\n")
    • Win32 = "\012\015" ("\r\n")
    • Mac = "\015" ("\r")
  • 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).
  • See Also: get_newline()

file_flavor 🍦

  • Usage: $object->file_flavor( <filename> );
  • Purpose: Returns the 'flavor' 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 (\n or 012 or ^J)
      • dos (\r\n or 015,012 or ^M^J)
      • mac (\r or 015 or ^M)
      • unknown
  • Throws:
    • Exception if argument is not a file
    • Propagates any exceptions thrown by Bio::Root::Utilities::get_newline().
  • See Also: get_newline(), taste_file()

mail_authority 📧

  • Title: mail_authority
  • Usage: $Util->mail_authority( $message )
  • Purpose: Syntactic sugar to send email to $Bio::Root::Global::AUTHORITY
  • See Also: send_mail()

authority 👑

  • Title: authority
  • Usage: $Util->authority('admin@example.com');
  • Purpose: Set/get the email address that should be notified by mail_authority()
  • See Also: mail_authority()

send_mail 💌

  • 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's tip at:
    • Using default From: 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.
  • See Also: mail_authority()

find_exe 🔍

  • 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: (empty)

yes_reply ✅

  • Title: yes_reply()
  • Usage: $Util->yes_reply( [query_string]);
  • Purpose: To test an STDIN input value for affirmation.
  • Example:
print +( $Util->yes_reply('Are you ok') ? "great!\n" : "sorry.\n" );
$Util->yes_reply('Continue') || die;
  • Returns: Boolean, true (1) if input string begins with 'y' or 'Y'
  • Argument: query_string = string to be used to prompt user (optional)
    • If not provided, 'Yes or no' will be used.
    • Question mark is automatically appended.

request_data 📝

  • 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('Name');
# 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, 'data' will be used, (not very helpful).
    • Question mark is automatically appended.

quit_reply ❌

  • Title: quit_reply
  • Usage: (empty)
  • Purpose: (empty)

verify_version 🔢

  • Purpose: Checks the version of Perl used to invoke the script.
    • Aborts program if version is less than the given argument.
  • Usage: verify_version('5.000')

And that's the tea, bestie! 🫶 This page is from perl v5.32.1, dated 2021-08-15, and it's part of Bio::R...lities(3pm). Stay slaying, and may your newlines always be unix-flavored! 💖✨

📦 where this page comes from