Provided by: libbio-eutilities-perl_1.77-2_all bug

NAME

       Bio::Tools::EUtilities::Summary::Item - Simple layered object for DocSum item data.

VERSION

       version 1.77

SYNOPSIS

         # Items can be nested up to three levels at this time. These levels can be
         # accessed via Item, ListItem, or StructureItem methods:

         while (my $item = $docsum->next_Item) {
            print "Name: ",$item->get_name,"\n";
            print "Data: ",$item->get_content,"\n";
            print "Type: ",$item->get_type,"\n";
            while (my $ls = $item->next_ListItem) {
               # do same here
               while (my $struct = $ls->next_StructureItem) {
                  # do more stuff here
               }
            }
         }

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). Up to three nested layers may appear in any
       document summary.

       This class contains methods to access data that can appear in a docsum for any individual
       item as well as describes methods to traverse the hierarchy of items present in a document
       summary.

       The unique name for items are accessed via get_name(), the content by get_content() (if
       present), and the data type by get_type(). Items can have ListItems (Item objects with a
       datatype() 'list'), which in turn can have StructureItems (Item objects with a datatype of
       'structure'). Items are initially traversed via a DocSum object using next_Item() or
       obtained all at once with get_Items(). Similarly, nested Items can be accessed by using
       next_ListItem/get_ListItems and next_StructureItem/get_StructureItem.  A flattened list of
       items can be accessed with get_all_Items().

   new
        Title    : new
        Usage    :
        Function :
        Returns  :
        Args     :

   get_ids
        Title    : get_ids
        Usage    : my ($id) = $item->get_ids;
        Function : returns array or array ref with id
        Returns  : array or array ref
        Args     : none
        Note     : the behavior of this method is to remain consistent with other
                   implementations of get_ids(). To retrieve the single DocSum ID use
                   get_id()

   get_id
        Title    : get_id
        Usage    : my ($id) = $item->get_id;
        Function : returns UID of record
        Returns  : integer
        Args     : none

   next_ListItem
        Title    : next_ListItem
        Usage    : while (my $ls = $item->next_ListItem) {...}
        Function : iterates through ListItems (nested layer of Item)
        Returns  : single ListItem
        Args     : none

   get_ListItems
        Title    : get_ListItems
        Usage    : my @ls = $item->get_ListItems
        Function : returns list of, well, List Items
        Returns  : array of List Items
        Args     : none

   next_StructureItem
        Title    : next_StructureItem
        Usage    : while (my $struc = $ls->next_StructureItem) {...}
        Function : iterates through StructureItems (nested layer of ListItem)
        Returns  : single StructureItems
        Args     : none

   get_StructureItems
        Title    : get_StructureItems
        Usage    : my @structs = $ls->get_StructureItems
        Function : returns list of Structure Items
        Returns  : array of StructureItems
        Args     : none

   next_subItem
        Title    : next_subItem
        Usage    : while (my $it = $ls->next_subItem) {...}
        Function : iterates through the next layer of Items
        Returns  : single Item
        Args     : none
        Notes    : unlike next_ListItem and next_StructureItem, this generically
                   accesses any sub Items (useful for recursive calls, for example)

   get_subItems
        Title    : get_subItems
        Usage    : my @items = $ls->get_subItems
        Function : returns list of sub Items
        Returns  : array of Items
        Args     : none
        Notes    : unlike get_ListItems and get_StructureItems, this generically
                   accesses any sub Items (useful for recursive calls, for example)

   get_name
        Title    : get_name
        Usage    : my $nm = $ls->get_name
        Function : retrieves Item/ListItem/StructureItem name for this Item
        Returns  : string
        Args     : none

   get_type
        Title    : get_type
        Usage    : my $type = $ls->get_type
        Function : retrieves Item/ListItem/StructureItem type
        Returns  : string
        Args     : none
        Note     : this is not the same as the datatype(), which describes the
                   group this Item object belongs to

   get_content
        Title    : get_content
        Usage    : my $data = $ls->get_content
        Function : retrieves Item/ListItem/StructureItem content (if any)
        Returns  : string
        Args     : none

   rewind
        Title    : rewind
        Usage    : $item->rewind()
        Function : rewinds iterators
        Returns  : none
        Args     : [optional] No arg - only rewinds current layer
                  'all' - rewind all DocSum object layers
                       (Items, ListItems, StructureItems)

ItemContainerI methods

   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()

   get_Items
        Title    : get_Items
        Usage    : my @items = $docsum->get_Items
        Function : returns list of, well, Items
        Returns  : array of Items
        Args     : none

   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

   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

   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)

   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)

   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)

   to_string
        Title    : to_string
        Usage    : $foo->to_string()
        Function : converts current object to string
        Returns  : none
        Args     : (optional) simple data for text formatting.  This implementation
                   passes an argument for layering Items/subItems
        Note     : Used generically for debugging and print_DocSums methods

FEEDBACK

   Mailing lists
       User feedback is an integral part of the evolution of this and other Bioperl modules. Send
       your comments and suggestions preferably to the Bioperl mailing list.  Your participation
       is much appreciated.

         bioperl-l@bioperl.org               - General discussion
         https://bioperl.org/Support.html    - About the mailing lists

   Support
       Please direct usage questions or support issues to the mailing list: bioperl-l@bioperl.org
       rather than to the module maintainer directly. Many experienced and reponsive experts will
       be able look at the problem and quickly address it. Please include a thorough description
       of the problem with code and data examples if at all possible.

   Reporting bugs
       Report bugs to the Bioperl bug tracking system to help us keep track of the bugs and their
       resolution. Bug reports can be submitted via the web:

         https://github.com/bioperl/bio-eutilities/issues

AUTHOR

       Chris Fields <cjfields@bioperl.org>

COPYRIGHT

       This software is copyright (c) 2006-2013 by Chris Fields.

       This software is available under the same terms as the perl 5 programming language system
       itself.