[Bioperl-guts-l] [15757] bioperl-live/trunk/Bio/Tools/EUtilities/Summary: * genericize the appropriate Item-related methods into a common ItemContainer interface (so Items and DocSums can use the same methods if needed, see the cookbook for an example)
Christopher John Fields
cjfields at dev.open-bio.org
Wed Jun 10 17:11:06 EDT 2009
Revision: 15757
Author: cjfields
Date: 2009-06-10 17:11:06 -0400 (Wed, 10 Jun 2009)
Log Message:
-----------
* genericize the appropriate Item-related methods into a common ItemContainer interface (so Items and DocSums can use the same methods if needed, see the cookbook for an example)
Modified Paths:
--------------
bioperl-live/trunk/Bio/Tools/EUtilities/Summary/DocSum.pm
bioperl-live/trunk/Bio/Tools/EUtilities/Summary/Item.pm
Added Paths:
-----------
bioperl-live/trunk/Bio/Tools/EUtilities/Summary/ItemContainerI.pm
Modified: bioperl-live/trunk/Bio/Tools/EUtilities/Summary/DocSum.pm
===================================================================
--- bioperl-live/trunk/Bio/Tools/EUtilities/Summary/DocSum.pm 2009-06-10 13:25:46 UTC (rev 15756)
+++ bioperl-live/trunk/Bio/Tools/EUtilities/Summary/DocSum.pm 2009-06-10 21:11:06 UTC (rev 15757)
@@ -73,7 +73,7 @@
use strict;
use warnings;
-use base qw(Bio::Root::Root Bio::Tools::EUtilities::EUtilDataI);
+use base qw(Bio::Root::Root Bio::Tools::EUtilities::Summary::ItemContainerI);
use Bio::Tools::EUtilities::Summary::Item;
@@ -130,6 +130,10 @@
return $self->{'_id'};
}
+=head1 ItemContainerI methods
+
+=cut
+
=head2 next_Item
Title : next_Item
@@ -142,18 +146,6 @@
=cut
-sub next_Item {
- my ($self, $request) = @_;
- unless ($self->{"_items_it"}) {
- #my @items = $self->get_Items;
- my @items = ($request && $request eq 'flatten') ?
- $self->get_all_Items :
- $self->get_Items ;
- $self->{"_items_it"} = sub {return shift @items}
- }
- $self->{'_items_it'}->();
-}
-
=head2 get_Items
Title : get_Items
@@ -164,11 +156,6 @@
=cut
-sub get_Items {
- my $self = shift;
- return ref $self->{'_items'} ? @{ $self->{'_items'} } : return ();
-}
-
=head2 get_all_Items
Title : get_all_Items
@@ -191,22 +178,6 @@
=cut
-sub get_all_Items {
- my $self = shift;
- unless ($self->{'_ordered_items'}) {
- for my $item ($self->get_Items) {
- push @{$self->{'_ordered_items'}}, $item;
- for my $ls ($item->get_ListItems) {
- push @{$self->{'_ordered_items'}}, $ls;
- for my $st ($ls->get_StructureItems) {
- push @{$self->{'_ordered_items'}}, $st;
- }
- }
- }
- }
- return @{$self->{'_ordered_items'}};
-}
-
=head2 get_all_names
Title : get_all_names
@@ -217,14 +188,6 @@
=cut
-sub get_all_names {
- my ($self) = @_;
- my %tmp;
- my @data = grep {!$tmp{$_}++}
- map {$_->get_name} $self->get_all_Items;
- return @data;
-}
-
=head2 get_Items_by_name
Title : get_Items_by_name
@@ -235,14 +198,6 @@
=cut
-sub get_Items_by_name {
- my ($self, $key) = @_;
- return unless $key;
- my @data = grep {$_->get_name eq $key}
- $self->get_all_Items;
- return @data;
-}
-
=head2 get_contents_by_name
Title : get_contents_by_name
@@ -254,15 +209,6 @@
=cut
-sub get_contents_by_name {
- my ($self, $key) = @_;
- return unless $key;
- my @data = map {$_->get_content}
- grep {$_->get_name eq $key}
- $self->get_all_Items;
- return @data;
-}
-
=head2 get_type_by_name
Title : get_type_by_name
@@ -274,13 +220,6 @@
=cut
-sub get_type_by_name {
- my ($self, $key) = @_;
- return unless $key;
- my ($it) = grep {$_->get_name eq $key} $self->get_all_Items;
- return $it->get_type;
-}
-
=head2 rewind
Title : rewind
Modified: bioperl-live/trunk/Bio/Tools/EUtilities/Summary/Item.pm
===================================================================
--- bioperl-live/trunk/Bio/Tools/EUtilities/Summary/Item.pm 2009-06-10 13:25:46 UTC (rev 15756)
+++ bioperl-live/trunk/Bio/Tools/EUtilities/Summary/Item.pm 2009-06-10 21:11:06 UTC (rev 15757)
@@ -241,7 +241,7 @@
Function : iterates through the next layer of Items
Returns : single Item
Args : none
- Notes : unlike next_ListItem and next_Structureitem, this generically
+ Notes : unlike next_ListItem and next_StructureItem, this generically
accesses any sub Items (useful for recursive calls, for example)
=cut
@@ -276,7 +276,7 @@
Title : get_name
Usage : my $nm = $ls->get_name
- Function : retrieves Item/ListItem/StructureItem name
+ Function : retrieves Item/ListItem/StructureItem name for this Item
Returns : string
Args : none
@@ -284,7 +284,7 @@
sub get_name {
my $self = shift;
- return $self->{'_itemname'};
+ return $self->{'_itemname'};
}
=head2 get_type
@@ -340,6 +340,161 @@
delete $self->{"_structures_it"} if $self->{"_structures_it"};
}
+=head1 ItemContainerI methods
+
+=cut
+
+=head2 next_Item
+
+ Title : next_Item
+ Usage : while (my $item = $docsum->next_Item) {...}
+ Function : iterates through Items (nested layer of Item)
+ Returns : single Item
+ Args : [optional] single arg (string)
+ 'flatten' - iterates through a flattened list ala
+ get_all_DocSum_Items()
+
+=cut
+
+sub next_Item {
+ my ($self, $request) = @_;
+ unless ($self->{"_items_it"}) {
+ #my @items = $self->get_Items;
+ my @items = ($request && $request eq 'flatten') ?
+ $self->get_all_Items :
+ $self->get_Items ;
+ $self->{"_items_it"} = sub {return shift @items}
+ }
+ $self->{'_items_it'}->();
+}
+
+=head2 get_Items
+
+ Title : get_Items
+ Usage : my @items = $docsum->get_Items
+ Function : returns list of, well, Items
+ Returns : array of Items
+ Args : none
+
+=cut
+
+sub get_Items {
+ my $self = shift;
+ return ref $self->{'_items'} ? @{ $self->{'_items'} } : return ();
+}
+
+=head2 get_all_Items
+
+ Title : get_all_Items
+ Usage : my @items = $docsum->get_all_Items
+ Function : returns flattened list of all Item objects (Items, ListItems,
+ StructureItems)
+ Returns : array of Items
+ Args : none
+ Note : items are added top-down (similar order to using nested calls)
+ in original list order.
+
+ 1 2 7 8
+ Item - Item - Item - Item ...
+ |
+ | 3 6
+ ListItem - ListItem
+ |
+ | 4 5
+ Structure - Structure
+
+=cut
+
+sub get_all_Items {
+ my $self = shift;
+ unless ($self->{'_ordered_items'}) {
+ for my $item ($self->get_Items) {
+ push @{$self->{'_ordered_items'}}, $item;
+ for my $ls ($item->get_ListItems) {
+ push @{$self->{'_ordered_items'}}, $ls;
+ for my $st ($ls->get_StructureItems) {
+ push @{$self->{'_ordered_items'}}, $st;
+ }
+ }
+ }
+ }
+ return @{$self->{'_ordered_items'}};
+}
+
+=head2 get_all_names
+
+ Title : get_all_names
+ Usage : my @names = get_all_names()
+ Function : Returns an array of names for all Item(s) in DocSum.
+ Returns : array of unique strings
+ Args : none
+
+=cut
+
+sub get_all_names {
+ my ($self) = @_;
+ my %tmp;
+ my @data = grep {!$tmp{$_}++}
+ map {$_->get_name} $self->get_all_Items;
+ return @data;
+}
+
+=head2 get_Items_by_name
+
+ Title : get_Items_by_name
+ Usage : my @items = get_Items_by_name('CreateDate')
+ Function : Returns named Item(s) in DocSum (indicated by passed argument)
+ Returns : array of Item objects
+ Args : string (Item name)
+
+=cut
+
+sub get_Items_by_name {
+ my ($self, $key) = @_;
+ return unless $key;
+ my @data = grep {$_->get_name eq $key}
+ $self->get_all_Items;
+ return @data;
+}
+
+=head2 get_contents_by_name
+
+ Title : get_contents_by_name
+ Usage : my ($data) = get_contents_by_name('CreateDate')
+ Function : Returns content for named Item(s) in DocSum (indicated by
+ passed argument)
+ Returns : array of values (type varies per Item)
+ Args : string (Item name)
+
+=cut
+
+sub get_contents_by_name {
+ my ($self, $key) = @_;
+ return unless $key;
+ my @data = map {$_->get_content}
+ grep {$_->get_name eq $key}
+ $self->get_all_Items;
+ return @data;
+}
+
+=head2 get_type_by_name
+
+ Title : get_type_by_name
+ Usage : my $data = get_type_by_name('CreateDate')
+ Function : Returns data type for named Item in DocSum (indicated by
+ passed argument)
+ Returns : scalar value (string) if present
+ Args : string (Item name)
+
+=cut
+
+sub get_type_by_name {
+ my ($self, $key) = @_;
+ return unless $key;
+ my ($it) = grep {$_->get_name eq $key} $self->get_all_Items;
+ return $it->get_type;
+}
+
# private data method
sub _add_data {
Added: bioperl-live/trunk/Bio/Tools/EUtilities/Summary/ItemContainerI.pm
===================================================================
--- bioperl-live/trunk/Bio/Tools/EUtilities/Summary/ItemContainerI.pm (rev 0)
+++ bioperl-live/trunk/Bio/Tools/EUtilities/Summary/ItemContainerI.pm 2009-06-10 21:11:06 UTC (rev 15757)
@@ -0,0 +1,248 @@
+# $Id$
+#
+# BioPerl module for Bio::Tools::EUtilities::Summary::ItemContainerI
+#
+# Please direct questions and support issues to <bioperl-l at bioperl.org>
+#
+# Cared for by Chris Fields
+#
+# Copyright Chris Fields
+#
+# You may distribute this module under the same terms as perl itself
+#
+# POD documentation - main docs before the code
+#
+# Part of the EUtilities BioPerl package
+
+=head1 NAME
+
+Bio::Tools::EUtilities::Summary::ItemContainerI - abtract interface methods
+for accessing Item information from any Item-containing class. This pertains
+to either DocSums or to Items themselves (which can be layered)
+
+=head1 SYNOPSIS
+
+ # Implement ItemContainerI
+
+ # $foo is any ItemContainerI (current implementations are DocSum and Item itself)
+
+ while (my $item = $foo->next_Item) { # iterate through contained Items
+ # do stuff here
+ }
+
+ @items = $foo->get_Items; # all Items in the container (hierarchy intact)
+ @items = $foo->get_all_Items; # all Items in the container (flattened)
+ @items = $foo->get_Items_by_name('bar'); # Specifically named Items
+ ($content) = $foo->get_contents_by_name('bar'); # content from specific Items
+ ($type) = $foo->get_type_by_name('bar'); # data type from specific Items
+
+=head1 DESCRIPTION
+
+DocSum data, as returned from esummary, normally is a simple list of
+item-content-content_type groups. However, items can also contain nested data to
+represent more complex data (such as structural data). This interface describes
+the basic methods to generically retrieve the next layer of Item data. For
+convenience classes may describe more specific methods, but they should be
@@ Diff output truncated at 10000 characters. @@
More information about the Bioperl-guts-l
mailing list