Bio::Root::IO(3pm)

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

🌸 NAME 🌸

Bio::Root::IO — BioPerl base IO handling class 💖 (this is the Bio::Root::IO(3pm) page, bestie, and it's a whole vibe)

✨ SYNOPSIS ✨

# Use stream I/O in your module
$self->{'io'} = Bio::Root::IO->new(-file => "myfile");
$self->{'io'}->_print("some stuff");
my $line = $self->{'io'}->_readline();
$self->{'io'}->_pushback($line);
$self->{'io'}->close();

# obtain platform-compatible filenames
$path = Bio::Root::IO->catfile($dir, $subdir, $filename);
# obtain a temporary file (created in $TEMPDIR)
($handle) = $io->tempfile();

💅 DESCRIPTION 💅

okay so this module is the moment for any and all file- or stream-related input/output 🫶. Like, it keeps track of a file handle for you, does transient printing and reading from that file handle, gives you a close method, and — the icon behavior — automatically closes the handle on garbage collection ✨. So many things. Very demure, very mindful.

If you wanna use this in your own code you've got two routes, bestie:

  • inherit from this module, or
  • instantiate an object for every single file or stream you're dealing with.

In that first case, this module will most likely not be the first class off which your class inherits 😭. Which means you need to call _initialize_io() with the named parameters so that stuff like the file handle and the opening of the file gets set up automatically. It's giving "you have to do one (1) thing yourself, sorry."

Most methods start with an underscore, which signals they're private. In OO speak they're not really private, they're protected — like, use them in your module code, but a client code of your module usually won't wanna call them (except for the ones that don't start with an underscore, those are fair game 💁).

On top of all that, this module also has a couple of convenience methods for cross-platform safe tempfile creation and similar tasks. There are some CPAN modules that are related but they may not be available on all platforms. At present, File::Spec and File::Temp are attempted. This module defines $PATHSEP, $TEMPDIR, and $ROOTDIR, which will always be set, and $OPENFLAGS, which will be set if either of File::Spec or File::Temp fails.

The -noclose boolean (accessed via the noclose method) prevents a filehandle from being closed when the IO object is cleaned up. This is special behavior for when an object like a parser might share a filehandle with an object like an indexer, where it is not proper to close the filehandle because it will continue to be reused until the end of the stream is reached. In general you won't want to play with this flag 🙈. Hands off, fr fr.

👑 AUTHOR 👑

Hilmar Lapp

💖 new

  • Title: new
  • Usage: my $io = Bio::Root::IO->new( -file => 'data.txt' );
  • Function: Create new class instance. It automatically calls _initialize_io.
  • Args: Same named parameters as _initialize_io.
  • Returns: A Bio::Root::IO object

🦋 _initialize_io

  • Title: _initialize_io
  • Usage: $io->_initialize_io(@params);
  • Function: Initializes filehandle and other properties from the parameters.
  • Args: The following named parameters are currently recognized:
    • -file — name of file to read or write to
    • -fh — file handle to read or write to (mutually exclusive with -file and -string)
    • -input — name of file, or filehandle (GLOB or IO::Handle object) to read of write to
    • -string — string to read from (will be converted to filehandle)
    • -url — name of URL to open
    • -flush — boolean flag to autoflush after each write
    • -noclose — boolean flag, when set to true will not close a filehandle (must explicitly call close($io->_fh)
    • -retries — number of times to try a web fetch before failure
    • -ua_parms — when using -url, hashref of key => value parameters to pass to LWP::UserAgent->new(). A useful value might be, for example, {timeout => 60 } (ua defaults to 180s)
  • Returns: True

🎀 _fh

  • Title: _fh
  • Usage: $io->_fh($newval);
  • Function: Get or set the file handle for the stream encapsulated.
  • Args: Optional filehandle to use
  • Returns: Filehandle for the stream

🔥 mode

  • Title: mode
  • Usage:
$io->mode();
$io->mode(-force => 1);
  • Function: Determine if the object was opened for reading or writing
  • Args: -force: Boolean. Once mode() has been called, the mode is cached for further calls to mode(). Use this argument to override this behavior and re-check the object's mode.
  • Returns: Mode of the object:
    • 'r' for readable
    • 'w' for writable
    • 'rw' for readable and writable
    • '?' if mode could not be determined (e.g. for a -url)

🍓 file

  • Title: file
  • Usage:
$io->file('>'.$file);
my $file = $io->file;
  • Function: Get or set the name of the file to read or write.
  • Args: Optional file name (including its mode, e.g. '<' for reading or '>' for writing)
  • Returns: A string representing the filename and its mode.

🧚 cleanfile

  • Title: cleanfile
  • Usage: my ($mode, $file) = $io->cleanfile;
  • Function: Get the name of the file to read or write, stripped of its mode ('>', '<', '+>', '>>', etc).
  • Args: None
  • Returns: In array context, an array of the mode and the clean filename.

🌈 format

  • Title: format
  • Usage: $io->format($newval)
  • Function: Get the format of a Bio::Root::IO sequence file or filehandle. Every object inheriting Bio::Root::IO is guaranteed to have a format.
  • Args: None
  • Returns: Format of the file or filehandle, e.g. fasta, fastq, genbank, embl.

💜 variant

  • Title: format (yes it really says format in the source, bestie — we're keeping it exactly as it is, no editing the icon's typos 💅)
  • Usage: $io->format($newval)
  • Function: Get the variant of a Bio::Root::IO sequence file or filehandle. The format variant depends on the specific format used. Note that not all formats have variants. Also, the Bio::Root::IO-implementing modules that require access to variants need to define a global hash that has the allowed variants as its keys.
  • Args: None
  • Returns: Variant of the file or filehandle, e.g. sanger, solexa or illumina for the fastq format, or undef for formats that do not have variants.

✨ _print

  • Title: _print
  • Usage: $io->_print(@lines)
  • Function: Print lines of text to the IO stream object.
  • Args: List of strings to print
  • Returns: True on success, undef on failure

🌸 _insert

  • Title: _insert
  • Usage: $io->_insert($string,1)
  • Function: Insert some text in a file at the given line number (1-based).
  • Args:
    • string to write in file
    • line number to insert the string at
  • Returns: True

🫶 _readline

  • Title: _readline
  • Usage:
local $Bio::Root::IO::HAS_EOL = 1;
my $io = Bio::Root::IO->new(-file => 'data.txt');
my $line = $io->_readline();
$io->close;
  • Function: Read a line of input and normalize all end of line characters.

End of line characters are typically "\n" on Linux platforms, "\r\n" on Windows and "\r" on older Mac OS. By default, the _readline() method uses the value of $/, Perl's input record separator, to detect the end of each line. This means that you will not get the expected lines if your input has Mac-formatted end of line characters 😭. Also, note that the current implementation does not handle pushed back input correctly unless the pushed back input ends with the value of $/. For each line parsed, its line ending, e.g. "\r\n" is converted to "\n", unless you provide the -raw argument.

Altogether it is easier to let the PerlIO::eol module automatically detect the proper end of line character and normalize it to "\n". Do so by setting $Bio::Root::IO::HAS_EOL to 1. That's the slay route, ngl.

  • Args: -raw : Avoid converting end of line characters to "\n" This option has no effect when using $Bio::Root::IO::HAS_EOL = 1.
  • Returns: Line of input, or undef when there is nothing to read anymore

💀 _pushback

  • Title: _pushback
  • Usage: $io->_pushback($newvalue)
  • Function: Puts a line previously read with _readline back into a buffer. buffer can hold as many lines as system memory permits.

Note that this is only supported for pushing back data ending with the current, localized value of $/. Using this method to push modified data back onto the buffer stack is not supported; see bug 843.

  • Args: newvalue
  • Returns: True

🎀 close

  • Title: close
  • Usage: $io->close()
  • Function: Closes the file handle associated with this IO instance, excepted if -noclose was specified.
  • Args: None
  • Returns: True

⭐ flush

  • Title: flush
  • Usage: $io->flush()
  • Function: Flushes the filehandle
  • Args: None
  • Returns: True

🙈 noclose

  • Title: noclose
  • Usage: $io->noclose($newval)
  • Function: Get or set the NOCLOSE flag — setting this to true will prevent a filehandle from being closed when an object is cleaned up or explicitly closed.
  • Args: Optional new value (a scalar or undef)
  • Returns: Value of noclose (a scalar)

💜 _io_cleanup

(the source page just names this one and moves on — no Title, Usage, Function, Args or Returns listed here, so there's nothing more to tell you, bestie 🫶)

🧚 exists_exe

  • Title: exists_exe
  • Usage:
$exists = $io->exists_exe('clustalw');
$exists = Bio::Root::IO->exists_exe('clustalw')
$exists = Bio::Root::IO::exists_exe('clustalw')
  • Function: Determines whether the given executable exists either as file or within the path environment. The latter requires File::Spec to be installed. On Win32-based system, .exe is automatically appended to the program name unless the program name already ends in .exe.
  • Args: Name of the executable
  • Returns: 1 if the given program is callable as an executable, and 0 otherwise

🔥 tempfile

  • Title: tempfile
  • Usage: my ($handle,$tempfile) = $io->tempfile();
  • Function: Create a temporary filename and a handle opened for reading and writing. Caveats: If you do not have File::Temp on your system you should avoid specifying TEMPLATE and SUFFIX.
  • Args: Named parameters compatible with File::Temp: DIR (defaults to $Bio::Root::IO::TEMPDIR), TEMPLATE, SUFFIX.
  • Returns: A 2-element array, consisting of temporary handle and temporary file name.

🦋 tempdir

  • Title: tempdir
  • Usage: my ($tempdir) = $io->tempdir(CLEANUP=>1);
  • Function: Creates and returns the name of a new temporary directory.
okay real talk bestie — do not use this function to grab "the" temp directory, okay?? Like, that's not what it's for. If you want the temp dir, you go straight to $Bio::Root::IO::TEMPDIR and you don't look back. Calling this method will literally create a brand new directory. It's giving ✨new-folder-energy✨, not ✨find-the-folder-energy✨. Important distinction, iykyk 💅
  • Args — args — the key CLEANUP tells it whether or not to clean up the dir when the object gets destroyed 🧹, and any other keys are exactly as specified by File::Temp.
  • Returns — the name of a new temporary directory. Slay. 🎀

🦋 catfile 🦋

  • Title — catfile
  • Usage —
$path = Bio::Root::IO->catfile(@dirs, $filename);
  • Function — builds a full pathname in a way that's cross-platform safe, no cap 🫶

If File::Spec exists on your system, this routine will merely delegate to it — like, it just hands the whole thing over, respectfully. Otherwise it tries to make a good guess (and honestly, it does pretty well for itself 💜).

You should use this method whenever you construct a path name from a directory and a filename. Otherwise you're risking cross-platform compatibility of your code and that's a vibe check you are going to fail, bestie 😭

You can call this method both as a class method and as an instance method. Versatile queen 👑

  • Args — components of the pathname (the directories and the filename, NOT an extension — do not try it 🙈)
  • Returns — a string

🌈 rmtree 🌈

  • Title — rmtree
  • Usage —
Bio::Root::IO->rmtree($dirname );
  • Function — removes a full directory tree 🌳💀

If File::Path exists on your system, this routine will merely delegate to it. Otherwise it runs a local version of that code. Either way, the tree is coming down.

You should use this method to remove directories which contain files. It's the whole point. It ate and left no crumbs 🍓

You can call this method both as a class method and as an instance method.

  • Args —
    • roots — rootdir to delete, or a reference to a list of dirs.
    • verbose — a boolean value, which if TRUE will cause rmtree to print a message each time it examines a file, giving the name of the file, and indicating whether it's using rmdir or unlink to remove it, or that it's skipping it. (defaults to FALSE) — very "narrating my own life" of it, love that for you 🎤
    • safe — a boolean value, which if TRUE will cause rmtree to skip any files to which you do not have delete access (if running under VMS) or write access (if running under another OS). This will change in the future when a criterion for 'delete permission' under OSs other than VMS is settled. (defaults to FALSE) — so like, it's a work in progress, be patient with her 🧚
  • Returns — number of files successfully deleted. Count them, bestie, every single one 💯

💅 _flush_on_write 💅

  • Title — _flush_on_write
  • Usage —
$io->_flush_on_write($newval)
  • Function — a boolean flag to indicate whether to flush the filehandle on writing when the end of a component is finished (Sequences, Alignments, etc). Basically: do we dump the buffer the second we wrap a thing up, or do we let it marinate? 🫧
  • Args — optional new value
  • Returns — value of _flush_on_write

✨ save_tempfiles ✨

  • Title — save_tempfiles
  • Usage —
$io->save_tempfiles(1)
  • Function — a boolean flag to indicate whether to retain tempfiles/tempdir. Like, are we keeping the receipts or are we deleting the whole conversation? 🗑️
  • Args — value evaluating to TRUE or FALSE
  • Returns — boolean value: 1 = save tempfiles/tempdirs, 0 = remove (default). She removes by default, she's tidy like that 💖

and that's the whole page, bestie 🎀

This one's from perl v5.32.1, dated 2021-08-15, and it lives in Bio::Root::IO(3pm). Go forth and construct paths responsibly, mwah 😘💜

📦 where this page comes from