Provided by: libbio-perl-perl_1.7.8-1_all bug

NAME

       Bio::Root::IO - BioPerl base IO handling class

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

       This module provides methods that will usually be needed for any sort of file- or stream-
       related input/output, e.g., keeping track of a file handle, transient printing and reading
       from the file handle, a close method, automatically closing the handle on garbage
       collection, etc.

       To use this for your own code you will either want to inherit from this module, or
       instantiate an object for every file or stream you are dealing with. In the first case
       this module will most likely not be the first class off which your class inherits;
       therefore you need to call _initialize_io() with the named parameters in order to set file
       handle, open file, etc automatically.

       Most methods start with an underscore, indicating they are private. In OO speak, they are
       not private but protected, that is, use them in your module code, but a client code of
       your module will usually not want to call them (except those not starting with an
       underscore).

       In addition this module contains a couple of convenience methods for cross-platform safe
       tempfile creation and similar tasks. There are some CPAN modules related that 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 when a object like a
       parser might share a filehandle with an object like an indexer where it is not proper to
       close the filehandle as 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.

AUTHOR Hilmar Lapp

   new
        Title   : new
        Usage   : my $io = Bio::Root::IO->new( -file => 'data.txt' );
        Function: Create new class instance. It automatically calls C<_initialize_io>.
        Args    : Same named parameters as C<_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
        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.

        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
   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.

                  Note that you should not use this function for obtaining "the"
                  temp directory. Use $Bio::Root::IO::TEMPDIR for that. Calling this
                  method will in fact create a new directory.

        Args    : args - ( key CLEANUP ) indicates whether or not to cleanup
                  dir on object destruction, other keys as specified by File::Temp
        Returns : The name of a new temporary directory.

   catfile
        Title   : catfile
        Usage   : $path = Bio::Root::IO->catfile(@dirs, $filename);
        Function: Constructs a full pathname in a cross-platform safe way.

                  If File::Spec exists on your system, this routine will merely
                  delegate to it. Otherwise it tries to make a good guess.

                  You should use this method whenever you construct a path name
                  from directory and filename. Otherwise you risk cross-platform
                  compatibility of your code.

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

        Args    : components of the pathname (directories and filename, NOT an
                  extension)
        Returns : a string

   rmtree
        Title   : rmtree
        Usage   : Bio::Root::IO->rmtree($dirname );
        Function: Remove 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.

                  You should use this method to remove directories which contain
                  files.

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

        Args    : roots - rootdir to delete or reference to list of dirs

                  verbose - a boolean value, which if TRUE will cause
                            C<rmtree> to print a message each time it
                            examines a file, giving the name of the file, and
                            indicating whether it's using C<rmdir> or
                            C<unlink> to remove it, or that it's skipping it.
                            (defaults to FALSE)

                  safe - a boolean value, which if TRUE will cause C<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)
        Returns : number of files successfully deleted

   _flush_on_write
        Title   : _flush_on_write
        Usage   : $io->_flush_on_write($newval)
        Function: Boolean flag to indicate whether to flush
                  the filehandle on writing when the end of
                  a component is finished (Sequences, Alignments, etc)
        Args    : Optional new value
        Returns : Value of _flush_on_write

   save_tempfiles
        Title   : save_tempfiles
        Usage   : $io->save_tempfiles(1)
        Function: Boolean flag to indicate whether to retain tempfiles/tempdir
        Args    : Value evaluating to TRUE or FALSE
        Returns : Boolean value : 1 = save tempfiles/tempdirs, 0 = remove (default)