MAGE::...iducial(3pm)

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

okay so bestie, welcome to MAGE::...iducial(3pm) from the User Contributed Perl Documentation — and yes the manual name really is truncated with a literal ... in the middle, that's not me being shady, that's just how it shipped 💀. Anyway. Sit down, grab a lil drink, we're learning Bio::MAGE::Array::Fiducial together and it's gonna be fine 🫶

🌸 NAME 🌸

Bio::MAGE::Array::Fiducial — the class for the MAGE-OM API. That's the whole vibe. Periodt. 💅

✨ SYNOPSIS ✨

here's the whole glow-up, copied exactly so you don't have to squint at the original:

  use Bio::MAGE::Array::Fiducial

  # creating an empty instance
  my $fiducial = Bio::MAGE::Array::Fiducial->new();

  # creating an instance with existing data
  my $fiducial = Bio::MAGE::Array::Fiducial->new(
        position=>$position_ref,
        auditTrail=>\@audit_list,
        propertySets=>\@namevaluetype_list,
        distanceUnit=>$distanceunit_ref,
        descriptions=>\@description_list,
        security=>$security_ref,
        fiducialType=>$ontologyentry_ref,
  );

  # 'position' association
  my $position_ref = $fiducial->position(); # getter
  $fiducial->position($position_ref); # setter

  # 'auditTrail' association
  my $audit_array_ref = $fiducial->auditTrail(); # getter
  $fiducial->auditTrail(\@audit_list); # setter

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

  # 'distanceUnit' association
  my $distanceunit_ref = $fiducial->distanceUnit(); # getter
  $fiducial->distanceUnit($distanceunit_ref); # setter

  # 'descriptions' association
  my $description_array_ref = $fiducial->descriptions(); # getter
  $fiducial->descriptions(\@description_list); # setter

  # 'security' association
  my $security_ref = $fiducial->security(); # getter
  $fiducial->security($security_ref); # setter

  # 'fiducialType' association
  my $ontologyentry_ref = $fiducial->fiducialType(); # getter
  $fiducial->fiducialType($ontologyentry_ref); # setter

look at all those getters and setters. it's giving object-oriented excellence 🦋

🎀 DESCRIPTION 🎀

straight from the MAGE-OM documentation for the "Fiducial" class, no notes:

A marking on the surface of the array that can be used to identify the array's origin, the coordinates of which are the fiducial's centroid.

so like… it's a little landmark on your array so you know where the array came from, and its coordinates are the centroid of that marking. iconic behavior honestly 👑

🧚 INHERITANCE 🧚

Bio::MAGE::Array::Fiducial has exactly one superclass, and it's:

Bio::MAGE::Describable

so everything Describable brings to the party? it's here too. family reunion vibes 🌈

👑 CLASS METHODS 👑

the slay here is that you can call all of these without making an instance first — just use the Bio::MAGE::Array::Fiducial->methodname() syntax. no object required, we're going straight to the class, main character energy fr fr.

new(), new(%args) — the object constructor. new() takes these optional named-value style args, and each one sets a whole association:
- auditTrail — sets the value of the "auditTrail" association (this one was inherited from class "Bio::MAGE::Describable"). The value must be of type: array of Bio::MAGE::AuditAndSecurity::Audit.
- position — sets the value of the "position" association. The value must be of type: instance of Bio::MAGE::DesignElement::Position.
- propertySets — sets the value of the "propertySets" association (this one was inherited from class "Bio::MAGE::Extendable"). The value must be of type: array of Bio::MAGE::NameValueType.
- descriptions — sets the value of the "descriptions" association (this one was inherited from class "Bio::MAGE::Describable"). The value must be of type: array of Bio::MAGE::Description::Description.
- distanceUnit — sets the value of the "distanceUnit" association. The value must be of type: instance of Bio::MAGE::Measurement::DistanceUnit.
- security — sets the value of the "security" association (this one was inherited from class "Bio::MAGE::Describable"). The value must be of type: instance of Bio::MAGE::AuditAndSecurity::Security.
- fiducialType — sets the value of the "fiducialType" association. The value must be of type: instance of Bio::MAGE::Description::OntologyEntry.
$obj = class->new(%parameters) — the "new()" method is the class constructor.
- Parameters: if you hand it a list of name/value parameters, the corresponding slots, attributes, or associations get their initial values set by the constructor. cute right?
- 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() — grabs the names of all the slots defined in a given class.

NOTE: that list of names does not include attribute or association names. don't come for me, that's just the rules 💀

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

@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.
$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 carry the meta-information for the association. iykyk 🫶

💜 INSTANCE METHODS 💜

$obj_copy = $obj->new() — when you call "new()" on an existing object reference instead of on a class name, it acts as a copy constructor — the new object's initial values get set to those of the existing object. lowkey the best trick here ✨
- Parameters: no input parameters are used in the copy constructor; the initial values are taken directly from the object being copied.
- Return value: 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 all at once, and it has two different invocation styles: the first takes a named parameter list, 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. so like, don't make stuff up bestie 😭
@obj_list = $obj->get_slots(@name_list) — the "get_slots()" method gets 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 gets 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

🌟 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 with separate setter and getter methods for each attribute.

"Bio::MAGE::Array::Fiducial" has the following attribute accessor methods:

(yep, that's it. nothing listed. the silence is loud 🙈)

🦋 ASSOCIATIONS 🦋

associations are references to other classes. associations in MAGE-OM have a cardinality that decides the minimum and maximum number of instances of the 'other' class that may be included in the association:

1 — there must be exactly one item in the association, i.e. this is a mandatory data field.
0..1 — there may be one item in the association, i.e. this is an optional data field.
1..N — there must be one or more items in the association, i.e. this is a mandatory data field, with list cardinality.
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::Array::Fiducial has the following association accessor methods:

🌈 auditTrail

methods for the "auditTrail" association.

from the MAGE-OM documentation:

A list of Audit instances that track changes to the instance of Describable.

$array_ref = $fiducial->setAuditTrail($array_ref) — the restricted setter for the "auditTrail" association.
- Input parameters: the value to which the "auditTrail" association will be set: a reference to an array of objects of type Bio::MAGE::AuditAndSecurity::Audit
- Return value: the current value of the "auditTrail" association: a reference to an array of objects of type Bio::MAGE::AuditAndSecurity::Audit
- 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 of class Bio::MAGE::AuditAndSecurity::Audit instances
$array_ref = $fiducial->getAuditTrail() — the restricted getter for the "auditTrail" association.
- Input parameters: none
- Return value: the current value of the "auditTrail" association: a reference to an array of objects of type Bio::MAGE::AuditAndSecurity::Audit
- Side effects: none
- Exceptions: will call "croak()" if any input parameters are specified
$val = $fiducial->addAuditTrail(@vals) — because the auditTrail association has list cardinality, it may store more than one value. this method adds the current list of objects in the auditTrail association.
- Input parameters: the list of values @vals to add to the auditTrail 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::AuditAndSecurity::Audit

⭐ position

methods for the "position" association.

from the MAGE-OM documentation:

The position, relative to the upper left corner, of the fiducial

$val = $fiducial->setPosition($val) — the restricted setter for the "position" association.
- Input parameters: the value to which the "position" association will be set: one of the accepted enumerated values.
Return value: the current value of the position association : one of the accepted enumerated values. 💫
- Side effects: none. nada. zero. 🫶
- Exceptions: will call croak() if no input parameters are specified, or if too many input parameters are specified, or if $val is not an instance of class Bio::MAGE::DesignElement::Position.
$val = $fiducial->getPosition() — the restricted getter for the position association. it only reads, bestie, it does not write. 💅
- Input parameters: none.
- Return value: the current value of the position association : an instance of type Bio::MAGE::DesignElement::Position. ✨
- Side effects: none.
- Exceptions: will call croak() if any input parameters are specified. so like… don't. 😭