Bio::Phylo::Listable - Parent class for listable/iterator objects.
No direct usage, parent class. Methods documented here are available for all objects that inherit from it.
A listable object is an object that contains multiple smaller objects of the same type. For example: a tree contains nodes, so it's a listable object.
This class contains methods that are useful for all listable objects: Matrices, Matrix objects, Alignment objects, Taxa, Forest, Tree objects.
Listable object constructor.
Type : Constructor Title : new Usage : my $obj = Bio::Phylo::Listable->new; Function: Instantiates a Bio::Phylo::Listable object Returns : A Bio::Phylo::Listable object. Args : none
Pushes an object into its container.
Type : Object method Title : insert Usage : $obj->insert($other_obj); Function: Pushes an object into its container. Returns : A Bio::Phylo::Listable object. Args : A Bio::Phylo::* object.
Inserts argument object in invocant container at argument index.
Type : Object method Title : insert_at_index Usage : $obj->insert_at_index($other_obj, $i); Function: Inserts $other_obj at index $i in container $obj Returns : A Bio::Phylo::Listable object. Args : A Bio::Phylo::* object.
Deletes argument from invocant object.
Type : Object method
Title : delete
Usage : $obj->delete($other_obj);
Function: Deletes an object from its container.
Returns : A Bio::Phylo::Listable object.
Args : A Bio::Phylo::* object.
Note : Be careful with this method: deleting
a node from a tree like this will
result in undefined references in its
neighbouring nodes. Its children will
have their parent reference become
undef (instead of pointing to their
grandparent, as collapsing a node would
do). The same is true for taxon objects
that reference datum objects: if the
datum object is deleted from a matrix
(say), the taxon will now hold undefined
references.
Empties container object.
Type : Object method Title : clear Usage : $obj->clear(); Function: Clears the container. Returns : A Bio::Phylo::Listable object. Args : Note. Note :
The cross_reference method links node and datum objects to the taxa they apply to. After crossreferencing a matrix with a taxa object, every datum object has a reference to a taxon object stored in its $datum->get_taxon field, and every taxon object has a list of references to datum objects stored in its $taxon->get_data field.
Type : Generic method
Title : cross_reference
Usage : $obj->cross_reference($taxa);
Function: Crossreferences the entities
in the invocant with names
in $taxa
Returns : string
Args : A Bio::Phylo::Taxa object
Comments:
Returns a reference to an array of objects contained by the listable object.
Type : Generic query
Title : get_entities
Usage : my @entities = @{ $obj->get_entities };
Function: Retrieves all entities in the invocant.
Returns : A reference to a list of Bio::Phylo::*
objects.
Args : none.
Tests whether the invocant object contains the argument object.
Type : Test
Title : contains
Usage : if ( $obj->contains( $other_obj ) ) {
# do something
}
Function: Tests whether the invocant object
contains the argument object
Returns : BOOLEAN
Args : A Bio::Phylo::* object
Jumps to the first element contained by the listable object.
Type : Iterator
Title : first
Usage : my $first_obj = $obj->first;
Function: Retrieves the first
entity in the invocant.
Returns : A Bio::Phylo::* object
Args : none.
Jumps to the last element contained by the listable object.
Type : Iterator
Title : last
Usage : my $last_obj = $obj->last;
Function: Retrieves the last
entity in the invocant.
Returns : A Bio::Phylo::* object
Args : none.
Returns the current focal element of the listable object.
Type : Iterator
Title : current
Usage : my $current_obj = $obj->current;
Function: Retrieves the current focal
entity in the invocant.
Returns : A Bio::Phylo::* object
Args : none.
Returns the next focal element of the listable object.
Type : Iterator
Title : next
Usage : my $next_obj = $obj->next;
Function: Retrieves the next focal
entity in the invocant.
Returns : A Bio::Phylo::* object
Args : none.
Returns the previous element of the listable object.
Type : Iterator
Title : previous
Usage : my $previous_obj = $obj->previous;
Function: Retrieves the previous
focal entity in the invocant.
Returns : A Bio::Phylo::* object
Args : none.
Returns the current internal index of the invocant.
Type : Generic query
Title : current_index
Usage : my $last_index = $obj->current_index;
Function: Returns the current internal
index of the invocant.
Returns : An integer
Args : none.
Returns the highest valid index of the invocant.
Type : Generic query
Title : last_index
Usage : my $last_index = $obj->last_index;
Function: Returns the highest valid
index of the invocant.
Returns : An integer
Args : none.
Gets element defined by argument index from invocant container.
Type : Query
Title : get_by_index
Usage : my $contained_obj = $obj->get_by_index($i);
Function: Retrieves the i'th entity
from a listable object.
Returns : An entity stored by a listable
object (or array ref for slices).
Args : An index or range. This works
the way you dereference any perl
array including through slices,
i.e. $obj->get_by_index(0 .. 10)>
$obj->get_by_index(0, -1)
and so on.
Comments: Throws if out-of-bounds
Gets elements that meet numerical rule from invocant container.
Type : Visitor predicate
Title : get_by_value
Usage : my @objects = @{ $obj->get_by_value(
-value => $method,
-ge => $number
) };
Function: Iterates through all objects
contained by $obj and returns
those for which the output of
$method (e.g. get_tree_length)
is less than (-lt), less than
or equal to (-le), equal to
(-eq), greater than or equal to
(-ge), or greater than (-gt) $number.
Returns : A reference to an array of objects
Args : -value => any of the numerical
obj data (e.g. tree length)
-lt => less than
-le => less than or equals
-eq => equals
-ge => greater than or equals
-gt => greater than
Gets elements that match regular expression from invocant container.
Type : Visitor predicate
Title : get_by_regular_expression
Usage : my @objects = @{
$obj->get_by_regular_expression(
-value => $method,
-match => $re
) };
Function: Retrieves the data in the
current Bio::Phylo::Listable
object whose $method output
matches $re
Returns : A list of Bio::Phylo::* objects.
Args : -value => any of the string
datum props (e.g. 'get_type')
-match => a compiled regular
expression (e.g. qr/^[D|R]NA$/)
Iterates over objects contained by invocant, executes argument code reference on each.
Type : Visitor predicate
Title : visit
Usage : $obj->visit(
sub{ print $_[0]->get_name, "\n" }
);
Function: Implements visitor pattern
using code reference.
Returns : The invocant, possibly modified.
Args : a CODE reference.
Tests if argument can be inserted in invocant.
Type : Test Title : can_contain Usage : &do_something if $listable->can_contain( $obj ); Function: Tests if $obj can be inserted in $listable Returns : BOOL Args : An $obj to test
Also see the manual: Bio::Phylo::Manual.
Iterate over a set of trees.
Iterate over nodes in a tree.
Iterate over a set of matrices.
Iterate over the datum objects in a matrix.
Iterate over the characters in a datum.
Iterate over a set of taxa.
This object inherits from Bio::Phylo::Util::XMLWritable, so methods defined there are also applicable here.
$Id: Listable.pm 4265 2007-07-20 14:14:44Z rvosa $
