4 # part of the Deobfuscator package
5 # by Laura Kavanaugh and Dave Messina
7 # cared for by Dave Messina <dave-pause@davemessina.net>
9 # POD documentation - main docs before the code
13 deob_interface.cgi - a WWW user interface to the BioPerl Deobfuscator
17 This document describes deob_interface.cgi version 0.0.3
22 This program is designed to be used through a web browser. To install
23 deob_interface.cgi and the rest of the Deobfuscator package, see the
29 Deob_interface.cgi provides a web-based front-end to the BioPerl Deobfuscator.
30 It uses the Deobfuscator package to open the Berkeley databases storing the
31 BioPerl documentation and then display a list of the available modules. A
32 search box is also provided if the user wants to pare down the list.
34 When a user clicks on the name of a class, deob_interface.cgi looks up the
35 stored documentation on the methods in that class, and all of the classes that
36 class inherits from, and displays a list of those methods. The list shows the
37 class, return values, and usage statement for each method. A user can see more
38 extensive documentation for a method by clicking on its name or its class's
46 =item C<< Can't open list of Perl module names >>
48 deob_interface.cgi can't locate the textfile F<package_list.txt>
49 containing the full list of BioPerl packages. By default this file should be
50 in the same directory as F<deob_interface.cgi>. See L</"CONFIGURATION AND
51 ENVIRONMENT"> for more information.
53 =item C<< Can't close list of Perl module names >>
55 deob_interface.cgi was unsuccessful in closing the F<package_list.txt>
56 file after reading it. This is most likely a transient filesystem error.
58 =item C<< Unknown sort option selected in deob_interface.cgi >>
60 In the event a sort parameter other than I<sort by class> or I<sort by method>
61 was sent to the sorting subroutine, deob_interface.cgi will exit with a fatal
67 =head1 CONFIGURATION AND ENVIRONMENT
69 See the F<README> for installation instructions.
71 There are four hardcoded variables you may need to set. Look in
72 deob_interface.cgi for a section labeled 'SET HARDCODED VALUES HERE'.
76 =item C<< $deob_detail_path >>
78 The URL of the F<deob_detail.cgi> program. Set to L<<
79 http://localhost/cgi-bin/deob_detail.cgi >> by default. F<deob_detail.cgi>
80 needs to be in your webserver's F<cgi-bin> directory or some location where
81 you are allowed to serve executable code to the web.
83 If you are setting up the Deobfuscator package on your own machine, the
84 default URL will probably work. Otherwise, you will need to change the URL,
85 replacing the C<< localhost portion >> with the hostname of your webserver,
86 and replacing C<< cgi-bin >> with the path to F<deob_detail.cgi> (starting
87 at your webserver's root directory).
89 =item C<< $PERLMODULES >>
91 The textfile containing a list of the BioPerl modules. Set to
92 F<package_list.txt> by default. F<package_list.txt> is automatically generated
93 by the L<< deob_index.pl >> script and its name is a hardcoded value.
95 If your copy of F<package_list.txt> has a different name or is not in the
96 same directory as F<deob_detail.cgi>, set $PERLMODULES to the full path of
97 F<package_list.txt>'s location.
99 =item C<< $BerkeleyDB_packages >>
101 The Berkeley DB file storing documentation on BioPerl packages. Set to
102 F<packages.db> by default. F<packages.db> is automatically generated by the
103 L<< deob_index.pl >> script and its name is a hardcoded value.
105 If your copy of F<packages.db> has a different name or is not in the same
106 directory as F<deob_detail.cgi>, set C<< $BerkeleyDB_packages >> to the
107 full path of F<packages.db>'s location.
109 =item C<< $BerkeleyDB_methods >>
111 The Berkeley DB file storing documentation on BioPerl methods. Set to F<methods.db> by default. F<methods.db> is automatically generated by the
112 F<deob_index.pl> script and its name is a hardcoded value.
114 If your copy of F<methods.db> has a different name or is not in the same
115 directory as F<deob_detail.cgi>, set C<< $BerkeleyDB_methods >> to the
116 full path of F<methods.db>'s location.
123 L<version>, L<CGI>, L<Deobfuscator>
126 =head1 INCOMPATIBILITIES
131 =head1 BUGS AND LIMITATIONS
135 =item C<< Selecting a class name returns no methods >>
137 Clicking on C<< Bio::Tools::dpAlign >> or C<< Bio::Tools::AlignFactory >> in
138 the upper class selection pane produces an empty lower methods pane. There are
139 undoubtedly other modules that will display this behavior. Reported by Laura
140 Kavanaugh 2006-04-18.
148 User feedback is an integral part of the evolution of this and other
149 Bioperl modules. Send your comments and suggestions preferably to one
150 of the Bioperl mailing lists. Your participation is much appreciated.
152 bioperl-l@bioperl.org - General discussion
153 http://www.bioperl.org/wiki/Mailing_lists - About the mailing lists
155 =head2 Reporting Bugs
157 Report bugs to the Bioperl bug tracking system to help us keep track
158 the bugs and their resolution. Bug reports can be submitted via the
161 https://github.com/bioperl/bioperl-live/issues
166 L<Deobfuscator>, L<deob_detail.cgi>, L<deob_index.pl>
178 =item Dave Messina C<< <dave-pause@davemessina.net> >>
185 =head1 ACKNOWLEDGMENTS
187 This software was developed originally at the Cold Spring Harbor Laboratory's
188 Advanced Bioinformatics Course between Oct 12-25, 2005. Many thanks to David
189 Curiel, who provided much-needed guidance and assistance on this project. Also, special thanks to Todd Wylie for his help with CGI.
191 =head1 LICENSE AND COPYRIGHT
193 Copyright (C) 2005-6 Laura Kavanaugh and Dave Messina. All Rights Reserved.
195 You may use modify or redistribute this software under the same terms as
201 This module is free software; you may redistribute it and/or modify it under the same terms as Perl itself. See L<perlartistic>.
207 # Let the code begin...
209 ## SET HARDCODED VALUES HERE ##
211 my $PERLMODULES = 'package_list.txt';
212 my $BerkeleyDB_packages = 'packages.db';
213 my $BerkeleyDB_methods = 'methods.db';
214 my $help_path = 'deob_help.html';
215 my $deob_detail_path = 'deob_detail.cgi';
217 ## You shouldn't need to change anything below here ##
219 use version
; $VERSION = qv
('0.0.2');
225 my @available_modules;
231 my $pattern_found = 0;
233 my $ref_BerkeleyDB_packages;
234 my $ref_BerkeleyDB_methods;
237 # if user previously set the sort order, we can send it with the first form
238 $sort_order = param
('sort_order') ? param
('sort_order') : 'by method';
242 = qq{style
="border-collapse:collapse;border:solid black 1px;font-family:verdana;font-size:10px;background-color:lightgrey;padding:3"};
244 = qq{style
="border-collapse:collapse;border:solid black 1px;font-family:verdana;font-size:10px;padding:3"};
246 = qq{style
="border-collapse:collapse;border:solid black 1px;font-family:verdana;font-size:14px;padding:3"};
248 = qq{style
="border-collapse:collapse;border:0px;font-family:verdana;font-size:18px;font-weight:bold;padding:3"};
249 my $style5 = qq{style
="font-family:verdana;font-size:14px;padding:3"};
251 # Open file containing all Bioperl package names
252 open my $MODS, '<', $PERLMODULES
253 or die "Could not read list of Perl module names '$PERLMODULES': $!\n";
255 # Open BerkeleyDB by getting hash references
256 $ref_BerkeleyDB_packages = Deobfuscator
::open_db
($BerkeleyDB_packages);
257 $ref_BerkeleyDB_methods = Deobfuscator
::open_db
($BerkeleyDB_methods);
259 # Grab input and remove whitespace
260 my $pattern = param
('search_string') ? param
('search_string') : ' ';
263 # Filter file names with user search string if one has been entered
265 if (/\S+/) { # capture list of all module names in case there are no
266 # matches found to user input string
267 push @all_modules, $_;
271 push @available_modules, $_;
277 push @available_modules, $_;
282 if ( scalar @available_modules < 1 ) {
283 @available_modules = @all_modules;
285 close $MODS or die "Could not close list of Perl module names $PERLMODULES: $!\n";
287 # grab BioPerl version string
288 my $version_string = '__BioPerl_Version'; # specified in deob_index.pl
289 my $BioPerl_version = $ref_BerkeleyDB_packages->{$version_string};
296 <title>BioPerl Deobfuscator</title>
297 <script language="JavaScript">
299 function submitMe(packageName) {
300 searchForm.module.value=packageName;
301 searchForm.Search.value='Search';
308 <div style="border:solid black 1px; width:100%; overflow:auto">
311 <td><p $style4>Welcome to the BioPerl Deobfuscator</p></td>
312 <td><p $style5>[ <font color="red">$BioPerl_version</font> ]</p></td>
313 <td><p align=right><a href="$help_path">what is it?</a></p></td>
320 <form name="searchForm" action="">
321 <input type="hidden" name="Search">
322 <input type="hidden" name="module">
323 <input type="hidden" name="sort_order" value="$sort_order">
325 Search <b>class names</b> by string or Perl regex (examples: Bio::SeqIO, seq, fasta\$)
327 <input style="width:30em" type="text" name="search_string" value="$pattern"></input>
328 <input type="submit" name="Filter"></input></form>
330 OR select a class from the list:
336 <div style="border:solid black 1px; width:100%; height:200; overflow:auto">
337 <table width="100%" $style2>
340 foreach my $package (@available_modules) {
344 = Deobfuscator::get_pkg_docs( $ref_BerkeleyDB_packages, $package,
346 my $link = qq{<a href="javascript:submitMe('$package')">$package</a>};
349 "<tr><td $style1>$link</td><td $style2 width='75%'>$packageDesc</td></tr>\n";
360 # keep track of all our form values
361 my $input_module = param
('module');
362 $filter = param
('Filter') ? param
('Filter') : ' ';
363 $search = param
('Search');
364 $sort_order = param
('sort_order');
366 # set position of sort button based on current sort order
370 if ($sort_order eq 'by method') {
371 $is_method = 'selected';
374 elsif ($sort_order eq 'by class') {
376 $is_class = 'selected';
379 $is_method = 'selected';
384 # Process user input and return result
387 # show button allowing user to set sort order
390 <form name="SORT" action="">
391 <input type="hidden
" name="Search
" value="$search">
392 <input type="hidden
" name="module
" value="$input_module">
393 <select name="sort_order
" onChange="submit
()">
394 <option value="by method
" $is_method>sort by method</option>
395 <option value="by
class" $is_class>sort by class</option>
400 # grab sort order from form or sort by method as a default
401 $sort_method = param('sort_order') ? param('sort_order') : 'by method';
403 # filter not yet implemented, so this 'if' should never be true
404 if ( ( $filter eq "" ) && ( $input_module eq "" ) ) {
406 print "filter
= $filter<br
>search
=$search<br
>";
407 print "Please
select a
class from the menu
or enter a search
\n";
408 print "string
and press
\"Filter
\" button
\n";
412 # Determine methods available to user's input class and the class
413 # where the methods reside. Store results in a hash.
414 $ref_Class_hash = get_methods($input_module);
416 # Sort the method/class data according to user input and display
418 = sorting( $input_module, $sort_method, $ref_Class_hash );
421 display( $input_module, $ref_sorted_keys, $ref_Class_hash,
422 $ref_BerkeleyDB_methods, $deob_detail_path );
425 # filter not yet implemented, so this 'if' should never be true
427 if ( !($pattern_found) ) {
428 print qq{<b><p style="color
:red
">No match to string found, please try again</p></b>};
429 h1('Welcome to the BioPerl Deobfuscator!'),;
433 print "Not sure about that input
. Please submit error report
\n";
443 Deobfuscator::close_db($BerkeleyDB_packages);
444 Deobfuscator::close_db($BerkeleyDB_methods);
447 ######################## SUBROUTINES #################################
451 # Get all available methods for user input class. Deobfuscator package
452 # returns hash with key as user input class and value as ref to array. The
453 # array contains references to an array for each Class, method pair. This
454 # subroutine unpacks this data structure and, for each user input class
455 # creates a hash where the keys are a concatinated class--method pair and the
456 # values are the method (There is method to the maddness, its just obscure).
458 my ($user_class) = shift;
460 my $hashref = Deobfuscator::return_methods($user_class);
462 # Put data from Deobfuscaotr into hash so it can be sorted later according
463 # to user specification
464 my %Package_hash = ();
466 foreach my $array_ref ( @{ $hashref->{$user_class} } ) { #3
467 my $key = $array_ref->[1] . "::" . $array_ref->[0];
468 $Package_hash{$key} = $array_ref->[0];
472 return \%Package_hash;
474 } #1 End sub get_methods
478 my ( $package, $sort, $ref_hash ) = @_;
481 # Sort by Class or method, depending on user request
482 if ( $sort =~ 'by class' ) { #3
483 # Sort by Class name (use "lc" to ensure names containing capital
484 # letters are not sorted separately from lower case names
485 foreach my $first ( sort { lc $a cmp lc $b } keys %$ref_hash ) { #4
487 my $package_name = $1;
488 push @sorted_keys, $first;
492 elsif ( $sort =~ 'by method' ) { #3
493 # Sort alphabetically by method name (use "lc" in sort because some
494 # method names are capitalized and will appear first in
495 # an alphabetized list unless lower cased.)
497 sort { lc $ref_hash->{$a} cmp lc $ref_hash->{$b} }
502 my $package_name = $1;
503 push @sorted_keys, $first;
509 "Unknown
sort option
>$sort< in deob_interface
.cgi
::sorting
()\n";
512 return \@sorted_keys;
514 } #1 End sorting subroutine
518 my ( $package, $ref_sorted_array, $ref_hash, $db_hashref, $detail_path ) = @_;
522 <div style="border
:solid black
1px
; width
:100%; overflow
:auto
">
523 <table width="100%" $style3>
524 <tr><td colspan=4><center>methods for <b>$package</b></center></td></tr>
527 <div style="border
:solid black
1px
; width
:100%; height
:200; overflow
:auto
">
528 <table width="100%" $style3>
531 <td $style3 align=center>Method</td>
532 <td $style3 align=center>Class</td>
533 <td $style3 align=center>Returns</td>
534 <td $style3 align=center>Usage</td>
539 foreach my $first (@
$ref_sorted_array) { #4
541 my $package_name = Deobfuscator
::urlify_pkg
($1);
543 # Get the return values part of the documentation
544 my $return_methods_raw
545 = Deobfuscator
::get_method_docs
( $db_hashref, $first, "returns" );
546 if ( $return_methods_raw eq "0" ) {
547 $return_methods_raw = "not documented";
550 # Get the usage part of the documentation
552 = Deobfuscator
::get_method_docs
( $db_hashref, $first, "usage" );
553 if ( $return_usage_raw eq "0" ) {
554 $return_usage_raw = "not documented";
557 # clean up formatting a little
558 my $return_methods = Deobfuscator
::htmlify
($return_methods_raw);
559 my $return_usage = Deobfuscator
::htmlify
($return_usage_raw);
562 my $href = $detail_path . "?method=$first";
564 = qq{<a target
="method" href
="$href">$ref_hash->{$first}</a
>};
567 = ( $link, $package_name, $return_methods, $return_usage );
570 print "<tr><td $style2>", join( "</td><td $style2>", @columns ),
581 } #1 End display subroutine