Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Bio::Index::Abstract(3User Contributed Perl DocumentatiBio::Index::Abstract(3)

       Bio::Index::Abstract - Abstract interface for indexing a	flat file

       You should not be using this module directly

       To use DB_File and not SDBM for this index, pass	the value:

	   -dbm_package	=> 'DB_File'

       to new (see below).

       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.

   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.			- General discussion	- About	the mailing lists

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

       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

AUTHOR - Ewan Birney, James Gilbert
       Email -,

       The rest	of the documentation details each of the object	methods.
       Internal	methods	are usually preceded with an "_" (underscore).

	 Usage	 : $index = Bio::Index::Abstract->new(
		       -filename    => $dbm_file,
		       -write_flag  => 0,
		       -dbm_package => 'DB_File',
		       -verbose	    => 0);
	 Function: Returns a new index object.	If filename is
		   specified, then open_dbm() is immediately called.
		   Bio::Index::Abstract->new() will usually be called
		   directly only when opening an existing index.
	 Returns : A new index object
	 Args	 : -filename	The name of the	dbm index file.
		   -write_flag	TRUE if	write access to	the dbm	file is
		   -dbm_package	The Perl dbm module to use for the
		   -verbose	Print debugging	output to STDERR if

	Title	: filename
	Usage	: $value = $self->filename();
	Function: Gets or sets the name	of the dbm index file.
	Returns	: The current value of filename
	Args	: Value	of filename if setting,	or none	if
		  getting the value.

	Title	: write_flag
	Usage	: $value = $self->write_flag();
	Function: Gets or sets the value of write_flag,	which
		  is whether the dbm file should be opened with
		  write	access.
	Returns	: The current value of write_flag (default 0)
	Args	: Value	of write_flag if setting, or none if
		  getting the value.

	Usage	: $value = $self->dbm_package();

	Function: Gets or sets the name	of the Perl dbm	module used.
		  If the value is unset, then it returns the value of
		  the package variable $USE_DBM_TYPE or	if that	is
		  unset, then it chooses the best available dbm	type,
		  choosing 'DB_File' in	preference to 'SDBM_File'.
		  Bio::Abstract::Index may work	with other dbm file

	Returns	: The current value of dbm_package
	Args	: Value	of dbm_package if setting, or none if
		  getting the value.

	 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	 : NONE

	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 won't 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

	 Usage	 : $index->cachesize(1000000)
	 Function: Sets	the dbm	file cache size	for the	index.
		   Needs to be set before the DBM file gets opened.
	 Example : $index->cachesize(1000000)
	 Returns : size	of the curent cache

	 Usage	 : $index->ffactor(1000000)
	 Function: Sets	the dbm	file fill factor.
			       Needs to	be set before the DBM file gets	opened.

	 Example : $index->ffactor(1000000)
	 Returns : size	of the curent cache

	 Usage	 : $index->open_dbm()
	 Function: Opens the dbm file associated with the index
		   object.  Write access is only given if explicitly
		   asked for by	calling	new(-write => 1) or having set
		   the write_flag(1) on	the index object.  The type of
		   dbm file opened is that returned by dbm_package().
		   The name of the file	to be is opened	is obtained by
		   calling the filename() method.

	 Example : $index->_open_dbm()
	 Returns : 1 on	success

	 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

	Title	: _code_base
	Usage	: $code	= $db->_code_base();
	Example	:
	Returns	: Code package to be used with this
	Args	:

	 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
	 Example :
	 Returns : 1 or	exception
	 Args	 : none

	 Title	 : _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 new()
	 Example :
	 Returns : 1 or	exception
	 Args	 :

	 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 _filename() on
		   each.  It supplies _filename() with the name	of the
		   file, and an	integer	which is stored	with each record
		   created by _filename().  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

	 Title	 : pathtype
	 Usage	 : $index->pathtype($pathtype)
	 Function: Set the type	of the file path
		   Only	two values are supported, 'relative' or	'absolute'.
		   If the user does not	give any value,	it is set to
		   absolute by default.	Thus it	mimics the default
		   behavior of Bio::Index::Abstract module.
	 Example : my $index = Bio::Index::Abstract->(-pathtype	=> 'relative',
						      -file	=> $file.inx,
	 Returns : Type	of the path.
	 Args	 : String (relative|absolute)

	 Title	 : _filename
	 Usage	 : $index->_filename( FILE INT )
	 Function: Indexes the file
	 Example :
	 Returns :
	 Args	 :

	 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 : $first_file_indexed = $index->_file_handle( 0 );
	 Returns : ref to a filehandle
	 Args	 : INT

	 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 : INT
	 Args	 : INT

	 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.
		   If $id is a reference to an array, then a new entry
		   is added under a key	corresponding to each element
		   of the array.
	 Example : $index->add_record( $id, $fileNumber, $begin, $end )
	 Returns : TRUE	on success or FALSE on failure
	 Args	 : ID LIST

	 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	 : LIST

	 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 034

	Title	: count_records
	Usage	: $recs	= $seqdb->count_records()
	Function: return count of all recs in the index
	Example	:
	Returns	: a scalar
	Args	: none

	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

perl v5.32.1			  2019-12-07	       Bio::Index::Abstract(3)


Want to link to this manual page? Use this URL:

home | help