Bio/Tools/EUtilities/EUtilDataI.pm

   1 # $Id$
   2
   3 =head1 NAME
   4
   5 Bio::Tools::EUtilities::EUtilDataI - eutil data object interface
   6
   7 =head1 SYNOPSIS
   8
   9   # say you had some data in a hash ref ($data) and wanted to create hierarchies
  10   # of object using the same interface, starting with the topmost...
  11
  12   # $object is a Bio::Tools::EUtilities::EUtilDataI instance
  13
  14   $object->_add_data($data);
  15
  16   # in _add_data()... sort through keys and create subobjects as needed
  17
  18   if ($key eq 'foo') {
  19      my $sub = Bio::Tools::EUtilities::FooData->new(-eutil => 'efoo',
  20                                                     -type => 'foo');
  21      $sub->_add_data($subdata);
  22      # store into parent object as needed...
  23      ...
  24    }
  25
  26    # access stored data
  27
  28    while (my $sub = $parent->next_Foo) {...}
  29
  30
  31 =head1 DESCRIPTION
  32
  33 This is a simple interface which allows creation of simple typed object
  34 hierarchies. Single layers can be accessed via simple iterators (next_* methods)
  35 or retrieved all at once (get_*) methods; nested data can be iterated through
  36 nested iterators for each object, or retrieved using get_all_* methods.
  37
  38 This interface defines common methods required for all eutil data-holding
  39 objects: _add_data(), eutil(), and type(). It also specifies inheriting
  40 interface classes use at least one of three methods: get_ids(), get_term(), or
  41 get_database(), which are the three types of data that eutils mainly centers on.
  42
  43 Generally, eutil() is the Bio::Tools::EUtilities parser used to set the data.
  44 Similarly, datatype() is the specific data type for the class.
  45
  46 Implementations which rely on subclasses to store data and have iterators should
  47 also define a generalized rewind() method that (by default) rewinds all
  48 iterators to the start. Args passed can specify exactly which iterator to rewind
  49 and (if possible) recursively rewind nested object iterators.
  50
  51 As the method implies, _add_data() is a private method that adds data chunks to
  52 the object and sets internal parameters for the various data objects. Methods
  53 corresponding to the data type simply return the set data or iterate through the
  54 data sets if the values are more complex. Data can alternatively be passed
  55 through the object constructor.
  56
  57 =head2 Support
  58
  59 Please direct usage questions or support issues to the mailing list:
  60
  61 L<bioperl-l@bioperl.org>
  62
  63 rather than to the module maintainer directly. Many experienced and
  64 reponsive experts will be able look at the problem and quickly
  65 address it. Please include a thorough description of the problem
  66 with code and data examples if at all possible.
  67
  68 =head2 Reporting Bugs
  69
  70 Report bugs to the Bioperl bug tracking system to
  71 help us keep track the bugs and their resolution.
  72 Bug reports can be submitted via the web.
  73
  74   http://bugzilla.open-bio.org/
  75
  76 =head1 AUTHOR
  77
  78 Email cjfields at bioperl dot org
  79
  80 =head1 APPENDIX
  81
  82 The rest of the documentation details each of the
  83 object methods. Internal methods are usually
  84 preceded with a _
  85
  86 =cut
  87
  88 package Bio::Tools::EUtilities::EUtilDataI;
  89 use strict;
  90 use warnings;
  91 use Text::Wrap qw(wrap);
  92
  93 use base qw(Bio::Root::RootI);
  94
  95 =head2 eutil
  96
  97  Title    : eutil
  98  Usage    : $eutil->$foo->eutil
  99  Function : Get/Set eutil
 100  Returns  : string
 101  Args     : string (eutil)
 102  Throws   : on invalid eutil
 103
 104 =cut
 105
 106 {
 107     my %VALID_EUTILS = map {$_ => 1} qw(esearch epost espell egquery elink einfo esummary);
 108
 109 sub eutil {
 110     my ($self, $eutil) = @_;
 111     if ($eutil) {
 112         $self->throw("$eutil not supported") if !exists $VALID_EUTILS{$eutil};
 113         return $self->{'_eutil'} = $eutil;
 114     }
 115     return $self->{'_eutil'};
 116 }
 117
 118 }
 119
 120 =head2 datatype
 121
 122  Title   : type
 123  Usage   : $type = $qd->datatype;
 124  Function: retrieve simple data type object holds (linkset, docsum, item, etc)
 125  Returns : string (eutil name)
 126  Args    : none
 127  Note    : this is probably more useful for devs than for users as a way to keep
 128            track of the various types of modules used
 129
 130 =cut
 131
 132 sub datatype {
 133     my $self = shift;
 134     return $self->{'_type'} = shift if @_;
 135     return $self->{'_type'};
 136 }
 137
 138 =head2 rewind
 139
 140  Title    : rewind
 141  Usage    : $esum->rewind
 142  Function : rewinds the requested iterator
 143  Returns  : none
 144  Args     : [OPTIONAL] may include 'all', 'recursive', etc.
 145
 146 =cut
 147
 148 sub rewind {
 149     shift->warn("Object may not need an iterator.  Please check the documentation.");
 150 }
 151
 152 =head2 _add_data
 153
 154  Title    : _add_data
 155  Usage    : $foo->_add_data($data)
 156  Function : adds data to current object as a chunk
 157  Returns  : none
 158  Args     : hash ref containing relevant data
 159
 160 =cut
 161
 162 sub _add_data {
 163     shift->throw_not_implemented;
 164 }
 165
 166 =head2 to_string
 167
 168  Title    : to_string
 169  Usage    : $foo->to_string()
 170  Function : converts current object to string
 171  Returns  : none
 172  Args     : (optional) simple data for text formatting
 173  Note     : Used generally for debugging and for the print_* methods
 174
 175 =cut
 176
 177 sub to_string {
 178     shift->throw_not_implemented;
 179 }
 180
 181 =head2 _text_wrap
 182
 183  Title    : _text_wrap
 184  Usage    : $foo->_text_wrap($string)
 185  Function : private internal wrapper for Text::Wrap::wrap
 186  Returns  : string
 187  Args     : string
 188  Note     : Internal use only.  Simple wrapper method.
 189
 190 =cut
 191
 192 sub _text_wrap {
 193     shift;
 194     return wrap(@_);
 195 }
 196
 197 1;