Bio/SearchIO/SearchWriterI.pm

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