Bio::Root::IO man page on Pidora

Man page or keyword search:  
man Server   31170 pages
apropos Keyword Search (all sections)
Output format
Pidora logo
[printable version]

Bio::Root::IO(3)      User Contributed Perl Documentation     Bio::Root::IO(3)

NAME
       Bio::Root::IO - module providing several methods often needed when
       dealing with file IO

SYNOPSIS
	   # utilize stream I/O in your module
	   $self->{'io'} = Bio::Root::IO->new(-file => "myfile");
	   $self->{'io'}->_print("some stuff");
	   $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.

FEEDBACK
   Mailing Lists
       User feedback is an integral part of the evolution of this and other
       Bioperl modules. Send your comments and suggestions preferably
	to one of the Bioperl mailing lists.  Your participation is much
       appreciated.

	 bioperl-l@bioperl.org			- General discussion
	 http://bioperl.org/wiki/Mailing_lists	- About the mailing lists

   Support
       Please direct usage questions or support issues to the mailing list:

       bioperl-l@bioperl.org

       rather than to the module maintainer directly. Many experienced and
       reponsive experts will be able look at the problem and quickly address
       it. Please include a thorough description of the problem with code and
       data examples if at all possible.

   Reporting Bugs
       Report bugs to the Bioperl bug tracking system to help us keep track
       the bugs and their resolution.  Bug reports can be submitted via the
       web:

	 http://bugzilla.open-bio.org/

AUTHOR - Hilmar Lapp
       Email hlapp@gmx.net

CONTRIBUTORS
       Mark A. Jensen ( maj -at- fortinbras -dot- us )

APPENDIX
       The rest of the documentation details each of the object methods.
       Internal methods are usually preceded with a _

   new
	Title	: new
	Usage	:
	Function: Overridden here to automatically call _initialize_io().
	Example :
	Returns : new instance of this class
	Args	: named parameters

   _initialize_io
	Title	: initialize_io
	Usage	: $self->_initialize_io(@params);
	Function: Initializes filehandle and other properties from the parameters.

		  Currently recognizes the following named parameters:
		     -file     name of file to open
		     -url      name of URL to open
		     -input    name of file, or GLOB, or IO::Handle object
		     -fh       file handle (mutually exclusive with -file)
		     -flush    boolean flag to autoflush after each write
		     -noclose  boolean flag, when set to true will not close a
			       filehandle (must explictly call close($io->_fh)
		     -retries  number of times to try a web fetch before failure

		     -ua_parms hashref of key => value parameters to pass
			       to LWP::UserAgent->new()
			       (only meaningful with -url is set)
			       A useful value might be, for example,
			       { timeout => 60 } (ua default is 180 sec)
	Returns : TRUE
	Args	: named parameters

   _fh
	Title	: _fh
	Usage	: $obj->_fh($newval)
	Function: Get/set the file handle for the stream encapsulated.
	Example :
	Returns : value of _filehandle
	Args	: newvalue (optional)

   mode
	Title	: mode
	Usage	: $obj->mode()
	Function:
	Example :
	Returns : mode of filehandle:
		  'r' for readable
		  'w' for writeable
		  '?' if mode could not be determined
	Args	: -force (optional), see notes.
	Notes	: once mode() has been called, the filehandle's mode is cached
		  for further calls to mode().	to override this behavior so
		  that mode() re-checks the filehandle's mode, call with arg
		  -force

   file
	Title	: file
	Usage	: $obj->file($newval)
	Function: Get/set the filename, if one has been designated.
	Example :
	Returns : value of file
	Args	: newvalue (optional)

   _print
	Title	: _print
	Usage	: $obj->_print(@lines)
	Function:
	Example :
	Returns : 1 on success, undef on failure

   _readline
	Title	: _readline
	Usage	: $obj->_readline(%args)
	Function: Reads a line of input.

		  Note that this method implicitely uses the value of $/ that is
		  in effect when called.

		  Note also that the current implementation does not handle pushed
		  back input correctly unless the pushed back input ends with the
		  value of $/.

	Example :
	Args	: Accepts a hash of arguments, currently only -raw is recognized
		  passing (-raw => 1) prevents \r\n sequences from being changed
		  to \n.  The default value of -raw is undef, allowing \r\n to be
		  converted to \n.
	Returns :

   _pushback
	Title	: _pushback
	Usage	: $obj->_pushback($newvalue)
	Function: puts a line previously read with _readline back into a buffer.
		  buffer can hold as many lines as system memory permits.
	Example : $obj->_pushback($newvalue)
	Returns : none
	Args	: newvalue
	Note	: 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.

   close
	Title	: close
	Usage	: $io->close()
	Function: Closes the file handle associated with this IO instance.
		  Will not close the FH if  -noclose is specified
	Returns : none
	Args	: none

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

   noclose
	Title	: noclose
	Usage	: $obj->noclose($newval)
	Function: Get/Set the NOCLOSE flag - setting this to true will
		  prevent a filehandle from being closed
		  when an object is cleaned up or explicitly closed
		  This is a bit of hack
	Returns : value of noclose (a scalar)
	Args	: on set, new value (a scalar or undef, optional)

   exists_exe
	Title	: exists_exe
	Usage	: $exists = $obj->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.
	Example :
	Returns : 1 if the given program is callable as an executable, and 0 otherwise
	Args	: the name of the executable

   tempfile
	Title	: tempfile
	Usage	: my ($handle,$tempfile) = $io->tempfile();
	Function: Returns a temporary filename and a handle opened for writing and
		  and reading.

	Caveats : If you do not have File::Temp on your system you should avoid
		  specifying TEMPLATE and SUFFIX. (We don't want to recode
		  everything, okay?)
	Returns : a 2-element array, consisting of temporary handle and temporary
		  file name
	Args	: named parameters compatible with File::Temp: DIR (defaults to
		  $Bio::Root::IO::TEMPDIR), TEMPLATE, SUFFIX.

   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.

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

   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.

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

   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.

	Returns : number of files successfully deleted
	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)

   _flush_on_write
	Title	: _flush_on_write
	Usage	: $obj->_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)
	Returns : value of _flush_on_write
	Args	: newvalue (optional)

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

perl v5.14.1			  2011-07-22		      Bio::Root::IO(3)
[top]

List of man pages available for Pidora

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net