Deobfuscator - get BioPerl method and package information from a Berkeley DB
This document describes Deobfuscator version 0.0.3
use Deobfuscator; # get all the methods available to objects belonging to a class # (including those inherited from parent classes) my $hashref = Deobfuscator::return_methods('Bio::SeqIO', 'Bio::AlignIO'); # retrieve the return values for a method my $method_db_ref = Deobfuscator::open_db('methods.db'); my $ret_vals = Deobfuscator::get_method_docs( $method_db_ref, 'Bio::SeqIO::next_seq', 'returns' ); close_db($method_db_ref); # retrieve the synopsis documentation for a class my $pkg_db_ref = Deobfuscator::open_db('packages.db'); my $synopsis = Deobfuscator::get_pkg_docs( $pkg_db_ref, 'Bio::SeqIO', 'synopsis' ); close_db($pkg_db_ref);
The Deobfuscator module contains functions which relate to retrieving specific types of documentation about BioPerl packages and methods.
The deob_index.pl script reads through all of the BioPerl files, extracts the documentation, and stores it in two BerkeleyDB databases. This module is then used to query those databases for information about a given method or package. (see the deob_index.pl documentation for more info.)
The types of information available for individual methods include: the usage statement, the return values, the arguments to give to the method, the description of the function, and an example of how to use the method.
The Deobfuscator module can be used also to retrieve the synopsis and description documentation for a given class.
error: couldn't eval $module
A package couldn't be loaded (eval'd), which would prevent us from determining what its methods are.
error: couldn't open $filename
One of the Berkeley databases couldn't be opened. Possible causes are: deob_index.pl wasn't run and so the databases weren't created, or the database files aren't in the correct place.
error: couldn't close database
One of the Berkeley databases couldn't be closed. This might just be a transient filesystem error.
This software requires:
The Berkeley DB comes standard with most UNIX distributions, so you may already have it installed. See http://www.sleepycat.com for more information.
Deobfuscator.pm recursively navigates a directory of BioPerl modules. Note that the BioPerl module directory need not be "installed"; any old location will do. See http://www.bioperl.org for the latest version.
version, Class::Inspector, DB_File
None reported.
In the current implementation, Deobfuscator does not show internal or private methods (i.e. those whose name begins with an underscore). This is simply an option in the Class::Inspector->methods call, and so could be presented as an option to the user (patches welcome).
No bugs have been reported.
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://www.bioperl.org/wiki/Mailing_lists - About the mailing lists
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.
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.bioperl.org/
deob_index.pl
Dave Messina <dave-pause@davemessina.net>
<dave-pause@davemessina.net>
This software was developed originally at the Cold Spring Harbor Laboratory's Advanced Bioinformatics Course between Oct 12-25, 2005. Many thanks to David Curiel, who provided much-needed guidance and assistance on this project.
Copyright (C) 2005-6 Laura Kavanaugh and Dave Messina. All Rights Reserved.
This module is free software; you may redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.
This software is provided "as is" without warranty of any kind.
The rest of the documentation details each of the functions. Internal methods are preceded with a "_".
Title : return_methods Usage : $methods_hashref = Deobfuscator::return_methods('Bio::AlignIO', 'Bio::SeqIO'); Function: traverses the inheritance tree for a given class to determine the methods available to objects belonging to that class
Returns : a reference to a hash. The hash keys are fully-qualified class names, such as 'Bio::SeqIO'. The hash values are references to an array of hashes, where each array element is a reference to a hash containing two key-value pairs, 'method' and 'class';
Args : a list of fully-qualified class names
Title : print_methods Usage : print_methods('Bio::AlignIO','Bio::SeqIO'); Function: traverses the inheritance tree for a given class to determine the methods available to objects belonging to that class, then pretty-prints the resulting information. Returns : nothing. But it does print to the current filehandle (usually STDOUT). Args : a list of fully-qualified class names
Title : _load_module Usage : * INTERNAL USE ONLY * Function: attempts to load a module Returns : nothing. But it does die upon failure to load. Args : a module name
Title : open_db Usage : open_db($filename) Function: opens a Berkeley DB Returns : a hashref tied to the DB Args : a filename as a scalar
Title : close_db Usage : closes a Berkeley DB Function: closes a database Returns : nothing. Args : a hashref to a tied Berkeley DB
Title : get_pkg_docs Usage : get_pkg_docs($db_hashref, 'Class name', 'documentation type'); Function: returns a specified part of the documentation for a class Returns : a string containing the desired documentation or ' ' if the documentation doesn't exist Args : - $db_hashref is the ref to the hash tied to the DB - Class name is of the form 'Bio::SeqIO' - documentation type is the subfield of the method's POD. The possible values of documentation type are: short_desc, synopsis, desc
Title : get_method_docs Usage : get_method_docs($db_hashref, 'Class+method name', 'documentation type'); Example : get_method_docs($db_hashref, 'Bio::SeqIO::next_aln', 'args'); Function: returns a specified part of the documentation for a class's method Returns : a string containing the desired documentation, or 0 if the desired documentation doesn't exist Args : - $db_hashref is the ref to the hash tied to the DB - Class+method name is of the form 'Bio::SeqIO::next_aln', where Bio::SeqIO is the class and next_aln is the method. - documentation type is the subfield of the method's POD. The possible values of documentation type are: title, usage, function, returns, args
Title : htmlify Usage : htmlify($string); Example : htmlify('this is a : doc); Function: does some crude reformatting of POD method documentation by swapping isolated colons (':') into HTML <br> tags Returns : a string Args : a string
Title : urlify_pkg Usage : urlify_pkg($string); Example : urlify('this is a : doc); Function: wraps a package name in an HTML href pointing to the bioperl.org pdoc docs for that package Returns : a string (an href in HTML) Args : a string
To install BioPerl, copy and paste the appropriate command in to your terminal.
cpanm
cpanm BioPerl
CPAN shell
perl -MCPAN -e shell install BioPerl
For more information on module installation, please visit the detailed CPAN module installation guide.