Version
This documentation refers to version 0.58 of this module.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...
}
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.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.
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).
OBJECT METHODS
store
Usage: $data_obj->store($file);
Saves a DataBlock object to disk. This method is in Storable.
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.
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.
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 '-'.
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.
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).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