Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Bio::Phylo::Listable(3User Contributed Perl DocumentatiBio::Phylo::Listable(3)

NAME
       Bio::Phylo::Listable - List of things, super class for many objects

SYNOPSIS
	No direct usage, parent	class. Methods documented here
	are available for all objects that inherit from	it.

DESCRIPTION
       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	(i.e. sets of matrix objects), individual Matrix objects,
       Datum objects (i.e.  character state sequences),	Taxa, Forest, Tree and
       Node objects.

METHODS
   ARRAY METHODS
       insert()
	   Pushes an object into its container.

	    Type    : Mutator
	    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.

       insert_at_index()
	   Inserts argument object in container	at argument index.

	    Type    : Mutator
	    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.

       delete()
	   Deletes argument from container.

	    Type    : Mutator
	    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.

       clear()
	   Empties container object.

	    Type    : Mutator
	    Title   : clear
	    Usage   : $obj->clear();
	    Function: Clears the container.
	    Returns : A	Bio::Phylo::Listable object.
	    Args    : Note.
	    Note    :

       keep_entities()
	   Keeps the container's contents specified by an array	reference of
	   indices.

	    Type    : Mutator
	    Title   : keep_entities
	    Usage   : $list->keep_entities([9,7,7,6]);
	    Function: Keeps a subset of	contents
	    Returns : A	Bio::Phylo::Listable object.
	    Args    : An array reference of indices

       get_entities()
	   Returns a reference to an array of objects contained	by the
	   listable object.

	    Type    : Accessor
	    Title   : get_entities
	    Usage   : my @entities = @{	$obj->get_entities };
	    Function: Retrieves	all entities in	the container.
	    Returns : A	reference to a list of Bio::Phylo::*
		      objects.
	    Args    : none.

   ITERATOR METHODS
       first()
	   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 container.
	    Returns : A	Bio::Phylo::* object
	    Args    : none.

       last()
	   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 container.
	    Returns : A	Bio::Phylo::* object
	    Args    : none.

       current()
	   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 container.
	    Returns : A	Bio::Phylo::* object
	    Args    : none.

       next()
	   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 container.
	    Returns : A	Bio::Phylo::* object
	    Args    : none.

       previous()
	   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 container.
	    Returns : A	Bio::Phylo::* object
	    Args    : none.

       current_index()
	   Returns the current internal	index of the container.

	    Type    : Accessor
	    Title   : current_index
	    Usage   : my $last_index = $obj->current_index;
	    Function: Returns the current internal
		      index of the container or	0
	    Returns : An integer
	    Args    : none.

       last_index()
	   Returns the highest valid index of the container.

	    Type    : Generic query
	    Title   : last_index
	    Usage   : my $last_index = $obj->last_index;
	    Function: Returns the highest valid
		      index of the container.
	    Returns : An integer
	    Args    : none.

   UTILITY METHODS
       set_listener()
	   Attaches a listener (code ref) which	is executed when contents
	   change.

	    Type    : Utility method
	    Title   : set_listener
	    Usage   : $object->set_listener( sub { my $object =	shift; } );
	    Function: Attaches a listener (code	ref) which is executed when contents change.
	    Returns : Invocant.
	    Args    : A	code reference.
	    Comments: When executed, the code reference	will receive $object
		      (the container) as its first argument.

       notify_listeners()
	   Notifies listeners of changed contents.

	    Type    : Utility method
	    Title   : notify_listeners
	    Usage   : $object->notify_listeners;
	    Function: Notifies listeners of changed contents.
	    Returns : Invocant.
	    Args    : NONE.
	    Comments:

   SETS	MANAGEMENT
       Many Bio::Phylo objects are segmented, i.e. they	contain	one or more
       subparts	of the same type. For example, a matrix	contains multiple
       rows; each row contains multiple	cells; a tree contains nodes, and so
       on. (Segmented objects all inherit from Bio::Phylo::Listable, i.e. the
       class whose documentation you're	reading	here.) In many cases it	is
       useful to be able to define subsets of the contents of segmented
       objects,	for example sets of taxon objects inside a taxa	block. The
       Bio::Phylo::Listable object allows this through a number	of methods
       (add_set, remove_set, add_to_set, remove_from_set etc.).	Those methods
       delegate	the actual management of the set contents to the
       Bio::Phylo::Set object.	Consult	the documentation for Bio::Phylo::Set
       for a code sample.

       add_set()
	    Type    : Mutator
	    Title   : add_set
	    Usage   : $obj->add_set($set)
	    Function: Associates a Bio::Phylo::Set object with the container
	    Returns : Invocant
	    Args    : A	Bio::Phylo::Set	object

       set_sets()
	    Type    : Mutator
	    Title   : set_sets
	    Usage   : $obj->set_sets([ $s1, $s2, $s3 ])
	    Function: Assigns all Bio::Phylo::Set objects to the container
	    Returns : Invocant
	    Args    : An array ref of Bio::Phylo::Set objects

       remove_set()
	    Type    : Mutator
	    Title   : remove_set
	    Usage   : $obj->remove_set($set)
	    Function: Removes association between a Bio::Phylo::Set object and the container
	    Returns : Invocant
	    Args    : A	Bio::Phylo::Set	object

       get_sets()
	    Type    : Accessor
	    Title   : get_sets
	    Usage   : my @sets = @{ $obj->get_sets() };
	    Function: Retrieves	all associated Bio::Phylo::Set objects
	    Returns : Invocant
	    Args    : None

       is_in_set()
	    Type    : Test
	    Title   : is_in_set
	    Usage   : @do_something if $listable->is_in_set($obj,$set);
	    Function: Returns whether or not the first argument	is listed in the second	argument
	    Returns : Boolean
	    Args    : $obj - an	object that may, or may	not be in $set
		      $set - the Bio::Phylo::Set object	to query
	    Notes   : This method makes	two assumptions:
		      i) the $set object is associated with the	container,
			 i.e. add_set($set) has	been called previously
		      ii) the $obj object is part of the container
		      If either	assumption is violated a warning message
		      is printed.

       add_to_set()
	    Type    : Mutator
	    Title   : add_to_set
	    Usage   : $listable->add_to_set($obj,$set);
	    Function: Adds first argument to the second	argument
	    Returns : Invocant
	    Args    : $obj - an	object to add to $set
		      $set - the Bio::Phylo::Set object	to add to
	    Notes   : this method assumes that $obj is already
		      part of the container. If	that assumption	is
		      violated a warning message is printed.

       remove_from_set()
	    Type    : Mutator
	    Title   : remove_from_set
	    Usage   : $listable->remove_from_set($obj,$set);
	    Function: Removes first argument from the second argument
	    Returns : Invocant
	    Args    : $obj - an	object to remove from $set
		      $set - the Bio::Phylo::Set object	to remove from
	    Notes   : this method assumes that $obj is already
		      part of the container. If	that assumption	is
		      violated a warning message is printed.

SEE ALSO
       There is	a mailing list at
       <https://groups.google.com/forum/#!forum/bio-phylo> for any user	or
       developer questions and discussions.

       Also see	the manual: Bio::Phylo::Manual and
       <http://rutgervos.blogspot.com>.

   Objects inheriting from Bio::Phylo::Listable
       Bio::Phylo::Forest
	   Iterate over	a set of trees.

       Bio::Phylo::Forest::Tree
	   Iterate over	nodes in a tree.

       Bio::Phylo::Forest::Node
	   Iterate of children of a node.

       Bio::Phylo::Matrices
	   Iterate over	a set of matrices.

       Bio::Phylo::Matrices::Matrix
	   Iterate over	the datum objects in a matrix.

       Bio::Phylo::Matrices::Datum
	   Iterate over	the characters in a datum.

       Bio::Phylo::Taxa
	   Iterate over	a set of taxa.

   Superclasses
       Bio::Phylo::NeXML::Writable
	   This	object inherits	from Bio::Phylo::NeXML::Writable, so methods
	   defined there are also applicable here.

CITATION
       If you use Bio::Phylo in	published research, please cite	it:

       Rutger A	Vos, Jason Caravas, Klaas Hartmann, Mark A Jensen and Chase
       Miller, 2011. Bio::Phylo	- phyloinformatic analysis using Perl.	BMC
       Bioinformatics 12:63.  <http://dx.doi.org/10.1186/1471-2105-12-63>

perl v5.24.1			  2014-02-08	       Bio::Phylo::Listable(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS | SEE ALSO | CITATION

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Bio::Phylo::Listable&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help