STAR::DataBlock(3) Perl extension for handling DataBlock objects created


This documentation refers to version 0.58 of this module.


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


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.

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

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.



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



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

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


  Usage: @item_data = $data_obj->get_item_data(-item=>$item[,
  my @names=$data_obj->
  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.


  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.


  Usage: @items = $data_obj->get_items;

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


  Usage: @categories = $data_obj->get_categories;

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


  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 '-'.


  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 '-'.


  Usage: $data_obj->set_item_data( -item=>$item, 
                                   -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.

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


  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


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

Title of the DataBlock object


  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)


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

Line number where data block started in the file


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

Line number where data block ended in the file


  Usage: $info = $data_obj->get_attributes;

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

  File: native/1fbm.cif   Lines: 1 to 5294
  cif_mm.dic (dictionary)
  File: dictionary/mmcif_dict.txt   Lines: 89 to 38008


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.


Wolfgang Bluhm, [email protected]


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


A full copyright statement is provided with the distribution Copyright (c) 2000 University of California, San Diego