Bio::I...stract(3pm)
💖 Bio::I...stract(3pm) 💖
ok so bestie, welcome to Bio::Index::Abstract — the Perl doc page for it (you'll see it filed under Bio::I...stract(3pm) in the man pages, which is just the terminal being dramatic and cutting off the name, it's fine, it's giving truncated icon behaviour 💅).
✨ NAME ✨
Bio::Index::Abstract</p> — the abstract interface for indexing a flat file. that's it, that's the name, she's abstract and she knows it 🎀
🌸 SYNOPSIS 🌸
You should not be using this module directlyperiodt. that's the whole synopsis. no cap, no examples, no flags. if you came here to use her directly, please don't — she's the blueprint, not the build 😭
🦋 USING DB_FILE 🦋
so like, if you want this index to use DB_File instead of SDBM (default behaviour vibes, but you can switch her up), you pass this value:
-dbm_package => 'DB_File'straight into new — see below for the new deets 👇
💜 DESCRIPTION 💜
okay so here's the whole vibe. this object gives you the basic mechanism to associate positions in files with names. the positions and the filenames get stored in DBM, and then you can come back and access them later whenever you want. it's literally the equivalent of flat file indexing (think SRS or efetch, iykyk).
and the way that this object is the guts of the whole mechanism? yeah. she's the engine. the specific objects that inherit from her are the ones who get to actually use all of this ✨
🫶 FEEDBACK 🫶
💌 Mailing Lists
user feedback is an integral part of the evolution of this module and the other Bioperl modules, so bestie, if you have comments or suggestions, please send them (preferably) to one of the Bioperl mailing lists. your participation is much appreciated — we genuinely love to see it 🥹
bioperl-l@bioperl.org - General discussion
http://bioperl.org/wiki/Mailing_lists - About the mailing lists🌈 Support
please direct your usage questions and support issues to the mailing list:
bioperl-l@bioperl.organd not to the module maintainer directly, okay? there are so many experienced and responsive experts hanging out there who'll be able to look at your problem and quickly address it. if it's at all possible, please include a thorough description of the problem with code and data examples — like, the whole picture, not just "it broke" 🙈
🐛 Reporting Bugs
report bugs to the Bioperl bug tracking system so we can keep track of the bugs and their resolution (slay, we love accountability 💅). bug reports can be submitted via the web:
https://github.com/bioperl/bioperl-live/issues👑 AUTHOR - Ewan Birney, James Gilbert 👑
Email — birney@sanger.ac.uk, jgrg@sanger.ac.uk
✨ to be continued, bestie — part 2 is coming, don't go anywhere ✨
🌸 APPENDIX 🌸
okay bestie, here's the deep lore 💅 — literally every method, one by one. the "secret" ones (the internal vibes) usually start with an _ (underscore), so you can clock them immediately. no cap, this is the good stuff.
✨ new ✨
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
needed.
-dbm_package The Perl dbm module to use for the
index.
-verbose Print debugging output to STDERR if
TRUE.so you want a brand new index object? this is the moment ✨ if you hand it a filename, it'll immediately go call open_dbm() on it, no hesitation, no questions asked. and fr fr, most of the time you'd only call Bio::Index::Abstract->new() directly when you're opening an index that already exists — not when you're making a fresh one.
here's what you can pass in:
-filename— the name of the dbm index file. 🗂️-write_flag—TRUEif you need write access to the dbm file. 🔥-dbm_package— the Perl dbm module to use for the index.-verbose— prints debugging output toSTDERRif it'sTRUE. (chaotic but helpful energy)
✨ filename ✨
Title : filename
Usage : $value = $self->filename();
$self->filename($value);
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.get or set the name of the dbm index file. pass a value and you're setting it, pass nothing and you're just getting the current one. simple as 🫶
✨ write_flag ✨
Title : write_flag
Usage : $value = $self->write_flag();
$self->write_flag($value);
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.gets or sets write_flag, which literally just answers the question: "should this dbm file be opened with write access?" 👑
default is 0, btw — so by default it's giving read-only, respectfully.
✨ dbm_package ✨
Usage : $value = $self->dbm_package();
$self->dbm_package($value);
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
types.
Returns : The current value of dbm_package
Args : Value of dbm_package if setting, or none if
getting the value.gets or sets the name of the Perl dbm module in use. and here's the tea ☕ — if it's unset, it returns the package variable $USE_DBM_TYPE. and if that's unset too? it just picks the best available dbm type, choosing 'DB_File' over 'SDBM_File', because it has taste 💅. also noted: Bio::Abstract::Index may work with other dbm file types. no promises, just possibilities.
✨ db ✨
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 : NONEreturns a ref to the hash that's tied to the dbm file. it's the internal plug for adding and pulling data out of the database, iykyk.
$db = $index->db();
$db->{ $some_key } = $data
$data = $index->db->{ $some_key };returns a ref to a HASH. takes NONE as args, bestie.
✨ get_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 won't do this for yougives you a file handle with the file pointer sitting at the appropriate spot 📍. it's the way to grab the actual file contents instead of an object — raw, unfiltered, iconic.
⚠️ WARNING: you have to parse the record delimiter yourself. Abstract will NOT do this for you, periodt. 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 — like this:
while( <$fh> ) {
/^\/\// && last; # end of record
# do something
}Returns: a filehandle object Args: a string that represents the accession number Notes: this method should not be used without forethought 😭 (fr, think before you leap)
✨ cachesize ✨
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 cachesets the dbm file cache size for the index. 🧠 but bestie — it needs to be set before the DBM file gets opened, so timing is everything. returns the size of the current cache.
✨ ffactor ✨
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 cachesets the dbm file fill factor. same rule as above: needs to be set before the DBM file gets opened ⏰. returns the size of the current cache.
✨ open_dbm ✨
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 successopens the dbm file attached to the index object. 🔓 but listen — write access is only given if you explicitly asked for it, either by calling new(-write => 1) or by setting write_flag(1) on the index object. the type of dbm file opened is whatever dbm_package() returns, and the name of the file being opened comes from calling the filename() method. it all connects, see? 🌈
returns 1 on success.
✨ _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 : nonereturns a string that identifies the version of an index module. it's how an index file permanently remembers which version of the index module made it — like a birth certificate for your index 👑. must be provided by the sub class, so don't come crying if you forgot.
✨ _code_base ✨
Title : _code_base
Usage : $code = $db->_code_base();
Function:
Example :
Returns : Code package to be used with this
Args :returns the code package to be used with this. short and sweet, no further notes given. 🤷♀️
✨ _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 : nonecalled by _initalize. it checks that the index you opened was made by the same index module — and the same version of that module — that's trying to open it. matching vibes only 💅. and if the index is empty? it just adds the information to the database. returns 1 or throws an exception.
✨ _check_file_sizes ✨
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()
function.
Example :
Returns : 1 or exception
Args :verifies that the files listed in the database are the same size as they were when the database was built — or it throws an exception 😤. called by the new() function, so it's out here doing quality control automatically.
returns 1 or an exception.
✨ 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 _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
Args : LIST OF FILEStakes a list of file names, checks that they're all fully qualified, and then calls _filename() on each one. it hands _filename() the name of the file and an integer that gets stored with every record _filename() creates. you can call it multiple times, and yes, you can use it to add to an existing index file. main character energy fr 🎀
$index->make_index( '/home/seqs1', '/home/seqs2', '/nfs/pub/big_db' );returns the number of files indexed. args: LIST OF FILES.
✨ pathtype ✨
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,
);
or
$index->pathtype('relative');
Returns : Type of the path.
Args : String (relative|absolute)sets the type of the file path. only two values are allowed, bestie: 'relative' or 'absolute' — that's it, those are the options. if you don't give any value, it defaults to absolute, which means it mimics the default behavior of the Bio::Index::Abstract module. so it's a lil throwback, respectfully. 💖
my $index = Bio::Index::Abstract->(-pathtype => 'relative',
-file => $file.inx,
);or
$index->pathtype('relative');returns the type of the path. args: a string (relative|absolute).
✨ _filename ✨
Title : _filename
Usage : $index->_filename( FILE INT )
Function: Indexes the file
Example :
Returns :
Args :indexes the file. that's the whole job description. 🫡
✨ _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 : $first_file_indexed = $index->_file_handle( 0 );
Returns : ref to a filehandle
Args : INTreturns an open filehandle for file index INT. when it opens a new filehandle, it caches it in the @{$index->_filehandle} array. and if the filehandle you asked for is already open? it just hands it right back from the array. efficient queen 👑
$first_file_indexed = $index->_file_handle( 0 );returns a 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 : INT
Args : INTused by the index-building sub inside a sub class to keep track of how many files have been indexed. 📊 call it with an argument and it sets the count; call it without one and it gets the count. versatile icon.
returns INT. args: INT.
✨ add_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.
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 LISTcalls pack_record on @stuff, then adds the result of pack_record to the index database under the key $id. and plot twist — if $id is a reference to an array, then a new entry gets added under a key corresponding to each element of the array. so one call, many keys. slay 💅
$index->add_record( $id, $fileNumber, $begin, $end )returns TRUE on success or FALSE on failure. args: ID LIST.
✨ pack_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 : LISTpacks an array of scalars into one single string, joined by ASCII 034 — which is unlikely to show up in any of the strings, so it's a safe lil separator ✨ — and returns it.
$packed_string = $index->pack_record( $fileNumber, $begin, $end )returns a STRING or undef. args: LIST.
✨ unpack_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 034splits the string you hand it into an array, splitting on ASCII 034. the reverse of pack_record, the yin to its yang 🌸
( $fileNumber, $begin, $end ) = $index->unpack_record( $self->db->{$id} )returns a 3 element ARRAY. args: a STRING containing ASCII 034.
✨ count_records ✨
Title : count_records
Usage : $recs = $seqdb->count_records()
Function: return count of all recs in the index
Example :
Returns : a scalar
Args : nonereturns the count of all the recs in the index. that's it, that's the method. 🔢
$recs = $seqdb->count_records()returns a scalar. args: none.
✨ 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 : NONEcalled automatically when the index goes out of scope — no invitation needed, it just shows up 🦋. it closes the connection to the database and the handles to the sequence files. clean exit, no loose ends.
returns: NEVER. args: NONE.
and that's a wrap on the whole entire page, bestie 💖 this one's perl v5.32.1, dated 2021-08-15, and it's from the Bio::I...stract(3pm) manpage — go forth and index responsibly, you absolute icon 👑✨
📦 where this page comes from
- debian bookworm: libbio-perl-perl 1.7.8-1 · Perl
- debian trixie: libbio-perl-perl 1.7.8-1 · Perl
- ubuntu jammy: libbio-perl-perl 1.7.8-1 · Perl
- ubuntu noble: libbio-perl-perl 1.7.8-1 · Perl
- 💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on : a language model's rewrite of the original, under its terms