Bio::S...uilder(3pm)

💖 Bio::Seq::SeqBuilder 💖

okay bestie, so this whole page is the manual for Bio::Seq::SeqBuilder — that's the <hotpink>Bio::S...uilder(3pm)</hotpink> header you just scrolled past, no cap, the terminal just clipped it because terminal widths are haters. anyway. pull up a chair 🫶

---

✨ NAME ✨

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

it's literally what it says on the tin: an object builder, and you can configure it. iconic behaviour honestly 💅

---

🌈 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
}

like. look at her. the way she just want_none()s and then asks for exactly three slots? main character energy fr fr 🌸

---

🦋 DESCRIPTION 🦋

so this class is an implementation of Bio::Factory::ObjectBuilderI, and it's the one that parsers of rich sequence streams actually use. it hands you a pretty chill, relatively easy-to-use configurator for the parsing flow 🎀

when is configuring the parsing process your moment? when you need much less information, or much less sequence, than the stream is actually carrying. and here's the slay: in both of those cases, configuring stuff can speed up the parsing time considerably, because the unwanted sections — or the rest of the unwanted sequences — get skipped over by the parser entirely. no notes. also? this configuration could conserve memory if you're running out of available RAM. your poor little machine is going through it and this is the self-care 💜

if you wanna know what specifically you can configure, go read the methods in the class-specific implementation section below. it's giving menu. it's giving options. we love that for us ✨

---

💌 FEEDBACK 💌

📬 Mailing Lists

user feedback is an integral part of the evolution of this and other Bioperl modules. so if you've got comments or suggestions, send them, 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

...and not to the module maintainer directly, bestie, i'm begging 🙈. there are many experienced and responsive experts hanging around who will be able to look at the problem and quickly address it. and if at all possible, please include a thorough description of the problem, with code and data examples. the more context you give, the faster someone can go "oh i know exactly what this is" 🔥

🐛 Reporting Bugs

report bugs to the Bioperl bug tracking system, it helps 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. heads up: internal methods are usually preceded with a _ (iykyk, the underscore is the "don't touch unless you know what you're doing" badge 💀)

🌟 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: (nothing — it's empty, she needs no input)

🧚 Methods for implementing Bio::Factory::ObjectBuilderI

🎀 want_slot

• Title: want_slot
• Usage: (blank)
• Function: tells you whether or not the object builder wants to populate the specified slot of the object that's being built.

you can name the slot either as the name of the respective method, or as the initialization parameter that would otherwise get passed to new() of the object being built.

note: usually only the parser will call this method. if you're doing configuration, use add_wanted_slots and add_unwanted_slots instead, okay? 🫶

• Example: (blank)
• 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: (blank)
• Function: adds one or more values to the specified slot of the object being built.

naming the slot works exactly the same as for want_slot().

the object builder may further filter the content that's about to be set, or even completely ignore the request. it's her world and we're just parsing in it 💅

if this method reports failure, the caller should not add more values to that same slot. on top of that, the caller may find it appropriate to abandon the object being built altogether. like, fully walk away. it's over.

this implementation will allow the caller to overwrite the return value from want_slot(), because the slot is not checked against want_slot(). yeah. she said what she said.

note: usually only the parser will call this method, but you may call it from anywhere if you know what you're doing. a derived class may be used to further manipulate the value to be added.

• Example: (blank)
• Returns: TRUE on success, and FALSE otherwise
• Args: the name of the slot (a string), plus parameters determining the value to be set

OR

alternatively, a list of slotname/value pairs in the style of named parameters, exactly as they'd 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: (blank)
• Function: tells you 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 — otherwise it risks the builder throwing an exception 😭. and on top of that, make_object() is likely to return undef after this method returned FALSE.

note: usually only the parser will call this method. for configuration, use add_object_condition instead.

• Example: (blank)
• Returns: TRUE if the object builder wants to continue building the present object, and FALSE otherwise.
• Args: none

⭐ make_object

• Title: make_object
• Usage: (blank)
• Function: get the built object. the reveal. the finale. 🎀

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: (blank)
• Returns: the object that was built
• Args: none

---

🌸 Implementation specific methods 🌸

Okay bestie, these are the lil knobs and dials that let you configure this sequence object builder however you like — which slots you actually want, and under what circumstances a whole sequence object should just be abandoned, periodt. 💅

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. Default behavior, iconic behavior. 👑

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.

So like, want_all(1) means want all slots except for the unwanted, and want_none() means only those explicitly wanted. No cap. 🫶

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. (Truly the only correct move, ngl.) 😭

---

🎀 get_wanted_slots

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

🎀 add_wanted_slot

• Title: add_wanted_slot
• Usage: (none)
• Function: Adds the specified slots to the list of wanted slots.
• Example: (none)
• Returns: TRUE
• Args: an array of slot names (strings)

🎀 remove_wanted_slots

• Title: remove_wanted_slots
• Usage: (none)
• Function: Removes all wanted slots added previously through add_wanted_slots().
• Example: (none)
• 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: (none)
• Returns: a list of strings
• Args: none

🎀 add_unwanted_slot

• Title: add_unwanted_slot
• Usage: (none)
• Function: Adds the specified slots to the list of unwanted slots.
• Example: (none)
• Returns: TRUE
• Args: an array of slot names (strings)

🎀 remove_unwanted_slots

• Title: remove_unwanted_slots
• Usage: (none)
• Function: Removes the list of unwanted slots added previously through add_unwanted_slots().
• Example: (none)
• Returns: the previous list of unwanted slot names
• Args: none

🎀 want_none

• Title: want_none
• Usage: (none)
• 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: (none)
• 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: (none)
• 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: (none)
• 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: (none)
• Returns: a list of closures
• Args: none

🎀 add_object_condition

• Title: add_object_condition
• Usage: (none)
• 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: (none)
• Returns: TRUE
• Args: the list of conditions

🎀 remove_object_conditions

• Title: remove_object_conditions
• Usage: (none)
• Function: Removes the conditions an object must meet in order to be 'wanted.'
• Example: (none)
• 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: (none)
• Returns: the Bio::Factory::SequenceFactoryI implementing object to use
• Args: on set, new value (a Bio::Factory::SequenceFactoryI implementing object or undef, optional)

---

And that's the whole vibe, bestie — you made it to the end of the page. 🫶 This one's from perl v5.32.1, dated 2021-08-15, and it lives under the name Bio::S...uilder(3pm). Go forth and build those objects. Slay. 💖✨