MAGE::...eLayout(3pm)

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

MAGE::...eLayout (3pm) 💖

okay bestie, this is a page from the User Contributed Perl Documentation and it's giving Bio::MAGE::ArrayDesign::ZoneLayout energy. It's long so we're doing it in 3 parts — this is part 1, don't go anywhere 👑

✨ NAME ✨

Bio::MAGE::ArrayDesign::ZoneLayout — Class for the MAGE-OM API 🧬

✨ SYNOPSIS ✨

  use Bio::MAGE::ArrayDesign::ZoneLayout

  # creating an empty instance
  my $zonelayout = Bio::MAGE::ArrayDesign::ZoneLayout->new();

  # creating an instance with existing data
  my $zonelayout = Bio::MAGE::ArrayDesign::ZoneLayout->new(
        numFeaturesPerRow=>$numfeaturesperrow_val,
        spacingBetweenRows=>$spacingbetweenrows_val,
        numFeaturesPerCol=>$numfeaturespercol_val,
        spacingBetweenCols=>$spacingbetweencols_val,
        propertySets=>\@namevaluetype_list,
        distanceUnit=>$distanceunit_ref,
  );

  # 'numFeaturesPerRow' attribute
  my $numFeaturesPerRow_val = $zonelayout->numFeaturesPerRow(); # getter
  $zonelayout->numFeaturesPerRow($value); # setter

  # 'spacingBetweenRows' attribute
  my $spacingBetweenRows_val = $zonelayout->spacingBetweenRows(); # getter
  $zonelayout->spacingBetweenRows($value); # setter

  # 'numFeaturesPerCol' attribute
  my $numFeaturesPerCol_val = $zonelayout->numFeaturesPerCol(); # getter
  $zonelayout->numFeaturesPerCol($value); # setter

  # 'spacingBetweenCols' attribute
  my $spacingBetweenCols_val = $zonelayout->spacingBetweenCols(); # getter
  $zonelayout->spacingBetweenCols($value); # setter

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

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

✨ DESCRIPTION ✨

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

Specifies the layout of features in a rectangular grid. 🎀

like. a grid. features. arranged. iconic behaviour honestly 💅

✨ INHERITANCE ✨

Bio::MAGE::ArrayDesign::ZoneLayout has the following superclasses:

  • Bio::MAGE::Extendable

so yeah, it's got that Extendable DNA in it 🧬✨

✨ CLASS METHODS ✨

The following methods can all be called without first having an instance of the class via the Bio::MAGE::ArrayDesign::ZoneLayout->methodname() syntax. no object needed, just vibes 🫶

new()

new(%args)

The object constructor new() accepts the following optional named-value style arguments:

  • numFeaturesPerRow — Sets the value of the numFeaturesPerRow attribute
  • spacingBetweenRows — Sets the value of the spacingBetweenRows attribute
  • numFeaturesPerCol — Sets the value of the numFeaturesPerCol attribute
  • spacingBetweenCols — Sets the value of the spacingBetweenCols attribute
  • propertySets — Sets the value of the propertySets association (this association was inherited from class Bio::MAGE::Extendable).

The value must be of type: array of Bio::MAGE::NameValueType.

  • distanceUnit — Sets the value of the distanceUnit association

The value must be of type: instance of Bio::MAGE::Measurement::DistanceUnit.

$obj = class->new(%parameters)

The new() method is the class constructor. it makes objects. that's the whole job 🎀

Parameters: if given a list of name/value parameters the corresponding slots, attributes, or associations will have 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 it is defined by the class.

@names = class->get_slot_names()

The get_slot_names() method is 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. bestie don't get caught out by this one 😭

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.

$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.

ok so that's part 1, and there's more coming 🌈 don't close the tab yet 🦋

✨ INSTANCE METHODS ✨

bestie these are the methods you call on an actual object, not the class. we love an instance moment 💅

🌸 $obj_copy = $obj->new() 🌸

okay so when you call new() on an existing object reference instead of on a class name, it pulls a copy-constructor move — the brand new object starts out with all the same initial values as the old one. twin energy fr fr 🫶

  • Parameters: none, bestie. the copy constructor takes no input parameters, the initial values are just lifted straight off the object you're copying.
  • Return value: a reference to an object of the class.
  • Side effects: it invokes the initialize() method if the class defines one. slay.

🎀 $obj->set_slots(%parameters) 🎀

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

set_slots() is the "set a bunch of slots at once" girlie. she has two different invocation methods: the first one 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. so like, don't make up slots, she will notice 😭

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

get_slots() gets you the values of a number of slots at the same time. bulk grab, no cap.

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

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

set_slot() sets the slot $name to the value $val. one slot, one value, very demure.

  • 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. (the undef is giving "she's not ready yet" 🙈)
  • 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. one for each, iconic behaviour tbh.

Bio::MAGE::ArrayDesign::ZoneLayout has the following attribute accessor methods:

🍓 numFeaturesPerRow 🍓

Methods for the numFeaturesPerRow attribute.

From the MAGE-OM documentation:

The number of features from left to right.

$val = $zonelayout->setNumFeaturesPerRow($val)

The restricted setter method for the numFeaturesPerRow attribute.

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

$val = $zonelayout->getNumFeaturesPerRow()

The restricted getter method for the numFeaturesPerRow attribute.

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

🧚 spacingBetweenRows 🧚

Methods for the spacingBetweenRows attribute.

From the MAGE-OM documentation:

Spacing between the rows.

$val = $zonelayout->setSpacingBetweenRows($val)

The restricted setter method for the spacingBetweenRows attribute.

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

$val = $zonelayout->getSpacingBetweenRows()

The restricted getter method for the spacingBetweenRows attribute.

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

🌸 numFeaturesPerCol 🌸

Methods for the numFeaturesPerCol attribute.

From the MAGE-OM documentation:

The number of features from top to bottom of the grid.

$val = $zonelayout->setNumFeaturesPerCol($val)

The restricted setter method for the numFeaturesPerCol attribute.

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

$val = $zonelayout->getNumFeaturesPerCol()

The restricted getter method for the numFeaturesPerCol attribute.

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

💖 spacingBetweenCols 💖

Methods for the spacingBetweenCols attribute.

From the MAGE-OM documentation:

Spacing between the columns.

$val = $zonelayout->setSpacingBetweenCols($val)

The restricted setter method for the spacingBetweenCols attribute.

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

$val = $zonelayout->getSpacingBetweenCols()

The restricted getter method for the spacingBetweenCols attribute.

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

🫶 ASSOCIATIONS 🫶

Associations are references to other classes. Associations in MAGE-OM have a cardinality that determines the minimum and maximum number of instances of the 'other' class that maybe included in the association. let's break it down:

  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::ArrayDesign::ZoneLayout 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 = $zonelayout->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 = $zonelayout->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 = $zonelayout->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.

  • 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

💫 distanceUnit 💫

Methods for the distanceUnit association.

From the MAGE-OM documentation:

Unit of the ZoneLayout attributes.

$val = $zonelayout->setDistanceUnit($val)

The restricted setter method for the distanceUnit association.

  • Input parameters: the value to which the distanceUnit association will be set : one of the accepted enumerated values.
  • Return value: the current value of the distanceUnit association : one of the accepted enumerated values.
  • Side effects: none
  • 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::Measurement::DistanceUnit

$val = $zonelayout->getDistanceUnit()

The restricted getter method for the distanceUnit association.

  • Input parameters: none
  • Return value: the current value of the distanceUnit association : an instance of type Bio::MAGE::Measurement::DistanceUnit.
  • Side effects: none
  • Exceptions: will call croak() if any input parameters are specified

and then, plot twist, there's literally this just chillin' at the end of the association section, no cap:

sub initialize {

  my $self = shift;
  return 1;

}

she's short, she's simple, she returns 1. main character energy 🎀

💖 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 you gotta know which is which: "slots", "attributes", and "associations". 💅

✨ SLOTS ✨

so this API uses the word "slot" for a data member of the class that wasn't in the UML model and exists mostly for internal reasons. ngl: use only if you understand the inner workings of the API. 🙈 Most of the time slots are the ones the generic methods reach for, like the stuff in the XML writing and reading classes.

slots are implemented with unified getter/setter methods, like:

$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 the slots in the class. 🎀

DATA CHECKING: fr fr, no data type checking is made for these methods. 😭

🌸 ATTRIBUTES AND ASSOCIATIONS 🌸

the terms "attribute" and "association" mean data members of the class that came directly from the UML model. the real ones. 👑

in the Perl implementation of MAGE-OM classes, association and attribute accessors are built from 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. periodt.
  • 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. iykyk 💅
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, hands you a whole set of generic methods that will operate on slots, attributes, and associations. it's giving main character energy, honestly:

$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. 💜

💀 BUGS 💀

please send bug reports to the project mailing list: (mged-mage 'at' lists 'dot' sf 'dot' net) — we're nice, we promise 🫶

👑 AUTHOR 👑

Jason E. Stewart (jasons 'at' cpan 'dot' org) — iconic behaviour, no cap ⭐

🌈 SEE ALSO 🌈

perl(1).

🎀 POD ERRORS 🎀

hey! 😭 the above document had some coding errors, which are explained below:

  • Around line 326:
    • '=item' outside of any '=over'
  • Around line 411:
    • You forgot a '=back' before a '=head2'
  • Around line 727:
    • Expected '=item 2'
  • Around line 732:
    • Expected '=item 3'
  • Around line 737:
    • Expected '=item 4'

okay that's the whole page bestie, we ate and left no crumbs 🍓 this one's perl v5.32.0, dated 2020-11-27, and it's MAGE::...eLayout(3pm) — go forth and slay your MAGE-OM objects 💖✨🧚

📦 where this page comes from