Bio::Root::Vector(3)

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.