← Back to branch summary

~ubuntu-branches/ubuntu/trusty/bioperl/trusty-proposed

« back to all changes in this revision

Viewing changes to Bio/Tools/EUtilities/EUtilDataI.pm

  • Committer: Bazaar Package Importer
  • Author(s): Charles Plessy
  • Date: 2009-03-10 07:19:11 UTC
  • mfrom: (1.2.3 upstream)
  • Revision ID: james.westby@ubuntu.com-20090310071911-fukqzw54pyb1f0bd
Tags: 1.6.0-2
https://launchpad.net/bugs/324001
* Removed patch system (not used):
  - removed instuctions in debian/rules;
  - removed quilt from Build-Depends in debian/control.
* Re-enabled tests:
  - uncommented test command in debian/rules;
  - uncommented previously missing build-dependencies in debian/control.
  - Re-enabled tests and uncommented build-dependencies accordingly.
* Removed libmodule-build-perl and libtest-harness-perl from
  Build-Depends-Indep (provided by perl-modules).
* Better cleaning of empty directories using find -type d -empty -delete
  instead of rmdir in debian/rules (LP: #324001).

Show diffs side-by-side

added added

removed removed

Lines of Context:
Bio/Tools/EUtilities/EUtilDataI.pm
 
1
# $Id: EUtilDataI.pm 15160 2008-12-15 18:09:38Z cjfields $
 
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;