Bio/SearchIO/SearchWriterI.pm

   1 #-----------------------------------------------------------------
   2 #
   3 # BioPerl module Bio::SearchIO::SearchWriterI
   4 #
   5 # Please direct questions and support issues to <bioperl-l@bioperl.org>
   6 #
   7 # Cared for by Steve Chervitz <sac@bioperl.org>
   8 #
   9 # You may distribute this module under the same terms as perl itself
  10 #-----------------------------------------------------------------
  11
  12 =head1 NAME
  13
  14 Bio::SearchIO::SearchWriterI - Interface for outputting parsed Search results
  15
  16 =head1 SYNOPSIS
  17
  18 Bio::SearchIO::SearchWriterI objects cannot be instantiated since this
  19 module defines a pure interface.
  20
  21 Given an object that implements the Bio::SearchIO::SearchWriterI interface,
  22 you can do the following things with it:
  23
  24     print $writer->to_string( $result_obj, @args );
  25
  26 =head1 DESCRIPTION
  27
  28 This module defines abstract methods that all subclasses must implement
  29 to be used for outputting results from L<Bio::Search::Result::ResultI>
  30 objects.
  31
  32 =head1 AUTHOR
  33
  34 Steve Chervitz E<lt>sac-at-bioperl.orgE<gt>
  35
  36 =head1 DISCLAIMER
  37
  38 This software is provided "as is" without warranty of any kind.
  39
  40 =head1 APPENDIX
  41
  42 The rest of the documentation details each of the object methods.
  43
  44 =cut
  45
  46 package Bio::SearchIO::SearchWriterI;
  47
  48
  49 use base qw(Bio::Root::RootI);
  50
  51 =head2 to_string
  52
  53  Purpose   : Produces data for each Search::Result::ResultI in a string.
  54            : This is an abstract method. For some useful implementations,
  55            : see ResultTableWriter.pm, HitTableWriter.pm,
  56            : and HSPTableWriter.pm.
  57  Usage     : print $writer->to_string( $result_obj, @args );
  58  Argument  : $result_obj = A Bio::Search::Result::ResultI object
  59            : @args = any additional arguments used by your implementation.
  60  Returns   : String containing data for each search Result or any of its
  61            : sub-objects (Hits and HSPs).
  62  Throws    : n/a
  63
  64 =cut
  65
  66 sub to_string {
  67     my ($self, $result, @args) = @_;
  68     $self->throw_not_implemented;
  69 }
  70
  71 =head2 start_report
  72
  73  Title   : start_report
  74  Usage   : $self->start_report()
  75  Function: The method to call when starting a report. You can override it
  76            to make a custom header
  77  Returns : string
  78  Args    : none
  79
  80 =cut
  81
  82 sub start_report { return '' }
  83
  84 =head2 end_report
  85
  86  Title   : end_report
  87  Usage   : $self->end_report()
  88  Function: The method to call when ending a report, this is
  89            mostly for cleanup for formats which require you to
  90            have something at the end of the document (</BODY></HTML>)
  91            for HTML
  92  Returns : string
  93  Args    : none
  94
  95
  96 =cut
  97
  98 sub end_report {  return '' }
  99
 100 =head2 filter
 101
 102  Title   : filter
 103  Usage   : $writer->filter('hsp', \&hsp_filter);
 104  Function: Filter out either at HSP,Hit,or Result level
 105  Returns : none
 106  Args    : string => data type,
 107            CODE reference
 108
 109
 110 =cut
 111
 112 # yes this is an implementation in the interface,
 113 # yes it assumes that the underlying class is hash-based
 114 # yes that might not be a good idea, but until people
 115 # start extending the SearchWriterI interface I think
 116 # this is an okay way to go
 117
 118 sub filter {
 119     my ($self,$method,$code) = @_;
 120     return unless $method;
 121     $method = uc($method);
 122     if( $method ne 'HSP' &&
 123         $method ne 'HIT' &&
 124         $method ne 'RESULT' ) {
 125         $self->warn("Unknown method $method");
 126         return;
 127     }
 128     if( $code )  {
 129         $self->throw("Must provide a valid code reference") unless ref($code) =~ /CODE/;
 130         $self->{$method} = $code;
 131     }
 132     return $self->{$method};
 133 }
 134
 135 1;
 136
 137