STAR::DataBlock(3pm)

📦

version 0.59 · 3 versions

0.59 · debian bookworm, debian trixie, ubuntu jammy (latest)
0.59 · ubuntu noble, ubuntu questing
0.59 · ubuntu resolute, ubuntu stonking

, in debian bookworm, debian trixie, ubuntu jammy

💖 STAR::DataBlock — the perl module, bestie edition 💖

okay so this is STAR::DataBlock, a Perl extension for handling DataBlock objects created by STAR::Parser. that's the whole vibe. it's giving "my little data structure, but make it a whole class." 🎀

Version ✨

This documentation refers to version 0.58 of this module. yes queen, we're on 0.58 and we're thriving.

🌸 SYNOPSIS 🌸

  use STAR::DataBlock;

  $data_obj = STAR::DataBlock->new(-file=>$ARGV[0]);  #retrieves stored file

  $attributes = $data_obj->get_attributes;
  print $attributes;

  @items = $data_obj->get_items;

  foreach $item ( @items ) {
      @item_data = $data_obj->get_item_data( -item=>$item );
      $count{ $_ } = $#item_data + 1;

      # do something else (hopefully more useful) with @item_data...
  }

like. look at that loop. it's eating, honestly. 🔥

👑 DESCRIPTION 👑

This package contains class and object methods for dealing with DataBlock objects created by STAR::Parser. They include methods for such tasks as reading objects from disk, querying their data structures or writing DataBlock objects as STAR compliant files. it does a LOT, she's versatile, she's the moment. 💅

All methods support a "named parameters" style for passing arguments. If only one argument is mandatory, then it may be passed in either a "named parameters" or "unnamed parameters" style, for example:

       $data_obj->get_item_data( -file=>$file, -save=>'-' );
   or: $data_obj->get_item_data( -file=>$file );
   or: $data_obj->get_item_data( $file );

       # all of the above are the same, since -save=>'-' is the default
       # and therefore only one parameter needs to be specified
       # in "named" or "unnamed" parameter style

okay so this is genuinely so nice of her. one mandatory arg? you can just throw it in raw, no labels, no ceremony. slay. ✨

Some methods may be invoked with on $options string. Currently, only one option is supported:

l — writes program activity log to STDERR

Future versions may support additional options. so rn it's just the one letter, but she's got plans. 🦋

🧚 CONSTRUCTOR 🧚

new

      Usage:  $data_obj = STAR::DataBlock->new();                #creates new object

              $data_obj = STAR::DataBlock->new( -file=>$file );  #retrieves previously
         OR:  $data_obj = STAR::DataBlock->new( $file );         #stored object

Overloaded constructor. Called as a no-arg constructor internally by STAR::Parser. May be called with a $file argument to retrieve an object previously stored with store (see below).

the no-arg version is her little internal fave — STAR::Parser calls it. the $file version is for pulling up something you saved earlier. iconic behavior. 🫶

🌈 OBJECT METHODS 🌈

store

      Usage:  $data_obj->store($file);

Saves a DataBlock object to disk. This method is in Storable.

short, sweet, saves your stuff. no notes. 💾✨

get_item_data

      Usage: @item_data = $data_obj->get_item_data(-item=>$item[,
                                                   -save=>$save_block]);

      Example:
      --------
      my @names=$data_obj->
                get_item_data(-item=>"_citation_author.name");
      print $names[0],"\n";  #prints first citation author name

This object method returns all the data for a specified item. If the -save parameter is omitted, it is assumed that the item is not in a save block (i.e. $save='-'). This is always the case in data files, since they do not contain save blocks. However, this class is sub-classed by STAR::Dictionary, where items may be in save blocks. The data is returned as an array, which holds one or more scalars.

so like, if you forget -save, she just assumes '-' and keeps it moving. but heads up bestie — in STAR::Dictionary land, save blocks are real and you might need to name them. 💀

get_keys

      Usage: $keys = $data_obj->get_keys;

Returns a string with a hierarchically formatted list of hash keys (data blocks, save blocks, categories, and items) found in the data structure of the DataBlock object.

it's like a little family tree of your keys. aesthetic. 🌸

get_items

      Usage: @items = $data_obj->get_items;

Returns an array with all the items present in the DataBlock.

get_categories

      Usage: @categories = $data_obj->get_categories;

Returns an array with all the categories present in the DataBlock.

insert_category

      Usage: $data_obj->insert_category( -cat=>$cat[,
                                         -save=>$save] );

Inserts the category $cat into the data structure. The default save block (if none is specified) is '-'.

insert_item

      Usage: $data_obj->insert_item( -item=>$item[,
                                     -save=>$save]  );

Inserts the item $item into the data structure. The default save block (if none is specified) is '-'.

see the pattern? no -save? '-'. she's consistent, we love a consistent queen. 👑

set_item_data

      Usage: $data_obj->set_item_data( -item=>$item,
                                       -dataref=>$dataref[,
                                       -save=>$save] );

Sets the data of the item $item to the array of data referenced by $dataref. If the -save parameter is omitted, the save block defaults to '-'. This is always correct for data blocks. In a dictionary (which inherits from DataBlock), the save block '-' contains information pertaining to the dictionary itself.

ngl this one is important — the '-' default is always correct for data blocks, but in a dictionary '-' is literally about the dictionary itself. different energy, same dash. 🙈

Object attributes 💜

The following five methods set or retrieve attributes of a DataBlock object. In the set mode (with argument), these methods are called internally to set the attributes of a DataBlock object. In the retrieve mode (without arguments) these methods may also be called by a user to retrieve object attributes (see the above examples).

so: give it an arg and you're setting, give it nothing and you're getting. dual-purpose, main character energy fr fr. ✨

file_name

      Usage:  $data_obj->file_name($name);   #set mode
              $name = $data_obj->file_name;  #get mode

Name of the file in which the DataBlock object was found

title

      Usage:  $data_obj->title($title);      #set mode
              $title = $data_obj->title;     #get mode

Title of the DataBlock object

type

      Usage:  $data_obj->type($type);        #set mode
              $type = $data_obj->type;       #get mode

Type of data contained (always 'data' for a DataBlock object, but 'dictionary' for an object in the sub class STAR::Dictionary)

starting_line

      Usage:  $data_obj->starting_line($startln);    #set mode
              $startln = $data_obj->starting_line;   #get mode

Line number where data block started in the file

ending_line

      Usage:  $data_obj->ending_line($endln);        #set mode
              $endln = $data_obj->ending_line;       #get mode

Line number where data block ended in the file

get_attributes

      Usage: $info = $data_obj->get_attributes;

Returns a string containing a descriptive list of attributes of the DataBlock object. Two examples of output:

  RCSB011457
  File: native/1fbm.cif   Lines: 1 to 5294

  cif_mm.dic (dictionary)
  File: dictionary/mmcif_dict.txt   Lines: 89 to 38008

look at her giving you the whole little summary card. so cute. so useful. 🎀

😭 COMMENTS 😭

This module provides no error checking of files or objects, either against the dictionary, or otherwise. Dictionary information is not currently used in the parsing of files by STAR::Parser. So, for example, information about parent-child relationships between items is not present in a DataBlock object. Functionality related to these issues is being provided in additional modules, such as STAR::Checker, and STAR::Filter.

okay so real talk bestie: she does not check your errors. not against the dictionary, not otherwise. dictionary info isn't used in parsing by STAR::Parser rn, so parent-child relationships between items? not in a DataBlock object. if you need that, go knock on STAR::Checker or STAR::Filter's door. no cap. 💀

🦋 AUTHOR 🦋

Wolfgang Bluhm, mail@wbluhm.com

Acknowledgments 🫶

Thanks to Phil Bourne, Helge Weissig, Anne Kuller, Doug Greer, Michele Bluhm, and others for support, help, and comments.

the way this whole thing exists because of a group chat of very nice people. we love the support system. 🌸

⭐ COPYRIGHT ⭐

🔥 SEE ALSO 🔥

STAR::Parser, STAR::Dictionary.

go read those next, bestie, they're the extended universe. 🌈

and that's the whole page!! 💖 this party was brought to you by perl v5.18.1 and dated 2001-07-10 — yes she's vintage, yes she still serves. <rainbow>slay, periodt, bye bestie!! 🎀✨👑🦋</rainbow>

📦 where this page comes from

debian bookworm: libstar-parser-perl 0.59-4
debian trixie: libstar-parser-perl 0.59-4
ubuntu jammy: libstar-parser-perl 0.59-4
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms