lib/Bio/Event/EventHandlerI.pm

   1 #
   2 # BioPerl module for Bio::Event::EventHandlerI
   3 #
   4 # Please direct questions and support issues to <bioperl-l@bioperl.org>
   5 #
   6 # Cared for by Jason Stajich <jason@bioperl.org>
   7 #
   8 # Copyright Jason Stajich
   9 #
  10 # You may distribute this module under the same terms as perl itself
  11
  12 # POD documentation - main docs before the code
  13
  14 =head1 NAME
  15
  16 Bio::Event::EventHandlerI - An Event Handler Interface
  17
  18 =head1 SYNOPSIS
  19
  20     # do not use this module directly
  21     # See Bio::SearchIO::SearchResultEventHandler for an example of
  22     # implementation.
  23
  24 =head1 DESCRIPTION
  25
  26 This interface describes the basic methods required for
  27 EventHandlers.  These are essentially SAX methods.
  28
  29 =head1 Developer Notes
  30
  31 EventHandlerI implementations are used in the BioPerl IO systems to
  32 decouple the task of tokenizing the input stream into data elements
  33 and their attributes, which is format-specific, and the task of
  34 collecting those elements and attributes into whatever is the result
  35 of a parser, which is specific to the kind of result to be produced,
  36 such as BioPerl objects, a tabular or array data structure, etc.
  37
  38 You can think of EventHandlerI-compliant parsers as faking a SAX XML
  39 parser, making their input (typically a non-XML document) behave as if
  40 it were XML. The overhead to do this can be quite substantial, at the
  41 gain of not having to duplicate the parsing code in order to change
  42 the parsing result, and not having to duplicate the logic of
  43 instantiating objects between parsers for different formats that all
  44 give rise to the same types of objects. This is perhaps best
  45 illustrated by the Bio::SearchIO system, where many different formats
  46 exist for sequence similarity and pairwise sequence alignment exist
  47 that essentially all result in Bio::Search objects.
  48
  49 The method names and their invocation semantics follow their XML SAX
  50 equivalents, see http://www.saxproject.org/apidoc/, especially the
  51 org.xml.sax.ContentHandler interface.
  52
  53 =head1 FEEDBACK
  54
  55 =head2 Mailing Lists
  56
  57 User feedback is an integral part of the evolution of this and other
  58 Bioperl modules. Send your comments and suggestions preferably to
  59 the Bioperl mailing list.  Your participation is much appreciated.
  60
  61   bioperl-l@bioperl.org                  - General discussion
  62   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
  63
  64 =head2 Support
  65
  66 Please direct usage questions or support issues to the mailing list:
  67
  68 I<bioperl-l@bioperl.org>
  69
  70 rather than to the module maintainer directly. Many experienced and
  71 reponsive experts will be able look at the problem and quickly
  72 address it. Please include a thorough description of the problem
  73 with code and data examples if at all possible.
  74
  75 =head2 Reporting Bugs
  76
  77 Report bugs to the Bioperl bug tracking system to help us keep track
  78 of the bugs and their resolution. Bug reports can be submitted via the
  79 web:
  80
  81   https://github.com/bioperl/bioperl-live/issues
  82
  83 =head1 AUTHOR - Jason Stajich
  84
  85 Email jason@bioperl.org
  86
  87 =head1 APPENDIX
  88
  89 The rest of the documentation details each of the object methods.
  90 Internal methods are usually preceded with a _
  91
  92 =cut
  93
  94
  95 # Let the code begin...
  96
  97
  98 package Bio::Event::EventHandlerI;
  99
 100 use strict;
 101 use Carp;
 102
 103 use base qw(Bio::Root::RootI);
 104
 105 =head2 will_handle
 106
 107  Title   : will_handle
 108  Usage   : if( $handler->will_handle($event_type) ) { ... }
 109  Function: Tests if this event builder knows how to process a specific event
 110  Returns : boolean
 111  Args    : event type name
 112
 113
 114 =cut
 115
 116 sub will_handle{
 117    my ($self,$type) = @_;
 118    $self->throw_not_implemented();
 119 }
 120
 121 =head2 SAX methods
 122
 123 =cut
 124
 125 =head2 start_document
 126
 127  Title   : start_document
 128  Usage   : $resultObj = $parser->start_document();
 129  Function: Receive notification of the beginning of a document (the
 130            input file of a parser). The parser will invoke this method
 131            only once, before any other event callbacks.
 132
 133            Usually, a handler will reset any internal state structures
 134            when this method is called.
 135
 136  Returns : none
 137  Args    : none
 138
 139
 140 =cut
 141
 142 sub start_document{
 143    my ($self,@args) = @_;
 144    $self->throw_not_implemented;
 145 }
 146
 147 =head2 end_document
 148
 149  Title   : end_document
 150  Usage   : $parser->end_document();
 151  Function: Receive notification of the end of a document (normally the
 152            input file of a parser). The parser will invoke this method
 153            only once, and it will be the last method invoked during
 154            the parse of the document. The parser shall not invoke this
 155            method until it has either abandoned parsing (because of an
 156            unrecoverable error) or reached the end of input.
 157
 158            Unlike the XML SAX signature of this method, this method is
 159            expected to return the object representing the result of
 160            parsing the document.
 161
 162  Returns : The object representing the result of parsing the input
 163            stream between the calls to start_document() and this method.
 164  Args    : none
 165
 166
 167 =cut
 168
 169 sub end_document{
 170    my ($self,@args) = @_;
 171    $self->throw_not_implemented;
 172 }
 173
 174 =head2 start_element
 175
 176  Title   : start_element
 177  Usage   : $parser->start_element
 178
 179  Function: Receive notification of the beginning of an element. The
 180            Parser will invoke this method at the beginning of every
 181            element in the input stream; there will be a corresponding
 182            end_element() event for every start_element() event (even when
 183            the element is empty). All of the element's content will be
 184            reported, in order, before the corresponding end_element()
 185            event.
 186
 187  Returns : none
 188  Args : A hashref with at least 2 keys: 'Data' and 'Name'. The value
 189         for 'Name' is expected to be the type of element being
 190         encountered; the understood values will depend on the IO
 191         parser to which this interface is being applied. Likewise, the
 192         value for 'Data' will be specific to event handler
 193         implementions, and the specific data chunking needs of input
 194         formats to be handled efficiently.
 195
 196
 197 =cut
 198
 199 sub start_element{
 200    my ($self,@args) = @_;
 201    $self->throw_not_implemented;
 202 }
 203
 204 =head2 end_element
 205
 206  Title   : end_element
 207  Usage   : $parser->end_element
 208
 209  Function: Receive notification of the end of an element. The parser
 210            will invoke this method at the end of every element in the
 211            input stream; there will be a corresponding start_element()
 212            event for every end_element() event (even when the element
 213            is empty).
 214
 215  Returns : none
 216
 217  Args    : hashref with at least 2 keys, 'Data' and 'Name'. The semantics
 218            are the same as for start_element().
 219
 220
 221 =cut
 222
 223 sub end_element{
 224    my ($self,@args) = @_;
 225    $self->throw_not_implemented;
 226 }
 227
 228
 229 =head2 in_element
 230
 231  Title   : in_element
 232  Usage   : if( $handler->in_element($element) ) {}
 233
 234  Function: Test if we are in a particular element.
 235
 236            Normally, in_element() will test for particular attributes,
 237            or nested elements, within a containing
 238            element. Conversely, the containing element can be queries
 239            with within_element(). The names understood as argument
 240            should be the same as the ones understood for the 'Name'
 241            key in start_element() and end_element().
 242
 243            Typically, handler implementations will call this method
 244            from within the characters() method to determine the
 245            context of the data that were passed to characters().
 246
 247  Returns : boolean
 248
 249  Args    : A string, the name of the element (normally an attribute name or nested sub-element name).
 250
 251 =cut
 252
 253 sub in_element{
 254    my ($self,@args) = @_;
 255    $self->throw_not_implemented;
 256
 257 }
 258
 259 =head2 within_element
 260
 261  Title   : within_element
 262  Usage   : if( $handler->within_element($element) ) {}
 263
 264  Function: Test if we are within a particular kind of element.
 265
 266            Normally, the element type names understood as argument
 267            values will be for containing elements or data
 268            chunks. Conversely, in_element() can be used to test
 269            whether an attribute or nested element is the ccurrent
 270            context.
 271
 272            Typically, a handler will call this method from within the
 273            characters() method to determine the context for the data
 274            that were passed to characters().
 275
 276  Returns : boolean
 277  Args    : string element name
 278
 279
 280 =cut
 281
 282 sub within_element{
 283    my ($self,@args) = @_;
 284    $self->throw_not_implemented;
 285 }
 286
 287 =head2 characters
 288
 289  Title   : characters
 290  Usage   : $parser->characters($str)
 291  Function: Receive notification of character data. The parser will
 292            call this method to report values of attributes, or larger
 293            data chunks, depending on the IO subsystem and event
 294            handler implementation. Values may be whitespace-padded
 295            even if the whitespace is insignificant for the format.
 296
 297            The context of the character data being passed can be
 298            determined by calling the in_element() and within_element()
 299            methods.
 300
 301  Returns : none
 302  Args    : string, the character data
 303
 304
 305 =cut
 306
 307 sub characters{
 308    my ($self,@args) = @_;
 309    $self->throw_not_implemented;
 310 }
 311
 312 1;