/ 
bioperl-1.5.2_004-RCd
/ Deobfuscator

NAME

Deobfuscator - get BioPerl method and package information from a Berkeley DB

VERSION

This document describes Deobfuscator version 0.0.2

SYNOPSIS

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);

DESCRIPTION

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.

DIAGNOSTICS

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.

CONFIGURATION AND ENVIRONMENT

This software requires:

A working installation of the Berkeley DB

The Berkeley DB comes standard with most UNIX distributions, so you may already have it installed. See http://www.sleepycat.com for more information.

BioPerl

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.

DEPENDENCIES

version, Class::Inspector, DB_File

INCOMPATIBILITIES

None reported.

BUGS AND LIMITATIONS

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.

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://www.bioperl.org/wiki/Mailing_lists   - About the mailing lists

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/

SEE ALSO

deob_index.pl

AUTHOR

Dave Messina <dave-pause@davemessina.net>

CONTRIBUTORS

Laura Kavanaugh
David Curiel

ACKNOWLEDGMENTS

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.

LICENSE AND COPYRIGHT

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.

DISCLAIMER

This software is provided "as is" without warranty of any kind.

APPENDIX

The rest of the documentation details each of the functions. Internal methods are preceded with a "_".

return_methods

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

_load_module

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

open_db

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

close_db

Title : close_db Usage : closes a Berkeley DB Function: closes a database Returns : nothing. Args : a hashref to a tied Berkeley DB

get_pkg_docs

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

get_method_docs

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

htmlify

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