MAGE::Protocol(3pm)

📦 version 20030502.3, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu resolute, ubuntu stonking

okay bestie, deep breath, we're doing this 💖 you just cracked open MAGE::Protocol(3pm), straight out of the User Contributed Perl Documentation pile, and it's a big one. Part 1 of 2, so don't you dare think we're done at the bottom. Let's go 🫶

✨ NAME ✨

Bio::MAGE::Protocol — it's the container module for all the classes living in the MAGE package called Protocol. Think of it as the group chat where all the Protocol-adjacent classes hang out 💅

🌸 SYNOPSIS 🌸

use Bio::MAGE::Protocol;

that's literally it, she's lowkey iconic for that

🦋 DESCRIPTION 🦋

So, this is a package module. What that means, bestie, is that it's a lil wrapper that encapsulates a whole bunch of classes in the Bio::MAGE hierarchy 🎀

And which hierarchy branch are we talking about? These classes belong to the Protocol package of the MAGE-OM object model. That's the vibe. No cap.

🎀 CLASSES 🎀

The Bio::MAGE::Protocol module contains the following Bio::MAGE classes, and yes, all ten of them, I'm not skipping a single one:

  • Protocol
  • Parameter
  • ParameterValue
  • ProtocolApplication
  • Software
  • Hardware
  • HardwareApplication
  • SoftwareApplication
  • Parameterizable
  • ParameterizableApplication

look at that roster. main character energy across the board 👑

💅 CLASS METHODS 💅

these are the ones you call on the class, not on an object. iykyk.

⭐ @class_list = Bio::MAGE::Protocol::classes();

This one hands you back a list of non-fully qualified class names — meaning they do not have Bio::MAGE:: stuck on the front as a prefix — that live in this package. Short names only, periodt.

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

The new() method is the class constructor. Yeah, the classic.

  • Parameters: if you pass it a list of name/value parameters, then the corresponding slots, attributes, or associations get their initial values set by the constructor. You feed it, it fills them in 🍓
  • Return value: it returns 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()

The get_slot_names() method is how you retrieve the name of all slots defined in a given class.

NOTE: the list of names does not include attribute or association names. Just slots. Don't come for me, that's what it says 💀
  • 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 thing. Government name energy ✨

⭐ $package_name = package_name()

Returns the base package name — i.e. with 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.

🫶 INSTANCE METHODS 🫶

okay now the ones you call on an actual object. this is where it gets fun.

💖 $obj_copy = $obj->new()

When you invoke new() with an existing object reference and not a class name, it acts as a copy constructor — the new object's initial values get set to be those of the existing object. it's giving clone, it's giving photocopy, it's giving slay 🦋

  • Parameters: no input parameters are used in the copy constructor — the initial values are taken directly from the object being copied.
  • Return value: it returns a reference to an object of the class.
  • Side effects: it invokes the initialize() method if the class defines one.

💖 $obj->set_slots(%parameters)

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

The set_slots() method sets a bunch of slots at the same time, and she has two different invocation methods, because why choose:

  1. the first takes a named parameter list
  2. 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 🙈

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

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

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

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

The set_slot() method 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)

The get_slot() method 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 = $protocol->xml_lists()

💖 $inval = $protocol->xml_lists($inval)

This is 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 = $protocol->tagname()

💖 $inval = $protocol->tagname($inval)

This is 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

💖 $val = $protocol->hardware_list()

💖 $inval = $protocol->hardware_list($inval)

This is the unified setter/getter method for the hardware_list 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 hardware_list slot
  • Side effects: none
  • Exceptions: none

💖 $val = $protocol->software_list()

💖 $inval = $protocol->software_list($inval)

This is the unified setter/getter method for the software_list 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 software_list slot
  • Side effects: none
  • Exceptions: none

💖 $val = $protocol->protocol_list()

💖 $inval = $protocol->protocol_list($inval)

This is the unified setter/getter method for the protocol_list 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 protocol_list slot
  • Side effects: none
  • Exceptions: none

💖 $array_ref = $protocol->getHardware_list()

This method handles the list for the Bio::MAGE::Protocol::Hardware class. It 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. very much a "read the receipts" situation 🧚

💖 $protocol->addHardware(@vals)

This method is an interface for adding Bio::MAGE::Protocol::Hardware objects to the hardware_list list. It is 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 enough bestie, we don't judge 💜
  • 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::Protocol::Hardware

💖 $array_ref = $protocol->getSoftware_list()

This method handles the list for the Bio::MAGE::Protocol::Software class. It 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.

💖 $protocol->addSoftware(@vals)

This method is an interface for adding Bio::MAGE::Protocol::Software objects to the software_list list. It is 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::Protocol::Software

💖 $array_ref = $protocol->getProtocol_list()

This method handles the list for the Bio::MAGE::Protocol::Protocol class. It 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.

💖 $protocol->addProtocol(@vals)

This method is an interface for adding Bio::MAGE::Protocol::Protocol objects to the protocol_list list. It is 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::Protocol::Protocol

💖 $protocol->obj2xml($writer)

Write out this object, and all sub-objects, as XML, using the supplied $writer to actually do the XML formatting. it's giving ✨ delegation ✨

  • 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::Protocol 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. so much power, honestly 👑
  • Exceptions: will call croak() if no identifier has been set for the Bio::MAGE::Protocol instance.

💖 $protocol->register($obj)

Store an object for later writing as XML. it's literally a "save for later" button 🎀

  • 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 so this is the part where we talk about the three ✨flavors✨ of data members a class can have in the Perl implementation of MAGE-OM classes: slots, attributes, and associations. bestie, they are NOT the same thing and the API treats them differently, so let's get into it 💅

🎀 SLOTS 🎀

so, a "slot" is a data member of the class that was not present in the UML model. it exists for mainly internal purposes. the API's whole vibe here is: use only if you understand the inner workings of the API. like, this is the backstage area, not the stage 💀

most often slots get used by generic methods, like the ones in the XML writing and reading classes. iykyk.

slots are implemented using unified getter/setter methods, which look like this:

$var = $obj->slot_name();

Retrieves the current value of the slot.

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

Store $new_var in the slot — the return value is also $new_var. cute, it hands it right back 🫶

@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. proceed accordingly 😭

💜 ATTRIBUTES AND ASSOCIATIONS 💜

now, the terms "attribute" and "association" mean data members of the class that were specified directly from the UML model. so these are the legit, on-the-model ones, not the backstage slots.

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. (so like, you get a ref, not the list, bestie — don't get caught out 💀)
DATA CHECKING: Ensure that no argument is provided.
  • set* — Sets the current value, replacing any existing value. out with the old, in with the new, periodt.
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. like fr fr, just use add*.
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. if it's not list-cardinality, this method simply does not exist, no cap.

Appends a list of objects to any values that may already be stored in the association. it adds, it does not replace. she's an accumulator ✨

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. one base class to rule them all 👑

$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. (yes bestie, the full tea is on the rest of the page, go look 💖)

💀 BUGS 💀

found a bug? not the vibe, but okay — please send bug reports to the project mailing list: (mged-mage 'at' lists 'dot' sf 'dot' net)

🌈 AUTHOR 🌈

Jason E. Stewart (jasons 'at' cpan 'dot' org) — iconic, honestly 👑

⭐ SEE ALSO ⭐

and that's the whole page, bestie!! this one's MAGE::Protocol(3pm), from perl v5.32.0, dated 2020-11-27. you ate that read 🫶✨

📦 where this page comes from