MAGE::...cation(3pm)

💖 NAME 💖

Bio::MAGE::DesignElement::FeatureLocation — a whole class for the MAGE-OM API, and yes bestie, this is the MAGE::...cation(3pm) page from the User Contributed Perl Documentation. Buckle up, it's a long one, and this is only part one. 🎀

---

✨ SYNOPSIS ✨

Okay so here's the vibe, copy-paste style:

use Bio::MAGE::DesignElement::FeatureLocation

# creating an empty instance
my $featurelocation = Bio::MAGE::DesignElement::FeatureLocation->new();

# creating an instance with existing data
my $featurelocation = Bio::MAGE::DesignElement::FeatureLocation->new(
      row=>$row_val,
      column=>$column_val,
      propertySets=>\@namevaluetype_list,
);

# 'row' attribute
my $row_val = $featurelocation->row(); # getter
$featurelocation->row($value); # setter

# 'column' attribute
my $column_val = $featurelocation->column(); # getter
$featurelocation->column($value); # setter

# 'propertySets' association
my $namevaluetype_array_ref = $featurelocation->propertySets(); # getter
$featurelocation->propertySets(\@namevaluetype_list); # setter

---

🌸 DESCRIPTION 🌸

Straight from the MAGE-OM documentation for the FeatureLocation class, no notes:

Specifies where a feature is located relative to a grid.

That's it, that's the whole point of this class. Grid math era. ✨

---

🦋 INHERITANCE 🦋

Bio::MAGE::DesignElement::FeatureLocation has these superclasses, aka its whole ancestry:

• Bio::MAGE::Extendable

---

👑 CLASS METHODS 👑

Bestie listen — every single one of these can be called without making an instance first. Just use the Bio::MAGE::DesignElement::FeatureLocation->methodname() syntax and you're good. 💅

new()

new(%args)

The object constructor new() takes these optional named-value style arguments, and they're all optional, so no pressure:

• row — sets the value of the row attribute
• column — sets the value of the column attribute
• propertySets — sets the value of the propertySets association (fun fact: this association was inherited from the class Bio::MAGE::Extendable). The value has to be of type: array of Bio::MAGE::NameValueType.

$obj = class->new(%parameters)

The new() method IS the class constructor. Main character energy fr.

• Parameters: if you hand it a list of name/value parameters, the matching slots, attributes, or associations get their initial values set by the constructor.
• 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 grabs the name of every slot defined in a given class.

⚠️ NOTE: this list of names does not include attribute or association names. Don't come for me, that's just how it is.

• 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. Simple, iconic.

$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, but make it a hash. 💜

---

💅 INSTANCE METHODS 💅

$obj_copy = $obj->new()

When you call it on an existing object reference and not a class name, the new() method acts as a copy constructor — the new object's initial values get set to be 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: 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. It's got two different invocation methods — the first takes a named parameter list, and the second takes two array references. Pick your fighter. ⚔️

• Return value: none
• Side effects: will call croak() if a slot_name is used that the class does not define. Do not test this on purpose bestie. 💀

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

The get_slots() method gets the values of a bunch 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 gets the values of a bunch of slots at the same time.

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

---

🍓 ATTRIBUTES 🍓

Attributes are simple data types that belong to a single instance of a class. In the Perl implementation of the MAGE-OM classes, the interface to attributes is implemented using separate setter and getter methods for each attribute. So yes, you get a whole lil pair of methods per attribute.

Bio::MAGE::DesignElement::FeatureLocation has the following attribute accessor methods:

row

Methods for the row attribute.

From the MAGE-OM documentation:

row position in the Zone

$val = $featurelocation->setRow($val)

The restricted setter method for the row attribute.

• Input parameters: the value to which the row attribute will be set
• Return value: the current value of the row attribute
• Side effects: none
• Exceptions: will call croak() if no input parameters are specified, or if too many input parameters are specified 😭

$val = $featurelocation->getRow()

The restricted getter method for the row attribute.

• Input parameters: none
• Return value: the current value of the row attribute
• Side effects: none
• Exceptions: will call croak() if any input parameters are specified 😭

column

Methods for the column attribute.

From the MAGE-OM documentation:

column position in the Zone.

$val = $featurelocation->setColumn($val)

The restricted setter method for the column attribute.

• Input parameters: the value to which the column attribute will be set
• Return value: the current value of the column attribute
• Side effects: none
• Exceptions: will call croak() if no input parameters are specified, or if too many input parameters are specified 😭

$val = $featurelocation->getColumn()

The restricted getter method for the column attribute.

• Input parameters: none
• Return value: the current value of the column attribute
• Side effects: none
• Exceptions: will call croak() if any input parameters are specified 😭

---

🧚 ASSOCIATIONS 🧚

Associations are references to other classes. In MAGE-OM, associations have a cardinality that determines the minimum and maximum number of instances of the 'other' class that may be included in the association. Cardinality is literally just the "how many of these am I allowed to have" vibe check.

1. There must be exactly one item in the association, i.e. this is a mandatory data field.
2. 0..1 There may be one item in the association, i.e. this is an optional data field.
3. 1..N There must be one or more items in the association, i.e. this is a mandatory data field, with list cardinality.
4. 0..N There may be one or more items in the association, i.e. this is an optional data field, with list cardinality.

Bio::MAGE::DesignElement::FeatureLocation has the following association accessor methods:

propertySets

Methods for the propertySets association.

From the MAGE-OM documentation:

Allows specification of name/value pairs. Meant to primarily help in-house, pipeline processing of instances by providing a place for values that aren't part of the specification proper.

$array_ref = $featurelocation->setPropertySets($array_ref)

The restricted setter method for the propertySets association.

• Input parameters: the value to which the propertySets association will be set : a reference to an array of objects of type Bio::MAGE::NameValueType
• Return value: the current value of the propertySets association : a reference to an array of objects of type Bio::MAGE::NameValueType
• Side effects: none
• Exceptions: will call croak() if no input parameters are specified, or if too many input parameters are specified, or if $array_ref is not a reference to an array class Bio::MAGE::NameValueType instances 😭

$array_ref = $featurelocation->getPropertySets()

The restricted getter method for the propertySets association.

• Input parameters: none
• Return value: the current value of the propertySets association : a reference to an array of objects of type Bio::MAGE::NameValueType
• Side effects: none
• Exceptions: will call croak() if any input parameters are specified 😭

$val = $featurelocation->addPropertySets(@vals)

Because the propertySets association has list cardinality, it may store more than one value. This method adds the current list of objects in the propertySets association. Add-to-the-pile behaviour, we love to see it.

• Input parameters: the list of values @vals to add to the propertySets association. NOTE: submitting a single value is permitted.
• Return value: the number of items stored in the slot after adding @vals
• Side effects: none
• Exceptions: will call croak() if no input parameters are specified, or if any of the objects in @vals is not an instance of class Bio::MAGE::NameValueType 😭

---

And then there's this lil guy hanging out at the end, exactly as written:

sub initialize {

  my $self = shift;
  return 1;

}

Okay but don't go anywhere yet — part two is coming. 🌈

✨ SLOTS, ATTRIBUTES, AND ASSOCIATIONS ✨

Okay bestie, so in the Perl glow-up of MAGE-OM classes, there are literally three flavors of class data members: slots, attributes, and associations. Let's get into it. 💖

💅 SLOTS 💅

This API calls a data member a slot when it wasn't in the UML model and is mostly for internal stuff — only touch if you <em>really</em> know the API's inner workings, no cap. Most of the time slots get used by generic methods like the ones in the XML writing and reading classes. 🧚

Slots are built with unified getter/setter methods:

• $var = $obj->slot_name(); — grabs 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. Slay.
• @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. So like, be careful, bestie. 💀

🦋 ATTRIBUTES AND ASSOCIATIONS 🦋

The words attribute and association mean data members of the class that came straight from the UML model. Iconic.

In the Perl implementation of MAGE-OM classes, association and attribute accessors are implemented with 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. Don't be out here passing args, okay? 🙈

• 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. Lowkey important.

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. Basically, match the vibe of the class, periodt.

• 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. No random objects allowed. 💅

🌸 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. It's giving "go read the rest, bestie." 📖✨

---

🐛 BUGS 🐛

Please send bug reports to the project mailing list: (mged-mage 'at' lists 'dot' sf 'dot' net). They wanna hear from you. 🫶

👑 AUTHOR 👑

Jason E. Stewart (jasons 'at' cpan 'dot' org). Legend behavior. 🌟

🔗 SEE ALSO 🔗

perl(1).

💀 POD ERRORS 💀

Hey! The above document had some coding errors, which are explained below:

• Around line 274: '=item' outside of any '=over'
• Around line 359: You forgot a '=back' before '=head2'
• Around line 531: Expected '=item 2'
• Around line 536: Expected '=item 3'
• Around line 541: Expected '=item 4'

---

Okay bestie, that's the whole vibe. This page was cooked up with perl v5.32.0 on 2020-11-27 and it's MAGE::...cation(3pm) — go forth and code slay. 💖✨🦋