STAR::DataBlock - Perl extension for handling DataBlock objects created by STAR::Parser.
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[,
-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.
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,
-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.
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:
RCSB011457 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, mail@wbluhm.com
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
STAR::Parser, STAR::Dictionary.