.\" 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::Seq::SeqBuilder 3pm"
.TH Bio::Seq::SeqBuilder 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::Seq::SeqBuilder \- Configurable object builder for sequence stream parsers
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&   use Bio::SeqIO;
\&
\&   # usually you won\*(Aqt instantiate this yourself \- a SeqIO object \-
\&   # you will have one already
\&   my $seqin = Bio::SeqIO\->new(\-fh => \e*STDIN, \-format => "genbank");
\&   my $builder = $seqin\->sequence_builder();
\&
\&   # if you need only sequence, id, and description (e.g. for 
\&   # conversion to FASTA format):
\&   $builder\->want_none();
\&   $builder\->add_wanted_slot(\*(Aqdisplay_id\*(Aq,\*(Aqdesc\*(Aq,\*(Aqseq\*(Aq);
\&
\&   # if you want everything except the sequence and features
\&   $builder\->want_all(1); # this is the default if it\*(Aqs untouched
\&   $builder\->add_unwanted_slot(\*(Aqseq\*(Aq,\*(Aqfeatures\*(Aq);
\&
\&   # if you want only human sequences shorter than 5kb and skip all
\&   # others
\&   $builder\->add_object_condition(sub {
\&       my $h = shift;
\&       return 0 if $h\->{\*(Aq\-length\*(Aq} > 5000;
\&       return 0 if exists($h\->{\*(Aq\-species\*(Aq}) &&
\&                   ($h\->{\*(Aq\-species\*(Aq}\->binomial() ne "Homo sapiens");
\&       return 1;
\&   });
\&
\&   # when you are finished with configuring the builder, just use
\&   # the SeqIO API as you would normally
\&   while(my $seq = $seqin\->next_seq()) {
\&       # do something
\&   }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This is an implementation of Bio::Factory::ObjectBuilderI used by
parsers of rich sequence streams. It provides for a relatively
easy-to-use configurator of the parsing flow.
.PP
Configuring the parsing process may be for you if you need much less
information, or much less sequence, than the stream actually
contains. Configuration can in both cases speed up the parsing time
considerably, because unwanted sections or the rest of unwanted
sequences are skipped over by the parser. This configuration could
also conserve memory if you're running out of available \s-1RAM.\s0
.PP
See the methods of the class-specific implementation section for
further documentation of what can be configured.
.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 \- Hilmar Lapp"
.IX Header "AUTHOR - Hilmar Lapp"
Email hlapp at gmx.net
.SH "APPENDIX"
.IX Header "APPENDIX"
The rest of the documentation details each of the object methods.
Internal methods are usually preceded with a _
.SS "new"
.IX Subsection "new"
.Vb 5
\& Title   : new
\& Usage   : my $obj = Bio::Seq::SeqBuilder\->new();
\& Function: Builds a new Bio::Seq::SeqBuilder object 
\& Returns : an instance of Bio::Seq::SeqBuilder
\& Args    :
.Ve
.SH "Methods for implementing Bio::Factory::ObjectBuilderI"
.IX Header "Methods for implementing Bio::Factory::ObjectBuilderI"
.SS "want_slot"
.IX Subsection "want_slot"
.Vb 4
\& Title   : want_slot
\& Usage   :
\& Function: Whether or not the object builder wants to populate the
\&           specified slot of the object to be built.
\&
\&           The slot can be specified either as the name of the
\&           respective method, or the initialization parameter that
\&           would be otherwise passed to new() of the object to be
\&           built.
\&
\&           Note that usually only the parser will call this
\&           method. Use add_wanted_slots and add_unwanted_slots for
\&           configuration.
\&
\& Example :
\& Returns : TRUE if the object builder wants to populate the slot, and
\&           FALSE otherwise.
\& Args    : the name of the slot (a string)
.Ve
.SS "add_slot_value"
.IX Subsection "add_slot_value"
.Vb 4
\& Title   : add_slot_value
\& Usage   :
\& Function: Adds one or more values to the specified slot of the object
\&           to be built.
\&
\&           Naming the slot is the same as for want_slot().
\&
\&           The object builder may further filter the content to be
\&           set, or even completely ignore the request.
\&
\&           If this method reports failure, the caller should not add
\&           more values to the same slot. In addition, the caller may
\&           find it appropriate to abandon the object being built
\&           altogether.
\&
\&           This implementation will allow the caller to overwrite the
\&           return value from want_slot(), because the slot is not
\&           checked against want_slot().
\&
\&           Note that usually only the parser will call this method,
\&           but you may call it from anywhere if you know what you are
\&           doing. A derived class may be used to further manipulate
\&           the value to be added.
\&
\& Example :
\& Returns : TRUE on success, and FALSE otherwise
\& Args    : the name of the slot (a string)
\&           parameters determining the value to be set
\&
\&                 OR
\&
\&           alternatively, a list of slotname/value pairs in the style
\&           of named parameters as they would be passed to new(), where
\&           each element at an even index is the parameter (slot) name
\&           starting with a dash, and each element at an odd index is
\&           the value of the preceding name.
.Ve
.SS "want_object"
.IX Subsection "want_object"
.Vb 4
\& Title   : want_object
\& Usage   :
\& Function: Whether or not the object builder is still interested in
\&           continuing with the object being built.
\&
\&           If this method returns FALSE, the caller should not add any
\&           more values to slots, or otherwise risks that the builder
\&           throws an exception. In addition, make_object() is likely
\&           to return undef after this method returned FALSE.
\&
\&           Note that usually only the parser will call this
\&           method. Use add_object_condition for configuration.
\&
\& Example :
\& Returns : TRUE if the object builder wants to continue building
\&           the present object, and FALSE otherwise.
\& Args    : none
.Ve
.SS "make_object"
.IX Subsection "make_object"
.Vb 3
\& Title   : make_object
\& Usage   :
\& Function: Get the built object.
\&
\&           This method is allowed to return undef if no value has ever
\&           been added since the last call to make_object(), or if
\&           want_object() returned FALSE (or would have returned FALSE)
\&           before calling this method.
\&
\&           For an implementation that allows consecutive building of
\&           objects, a caller must call this method once, and only
\&           once, between subsequent objects to be built. I.e., a call
\&           to make_object implies \*(Aqend_object.\*(Aq
\&
\& Example :
\& Returns : the object that was built
\& Args    : none
.Ve
.SH "Implementation specific methods"
.IX Header "Implementation specific methods"
These methods allow one to conveniently configure this sequence object
builder as to which slots are desired, and under which circumstances a
sequence object should be abandoned altogether. The default mode is
\&\fBwant_all\fR\|(1), which means the builder will report all slots as wanted
that the object created by the sequence factory supports.
.PP
You can add specific slots you want through \fBadd_wanted_slots()\fR. In
most cases, you will want to call \fBwant_none()\fR before in order to relax
zero acceptance through a list of wanted slots.
.PP
Alternatively, you can add specific unwanted slots through
\&\fBadd_unwanted_slots()\fR. In this case, you will usually want to call
\&\fBwant_all\fR\|(1) before (which is the default if you never touched the
builder) to restrict unrestricted acceptance.
.PP
I.e., \fBwant_all\fR\|(1) means want all slots except for the unwanted, and
\&\fBwant_none()\fR means only those explicitly wanted.
.PP
If a slot is in both the unwanted and the wanted list, the following
rules hold. In want-all mode, the unwanted list overrules. In
want-none mode, the wanted list overrides the unwanted list. If this
is confusing to you, just try to avoid having slots at the same time
in the wanted and the unwanted lists.
.SS "get_wanted_slots"
.IX Subsection "get_wanted_slots"
.Vb 6
\& Title   : get_wanted_slots
\& Usage   : $obj\->get_wanted_slots($newval)
\& Function: Get the list of wanted slots
\& Example : 
\& Returns : a list of strings
\& Args    :
.Ve
.SS "add_wanted_slot"
.IX Subsection "add_wanted_slot"
.Vb 6
\& Title   : add_wanted_slot
\& Usage   :
\& Function: Adds the specified slots to the list of wanted slots.
\& Example :
\& Returns : TRUE
\& Args    : an array of slot names (strings)
.Ve
.SS "remove_wanted_slots"
.IX Subsection "remove_wanted_slots"
.Vb 7
\& Title   : remove_wanted_slots
\& Usage   :
\& Function: Removes all wanted slots added previously through
\&           add_wanted_slots().
\& Example :
\& Returns : the previous list of wanted slot names
\& Args    : none
.Ve
.SS "get_unwanted_slots"
.IX Subsection "get_unwanted_slots"
.Vb 6
\& Title   : get_unwanted_slots
\& Usage   : $obj\->get_unwanted_slots($newval)
\& Function: Get the list of unwanted slots.
\& Example : 
\& Returns : a list of strings
\& Args    : none
.Ve
.SS "add_unwanted_slot"
.IX Subsection "add_unwanted_slot"
.Vb 6
\& Title   : add_unwanted_slot
\& Usage   :
\& Function: Adds the specified slots to the list of unwanted slots.
\& Example :
\& Returns : TRUE
\& Args    : an array of slot names (strings)
.Ve
.SS "remove_unwanted_slots"
.IX Subsection "remove_unwanted_slots"
.Vb 7
\& Title   : remove_unwanted_slots
\& Usage   :
\& Function: Removes the list of unwanted slots added previously through
\&           add_unwanted_slots().
\& Example :
\& Returns : the previous list of unwanted slot names
\& Args    : none
.Ve
.SS "want_none"
.IX Subsection "want_none"
.Vb 4
\& Title   : want_none
\& Usage   :
\& Function: Disables all slots. After calling this method, want_slot()
\&           will return FALSE regardless of slot name.
\&
\&           This is different from removed_wanted_slots() in that it
\&           also sets want_all() to FALSE. Note that it also resets the
\&           list of unwanted slots in order to avoid slots being in
\&           both lists.
\&
\& Example :
\& Returns : TRUE
\& Args    : none
.Ve
.SS "want_all"
.IX Subsection "want_all"
.Vb 7
\& Title   : want_all
\& Usage   : $obj\->want_all($newval)
\& Function: Whether or not this sequence object builder wants to
\&           populate all slots that the object has. Whether an object
\&           supports a slot is generally determined by what can()
\&           returns. You can add additional \*(Aqvirtual\*(Aq slots by calling
\&           add_wanted_slot.
\&
\&           This will be ON by default. Call $obj\->want_none() to
\&           disable all slots.
\&
\& Example : 
\& Returns : TRUE if this builder wants to populate all slots, and
\&           FALSE otherwise.
\& Args    : on set, new value (a scalar or undef, optional)
.Ve
.SS "get_object_conditions"
.IX Subsection "get_object_conditions"
.Vb 4
\& Title   : get_object_conditions
\& Usage   :
\& Function: Get the list of conditions an object must meet in order to
\&           be \*(Aqwanted.\*(Aq See want_object() for where this is used.
\&
\&           Conditions in this implementation are closures (anonymous
\&           functions) which are passed one parameter, a hash reference
\&           the keys of which are equal to initialization
\&           parameters. The closure must return TRUE to make the object
\&           \*(Aqwanted.\*(Aq
\&
\&           Conditions will be implicitly ANDed.
\&
\& Example :
\& Returns : a list of closures
\& Args    : none
.Ve
.SS "add_object_condition"
.IX Subsection "add_object_condition"
.Vb 4
\& Title   : add_object_condition
\& Usage   :
\& Function: Adds a condition an object must meet in order to be \*(Aqwanted.\*(Aq
\&           See want_object() for where this is used.
\&
\&           Conditions in this implementation must be closures
\&           (anonymous functions). These will be passed one parameter,
\&           which is a hash reference with the sequence object
\&           initialization parameters being the keys.
\&
\&           Conditions are implicitly ANDed. If you want other
\&           operators, perform those tests inside of one closure
\&           instead of multiple.  This will also be more efficient.
\&
\& Example :
\& Returns : TRUE
\& Args    : the list of conditions
.Ve
.SS "remove_object_conditions"
.IX Subsection "remove_object_conditions"
.Vb 7
\& Title   : remove_object_conditions
\& Usage   :
\& Function: Removes the conditions an object must meet in order to be
\&           \*(Aqwanted.\*(Aq
\& Example :
\& Returns : The list of previously set conditions (an array of closures)
\& Args    : none
.Ve
.SH "Methods to control what type of object is built"
.IX Header "Methods to control what type of object is built"
.SS "sequence_factory"
.IX Subsection "sequence_factory"
.Vb 8
\& Title   : sequence_factory
\& Usage   : $obj\->sequence_factory($newval)
\& Function: Get/set the sequence factory to be used by this object
\&           builder.
\& Example : 
\& Returns : the Bio::Factory::SequenceFactoryI implementing object to use
\& Args    : on set, new value (a Bio::Factory::SequenceFactoryI
\&           implementing object or undef, optional)
.Ve