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 use strict;
 100 use Carp;
 101
 102 use base qw(Bio::Root::RootI);
 103
 104 =head2 will_handle
 105
 106  Title   : will_handle
 107  Usage   : if( $handler->will_handle($event_type) ) { ... }
 108  Function: Tests if this event builder knows how to process a specific event
 109  Returns : boolean
 110  Args    : event type name
 111
 112
 113 =cut
 114
 115 sub will_handle{
 116    my ($self,$type) = @_;
 117    $self->throw_not_implemented();
 118 }
 119
 120 =head2 SAX methods
 121
 122 =cut
 123
 124 =head2 start_document
 125
 126  Title   : start_document
 127  Usage   : $resultObj = $parser->start_document();
 128  Function: Receive notification of the beginning of a document (the
 129            input file of a parser). The parser will invoke this method
 130            only once, before any other event callbacks.
 131
 132            Usually, a handler will reset any internal state structures
 133            when this method is called.
 134
 135  Returns : none
 136  Args    : none
 137
 138
 139 =cut
 140
 141 sub start_document{
 142    my ($self,@args) = @_;
 143    $self->throw_not_implemented;
 144 }
 145
 146 =head2 end_document
 147
 148  Title   : end_document
 149  Usage   : $parser->end_document();
 150  Function: Receive notification of the end of a document (normally the
 151            input file of a parser). The parser will invoke this method
 152            only once, and it will be the last method invoked during
 153            the parse of the document. The parser shall not invoke this
 154            method until it has either abandoned parsing (because of an
 155            unrecoverable error) or reached the end of input.
 156
 157            Unlike the XML SAX signature of this method, this method is
 158            expected to return the object representing the result of
 159            parsing the document.
 160
 161  Returns : The object representing the result of parsing the input
 162            stream between the calls to start_document() and this method.
 163  Args    : none
 164
 165
 166 =cut
 167
 168 sub end_document{
 169    my ($self,@args) = @_;
 170    $self->throw_not_implemented;
 171 }
 172
 173 =head2 start_element
 174
 175  Title   : start_element
 176  Usage   : $parser->start_element
 177
 178  Function: Receive notification of the beginning of an element. The
 179            Parser will invoke this method at the beginning of every
 180            element in the input stream; there will be a corresponding
 181            end_element() event for every start_element() event (even when
 182            the element is empty). All of the element's content will be
 183            reported, in order, before the corresponding end_element()
 184            event.
 185
 186  Returns : none
 187  Args : A hashref with at least 2 keys: 'Data' and 'Name'. The value
 188         for 'Name' is expected to be the type of element being
 189         encountered; the understood values will depend on the IO
 190         parser to which this interface is being applied. Likewise, the
 191         value for 'Data' will be specific to event handler
 192         implementions, and the specific data chunking needs of input
 193         formats to be handled efficiently.
 194
 195
 196 =cut
 197
 198 sub start_element{
 199    my ($self,@args) = @_;
 200    $self->throw_not_implemented;
 201 }
 202
 203 =head2 end_element
 204
 205  Title   : end_element
 206  Usage   : $parser->end_element
 207
 208  Function: Receive notification of the end of an element. The parser
 209            will invoke this method at the end of every element in the
 210            input stream; there will be a corresponding start_element()
 211            event for every end_element() event (even when the element
 212            is empty).
 213
 214  Returns : none
 215
 216  Args    : hashref with at least 2 keys, 'Data' and 'Name'. The semantics
 217            are the same as for start_element().
 218
 219
 220 =cut
 221
 222 sub end_element{
 223    my ($self,@args) = @_;
 224    $self->throw_not_implemented;
 225 }
 226
 227
 228 =head2 in_element
 229
 230  Title   : in_element
 231  Usage   : if( $handler->in_element($element) ) {}
 232
 233  Function: Test if we are in a particular element.
 234
 235            Normally, in_element() will test for particular attributes,
 236            or nested elements, within a containing
 237            element. Conversely, the containing element can be queries
 238            with within_element(). The names understood as argument
 239            should be the same as the ones understood for the 'Name'
 240            key in start_element() and end_element().
 241
 242            Typically, handler implementations will call this method
 243            from within the characters() method to determine the
 244            context of the data that were passed to characters().
 245
 246  Returns : boolean
 247
 248  Args    : A string, the name of the element (normally an attribute name or nested sub-element name).
 249
 250 =cut
 251
 252 sub in_element{
 253    my ($self,@args) = @_;
 254    $self->throw_not_implemented;
 255
 256 }
 257
 258 =head2 within_element
 259
 260  Title   : within_element
 261  Usage   : if( $handler->within_element($element) ) {}
 262
 263  Function: Test if we are within a particular kind of element.
 264
 265            Normally, the element type names understood as argument
 266            values will be for containing elements or data
 267            chunks. Conversely, in_element() can be used to test
 268            whether an attribute or nested element is the ccurrent
 269            context.
 270
 271            Typically, a handler will call this method from within the
 272            characters() method to determine the context for the data
 273            that were passed to characters().
 274
 275  Returns : boolean
 276  Args    : string element name
 277
 278
 279 =cut
 280
 281 sub within_element{
 282    my ($self,@args) = @_;
 283    $self->throw_not_implemented;
 284 }
 285
 286 =head2 characters
 287
 288  Title   : characters
 289  Usage   : $parser->characters($str)
 290  Function: Receive notification of character data. The parser will
 291            call this method to report values of attributes, or larger
 292            data chunks, depending on the IO subsystem and event
 293            handler implementation. Values may be whitespace-padded
 294            even if the whitespace is insignificant for the format.
 295
 296            The context of the character data being passed can be
 297            determined by calling the in_element() and within_element()
 298            methods.
 299
 300  Returns : none
 301  Args    : string, the character data
 302
 303
 304 =cut
 305
 306 sub characters{
 307    my ($self,@args) = @_;
 308    $self->throw_not_implemented;
 309 }
 310
 311 1;