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.