SWISS::ListBase(3pm)

✨ SWISS::ListBase ✨

okay bestie, gather round, because this is SWISS::ListBase.pm from the User Contributed Perl Documentation collection and it is literally the blueprint 💅

---

🎀 Name 🎀

SWISS::ListBase.pm — the base class of the SWISS:: universe, and yes she's the mother of all list-oriented classes, no cap 👑

---

🌸 Description 🌸

So basically: this is the base class for list oriented classes in the SWISS:: hierarchy. She hands down a whole set of quite general list manipulation methods to all the inheriting classes. Think of her as the cool older sister who already did the homework and lets the subclasses copy her notes 🫶

---

🦋 Attributes 🦋

• list — holds an array, and that array is the essential content of the object. and plot twist: the array elements can be — and, fr fr, frequently are — arrays themselves. arrays all the way down bestie 😭

---

💖 Methods 💖

⭐ Standard methods ⭐

• new
• initialize

💜 Reading methods 💜

• head — returns the first element of the list. she's the front of the line 💅
• tail — returns all but the first element of the list. bye first element, everybody else stays ✨
• get pattern — returns a list of all elements matched by $pattern. Only exact matches are returned, but you can absolutely use Perl's regular expressions to pop off. Example:

 $listBaseObject->set('EMBL', 'TREMBL', 'SWISSPROT');
 $listBaseObject->get('.*EMBL');

returns ('EMBL', 'TREMBL')

• get @patternList — use this one when the ListBase elements are themselves arrays. An array gets returned if all its elements are matched exactly by the elements from @patternList with the same index. And listen: empty elements in @patternList always match, every single time. Example:

 $listBaseObject->set(['EMBL', 'M1', 'G1', '-'],
                      ['EMBL', 'M2', 'A2', '-'],
                      ['EMBL', 'M2', 'G3', 'ALT_TERM'],
                      ['PROSITE', 'P00001', '1433_2', '1']);
 $listBaseObject->get('EMBL');

 returns (['EMBL', 'M1', 'G1', '-'],
          ['EMBL', 'M2', 'A2', '-'],
          ['EMBL', 'M2', 'G3', 'ALT_TERM'])

 $listBaseObject->get('',M2);

 returns (['EMBL', 'M2', 'A2', '-'],
          ['EMBL', 'M2', 'G3', 'ALT_TERM']);

ngl, offering get in the interface is not particularly nice, because it exports implementation details straight into the interface 🙈 but it is a powerful method that may save you a lot of programming time. As an alternative, the 'filter' concept is available. choices, bestie ✨

• getObject pattern
• getObject @patternList — same as get, but returns the results wrapped up cozy in a new ListBase object 🎁
• filter — returns a new object containing all of the elements that match a search criteria. It takes a function as the only parameter. That function should expect a list element, and return true or false depending on whether the element matches the criteria. And here's the iconic part: if the object is not a ListBase object but a member of a subclass, a new object of that subclass will be returned. periodt 💅

Example:

 $tmp = $entry->CCs->filter(&ccTopic('FUNCTION'));

returns a SWISS::CCs object containing all CC blocks from $entry which have the topic 'FUNCTION'.

Functions can also be anonymous functions, if you're feeling mysterious 🧚

• attributeEquals(string attributeName, string attributeValue) — a filter function. If the elements of a ListBase object are objects, they will be returned by this function if they have the attribute and it equals the attributeValue.

Example:

$matchedKWs =
$entry->KWs->filter(SWISS::ListBase::attributeEquals('text', $kw));

• attributeMatchedBy(string attributeName, string pattern) — a filter function. If the elements of a ListBase object are objects, they will be returned by this function if they have the attribute and the attribute is matched by the pattern.

Example:

$matchedKWs =
$entry->KWs->filter(SWISS::ListBase::attributeMatchedBy('text',
$kw));

• isEmpty
• size — the number of list elements in the object. she counts. she's an icon 👑
• elements — returns the array of elements
• hasEvidenceTag $arrayPointer $tag — returns true if the array pointed to by $arrayPointer has the evidence tag $tag
• getEvidenceTags $arrayPointer — returns the array of evidence tags of $arrayPointer
• getEvidenceTagsString $arrayPointer — returns a string containing the evidence tags of $arrayPointer

🍓 Writing methods 🍓

• item offset[, newValue] — returns the list element at a specific offset, and optionally sets it to a new value. Negative offsets are relative to the end of the list, so you can vibe backwards 🌈
• push list
• pop
• shift
• unshift list
• splice [offset[, length[, list]]]
• set list — sets the list attribute to @list
• add list — synonym for push
• merge (ListBase) — appends the elements of ListBase to the object. friendship bracelet behaviour 🫶
• sort [function] — applies a sort function to the list attribute, or by default, alphabetical sorting. Should be overwritten in derived classes with an adapted sort function. so like, do better in your subclass bestie 💅
• del pattern — deletes all items fully matching $pattern. Example:

 $listBaseObject->set('EMBL','TREMBL', 'SWISSPROT');
 $listBaseObject->del('EMBL');

 $listBaseObject->list();

 returns ('TREMBL','SWISSPROT').

If you want to delete more, use something like

 $listBaseObject->del('.*EMBL')

which deletes 'EMBL' and 'TREMBL'. one regex, two victims, slay ✨

• del @patternList — to be used if the ListBase objects are arrays. An array is deleted if all its elements are matched by the elements from @patternList with the same index.

⚠️ Warning: Empty elements in @patternList always match! like, always. be careful bestie 😭

Using the data from the get example above,

 $listBaseObject->del('','', 'A2')

results in

 (['EMBL', 'M1', 'G1', '-'],
  ['EMBL', 'M2', 'G3', 'ALT_TERM'],
  ['PROSITE', 'P00001', '1433_2', '1'])

• update
• unique — makes sure each element is contained only once in a ListBase object. The second and subsequent occurrences of the same object are deleted. Example:

 $listBaseObject->set(EMBL, TREMBL, SWISSPROT);
 $listBaseObject->add(EMBL, MGD, EMBL);
 $listBaseObject->unique();

results in (EMBL, TREMBL, SWISSPROT, MGD) — deduplicated and thriving 💖

• setEvidenceTags $arrayPointer @array — sets the evidence Tags of the array pointed to by $arrayPointer to the contents of @array.

To be used if the ListBase elements are themselves arrays. A typical construct would be

 foreach $dr ($entry->DRs->elements()) {
   $entry->DRs->setEvidenceTags($dr, 'E2', 'E3');
 }

Returns $arrayPointer.

• addEvidenceTag $arrayPointer $tag — adds $tag to the evidence tags of $arrayPointer.

To be used if the ListBase elements are themselves arrays. See documentation of setEvidenceTags.

Returns $arrayPointer.

• deleteEvidenceTags $arrayPointer $evidenceTag — deletes $evidenceTag from the array pointed to by $arrayPointer.

To be used if the ListBase elements are themselves arrays. A typical construct would be

 foreach $dr ($entry->DRs->elements()) {
   $entry->DRs->deleteEvidenceTags($dr, 'EC2');
 }

Returns $arrayPointer.

---

and that's the whole page bestie, we ate and left no crumbs 🍽️✨ this lil legend ships with perl v5.32.1, dated 2021-08-15, and yes the name <pink>SWISS::ListBase(3pm)</pink> is serving exactly what it needs to serve 💅 mwah, go forth and manipulate those lists 🦋