3
# module for retrieving method-specific documentation from a
6
# first version by Dave Messina (dmessina@watson.wustl.edu) at the
7
# Cold Spring Harbor Laboratory Advanced Bioinformatics Course
10
# part of the Deobfuscator package
11
# by Laura Kavanaugh and Dave Messina
13
# cared for by Dave Messina <dave-pause@davemessina.net>
15
# POD documentation - main docs before the code
19
Deobfuscator - get BioPerl method and package information from a Berkeley DB
24
This document describes Deobfuscator version 0.0.2
31
# get all the methods available to objects belonging to a class
32
# (including those inherited from parent classes)
33
my $hashref = Deobfuscator::return_methods('Bio::SeqIO', 'Bio::AlignIO');
35
# retrieve the return values for a method
36
my $method_db_ref = Deobfuscator::open_db('methods.db');
37
my $ret_vals = Deobfuscator::get_method_docs( $method_db_ref,
38
'Bio::SeqIO::next_seq',
40
close_db($method_db_ref);
42
# retrieve the synopsis documentation for a class
43
my $pkg_db_ref = Deobfuscator::open_db('packages.db');
44
my $synopsis = Deobfuscator::get_pkg_docs( $pkg_db_ref,
47
close_db($pkg_db_ref);
52
The Deobfuscator module contains functions which relate to retrieving
53
specific types of documentation about BioPerl packages and methods.
55
The deob_index.pl script reads through all of the BioPerl files, extracts
56
the documentation, and stores it in two BerkeleyDB databases. This module
57
is then used to query those databases for information about a given method
58
or package. (see the deob_index.pl documentation for more info.)
60
The types of information available for individual methods include: the
61
usage statement, the return values, the arguments to give to the method, the
62
description of the function, and an example of how to use the method.
64
The Deobfuscator module can be used also to retrieve the synopsis and
65
description documentation for a given class.
72
=item C<< error: couldn't eval $module >>
74
A package couldn't be loaded (eval'd), which would prevent us from determining
77
=item C<< error: couldn't open $filename >>
79
One of the Berkeley databases couldn't be opened. Possible causes are:
80
deob_index.pl wasn't run and so the databases weren't created, or the database
81
files aren't in the correct place.
83
=item C<< error: couldn't close database >>
85
One of the Berkeley databases couldn't be closed. This might just be a
86
transient filesystem error.
91
=head1 CONFIGURATION AND ENVIRONMENT
93
This software requires:
97
=item A working installation of the Berkeley DB
99
The Berkeley DB comes standard with most UNIX distributions, so you may
100
already have it installed. See L<http://www.sleepycat.com> for more information.
104
Deobfuscator.pm recursively navigates a directory of BioPerl modules. Note
105
that the BioPerl module directory need not be "installed"; any old location
106
will do. See L<http://www.bioperl.org> for the latest version.
113
L<version>, L<Class::Inspector>, L<DB_File>
116
=head1 INCOMPATIBILITIES
121
=head1 BUGS AND LIMITATIONS
123
In the current implementation, Deobfuscator does not show internal or private
124
methods (i.e. those whose name begins with an underscore). This is simply an
125
option in the Class::Inspector->methods call, and so could be presented as an
126
option to the user (patches welcome).
128
No bugs have been reported.
135
User feedback is an integral part of the evolution of this and other
136
Bioperl modules. Send your comments and suggestions preferably to one
137
of the Bioperl mailing lists. Your participation is much appreciated.
139
bioperl-l@bioperl.org - General discussion
140
http://www.bioperl.org/wiki/Mailing_lists - About the mailing lists
142
=head2 Reporting Bugs
144
Report bugs to the Bioperl bug tracking system to help us keep track
145
the bugs and their resolution. Bug reports can be submitted via the
148
http://bugzilla.open-bio.org/
158
Dave Messina C<< <dave-pause@davemessina.net> >>
165
=item Laura Kavanaugh
172
=head1 ACKNOWLEDGMENTS
174
This software was developed originally at the Cold Spring Harbor Laboratory's
175
Advanced Bioinformatics Course between Oct 12-25, 2005. Many thanks to David
176
Curiel, who provided much-needed guidance and assistance on this project.
179
=head1 LICENSE AND COPYRIGHT
181
Copyright (C) 2005-6 Laura Kavanaugh and Dave Messina. All Rights Reserved.
183
This module is free software; you may redistribute it and/or modify it under the
184
same terms as Perl itself. See L<perlartistic>.
189
This software is provided "as is" without warranty of any kind.
194
The rest of the documentation details each of the functions.
195
Internal methods are preceded with a "_".
200
use version; $VERSION = qv('0.0.2');
203
use Class::Inspector;
209
=head2 return_methods
211
Title : return_methods
212
Usage : $methods_hashref = Deobfuscator::return_methods('Bio::AlignIO',
214
Function: traverses the inheritance tree for a given class to determine
215
the methods available to objects belonging to that class
217
Returns : a reference to a hash. The hash keys are fully-qualified class
218
names, such as 'Bio::SeqIO'. The hash values are references to
219
an array of hashes, where each array element is a reference to
220
a hash containing two key-value pairs, 'method' and 'class';
222
Args : a list of fully-qualified class names
230
# key: full class name
231
# value: a reference to an array of hashes
232
# where each array element is a pointer to a hash
233
# which contains two key: 'method' and 'class'
237
foreach my $class (@input) {
239
# fancy eval so that we can loop through different modules
240
_load_module($class);
242
# methods returned from Class::Inspector as:
244
# [ 'Class::method1', 'Class', 'method1', \&Class::method1 ],
245
# [ 'Another::method2', 'Another', 'method2', \&Another::method2 ],
246
# [ 'Foo::bar', 'Foo', 'bar', \&Foo::bar ],
249
= Class::Inspector->methods( $class, 'expanded', 'public' );
252
for ( my $i = 0; $i < scalar @{$methods_aryref3}; $i++ ) {
253
foreach my $meth ( $methods_aryref3->[$i] ) {
254
my $method_name = $meth->[2];
255
my $inherited_from = $meth->[1];
256
push @{$methods_of{$class}}, [$method_name, $inherited_from];
267
Title : print_methods
268
Usage : print_methods('Bio::AlignIO','Bio::SeqIO');
269
Function: traverses the inheritance tree for a given class to determine
270
the methods available to objects belonging to that class, then
271
pretty-prints the resulting information.
272
Returns : nothing. But it does print to the current filehandle (usually
274
Args : a list of fully-qualified class names
282
foreach my $class (@input) {
284
# fancy eval so that we can loop through different modules
285
_load_module($class);
287
# methods returned as
289
# [ 'Class::method1', 'Class', 'method1', \&Class::method1 ],
290
# [ 'Another::method2', 'Another', 'method2', \&Another::method2 ],
291
# [ 'Foo::bar', 'Foo', 'bar', \&Foo::bar ],
294
= Class::Inspector->methods( $class, 'expanded', 'public' );
296
print "methods for $class\n";
297
print "=========================================\n";
299
for ( my $i = 0; $i < scalar @{$methods_aryref3}; $i++ ) {
301
foreach my $meth ( $methods_aryref3->[$i] ) {
302
print "\t class: $meth->[1]\n";
303
print "\t method: $meth->[2]\n";
305
print "--------------------------------------\n";
315
Usage : * INTERNAL USE ONLY *
316
Function: attempts to load a module
317
Returns : nothing. But it does die upon failure to load.
324
eval "require $module";
325
die "error! couldn't eval $module" if $@;
331
Usage : open_db($filename)
332
Function: opens a Berkeley DB
333
Returns : a hashref tied to the DB
334
Args : a filename as a scalar
342
my $hashref = \%hash;
344
tie %hash, "DB_File", $filename or die "error: couldn't open $filename: $!\n";
352
Usage : closes a Berkeley DB
353
Function: closes a database
355
Args : a hashref to a tied Berkeley DB
362
untie $hashref or die "error: couldn't close database: $!\n";
368
Usage : get_pkg_docs($db_hashref, 'Class name', 'documentation type');
369
Function: returns a specified part of the documentation for a class
370
Returns : a string containing the desired documentation or ' ' if the
371
documentation doesn't exist
372
Args : - $db_hashref is the ref to the hash tied to the DB
373
- Class name is of the form 'Bio::SeqIO'
374
- documentation type is the subfield of the method's POD.
375
The possible values of documentation type are:
376
short_desc, synopsis, desc
381
my ($db_hashref, $pkg_name, $info_type) = @_;
383
# hash to store our hash value, now split out into its constituent parts
386
my $rec_sep = 'DaVe-ReC-sEp';
388
# if the method isn't in our db
389
if ( ! exists($db_hashref->{$pkg_name}) ) {
393
# grab the constituent parts of the pkg record
394
( $record{'short_desc'}, $record{'synopsis'}, $record{'desc'} ) =
395
( split $rec_sep, $db_hashref->{$pkg_name} );
397
# return just the part that was asked for
398
if ( exists($record{$info_type}) ) {
399
return $record{$info_type};
404
=head2 get_method_docs
406
Title : get_method_docs
407
Usage : get_method_docs($db_hashref, 'Class+method name', 'documentation type');
408
Example : get_method_docs($db_hashref, 'Bio::SeqIO::next_aln', 'args');
409
Function: returns a specified part of the documentation for a class's method
410
Returns : a string containing the desired documentation, or 0 if the
411
desired documentation doesn't exist
412
Args : - $db_hashref is the ref to the hash tied to the DB
413
- Class+method name is of the form 'Bio::SeqIO::next_aln',
414
where Bio::SeqIO is the class and next_aln is the method.
415
- documentation type is the subfield of the method's POD.
416
The possible values of documentation type are:
417
title, usage, function, returns, args
421
sub get_method_docs {
422
my ($db_hashref, $meth_name, $info_type) = @_;
427
my $rec_sep = 'DaVe-ReC-sEp';
429
# if the method isn't in our db
430
if ( !exists( $db_hashref->{$meth_name} ) ) {
434
# separate the sub-records using the record separator and field tag
435
my @parts = split $rec_sep, $db_hashref->{$meth_name};
437
# put individual info types into separate hash entries...
438
foreach my $part (@parts) {
439
if ($part =~ /^-(\w+)\|(.*)/) { $record{$1} = $2; }
441
# ... and put the whole thing into one big string
442
$whole_record .= "$part\n";
445
# return a specific part if that was asked for
447
# return just the part that was asked for
448
if ( exists( $record{$info_type} ) ) {
450
# if there's really nothing in there, say so.
451
if ( ( $record{$info_type} =~ /^[\s\n]*$/)
452
|| ( $record{$info_type} eq '') ) { return 0; }
454
return $record{$info_type};
457
# or return everything
458
else { return $whole_record; }
460
# otherwise return whole record
462
return $whole_record;
469
Usage : htmlify($string);
470
Example : htmlify('this is a : doc);
471
Function: does some crude reformatting of POD method documentation by swapping
472
isolated colons (':') into HTML <br> tags
481
# change isolated colons into <br> tags
482
$string =~ s/\s:\s/ <br> /g;
added
removed
doc/Deobfuscator/lib/Deobfuscator.pm
