MAGE::BQS(3pm)

💖 MAGE::BQS 💖

okay bestie, welcome to Bio::MAGE::BQS — a User Contributed Perl Documentation moment, and honestly? it's giving "container module" and I'm obsessed. let's get into it 💅

---

✨ NAME ✨

Bio::MAGE::BQS — the container module for all the classes hanging out in the MAGE package: BQS. that's it, that's the name, slay 🎀

---

✨ SYNOPSIS ✨

like, here's the whole vibe in one line:

use Bio::MAGE::BQS;

that's the whole thing. short and iconic 🦋

---

✨ DESCRIPTION ✨

so basically this is a package module that wraps up a whole little friend group of classes inside the Bio::MAGE hierarchy 🌸 these classes all belong to the BQS package of the MAGE-OM object model. no cap.

---

✨ CLASSES ✨

the Bio::MAGE::BQS module is home to these Bio::MAGE classes:

• BibliographicReference

just the one bestie but she's carrying the whole package 💅

---

✨ CLASS METHODS ✨

🌟 @class_list = Bio::MAGE::BQS::classes();

this one hands you back a list of non-fully qualified class names living in this package — meaning they don't have Bio::MAGE:: glued on the front. just the short cute names 💫

🌟 $obj = class->new(%parameters)

the new() method is literally the class constructor. the main character of constructors.

• Parameters: if you pass it a list of name/value pairs, the matching slots, attributes, or associations get their starting values set right there by the constructor ✨
• Return value: a reference to an object of the class 🫶
• Side effects: it invokes the initialize() method if the class defines one.

🌟 @names = class->get_slot_names()

use get_slot_names() to pull the name of every slot defined in a given class 💖

NOTE: this list does not include attribute or association names. slots only, bestie.

• Return value: a list of the names of all slots defined for this class.
• Side effects: none 😌

🌟 @name_list = get_attribute_names()

returns the list of attribute data members for this class 🌸

🌟 @name_list = get_association_names()

returns the list of association data members for this class 🦋

🌟 @class_list = get_superclasses()

returns the list of superclasses for this class 👑

🌟 @class_list = get_subclasses()

returns the list of subclasses for this class 🌈

🌟 $name = class_name()

returns the full class name for this class. the whole government name fr fr 💅

🌟 $package_name = package_name()

returns the base package name — and by that I mean no namespace:: — of the package that contains this class 🎀

🌟 %assns = associations()

returns the association meta-information as a hash where the keys are the association names and the values are Association objects that carry the meta-info for that association 💜

---

✨ INSTANCE METHODS ✨

🌟 $obj_copy = $obj->new()

when you call new() on an existing object reference instead of a class name, it acts as a copy constructor — the new object's starting values get set to be exactly those of the existing object. it's giving twin energy 👯

• Parameters: no input parameters are used in the copy constructor, the initial values are taken directly from the object to be copied.
• Return value: a reference to an object of the class 🫶
• Side effects: it invokes the initialize() method if it is defined by the class.

🌟 $obj->set_slots(%parameters) and $obj->set_slots(\@name_list, \@value_list)

set_slots() sets a bunch of slots all at once ⚡ it's got two different ways to be invoked: the first takes a named parameter list, and the second takes two array references.

• Return value: none
• Side effects: will call croak() if a slot_name is used that the class does not define 💀

🌟 @obj_list = $obj->get_slots(@name_list)

get_slots() grabs the values of a whole bunch of slots at the same time 🍓

• Return value: a list of instance objects
• Side effects: none 😌

🌟 $val = $obj->set_slot($name,$val)

set_slot() sets the slot $name to the value $val ✨

• Return value: the new value of the slot, i.e. $val
• Side effects: none 😌

🌟 $val = $obj->get_slot($name)

get_slot() is used to get the values of a number of slots at the same time.

• Return value: a single slot value, or undef if the slot has not been initialized 😭
• Side effects: none 😌

🌟 $val = $bqs->xml_lists() and $inval = $bqs->xml_lists($inval)

the unified setter/getter method for the xml_lists slot 🎀

if $inval is specified, the setter method is invoked; with no parameters, the getter method is invoked.

• Input parameters: the optional $inval will invoke the setter method.
• Return value: for both setter and getter, the current value of the xml_lists slot
• Side effects: none
• Exceptions: none

🌟 $val = $bqs->tagname() and $inval = $bqs->tagname($inval)

the unified setter/getter method for the tagname slot 🦋

if $inval is specified, the setter method is invoked; with no parameters, the getter method is invoked.

• Input parameters: the optional $inval will invoke the setter method.
• Return value: for both setter and getter, the current value of the tagname slot
• Side effects: none
• Exceptions: none

🌟 $bqs->obj2xml($writer)

writes out this object — and every single sub-object — as XML, using the supplied $writer to do the actual XML formatting ✨ it's the delegator, the project manager, the one who makes sure everything gets written properly 👑

• Input parameters: $writer must be an XML writer, e.g. an instance of Bio::MAGE::XML::Writer. It must have methods: write_start_tag(), write_end_tag(), and obj2xml().
• Return value: none
• Side effects: all writing is delegated to the $writer — its write_start_tag() and write_end_tag() methods are invoked with the appropriate data, and all class sub-objects of the Bio::MAGE::BQS instance will have their obj2xml() methods invoked in turn. By allowing the $writer to do the actual formatting of the output XML, it enables the user to precisely control the format 💅
• Exceptions: will call croak() if no identifier has been set for the Bio::MAGE::BQS instance 💀

🌟 $bqs->register($obj)

stores an object for later writing as XML 📦

• Input parameters: object to be added to the list of registered objects.
• Return value: none
• Side effects: if $obj needs to be stored by this class, a reference will be stored in the correct XML list for this class.
• Exceptions: none

---

✨ SLOTS, ATTRIBUTES, AND ASSOCIATIONS ✨

in the Perl implementation of MAGE-OM classes there are three types of class data members: slots, attributes, and associations 🌈

---

🎀 SLOTS 🎀

this API uses the term slot to mean a data member of the class that was not present in the UML model and is used mainly for internal purposes — so like, only touch it if you actually understand the inner workings of the API bestie, I'm serious 🙈 most of the time slots are used by generic methods like the ones in the XML writing and reading classes.

slots are implemented using unified getter/setter methods:

$var = $obj->slot_name();

retrieves the current value of the slot 💖

$new_var = $obj->slot_name($new_var);

stores $new_var in the slot — and the return value is also $new_var ✨

@names = $obj->get_slot_names()

returns the list of all slots in the class 🦋

DATA CHECKING: no data type checking is made for these methods. zero. none. she does not check. 💀

---

🎀 ATTRIBUTES AND ASSOCIATIONS 🎀

the terms attribute and association mean data members of the class that were specified directly from the UML model 💜

in the Perl implementation of MAGE-OM classes, association and attribute accessors are implemented using three separate methods:

get*

retrieves the current value.

NOTE: for associations, if the association has list cardinality, an array reference is returned.

DATA CHECKING: ensure that no argument is provided.

set*

sets the current value, replacing any existing value ✨

NOTE: for associations, if the association has list cardinality, the argument must be an array reference. Because of this, you probably should be using the add* methods.

DATA CHECKING: for attributes, ensure that a single value is provided as the argument. For associations, if the association has list cardinality, ensure that the argument is a reference to an array of instances of the correct MAGE-OM class, otherwise ensure that there is a single argument of the correct MAGE-OM class.

add*

NOTE: only present in associations with list cardinality.

appends a list of objects to any values that may already be stored in the association 🌸

DATA CHECKING: ensure that all arguments are of the correct MAGE-OM class.

---

🎀 GENERIC METHODS 🎀

the unified base class of all MAGE-OM classes, Bio::MAGE::Base, provides a set of generic methods that will operate on slots, attributes, and associations 👑

$val = $obj->get_slot($name)

\@list_ref = $obj->get_slots(@name_list);

$val = $obj->set_slot($name,$val)

$obj->set_slots(%parameters)

$obj->set_slots(\@name_list, \@value_list)

see elsewhere in this page for a detailed description of these methods 🫶 (they're up in INSTANCE METHODS, bestie, I got you)

---

✨ BUGS ✨

found a bug? 😭 please send bug reports to the project mailing list: (mged-mage 'at' lists 'dot' sf 'dot' net) — they want to hear from you fr fr 💌

---

✨ AUTHOR ✨

Jason E. Stewart (jasons 'at' cpan 'dot' org) 👑 an icon, a legend, the moment.

---

✨ SEE ALSO ✨

• perl(1) 🐪

---

and that's the whole page bestie!! 💖✨ this was perl v5.32.0, dated 2020-11-27, and honestly? iconic behavior. go write some XML, you're gonna eat 🎀🦋💅