.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" 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::PullParserI 3pm"
.TH Bio::PullParserI 3pm "2020-10-28" "perl v5.30.3" "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::PullParserI \- A base module for fast 'pull' parsing
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&    # do not use this class, it is intended for parser module
\&    # writers only
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
If you are writing a module to parse some new format, you may wish to use
a 'pull' approach whereby you only do work (reading file data, parsing it,
turning the parsed data in an object) when absolutely necessary.
.PP
PullParserI provides a system for doing exactly that. As a PullParser you
need a chunk. A chunk is just a Bio::Root::IO that contains all the raw data
you would want to parse. You can use the \fBchunk()\fR method to create a chunk from
a filename, existing filehandle or even a string. If you make a chunk from a
large file, but actually only want your chunk to be some portion of the whole
file, supply start and end amounts in bytes to \fBchunk()\fR at the same time.
The methods \fB_chunk_seek()\fR and \fB_chunk_tell()\fR provide seeks and tells that are
relative to the start and end of your chunk, not the whole file.
.PP
The other thing you will need to decide when making a chunk is how to handle
piped input. A PullParser typically needs seekable data to parse, so if your
data is piped in and unseekable, you must decide between creating a temp file
or reading the input into memory, which will be done before the chunk becomes
usable and you can begin any parsing. Alternatively you can choose to force
a sequential read, in which case you can make use of \fB_dependencies()\fR to define
the linear order of methods that would result in the file being read
sequentially. The return value of \fB_sequential()\fR is also useful here, if you
would need to cache some data or otherwise behave differently during a
sequential read.
.PP
The main method in the system is \fBget_field()\fR. This method relies on the
existence of a private hash reference accessible to it with the method
\&\fB_fields()\fR. That hash ref should have as keys all the sorts of data you will want
to parse (eg. 'score'), and prior to parsing the values would be undefined. A
user of your module can then call either \f(CW$module\fR\->get_field('score') or
\&\f(CW$module\fR\->score and get_field will either return the answer from
\&\f(CW$self\fR\->_fields\->{score} if it is defined, or call a method \fB_discover_score()\fR
first if not. So for the system to work you need to define a _discover_*()
method for every field in the fields hash, and ensure that the method stores an
answer in the fields hash.
.PP
How you implement your _discover_* methods is up to you, though you should never
call a _discover_* method directly yourself; always use \fBget_field()\fR, since
\&\fBget_field()\fR will deal with calling dependent methods for you if a forced
sequenctial read is in progress due to piped input. You will almost certainly
want to make use of the various chunk-related methods of this class (that are
denoted private by the leading '_'; this means you can use them as the author of
a parser class, but users of your parser should not).
.PP
Primary amongst them is _*\fB_chunk_by_end()\fR to which you provide text that
represents the end of your desired chunk and it does a readline with your
argument as $/. The chunk knows about its line-endings, so if you want your
end definition to include a new line, just always use \*(L"\en\*(R" and PullParserI will
do any necessary conversion for you.
.PP
If your input data is hierarchical (eg. report\->many results\->many hits\->many
hsps), and you want an object at the leaf of the hierarchy to have access to
information that is shared amongst all of them (is parsed in the root), you
don't have to copy the data to each leaf object; simply by defining \fBparent()\fR,
when you call \fBget_field()\fR and the requested field isn't in your leaf's fields
hash, the leaf's parent will be asked for the field instead, and so on till
root.
.PP
See Bio::SearchIO::hmmer_pull for an example of implementing a parser using
PullParserI.
.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
the Bioperl mailing list.  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
of 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 \- Sendu Bala"
.IX Header "AUTHOR - Sendu Bala"
Email bix@sendu.me.uk
.SH "CONTRIBUTORS"
.IX Header "CONTRIBUTORS"
Inspired by a posting by Aaron J. Mackey
.SH "APPENDIX"
.IX Header "APPENDIX"
The rest of the documentation details each of the object methods.
Internal methods are usually preceded with a _
.SS "_fields"
.IX Subsection "_fields"
.Vb 6
\& Title   : _fields
\& Usage   : $obj\->_fields( { field1 => undef } );
\&           my $fields_ref = $obj\->_fields;
\& Function: Get/set the hash reference containing all the fields for this parser
\& Returns : hash ref
\& Args    : none to get, OR hash ref to set
.Ve
.SS "has_field"
.IX Subsection "has_field"
.Vb 5
\& Title   : has_field
\& Usage   : if ($obj\->has_field(\*(Aqfield_name\*(Aq) {...}
\& Function: Ask if a particular object has a given field (doesn\*(Aqt ask ancestors)
\& Returns : boolean
\& Args    : string (the field name to test)
.Ve
.SS "get_field"
.IX Subsection "get_field"
.Vb 8
\& Title   : get_field
\& Usage   : my $field_value = $obj\->get_field(\*(Aqfield_name\*(Aq);
\& Function: Get the value of a given field. If this $obj doesn\*(Aqt have the field,
\&           it\*(Aqs parent() will be asked, and so on until there are no more
\&           parents.
\& Returns : scalar, warns if a value for the field couldn\*(Aqt be found and returns
\&           undef.
\& Args    : string (the field to get)
.Ve
.SS "parent"
.IX Subsection "parent"
.Vb 6
\& Title   : parent
\& Usage   : $obj\->parent($parent_obj);
\&           my $parent_obj = $obj\->parent;
\& Function: Get/set the parent object of this one.
\& Returns : Bio::PullParserI
\& Args    : none to get, OR Bio::PullParserI to set
.Ve
.SS "chunk"
.IX Subsection "chunk"
.Vb 10
\& Title   : chunk
\& Usage   : $obj\->chunk($filename);
\&           my $chunk = $obj\->chunk;
\& Function: Get/set the chunk of this parser.
\& Returns : Bio:Root::IO
\& Args    : none to get, OR
\&           First argument of a GLOB reference, filename string, string data to
\&           treat as the chunk, or Bio::Root::IO.
\&           Optionally, also provide:
\&           \-start => int : the byte position within the thing described by the
\&                           first argument to consider as the start of this
\&                           chunk (default 0)
\&           \-end   => int : the byte position to consider as the end (default
\&                           true end)
\&           \-piped_behaviour => \*(Aqmemory\*(Aq|\*(Aqtemp_file\*(Aq|\*(Aqsequential_read\*(Aq
\&
\&           The last option comes into effect when the first argument is
\&           something that cannot be seeked (eg. piped input filehandle).
\&            \*(Aqmemory\*(Aq          means read all the piped input into a string
\&                              first, then set the chunk to that string.
\&            \*(Aqtemp_file\*(Aq       means read all the piped input and output it to
\&                              a temp file, then set the chunk to that temp file.
\&            \*(Aqsequential_read\*(Aq means that the piped input should be read
\&                              sequentially and your parsing code must cope with
\&                              not being able to seek.
\&           \*(Aqmemory\*(Aq is the fastest but uses the most memory. \*(Aqtemp_file\*(Aq and
\&           \*(Aqsequential_read\*(Aq can be slow, with \*(Aqtemp_file\*(Aq being the most memory
\&           efficient but requiring disc space. The default is \*(Aqsequential_read\*(Aq.
\&           Note that in versions of perl earlier than 5.8 only temp_file works
\&           and will be used regardless of what value is supplied here.
.Ve
.SS "_sequential"
.IX Subsection "_sequential"
.Vb 7
\& Title   : _sequential
\& Usage   : if ($obj\->_sequential) {...}
\& Function: Ask if we have to do operations such that the input is read
\&           sequentially.
\& Returns : boolean
\& Args    : none to get, OR boolean to set (typically, you should never set this
\&           yourself)
.Ve
.SS "_dependencies"
.IX Subsection "_dependencies"
.Vb 9
\& Title   : _dependencies
\& Usage   : $obj\->_dependencies( { field1 => field2 } );
\&           my $dependancy = $obj\->_dependencies(\*(Aqfield_name\*(Aq);
\& Function: Set the fields that are dependent on each other, or get the field
\&           than another is dependent upon.
\& Returns : string (a field name)
\& Args    : string (a field name) to get, OR hash ref to initially set, with
\&           field names as keys and values, key field being dependent upon value
\&           field.
.Ve
.SS "_chunk_true_start"
.IX Subsection "_chunk_true_start"
.Vb 6
\& Title   : _chunk_true_start
\& Usage   : my $true_start = $obj\->_chunk_true_start;
\& Function: Get/set the true start position of the chunk within the filehandle
\&           it is part of.
\& Returns : int
\& Args    : none to get, OR int to set (typically, you won\*(Aqt set this yourself)
.Ve
.SS "_chunk_true_end"
.IX Subsection "_chunk_true_end"
.Vb 6
\& Title   : _chunk_true_end
\& Usage   : my $true_end = $obj\->_chunk_true_end;
\& Function: Get/set for the true end position of the chunk within the filehandle
\&           it is part of.
\& Returns : int
\& Args    : none to get, OR int to set (typically, you won\*(Aqt set this yourself)
.Ve
.SS "_line_ending"
.IX Subsection "_line_ending"
.Vb 6
\& Title   : _line_ending
\& Usage   : my $line_ending = $obj\->_line_ending;
\& Function: Get/set for the line ending for the chunk.
\& Returns : string
\& Args    : none to get, OR string to set (typically, you won\*(Aqt set this
\&           yourself)
.Ve
.SS "_chunk_seek"
.IX Subsection "_chunk_seek"
.Vb 4
\& Title   : _chunk_seek
\& Usage   : $obj\->_chunk_seek($pos);
\& Function: seek() the chunk to the provided position in bytes, relative to the
\&           defined start of the chunk within its filehandle.
\&
\&           In _sequential() mode, this function does nothing.
\&
\& Returns : n/a
\& Args    : int
.Ve
.SS "_chunk_tell"
.IX Subsection "_chunk_tell"
.Vb 4
\& Title   : _chunk_seek
\& Usage   : my $pos = $obj\->_chunk_tell;
\& Function: Get the current tell() position within the chunk, relative to the
\&           defined start of the chunk within its filehandle.
\&
\&           In _sequential() mode, this function does nothing.
\&
\& Returns : int
\& Args    : none
.Ve
.SS "_get_chunk_by_nol"
.IX Subsection "_get_chunk_by_nol"
.Vb 6
\& Title   : _chunk_seek
\& Usage   : my $string = $obj\->_get_chunk_by_nol;
\& Function: Get a chunk of chunk() from the current position onward for the given
\&           number of lines.
\& Returns : string
\& Args    : int (number of lines you want)
.Ve
.SS "_get_chunk_by_end"
.IX Subsection "_get_chunk_by_end"
.Vb 7
\& Title   : _get_chunk_by_end
\& Usage   : my $string = $obj\->_get_chunk_by_end;
\& Function: Get a chunk of chunk() from the current position onward till the end
\&           of the line, as defined by the supplied argument.
\& Returns : string
\& Args    : string (line ending \- if you want the line ending to include a new
\&           line, always use \en)
.Ve
.SS "_find_chunk_by_end"
.IX Subsection "_find_chunk_by_end"
.Vb 5
\& Title   : _find_chunk_by_end
\& Usage   : my $string = $obj\->_find_chunk_by_end;
\& Function: Get the start and end of what would be a chunk of chunk() from the
\&           current position onward till the end of the line, as defined by the
\&           supplied argument.
\&
\&           In _sequential() mode, this function does nothing.
\&
\& Returns : _chunk_tell values for start and end in 2 element list
\& Args    : string (line ending \- if you want the line ending to include a new
\&           line, always use \en)
.Ve
.SS "\s-1AUTOLOAD\s0"
.IX Subsection "AUTOLOAD"
.Vb 6
\& Title   : AUTOLOAD
\& Usage   : n/a
\& Function: Assumes that any unknown method called should be treated as
\&           get_field($method_name).
\& Returns : n/a
\& Args    : n/a
.Ve