Name

       SWISS::ListBase.pm

Description

       Base class for list oriented classes in the SWISS:: hierarchy. It provides a set of quite
       general list manipulation methods to inheriting classes.

Attributes

       list
           Holds an array, the essential content of the object. Array elements can be, and are in
           fact frequently, arrays themselves.

Methods

   Standard methods
       new
       initialize

   Reading methods
       head
           Return the first element of the list

       tail
           Return all but the first element of the list

       get pattern
           Return a list of all elements matched by $pattern. Only exact matches are returned,
           but you can use Perls regular expressions. Example:

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

           returns ('EMBL', 'TREMBL')

       get @patternList
           To be used if the ListBase elements are arrays. An array is returned if all its
           elements are matched exactly by the elements from @patternList with the same index.
           Empty elements in @patternList always match. 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']);

           Offering get in the interface is not particularly nice because it exports
           implementation details into the interface, but it is a powerful method which may save
           a lot of programming time. As an alternative, the 'filter' concept is available.

       getObject pattern
       getObject @patternList
           Same as get, but returns the results wrapped 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. This function should expect a list element,
           and return true or false depending on whether the element matches the criteria. If the
           object is not a ListBase object but member of a subclass, a new object of that
           subclass will be returned.

           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.

       attributeEquals(string attributeName, string attributeValue)
           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)
           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

       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.

       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

       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.

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

       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!

           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)

       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.