Provided by: libbio-perl-perl_1.7.2-2_all bug

NAME

       Bio::Seq::SeqBuilder - Configurable object builder for sequence stream parsers

SYNOPSIS

          use Bio::SeqIO;

          # usually you won't instantiate this yourself - a SeqIO object -
          # you will have one already
          my $seqin = Bio::SeqIO->new(-fh => \*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('display_id','desc','seq');

          # if you want everything except the sequence and features
          $builder->want_all(1); # this is the default if it's untouched
          $builder->add_unwanted_slot('seq','features');

          # 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->{'-length'} > 5000;
              return 0 if exists($h->{'-species'}) &&
                          ($h->{'-species'}->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
          }

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.

       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 RAM.

       See the methods of the class-specific implementation section for further documentation of
       what can be configured.

FEEDBACK

   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.

         bioperl-l@bioperl.org                  - General discussion
         http://bioperl.org/wiki/Mailing_lists  - About the mailing lists

   Support
       Please direct usage questions or support issues to the mailing list:

       bioperl-l@bioperl.org

       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.

   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:

         https://github.com/bioperl/bioperl-live/issues

AUTHOR - Hilmar Lapp

       Email hlapp at gmx.net

APPENDIX

       The rest of the documentation details each of the object methods.  Internal methods are
       usually preceded with a _

   new
        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    :

Methods for implementing Bio::Factory::ObjectBuilderI

   want_slot
        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)

   add_slot_value
        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.

   want_object
        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

   make_object
        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 'end_object.'

        Example :
        Returns : the object that was built
        Args    : none

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 want_all(1), which means the builder will report all slots
       as wanted that the object created by the sequence factory supports.

       You can add specific slots you want through add_wanted_slots(). In most cases, you will
       want to call want_none() before in order to relax zero acceptance through a list of wanted
       slots.

       Alternatively, you can add specific unwanted slots through add_unwanted_slots(). In this
       case, you will usually want to call want_all(1) before (which is the default if you never
       touched the builder) to restrict unrestricted acceptance.

       I.e., want_all(1) means want all slots except for the unwanted, and want_none() means only
       those explicitly wanted.

       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.

   get_wanted_slots
        Title   : get_wanted_slots
        Usage   : $obj->get_wanted_slots($newval)
        Function: Get the list of wanted slots
        Example :
        Returns : a list of strings
        Args    :

   add_wanted_slot
        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)

   remove_wanted_slots
        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

   get_unwanted_slots
        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

   add_unwanted_slot
        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)

   remove_unwanted_slots
        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

   want_none
        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

   want_all
        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 'virtual' 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)

   get_object_conditions
        Title   : get_object_conditions
        Usage   :
        Function: Get the list of conditions an object must meet in order to
                  be 'wanted.' 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
                  'wanted.'

                  Conditions will be implicitly ANDed.

        Example :
        Returns : a list of closures
        Args    : none

   add_object_condition
        Title   : add_object_condition
        Usage   :
        Function: Adds a condition an object must meet in order to be 'wanted.'
                  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

   remove_object_conditions
        Title   : remove_object_conditions
        Usage   :
        Function: Removes the conditions an object must meet in order to be
                  'wanted.'
        Example :
        Returns : The list of previously set conditions (an array of closures)
        Args    : none

Methods to control what type of object is built

   sequence_factory
        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)