Bio::T...y::Item(3pm)

📦
version 1.77 · 4 versions
, in debian trixie, ubuntu resolute, ubuntu stonking

✨ NAME ✨

Bio::Tools::EUtilities::Summary::Item — the simple layered object for DocSum item data, bestie 💖 (manual name is Bio::T...y::Item(3pm), in case you were squinting at the top of your terminal).

🌸 VERSION 🌸

version 1.77 — yes queen, that's the one 👑

🦋 SYNOPSIS 🦋

okay so items can be nested up to three levels at this time, and you reach those levels through Item, ListItem, or StructureItem methods:

# 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 💅

So. DocSum data, the stuff you get back from esummary, is normally just a cute little simple list of item-content-content_type groups. No drama. But — and this is the plot twist 🫢 — items can also carry nested data to represent way more complex stuff, like structural data. Up to three nested layers may appear in any document summary. Three. Layers. Deep. It's giving onion, honestly 🧅

This class has the methods to get at data that can show up in a docsum for any individual item, and it describes the methods for walking the whole hierarchy of items in a document summary.

The unique name for items comes from get_name(), the content from get_content() (if it's there, which it might not be 🙈), and the data type from get_type(). Items can have ListItems (Item objects with a datatype() of 'list'), which can themselves have StructureItems (Item objects with a datatype of 'structure'). You start traversing Items through a DocSum object using next_Item(), or you can grab them all at once with get_Items(). Nested Items work the same way — next_ListItem/get_ListItems and next_StructureItem/get_StructureItem. And if you want everything flat, no nesting, just vibes, use get_all_Items() ✨

🎀 new 🎀

  • Title: new
  • Usage: (blank, bestie — it's just vibes)
  • Function: (blank)
  • Returns: (blank)
  • Args: (blank)

💖 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: this method stays consistent with other implementations of get_ids(). If you want the single DocSum ID, use get_id() instead — iykyk.

🍓 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 one generically accesses any sub Items — super 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 (again, recursive calls say hiii).

✨ 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. Two different things, don't mix them up 💀

🌸 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. (yes, "reponsive" — that's how it's spelled in the original, don't come for me 🙈)

🐛 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>

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.

💀 lowkey important: this page is part of the User Contributed Perl Documentation for the module Bio::T...y::Item(3pm), and it's the version that shipped with perl v5.40.0 on 2025-01-27. That's the whole sign-off bestie, mwah 💋✨ go forth and traverse those items, queen 👑
📦 where this page comes from