Bio/SearchIO/SearchWriterI.pm

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