NAME

STAR::DataBlock - Perl extension for handling DataBlock objects created by STAR::Parser.


Version

This documentation refers to version 0.56 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

Copyright (c) 2000 Wolfgang Bluhm, San Diego Supercomputer Center, University of California, San Diego. All rights reserved. This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself.


SEE ALSO

STAR::Parser, STAR::Dictionary.