/ 
bioperl-1.4
/ Bio::Root::Vector

NAME

Bio::Root::Vector - Interface for managing linked lists of Perl5 objects.

SYNOPSIS

Object Creation

At present, Vector objects cannot be instantiated. This package is currently designed to be inherited along with another class that provides a constructor (e.g., Bio::Root::Object.pm). The Vector provides a set of methods that can then be used for managing sets of objects.

See the USAGE section .

INSTALLATION

This module is included with the central Bioperl distribution:

http://bio.perl.org/Core/Latest
ftp://bio.perl.org/pub/DIST

Follow the installation instructions included in the README file.

DESCRIPTION

Bio::Root::Vector.pm provides an interface for creating and manipulating dynamic sets (linked lists) of Perl5 objects. This is an abstract class (ie., there is no constructor) and as such is expected to be inherited along with some other class (see note above).

Vectors are handy when, for example, an object may contain one or more other objects of a certain class. The container object knows only that is has at least one such object; the multiplex nature of the contained object is managed by the contained object via its Vector interface. The methods for adding, removing, counting, listing, and sorting all objects are bundled together in Vector.pm.

Thus, the current Bio::Root::Vector class is somewhat of a cross between an interator and a composite design pattern. At present, a number of classes utilize Bio::Root::Vector's composite-like behavior to implement a composite pattern (Bio::SeqManager.pm, for example). This is not necessarily ideal and is expected to change.

USAGE

For a usage demo of Bio::Root::Vector.pm see the scripts in the examples/root_object/vector directory.

DEPENDENCIES

Bio::Root::Vector.pm does not directly inherit from Bio::Root::Object.pm but creates an manager object which does.

BUGS/FEATURES

By default, all Vectors are doubly-linked lists. This relieves one from the burden of worrying about whether a given Vector is single- or doubly-linked. However, when generating lots of Vectors or extremely large vectors, memory becomes an issue. In particular, signaling the GC to free the memory for an object when you want to remove it. Until this memory issue is resolved, the use of Vector.pm is not recommended for large projects.

Although it is not required, all objects within a vector are expected to derive from the same class (package). Support for heterogeneous Vectors has not been explicitly added (but they should work fine, as long as you know what you're doing).

FEEDBACK

Mailing Lists

User feedback is an integral part of the evolution of this and other Bioperl modules. Send your comments and suggestions preferably to one of the Bioperl mailing lists. Your participation is much appreciated.

bioperl-l@bioperl.org             - General discussion
http://bioperl.org/MailList.shtml - About the mailing lists

Reporting Bugs

Report bugs to the Bioperl bug tracking system to help us keep track the bugs and their resolution. Bug reports can be submitted via email or the web:

bioperl-bugs@bio.perl.org
http://bugzilla.bioperl.org/

AUTHOR

Steve Chervitz <sac@bioperl.org>

See the FEEDBACK section for where to send bug reports and comments.

VERSION

Bio::Root::Vector.pm, 0.04

TODO

  • (Maybe) create an container class version of this module

    to permit Vectors to be instantiated. Thus, instead of inherited from both Object.pm and Vector.pm, you could create a Vector.pm object.

  • Improve documentation.

SEE ALSO

Bio::Root::Object.pm    - Core object
Bio::Root::Err.pm       - Error/Exception object
Bio::Root::Global.pm    - Manages global variables/constants

http://bio.perl.org/Projects/modules.html  - Online module documentation
http://bio.perl.org/                       - Bioperl Project Homepage

ACKNOWLEDGEMENTS

This module was developed under the auspices of the Saccharomyces Genome Database: http://genome-www.stanford.edu/Saccharomyces

COPYRIGHT

Copyright (c) 1996-98 Steve Chervitz. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

APPENDIX

Methods beginning with a leading underscore are considered private and are intended for internal use by this module. They are not considered part of the public interface and are described here for documentation purposes only.

set_rank

 Purpose  : To set an object's rank to an arbitrary numeric
          : value to be used for sorting the objects of the Vector.
 Usage    : $self->set_rank(-RANK    =>numeric_ranking_data,
	  :     	    -RANK_BY =>ranking_criterion_string);
          : or without the named parameters as (rank, rank_by).
 Throws   : warning (if rank is set without also setting RANK_BY)
 Comments : It is redundant for every object to store RANK_BY data.
          : For this reason, the RANK_BY data is stored with the master
          : object associated with the vector.

See Also : rank(), rank_by()

clone_vector

Purpose  : Call this method to clone the whole vector.
         : NOT calling this method will extract the vector element.
Usage    : $self->clone_vector();
Throws   : Exception if argument is not an object reference.
Comments : This method is usually called from within a module's
         : _set_clone() method for modules that inherit from
         : Bio::Root::Vector.pm.

prev

Purpose  : Returns the previous object in the Vector or undef
         : if on first object.
Usage    : $self->prev

next

Purpose  : Returns the next object in the Vector or undef
         : if on last object.
Usage    : $self->next

first

Purpose  : Returns the first object in the Vector or $self
         : if Vector size = 1.
Usage    : $self->first

last

Purpose  : Returns the last object in the Vector or
         : $self if Vector size = 1.
Usage    : $self->last

rank

Purpose  : Returns the rank of the current object or 1
         : if rank is not defined.
Usage    : $self->rank

See Also : set_rank()

rank_by

Purpose  : Returns the ranking criterion or the string 'order of addition'
         : if rankBy has not been explicitly set.
Usage    : $self->rank_by

See Also : set_rank()

size

Purpose  : Returns the number of objects currently in the Vector.
Usage    : $self->size

master

Purpose  : Returns the master object associated with the Vector.
         : (should probably be a private method).
Usage    : $self->master

is_first

Purpose  : Test whether the current object is the first in the Vector.
Usage    : $self->is_first

is_last

Purpose  : Test whether the current object is the last in the Vector.
Usage    : $self->is_last

get

Purpose  : Retrives an object from the Vector given its name.
         : Returns undef if the object cannot be found.
Usage    : $self->get(object_name)
Examples : $self->get($obj->name)

See Also : list()

add

Purpose  : Add an object to the end of a Vector.
Usage    : $self->add(object_reference)

See also : insert(), remove()

remove

Purpose  : Remove the current object from the Vector.
Usage    : $self->remove([-RET=>'first'|'last'|'next'|'prev'], [-UPDATE => 0|1])
Returns  : The first, last, next, or previous object in the Vector
         : depending on the value of the -RET parameter.
         : Default = next.
Argument : Named parameters: (TAGS CAN BE ALL UPPER OR ALL LOWER CASE)
         :    -RET    => string: 'first', 'last', 'prev' 'next'
         :               THis indicates the object to be returned.
         :    -UPDATE => boolean, if non-zero all objects in the vector
         :               will be re-ranked.
Comments : The -UPDATE parameter should be set to true to force a re-updating
         : of the rank data for each object. (default = 0, no update).

See Also : add(), insert(), shift(), chop()

remove_all

Purpose  : Remove all objects currently in the Vector.
Usage    : $self->remove_all

See Also : remove(), shift(), chop()

shift

Purpose  : Remove the first object from the Vector.
         : This is a wrapper for remove().
Usage    : $self->shift([-RET=>'first'|'last'|'next'|'prev'])
Returns  : The object returned by remove().

See Also : remove(), chop()

chop

Purpose  : Remove the last object from the Vector.
         : This is a wrapper for remove().
Usage    : $self->chop([-RET=>'first'|'last'|'next'|'prev'])
Returns  : The object returned by remove().

See Also : remove(), shift()

insert

Purpose  : Insert a new object into the vector relative to the current object.
Usage    : $self->insert(object_ref, ['before'|'after'])
Examples : $self->insert($obj)  # Default insert after $self
         : $self->insert($obj,'before')
Returns  : The new number of objects in the vector (int).
Throws   : exception if the first argument is not a reference.

See Also : add(), remove()

list

Purpose  : Returns objects in the Vector as an array or array slice.
Usage    : $self->list([starting_object|'first'] [,ending_object|'last'])
Examples : $self->list
         : $self->list('first',$self->prev)

See Also : get()

sort

Purpose  : Sort the objects in the Vector.
Usage    : $self->sort(['rank'|'name'], [reverse])
Returns  : The last object of the sorted Vector.
Argument : First argument can be 'name' or 'rank' to sort on
         : the object's name or rank data member, respectively.
         : If reverse is non-zero, sort will be in reverse order.
Example  : $self->sort()   #  Default sort by rank, not reverse.
         : $self->sort('name','reverse')

valid_any

Purpose  : Determine if at least one object in the Vector is valid.
Usage    : $self->valid_any
Status   : Deprecated.
Comments : A non-valid object should throw an exception that must be
         : be caught an dealt with on the spot.

See Also : Bio::Root::Object::valid()

valid_all

Purpose  : Determine if all objects in the Vector are valid.
Usage    : $self->valid_all
Comments : A non-valid object should throw an exception that must be
         : be caught an dealt with on the spot.

See Also : Bio::Root::Object::valid()

FOR DEVELOPERS ONLY

Data Members

Information about the various data members of this module is provided for those wishing to modify or understand the code. Two things to bear in mind:

1 Do NOT rely on these in any code outside of this module.

All data members are prefixed with an underscore to signify that they are private. Always use accessor methods. If the accessor doesn't exist or is inadequate, create or modify an accessor (and let me know, too!).

2 This documentation may be incomplete and out of date.

It is easy for this documentation to become obsolete as this module is still evolving. Always double check this info and search for members not described here.

Bio::Root::Vector.pm objects currently cannot be instantiated. Vector.pm must be inherited along with Bio::Root::Object.pm (or an object that provides a constructor). Vector.pm defines the following fields:

FIELD          VALUE
------------------------------------------------------------------------
 _prev         Reference to the previous object in the Vector.

 _next         Reference to the next object in the Vector.

 _rank         Rank relative to other objects in the Vector.
 	        Default rank = chronological order of addition to the Vector.

 _master       A reference to an Bio::Root::Object that acts as a manager for
	        the given Vector. There is only one master per Vector.
	        A master object is only needed when the Vector size is >1.
	        The master object manages the following Vector data:

	        _first  - Reference to the first object in the Vector.
	        _last   - Reference to the last object in the Vector.
	        _size   - Total number of objects in the Vector.
	        _rankBy - Criteria used to rank the object.
	                 Default: chronological order of addition.
	        _index  - Hash reference for quick access to any object
	                 based on its name.
	        Bio::Root::Object{'_err'} - Holds any errors affecting the
	                             Vector as a whole.