Provided by: libstar-parser-perl_0.59-4_all 
NAME
STAR::DataBlock - Perl extension for handling DataBlock objects created by STAR::Parser.
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
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.
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.
COPYRIGHT
A full copyright statement is provided with the distribution Copyright (c) 2000 University of California,
San Diego
SEE ALSO
STAR::Parser, STAR::Dictionary.