branch-1-6/Bio/Tools/EUtilities/Summary/ItemContainerI.pm

   1 # $Id$
   2 #
   3 # BioPerl module for Bio::Tools::EUtilities::Summary::ItemContainerI
   4 #
   5 # Please direct questions and support issues to <bioperl-l@bioperl.org>
   6 #
   7 # Cared for by Chris Fields
   8 #
   9 # Copyright Chris Fields
  10 #
  11 # You may distribute this module under the same terms as perl itself
  12 #
  13 # POD documentation - main docs before the code
  14 #
  15 # Part of the EUtilities BioPerl package
  16
  17 =head1 NAME
  18
  19 Bio::Tools::EUtilities::Summary::ItemContainerI - abtract interface methods
  20 for accessing Item information from any Item-containing class.  This pertains
  21 to either DocSums or to Items themselves (which can be layered)
  22
  23 =head1 SYNOPSIS
  24
  25   # Implement ItemContainerI
  26
  27   # $foo is any ItemContainerI (current implementations are DocSum and Item itself)
  28
  29   while (my $item = $foo->next_Item) { # iterate through contained Items
  30      # do stuff here
  31   }
  32
  33   @items = $foo->get_Items;  # all Items in the container (hierarchy intact)
  34   @items = $foo->get_all_Items;  # all Items in the container (flattened)
  35   @items = $foo->get_Items_by_name('bar'); # Specifically named Items
  36   ($content) = $foo->get_contents_by_name('bar'); # content from specific Items
  37   ($type) = $foo->get_type_by_name('bar'); # data type from specific Items
  38
  39 =head1 DESCRIPTION
  40
  41 DocSum data, as returned from esummary, normally is a simple list of
  42 item-content-content_type groups. However, items can also contain nested data to
  43 represent more complex data (such as structural data). This interface describes
  44 the basic methods to generically retrieve the next layer of Item data. For
  45 convenience classes may describe more specific methods, but they should be
  46 defined in terms of this interface and it's methods.
  47
  48 =head1 FEEDBACK
  49
  50 =head2 Mailing Lists
  51
  52 User feedback is an integral part of the
  53 evolution of this and other Bioperl modules. Send
  54 your comments and suggestions preferably to one
  55 of the Bioperl mailing lists. Your participation
  56 is much appreciated.
  57
  58   bioperl-l@lists.open-bio.org               - General discussion
  59   http://www.bioperl.org/wiki/Mailing_lists  - About the mailing lists
  60
  61 =head2 Support
  62
  63 Please direct usage questions or support issues to the mailing list:
  64
  65 I<bioperl-l@bioperl.org>
  66
  67 rather than to the module maintainer directly. Many experienced and
  68 reponsive experts will be able look at the problem and quickly
  69 address it. Please include a thorough description of the problem
  70 with code and data examples if at all possible.
  71
  72 =head2 Reporting Bugs
  73
  74 Report bugs to the Bioperl bug tracking system to
  75 help us keep track the bugs and their resolution.
  76 Bug reports can be submitted via the web.
  77
  78   http://bugzilla.open-bio.org/
  79
  80 =head1 AUTHOR Chris Fields
  81
  82 Email cjfields at bioperl dot org
  83
  84 =head1 APPENDIX
  85
  86 The rest of the documentation details each of the
  87 object methods. Internal methods are usually
  88 preceded with a _
  89
  90 =cut
  91
  92 package Bio::Tools::EUtilities::Summary::ItemContainerI;
  93 use strict;
  94 use warnings;
  95
  96 use base qw(Bio::Tools::EUtilities::EUtilDataI);
  97
  98 =head2 next_Item
  99
 100  Title    : next_Item
 101  Usage    : while (my $item = $docsum->next_Item) {...}
 102  Function : iterates through Items (nested layer of Item)
 103  Returns  : single Item
 104  Args     : [optional] single arg (string)
 105             'flatten' - iterates through a flattened list ala
 106                           get_all_DocSum_Items()
 107
 108 =cut
 109
 110 sub next_Item {
 111     my ($self, $request) = @_;
 112     unless ($self->{"_items_it"}) {
 113         my @items = ($request && $request eq 'flatten') ?
 114                     $self->get_all_Items :
 115                     $self->get_Items ;
 116         $self->{"_items_it"} = sub {return shift @items}
 117     }
 118     $self->{'_items_it'}->();
 119 }
 120
 121 =head2 get_Items
 122
 123  Title    : get_Items
 124  Usage    : my @items = $docsum->get_Items
 125  Function : returns list of, well, Items
 126  Returns  : array of Items
 127  Args     : none
 128
 129 =cut
 130
 131 sub get_Items {
 132     my $self = shift;
 133     return ref $self->{'_items'} ? @{ $self->{'_items'} } : return ();
 134 }
 135
 136 =head2 get_all_Items
 137
 138  Title    : get_all_Items
 139  Usage    : my @items = $docsum->get_all_Items
 140  Function : returns flattened list of all Item objects (Items, ListItems,
 141             StructureItems)
 142  Returns  : array of Items
 143  Args     : none
 144  Note     : items are added top-down (similar order to using nested calls)
 145             in original list order.
 146
 147              1         2        7        8
 148            Item  -   Item  -  Item  -  Item ...
 149                      |
 150                     | 3        6
 151                  ListItem - ListItem
 152                    |
 153                   | 4          5
 154                Structure - Structure
 155
 156 =cut
 157
 158 sub get_all_Items {
 159     my $self = shift;
 160     unless ($self->{'_ordered_items'}) {
 161         for my $item ($self->get_Items) {
 162             push @{$self->{'_ordered_items'}}, $item;
 163             for my $ls ($item->get_ListItems) {
 164                 push @{$self->{'_ordered_items'}}, $ls;
 165                 for my $st ($ls->get_StructureItems) {
 166                     push @{$self->{'_ordered_items'}}, $st;
 167                 }
 168             }
 169         }
 170     }
 171     return @{$self->{'_ordered_items'}};
 172 }
 173
 174 =head2 get_all_names
 175
 176  Title    : get_all_names
 177  Usage    : my @names = get_all_names()
 178  Function : Returns an array of names for all Item(s) in DocSum.
 179  Returns  : array of unique strings
 180  Args     : none
 181
 182 =cut
 183
 184 sub get_all_names {
 185     my ($self) = @_;
 186     my %tmp;
 187     my @data = grep {!$tmp{$_}++}
 188         map {$_->get_name} $self->get_all_Items;
 189     return @data;
 190 }
 191
 192 =head2 get_Items_by_name
 193
 194  Title    : get_Items_by_name
 195  Usage    : my @items = get_Items_by_name('CreateDate')
 196  Function : Returns named Item(s) in DocSum (indicated by passed argument)
 197  Returns  : array of Item objects
 198  Args     : string (Item name)
 199
 200 =cut
 201
 202 sub get_Items_by_name {
 203     my ($self, $key) = @_;
 204     return unless $key;
 205     my @data = grep {$_->get_name eq $key}
 206         $self->get_all_Items;
 207     return @data;
 208 }
 209
 210 =head2 get_contents_by_name
 211
 212  Title    : get_contents_by_name
 213  Usage    : my ($data) = get_contents_by_name('CreateDate')
 214  Function : Returns content for named Item(s) in DocSum (indicated by
 215             passed argument)
 216  Returns  : array of values (type varies per Item)
 217  Args     : string (Item name)
 218
 219 =cut
 220
 221 sub get_contents_by_name {
 222     my ($self, $key) = @_;
 223     return unless $key;
 224     my @data = map {$_->get_content}
 225         grep {$_->get_name eq $key}
 226         $self->get_all_Items;
 227     return @data;
 228 }
 229
 230 =head2 get_type_by_name
 231
 232  Title    : get_type_by_name
 233  Usage    : my $data = get_type_by_name('CreateDate')
 234  Function : Returns data type for named Item in DocSum (indicated by
 235             passed argument)
 236  Returns  : scalar value (string) if present
 237  Args     : string (Item name)
 238
 239 =cut
 240
 241 sub get_type_by_name {
 242     my ($self, $key) = @_;
 243     return unless $key;
 244     my ($it) = grep {$_->get_name eq $key} $self->get_all_Items;
 245     return $it->get_type;
 246 }
 247
 248 1;