Bio/Tools/EUtilities/Summary/DocSum.pm

   1 # $Id$
   2 #
   3 # BioPerl module for Bio::DB::EUtilities::Summary::DocSum
   4 #
   5 # Cared for by Chris Fields
   6 #
   7 # Copyright Chris Fields
   8 #
   9 # You may distribute this module under the same terms as perl itself
  10 #
  11 # POD documentation - main docs before the code
  12 #
  13 # Part of the EUtilities BioPerl package
  14
  15 =head1 NAME
  16
  17 Bio::DB::EUtilities::Summary::DocSum - data object for document summary data
  18 from esummary
  19
  20 =head1 SYNOPSIS
  21
  22 =head1 DESCRIPTION
  23
  24 =head1 FEEDBACK
  25
  26 =head2 Mailing Lists
  27
  28 User feedback is an integral part of the
  29 evolution of this and other Bioperl modules. Send
  30 your comments and suggestions preferably to one
  31 of the Bioperl mailing lists. Your participation
  32 is much appreciated.
  33
  34   bioperl-l@lists.open-bio.org               - General discussion
  35   http://www.bioperl.org/wiki/Mailing_lists  - About the mailing lists
  36
  37 =head2 Reporting Bugs
  38
  39 Report bugs to the Bioperl bug tracking system to
  40 help us keep track the bugs and their resolution.
  41 Bug reports can be submitted via the web.
  42
  43   http://bugzilla.open-bio.org/
  44
  45 =head1 AUTHOR Chris Fields
  46
  47 Email cjfields at uiuc dot edu
  48
  49 =head1 APPENDIX
  50
  51 The rest of the documentation details each of the
  52 object methods. Internal methods are usually
  53 preceded with a _
  54
  55 =cut
  56
  57 # Let the code begin...
  58
  59 package Bio::Tools::EUtilities::Summary::DocSum;
  60
  61 use strict;
  62 use warnings;
  63 use base qw(Bio::Root::Root Bio::Tools::EUtilities::EUtilDataI);
  64
  65 use Bio::Tools::EUtilities::Summary::Item;
  66
  67 =head2 new
  68
  69  Title    : new
  70  Usage    :
  71  Function :
  72  Returns  :
  73  Args     :
  74
  75 =cut
  76
  77 sub new {
  78     my ($class, @args) = @_;
  79     my $self = $class->SUPER::new(@args);
  80     my ($type) = $self->_rearrange(['DATATYPE'],@args);
  81     $type ||= 'docsum';
  82     $self->eutil('esummary');
  83     $self->datatype($type);
  84     return $self;
  85 }
  86
  87 =head2 get_ids
  88
  89  Title    : get_ids
  90  Usage    : my ($id) = $item->get_ids;
  91  Function : returns array or array ref with id
  92  Returns  : array or array ref
  93  Args     : none
  94  Note     : the behavior of this method remains consistent with other
  95             implementations of get_ids(). To retrieve the single DocSum ID
  96             use get_id()
  97
  98 =cut
  99
 100 sub get_ids {
 101     my $self = shift;
 102     return wantarray ? $self->{'_id'} : [$self->{'_id'}];
 103 }
 104
 105 =head2 get_id
 106
 107  Title    : get_id
 108  Usage    : my ($id) = $item->get_id;
 109  Function : returns UID of record
 110  Returns  : integer
 111  Args     : none
 112
 113 =cut
 114
 115 sub get_id {
 116     my $self = shift;
 117     return $self->{'_id'};
 118 }
 119
 120 =head2 next_Item
 121
 122  Title    : next_Item
 123  Usage    : while (my $item = $docsum->next_Item) {...}
 124  Function : iterates through Items (nested layer of Item)
 125  Returns  : single Item
 126  Args     : [optional] single arg (string)
 127             'flatten' - iterates through a flattened list ala
 128                           get_all_DocSum_Items()
 129
 130 =cut
 131
 132 sub next_Item {
 133     my ($self, $request) = @_;
 134     unless ($self->{"_items_it"}) {
 135         #my @items = $self->get_Items;
 136         my @items = ($request && $request eq 'flatten') ?
 137                     $self->get_all_Items :
 138                     $self->get_Items ;
 139         $self->{"_items_it"} = sub {return shift @items}
 140     }
 141     $self->{'_items_it'}->();
 142 }
 143
 144 =head2 get_Items
 145
 146  Title    : get_Items
 147  Usage    : my @items = $docsum->get_Items
 148  Function : returns list of, well, Items
 149  Returns  : array of Items
 150  Args     : none
 151
 152 =cut
 153
 154 sub get_Items {
 155     my $self = shift;
 156     return ref $self->{'_items'} ? @{ $self->{'_items'} } : return ();
 157 }
 158
 159 =head2 get_all_Items
 160
 161  Title    : get_all_Items
 162  Usage    : my @items = $docsum->get_all_Items
 163  Function : returns flattened list of all Item objects (Items, ListItems,
 164             StructureItems)
 165  Returns  : array of Items
 166  Args     : none
 167  Note     : items are added top-down (similar order to using nested calls)
 168             in original list order.
 169
 170              1         2        7        8
 171            Item  -   Item  -  Item  -  Item ...
 172                      |
 173                     | 3        6
 174                  ListItem - ListItem
 175                    |
 176                   | 4          5
 177                Structure - Structure
 178
 179 =cut
 180
 181 sub get_all_Items {
 182     my $self = shift;
 183     unless ($self->{'_ordered_items'}) {
 184         for my $item ($self->get_Items) {
 185             push @{$self->{'_ordered_items'}}, $item;
 186             for my $ls ($item->get_ListItems) {
 187                 push @{$self->{'_ordered_items'}}, $ls;
 188                 for my $st ($ls->get_StructureItems) {
 189                     push @{$self->{'_ordered_items'}}, $st;
 190                 }
 191             }
 192         }
 193     }
 194     return @{$self->{'_ordered_items'}};
 195 }
 196
 197 =head2 get_content_by_name
 198
 199  Title    : get_content_by_Item_name
 200  Usage    : my $data = get_content_by_name('CreateDate')
 201  Function : Returns scalar content for named Item in DocSum (indicated by
 202             passed argument)
 203  Returns  : scalar value (string) if present
 204  Args     : string (Item name)
 205  Warns    : If Item with name is not found
 206
 207 =cut
 208
 209 sub get_content_by_name {
 210     my ($self, $key) = @_;
 211     return unless $key;
 212     my ($it) = grep {$_->get_name eq $key} $self->get_all_Items;
 213     return $it->get_content;
 214 }
 215
 216 =head2 get_type_by_name
 217
 218  Title    : get_type_by_name
 219  Usage    : my $data = get_type_by_name('CreateDate')
 220  Function : Returns data type for named Item in DocSum (indicated by
 221             passed argument)
 222  Returns  : scalar value (string) if present
 223  Args     : string (Item name)
 224  Warns    : If Item with name is not found
 225
 226 =cut
 227
 228 sub get_type_by_name {
 229     my ($self, $key) = @_;
 230     return unless $key;
 231     my ($it) = grep {$_->get_name eq $key} $self->get_all_Items;
 232     return $it->get_type;
 233 }
 234
 235 =head2 rewind
 236
 237  Title    : rewind
 238  Usage    : $docsum->rewind();
 239  Function : rewinds DocSum iterator
 240  Returns  : none
 241  Args     : [optional]
 242            'recursive' - rewind all DocSum object layers
 243                          (Items, ListItems, StructureItems)
 244
 245 =cut
 246
 247 sub rewind {
 248     my ($self, $request) = @_;
 249     if ($request && $request eq 'all') {
 250         map {$_->rewind('all') } $self->get_Items;
 251     }
 252     delete $self->{"_items_it"};
 253 }
 254
 255 # private EUtilDataI method
 256
 257 sub _add_data {
 258     my ($self, $data) = @_;
 259     if ($data->{Item}) {
 260         $self->{'_id'} = $data->{Id} if exists $data->{Id};
 261         for my $sd (@{ $data->{Item} } ) {
 262             $sd->{Id} = $data->{Id} if exists $data->{Id};
 263             my $subdoc =
 264                 Bio::Tools::EUtilities::Summary::Item->new(-datatype => 'item',
 265                                                   -verbose => $self->verbose);
 266             $subdoc->_add_data($sd);
 267             push @{ $self->{'_items'} }, $subdoc;
 268         }
 269     }
 270     $self->{'_id'} = $data->{Id} if exists $data->{Id};
 271 }
 272
 273 1;