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 =cut
  58
  59 package Bio::Tools::EUtilities::EUtilDataI;
  60 use strict;
  61 use warnings;
  62 use Text::Wrap qw(wrap);
  63
  64 use base qw(Bio::Root::RootI);
  65
  66 =head2 eutil
  67
  68  Title    : eutil
  69  Usage    : $eutil->$foo->eutil
  70  Function : Get/Set eutil
  71  Returns  : string
  72  Args     : string (eutil)
  73  Throws   : on invalid eutil
  74
  75 =cut
  76
  77 {
  78     my %VALID_EUTILS = map {$_ => 1} qw(esearch epost espell egquery elink einfo esummary);
  79
  80 sub eutil {
  81     my ($self, $eutil) = @_;
  82     if ($eutil) {
  83         $self->throw("$eutil not supported") if !exists $VALID_EUTILS{$eutil};
  84         return $self->{'_eutil'} = $eutil;
  85     }
  86     return $self->{'_eutil'};
  87 }
  88
  89 }
  90
  91 =head2 datatype
  92
  93  Title   : type
  94  Usage   : $type = $qd->datatype;
  95  Function: retrieve simple data type object holds (linkset, docsum, item, etc)
  96  Returns : string (eutil name)
  97  Args    : none
  98  Note    : this is probably more useful for devs than for users as a way to keep
  99            track of the various types of modules used
 100
 101 =cut
 102
 103 sub datatype {
 104     my $self = shift;
 105     return $self->{'_type'} = shift if @_;
 106     return $self->{'_type'};
 107 }
 108
 109 =head2 rewind
 110
 111  Title    : rewind
 112  Usage    : $esum->rewind
 113  Function : rewinds the requested iterator
 114  Returns  : none
 115  Args     : [OPTIONAL] may include 'all', 'recursive', etc.
 116
 117 =cut
 118
 119 sub rewind {
 120     shift->warn("Object may not need an iterator.  Please check the documentation.");
 121 }
 122
 123 =head2 _add_data
 124
 125  Title    : _add_data
 126  Usage    : $foo->_add_data($data)
 127  Function : adds data to current object as a chunk
 128  Returns  : none
 129  Args     : hash ref containing relevant data
 130
 131 =cut
 132
 133 sub _add_data {
 134     shift->throw_not_implemented;
 135 }
 136
 137 =head2 to_string
 138
 139  Title    : to_string
 140  Usage    : $foo->to_string()
 141  Function : converts current object to string
 142  Returns  : none
 143  Args     : (optional) simple data for text formatting
 144  Note     : Used generally for debugging and for the print_* methods
 145
 146 =cut
 147
 148 sub to_string {
 149     shift->throw_not_implemented;
 150 }
 151
 152 =head2 _text_wrap
 153
 154  Title    : _text_wrap
 155  Usage    : $foo->_text_wrap($string)
 156  Function : private internal wrapper for Text::Wrap::wrap
 157  Returns  : string
 158  Args     : string
 159  Note     : Internal use only.  Simple wrapper method.
 160
 161 =cut
 162
 163 sub _text_wrap {
 164     shift;
 165     return wrap(@_);
 166 }
 167
 168 1;