NAME
Bio::Index::Abstract - Abstract interface for indexing a flat file
SYNOPSIS
You should not be using this module directly
USING DB_FILE
To use DB_FILE and not SDBM for this index, do the following
$Bio::Index::Abstract::USE_DBM_TYPE = 'DB_File';DESCRIPTION
This object provides the basic mechanism to associate positions in files with names. The position and filenames are stored in DBM which can then be accessed later on. It is the equivalent of flat file indexing (eg, SRS or efetch).
This object is the guts to the mechanism, which will be used by the specific objects inheriting from it.
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.
vsns-bcd-perl@lists.uni-bielefeld.de - General discussion
vsns-bcd-perl-guts@lists.uni-bielefeld.de - Technically-oriented discussion
http://bio.perl.org/MailList.html - About the mailing listsReporting 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 email or the web:
bioperl-bugs@bio.perl.org
http://bio.perl.org/bioperl-bugs/AUTHOR - Ewan Birney, James Gilbert
Email - birney@sanger.ac.uk, jgrg@sanger.ac.uk
APPENDIX
The rest of the documentation details each of the object methods. Internal methods are usually preceded with an "_" (underscore).
_initialize
Title : _initialize
Usage : $index->_initialize
Function: Initializes data structures in the index object,
opens or creates the dbm file, and performs a number
of pre-flight checks, which depend on the existance
of certain methods in the sub class. In particular
the sub class should provide the _version() and
_type() methods (see below).
Example : $index->SUPER::_initialize # add this call to the
# sub class's _initialize()
# function if the sub
# class needs to do its
# own initializing
Returns :
Args : filename
Title : filename
Usage : $name = $index->filename()
Function: Returns the name of the index file
Example :
Returns : STRING
Args : NONEdb
Title : db
Usage : $index->db
Function: Returns a ref to the hash which is tied to the dbm
file. Used internally when adding and retrieving
data from the database.
Example : $db = $index->db();
$db->{ $some_key } = $data
$data = $index->db->{ $some_key };
Returns : ref to HASH
Args : NONEget_stream
Title : get_stream
Usage : $stream = $index->get_stream( $id );
Function: Returns a file handle with the file pointer
at the approprite place
This provides for a way to get the actual
file contents and not an object
WARNING: you must parse the record deliminter
*yourself*. Abstract wont do this for you
So this code
$fh = $index->get_stream($myid);
while( <$fh> ) {
# do something
}
will parse the entire file if you don't put in
a last statement in, like
while( <$fh> ) {
/^\/\// && last; # end of record
# do something
}
Returns : A filehandle object
Args : string represents the accession number
Notes :
This method should not be used without forethought _open_dbm
Title : _open_dbm
Usage : $index->_open_dbm()
Function: Called by _initialize() to create or open an existing
index dbm file for adding and retieving records. Write
access is only given if explicitly asked for by passing
the string 'WRITE' as the second argument to the new()
function (which calls initialize). The type of dbm file
opened, DB_File or SDBM_File, depends upon wether the
global variable $USE_DBM_TYPE is set to 'DB_File' or
'SDBM_File' respectively. The name of the file to be is
opened is obtained by calling the filename() method.
Example : $index->_open_dbm('WRITE')
Returns : 1 on success
Args : 'WRITE' - optional_version
Title : _version
Usage : $type = $index->_version()
Function: Returns a string which identifes the version of an
index module. Used to permanently identify an index
file as having been created by a particular version
of the index module. Must be provided by the sub class
Example :
Returns :
Args : none_code_base
Title : _code_base
Usage : $code = $db->_code_base();
Function:
Example :
Returns : Code package to be used with this
Args :_type_and_version
Title : _type_and_version
Usage : Called by _initalize
Function: Checks that the index opened is made by the same index
module and version of that module that made it. If the
index is empty, then it adds the information to the
database.
Example :
Returns : 1 or exception
Args : noneTitle : _check_file_sizes
Usage : $index->_check_file_sizes()
Function: Verifies that the files listed in the database
are the same size as when the database was built,
or throws an exception. Called by the _initialize()
function.
Example :
Returns : 1 or exception
Args : make_index
Title : make_index
Usage : $index->make_index( FILE_LIST )
Function: Takes a list of file names, checks that they are
all fully qualified, and then calls _index_file() on
each. It supplies _index_file() with the name of the
file, and an integer which is stored with each record
created by _index_file(). Can be called multiple times,
and can be used to add to an existing index file.
Example : $index->make_index( '/home/seqs1', '/home/seqs2', '/nfs/pub/big_db' );
Returns : Number of files indexed
Args : LIST OF FILES_index_file
Title : _index_file
Usage : $index->_index_file( FILE INT )
Function: Indexes the file
Example :
Returns :
Args : _file_handle
Title : _file_handle
Usage : $fh = $index->_file_handle( INT )
Function: Returns an open filehandle for the file
index INT. On opening a new filehandle it
caches it in the @{$index->_filehandle} array.
If the requested filehandle is already open,
it simply returns it from the array.
Example : $fist_file_indexed = $index->_file_handle( 0 );
Returns : ref to a filehandle
Args : INT_file_count
Title : _file_count
Usage : $index->_file_count( INT )
Function: Used by the index building sub in a sub class to
track the number of files indexed. Sets or gets
the number of files indexed when called with or
without an argument.
Example :
Returns :
Args : INTadd_record
Title : add_record
Usage : $index->add_record( $id, @stuff );
Function: Calls pack_record on @stuff, and adds the result
of pack_record to the index database under key $id.
Example : $index->add_record( $id, $fileNumber, $begin, $end )
Returns : TRUE on success or FALSE on failure
Args : ID LISTpack_record
Title : pack_record
Usage : $packed_string = $index->pack_record( LIST )
Function: Packs an array of scalars into a single string
joined by ASCII 034 (which is unlikely to be used
in any of the strings), and returns it.
Example : $packed_string = $index->pack_record( $fileNumber, $begin, $end )
Returns : STRING or undef
Args : LISTunpack_record
Title : unpack_record
Usage : $index->unpack_record( STRING )
Function: Splits the sting provided into an array,
splitting on ASCII 034.
Example : ( $fileNumber, $begin, $end ) = $index->unpack_record( $self->db->{$id} )
Returns : A 3 element ARRAY
Args : STRING containing ASCII 034verbose
Title : verbose
Usage : $obj->verbose($newval)
Function: sets whether a report to STDERR should be issued or not
for each sequence indexed. Helps track errors
Example :
Returns : value of verbose
Args : newvalue (optional)DESTROY
Title : DESTROY
Usage : Called automatically when index goes out of scope
Function: Closes connection to database and handles to
sequence files
Returns : NEVER
Args : NONE