MAGE::...yDesign(3pm)

💖 MAGE::...yDesign(3pm) — aka the Bio::MAGE::ArrayDesign page

Bestie. Come sit. This one comes from the User Contributed Perl Documentation shelf of your manual pages, and it's the full rundown on Bio::MAGE::ArrayDesign. She's long, she's thorough, and honestly? She ate. 🍓

---

🌸 NAME 🌸

Bio::MAGE::ArrayDesign — a container module for the classes in the MAGE package: ArrayDesign. That's the whole job description and she does it flawlessly. 💅

---

✨ SYNOPSIS ✨

use Bio::MAGE::ArrayDesign;

One line. No notes. Iconic. 🎀

---

🦋 DESCRIPTION 🦋

Okay so this is a package module, which lowkey means she's the friend holding the whole group chat together — she encapsulates a whole bunch of classes inside the Bio::MAGE hierarchy. And those classes? They belong to the ArrayDesign package of the MAGE-OM object model. That's the vibe, that's the assignment, periodt. 🌈

---

👑 CLASSES 👑

The Bio::MAGE::ArrayDesign module contains the following Bio::MAGE classes, and yes, we're listing all of them because every single one matters:

• ArrayDesign
• PhysicalArrayDesign
• ZoneLayout
• ZoneGroup
• Zone
• ReporterGroup
• FeatureGroup
• DesignElementGroup
• CompositeGroup

Nine classes. A whole little family. 🫶

---

🔥 CLASS METHODS 🔥

These are the ones you call on the class itself, not on an instance. Big main-character energy, no object required.

• @class_list = Bio::MAGE::ArrayDesign::classes(); — hands you back a list of non-fully qualified class names living in this package. And by non-fully qualified we mean they do not have 'Bio::MAGE::' as a prefix. Just the short names, bestie. ✨
• $obj = class->new(%parameters) — the class constructor, the birth of an object, the moment of creation. 💖
  • Parameters: if you hand her a list of name/value parameters, the corresponding slots, attributes, or associations will have their initial values set by the constructor.
  • Return value: a reference to an object of the class.
  • Side effects: she invokes the initialize() method if it's defined by the class.
• @names = class->get_slot_names() — used to retrieve the name of all slots defined in a given class.

NOTE: the list of names does not include attribute or association names. Slots only. Don't @ me.

• 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. (Her ancestors. Her lineage. 💜)
• @class_list = get_subclasses() — returns the list of subclasses for this class.
• $name = class_name() — returns the full class name for this class.
• $package_name = package_name() — returns the base package name (i.e. no 'namespace::') of the package that contains this class.
• %assns = associations() — returns the association meta-information in a hash where the keys are the association names and the values are Association objects that provide the meta-information for the association. Meta on meta, we love to see it. 😭

---

💅 INSTANCE METHODS 💅

Now the ones you call on an actual object. This is where it gets juicy.

• $obj_copy = $obj->new() — when you invoke new() with an existing object reference and not a class name, she acts as a copy constructor: the new object's initial values get set to those of the existing object. Clone era. 🙈
  • 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: she invokes the initialize() method if it's defined by the class.
• $obj->set_slots(%parameters) $obj->set_slots(\@name_list, \@value_list) — sets a bunch of slots all at the same time. She has two whole invocation methods, because she contains multitudes: the first takes a named parameter list, 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. So don't try it. She will literally croak.
• @obj_list = $obj->get_slots(@name_list) — gets the values of a number of slots at the same time. Grabby hands, but efficient. 🫶
  • Return value: a list of instance objects.
  • Side effects: none.
• $val = $obj->set_slot($name,$val) — 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) — 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. (Undef is her way of saying "idk her" 💀)
  • Side effects: none.

---

🌟 The unified setter/getter girlies 🌟

Each of these next ones is the same beautiful pattern, just for a different slot. If $inval is specified, the setter method is invoked; with no parameters, the getter method is invoked. And for both setter and getter, you get back the current value of that slot. Side effects: none. Exceptions: none. Clean, no drama. ✨

• $val = $arraydesign->xml_lists() $inval = $arraydesign->xml_lists($inval) — the unified setter/getter for the xml_lists slot.
  • 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 = $arraydesign->tagname() $inval = $arraydesign->tagname($inval) — the unified setter/getter for the tagname slot.
  • 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.
• $val = $arraydesign->reportergroup_list() $inval = $arraydesign->reportergroup_list($inval) — the unified setter/getter for the reportergroup_list slot.
  • Input parameters: the optional $inval will invoke the setter method.
  • Return value: for both setter and getter, the current value of the reportergroup_list slot.
  • Side effects: none.
  • Exceptions: none.
• $val = $arraydesign->compositegroup_list() $inval = $arraydesign->compositegroup_list($inval) — the unified setter/getter for the compositegroup_list slot.
  • Input parameters: the optional $inval will invoke the setter method.
  • Return value: for both setter and getter, the current value of the compositegroup_list slot.
  • Side effects: none.
  • Exceptions: none.
• $val = $arraydesign->arraydesign_list() $inval = $arraydesign->arraydesign_list($inval) — the unified setter/getter for the arraydesign_list slot.
  • Input parameters: the optional $inval will invoke the setter method.
  • Return value: for both setter and getter, the current value of the arraydesign_list slot.
  • Side effects: none.
  • Exceptions: none.

---

🎀 The list-handling methods 🎀

Okay these ones are the interface girlies — they handle the lists for their respective classes.

• $array_ref = $arraydesign->getReporterGroup_list() — handles the list for the Bio::MAGE::ArrayDesign::ReporterGroup class. She returns a reference to an array of the class objects that have been associated with the package instance.
  • This is useful when retrieving data from a parsed MAGE-ML file. 👑
• $arraydesign->addReporterGroup(@vals) — an interface for adding Bio::MAGE::ArrayDesign::ReporterGroup objects to the reportergroup_list list. It's generally used by generic methods such as those in the XMLWriter.
  • Input parameters: the list of values @vals to add to the owner association. NOTE: submitting a single value is permitted. (One is fine. She's flexible. 🫶)
  • Return value: none.
  • Side effects: none.
  • Exceptions: will call croak() if no input parameters are specified, or if any of the objects in @vals is not a subclass of class Bio::MAGE::ArrayDesign::ReporterGroup. So bring the right type or don't bring anything. 💀
• $array_ref = $arraydesign->getCompositeGroup_list() — handles the list for the Bio::MAGE::ArrayDesign::CompositeGroup class. Returns a reference to an array of the class objects that have been associated with the package instance.
  • This is useful when retrieving data from a parsed MAGE-ML file. ✨
• $arraydesign->addCompositeGroup(@vals) — an interface for adding Bio::MAGE::ArrayDesign::CompositeGroup objects to the compositegroup_list list. Generally used by generic methods such as those in the XMLWriter.
  • Input parameters: the list of values @vals to add to the owner association. NOTE: submitting a single value is permitted.
  • Return value: none.
  • Side effects: none.
  • Exceptions: will call croak() if no input parameters are specified, or if any of the objects in @vals is not a subclass of class Bio::MAGE::ArrayDesign::CompositeGroup.
• $array_ref = $arraydesign->getArrayDesign_list() — handles the list for the Bio::MAGE::ArrayDesign::ArrayDesign class. Returns a reference to an array of the class objects that have been associated with the package instance.
  • This is useful when retrieving data from a parsed MAGE-ML file. 🌈
• $arraydesign->addArrayDesign(@vals) — an interface for adding Bio::MAGE::ArrayDesign::ArrayDesign objects to the arraydesign_list list. Generally used by generic methods such as those in the XMLWriter.
  • Input parameters: the list of values @vals to add to the owner association. NOTE: submitting a single value is permitted.
  • Return value: none.
  • Side effects: none.
  • Exceptions: will call croak() if no input parameters are specified, or if any of the objects in @vals is not a subclass of class Bio::MAGE::ArrayDesign::ArrayDesign.

---

🦋 XML era 🦋

• $arraydesign->obj2xml($writer) — writes out this object, and all sub-objects, as XML, using the supplied $writer to actually do the XML formatting. She's the author, the writer is the typesetter. 🎀
  • 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::ArrayDesign 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. (Customisation queen. 💅)
  • Exceptions: will call croak() if no identifier has been set for the Bio::MAGE::ArrayDesign instance. Set your identifier, bestie, or she will croak.
• $arraydesign->register($obj) — stores an object for later writing as XML. Little save-for-later moment. 🫶
  • 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 💖

okay bestie so in the Perl implementation of MAGE-OM classes there are literally three flavours of class data members and we gotta know them by name: slots, attributes, and associations. yes they're cousins. no they're not the same. stay with me 💅

---

SLOTS ✨

so this API uses the word "slot" to mean a data member of the class that was not present in the UML model and is there for mostly internal purposes. translation: use only if you understand the inner workings of the API. like, fr fr, do not touch unless you know what you're doing 🙈

most of the time slots get used by generic methods — the ones hanging out in the XML writing and reading classes and stuff like that. iykyk.

slots are implemented using unified getter/setter methods, which is giving main character energy:

$var = $obj->slot_name();

Retrieves the current value of the slot. 💖

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

Store $new_var in the slot — and the return value is also $new_var. cute, it gives you back what you put in 🫶

@names = $obj->get_slot_names()

Returns the list of all slots in the class. the whole roster 🌸

DATA CHECKING: No data type checking is made for these methods. like, zero. none. it will simply Not check for you 💀

---

ATTRIBUTES AND ASSOCIATIONS 🎀

now the words "attribute" and "association" mean data members of the class that were specified directly from the UML model. these are the official ones ✨

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. literally don't pass anything. it's a getter bestie, hands off 🙅

• 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. (not me warning you ahead of time 🫶)

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. yes it's checking. yes it's judging you. respectfully 💅

• 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. it stacks, it does not replace. slay ✨

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 whole set of generic methods that will operate on slots, attributes, and associations. one class, all the power 👑

$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. go look, the lore is there 📖✨

---

🐛 BUGS

found something broken? please send bug reports to the project mailing list: (mged-mage 'at' lists 'dot' sf 'dot' net) — they wanna hear it, fr fr 🫶

---

👑 AUTHOR

Jason E. Stewart (jasons 'at' cpan 'dot' org) — the icon, the moment, the legend 💖

---

🌈 SEE ALSO

• perl(1)

---

and that's a wrap on this page bestie 🎀 it's from the User Contributed Perl Documentation, running on perl v5.32.0, dated 2020-11-27, and it's the manual page for MAGE::...yDesign(3pm). go forth and not touch the slots unless you truly understand the inner workings, mwah 💅💖