.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Bio::HandlerBaseI 3pm"
.TH Bio::HandlerBaseI 3pm "2021-08-15" "perl v5.32.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Bio::HandlerBaseI \- Interface class for handler methods which interact with any
event\-driven parsers (drivers).
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  # MyHandler is a Bio::HandlerBaseI\-derived class for dealing with GenBank
\&  # sequence data, derived from a GenBank event\-driven parser
\&
\&  # inside a parser (driver) constructor
\&
\&  $self\->seqhandler($handler || MyHandler\->new(\-format => \*(Aqgenbank\*(Aq));
\&
\&  # in the driver parsing method ( such as next_seq() ) ...
\&
\&  $handler = $self\->seqhandler();
\&
\&  # roll data up into hashref chunks, pass off into Handler for processing...
\&
\&  $hobj\->data_handler($data);
\&
\&  # or retrieve Handler methods and pass data directly to Handler methods
\&
\&  my $hmeth = $hobj\->handler_methods;
\&
\&  if ($hmeth\->{ $data\->{NAME} }) {
\&      my $mth = $hmeth\->{ $data\->{NAME} }; # code ref
\&      $hobj\->$mth($data);
\&  }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This interface describes simple class methods used for processing data from an
event-based parser (a driver). This is similar in theme to an \s-1XML\s0 SAX-based
driver but differs in that one can optionally pass related data
semi-intelligently as chunks (defined in a hash reference) vs. passing as single
data elements in a stream. For instance, any reference-related and
species-related data as well as individual sequence features could be passed as
chunks of data to be processed in part or as a whole (from Data::Dumper output):
.PP
Annotation Data (References):
.PP
.Vb 7
\&  $VAR1 = {
\&          \*(AqNAME\*(Aq => \*(AqREFERENCE\*(Aq,
\&          \*(AqDATA\*(Aq => \*(Aq1  (bases 1 to 10001)\*(Aq
\&          \*(AqAUTHORS\*(Aq => \*(AqInternational Human Genome Sequencing Consortium.\*(Aq
\&          \*(AqTITLE\*(Aq => \*(AqThe DNA sequence of Homo sapiens\*(Aq
\&          \*(AqJOURNAL\*(Aq => \*(AqUnpublished (2003)\*(Aq
\&          };
.Ve
.PP
Sequence features (source seqfeature):
.PP
.Vb 10
\&  $VAR1 = {
\&          \*(Aqmol_type\*(Aq => \*(Aqgenomic DNA\*(Aq,
\&          \*(AqLOCATION\*(Aq => \*(Aq<1..>10001\*(Aq,
\&          \*(AqNAME\*(Aq => \*(AqFEATURES\*(Aq,
\&          \*(AqFEATURE_KEY\*(Aq => \*(Aqsource\*(Aq,
\&          \*(Aqnote\*(Aq => \*(AqAccession AL451081 sequenced by The Sanger Centre\*(Aq,
\&          \*(Aqdb_xref\*(Aq => \*(Aqtaxon:9606\*(Aq,
\&          \*(Aqclone\*(Aq => \*(AqRP11\-302I18\*(Aq,
\&          \*(Aqorganism\*(Aq => \*(AqHomo sapiens\*(Aq
\&          };
.Ve
.PP
These would be 'handled' accordingly by methods specified in a
HandlerI-based class. The data in a chunk is intentionally left vague
here since this may vary from implementation to implementation and can
be somewhat open to interpretation. A data chunk in a sequence record,
for instance, will be different than a data chunk in a \s-1BLAST\s0
report. This also allows one the flexibility to pass data as more
XML-like small bits, as huge chunks, or even as indexed locations in a
file (such as when using a \*(L"pull\*(R" parser, like a Bio::PullParserI).
.PP
For an sequence-based implementation see
Bio::SeqIO::RichSeq::GenericRichSeqHandler, which handles any GenBank,
UniProt, and \s-1EMBL\s0 data from their respective driver modules
(Bio::SeqIO::gbdriver, Bio::SeqIO::swissdriver, and
Bio::SeqIO::embldriver).
.SH "FEEDBACK"
.IX Header "FEEDBACK"
.SS "Mailing Lists"
.IX Subsection "Mailing Lists"
User feedback is an integral part of the evolution of this and other
Bioperl modules. Send your comments and suggestions preferably to one
of the Bioperl mailing lists.  Your participation is much appreciated.
.PP
.Vb 2
\&  bioperl\-l@bioperl.org                  \- General discussion
\&  http://bioperl.org/wiki/Mailing_lists  \- About the mailing lists
.Ve
.SS "Support"
.IX Subsection "Support"
Please direct usage questions or support issues to the mailing list:
.PP
\&\fIbioperl\-l@bioperl.org\fR
.PP
rather than to the module maintainer directly. Many experienced and 
reponsive experts will be able look at the problem and quickly 
address it. Please include a thorough description of the problem 
with code and data examples if at all possible.
.SS "Reporting Bugs"
.IX Subsection "Reporting Bugs"
Report bugs to the Bioperl bug tracking system to help us keep track
the bugs and their resolution.  Bug reports can be submitted via the
web:
.PP
.Vb 1
\&  https://github.com/bioperl/bioperl\-live/issues
.Ve
.SH "AUTHOR \- Chris Fields"
.IX Header "AUTHOR - Chris Fields"
Email cjfields at bioperl dot org
.SH "APPENDIX"
.IX Header "APPENDIX"
The rest of the documentation details each of the object methods. Internal
methods are usually preceded with a _
.SS "data_handler"
.IX Subsection "data_handler"
.Vb 5
\& Title   :  data_handler
\& Usage   :  $handler\->data_handler($data)
\& Function:  Centralized method which accepts all data chunks, then distributes
\&            to the appropriate methods for processing based on the chunk name
\&            from within the HandlerBaseI object.
\&
\&            One can also use
\& Returns :  None
\& Args    :  an hash ref containing a data chunk.
.Ve
.SS "handler_methods"
.IX Subsection "handler_methods"
.Vb 11
\& Title   :  handler_methods
\& Usage   :  $handler\->handler_methods(\*(AqGenBank\*(Aq)
\&            %handlers = $handler\->handler_methods();
\& Function:  Retrieve the handler methods used for the current format() in
\&            the handler.  This assumes the handler methods are already
\&            described in the HandlerI\-implementing class.
\& Returns :  a hash reference with the data type handled and the code ref
\&            associated with it.
\& Args    :  [optional] String representing the sequence format.  If set here
\&            this will also set sequence_format()
\& Throws  :  On unimplemented sequence format in %HANDLERS
.Ve
.SS "format"
.IX Subsection "format"
.Vb 10
\& Title   :  format
\& Usage   :  $handler\->format(\*(AqGenBank\*(Aq)
\&            $handler\->format(\*(AqBLAST\*(Aq)
\& Function:  Get/Set the format for the report/record being parsed. This can be
\&            used to set handlers in classes which are capable of processing
\&            similar data chunks from multiple driver modules.
\& Returns :  String with the sequence format
\& Args    :  [optional] String with the sequence format
\& Note    :  The format may be used to set the handlers (as in the
\&            current GenericRichSeqHandler implementation)
.Ve
.SS "get_params"
.IX Subsection "get_params"
.Vb 8
\& Title   :  get_params
\& Usage   :  $handler\->get_params(\*(Aq\-species\*(Aq)
\& Function:  Convenience method used to retrieve the specified
\&            parameters from the internal parameter cache
\& Returns :  Hash ref containing parameters requested and data as
\&            key\-value pairs.  Note that some parameter values may be
\&            objects, arrays, etc.
\& Args    :  List (array) representing the parameters requested
.Ve
.SS "set_params"
.IX Subsection "set_params"
.Vb 8
\& Title   :  set_params
\& Usage   :  $handler\->set_params({
\&                                \*(Aq\-species\*(Aq => $species,
\&                                \*(Aq\-accession_number\*(Aq => $acc
\&                                });
\& Function:  Convenience method used to set specific parameters
\& Returns :  None
\& Args    :  Hash ref containing the data to be passed as key\-value pairs
.Ve
.SS "reset_parameters"
.IX Subsection "reset_parameters"
.Vb 6
\& Title   :  reset_parameters
\& Usage   :  $handler\->reset_parameters()
\& Function:  Resets the internal cache of data (normally object parameters for
\&            a builder or factory)
\& Returns :  None
\& Args    :  None
.Ve