NAME

STAR::Parser - Perl extension for parsing STAR compliant files (with no nested loops).

Version

This documentation refers to version 0.59 of this module.

SYNOPSIS

  use STAR::Parser;
  
  ($data) = STAR::Parser->parse('1fbm.cif');

  ($dict) = STAR::Parser->parse(-file=>'mmcif_dict',
                                -dict=>1,
                                -options=>'l');  #logs activity

DESCRIPTION

STAR::Parser is one of several related Perl modules for parsing STAR compliant files (such as CIF and mmCIF files). Currently, these modules include STAR::Parser, STAR::DataBlock, STAR::Dictionary, STAR::Writer, STAR::Checker, and STAR::Filter.

STAR::Parser is the parsing module, with the class method parse for parsing any STAR compliant files or dictionaries, as long as they do not contain nested loops (i.e., only one level of loop is supported). Upon parsing of a file, an array of DataBlock objects is returned (one for each data_ entry in the file). The class STAR::DataBlock contains object methods for these objects. STAR::DataBlock is automatically accessible through STAR::Parser. Upon parsing of a dictionary (indicated with the -dict=>1 parameter), an array of Dictionary objects is returned. STAR::Dictionary is a sub-class of STAR::DataBlock.

The methods of this module and the accompanying modules (STAR::DataBlock, STAR::Checker, etc.) support "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:

       @objs = STAR::Parser->parse( -file=>$file, -options=>'d' );  #debugging

       @objs = STAR::Parser->parse( -file=>$file );  #no options
   or: @objs = STAR::Parser->parse( $file );

CLASS METHODS

parse

  Usage:  @objs = STAR::Parser->parse(-file=>$file[,
                                      -dict=>1,
                                      -options=>$options]);

     or:  @objs = STAR::Parser->parse($file);
                                    
  Examples: 
  
  1)  @objs = STAR::Parser->parse('1fbm.cif');
      $data = $objs[0];

      OR:

      ($data) = STAR::Parser->parse('1fbm.cif');

  2)  @objs = STAR::Parser->parse('7files.txt');
      foreach $obj (@objs) {
          # do something, see STAR::DataBlock
      }

  3)  @objs = STAR::Parser->parse(-file=>'mmcif_dict',
                                  -dict=>1,
                                  -options=>'l'); #logs activity
      $dict = @objs[0];

This method first searches the file and creates a DataBlock object for each data_ identifier found in the file. If no data_ identifier is found, then only one DataBlock object will be created (with $d='untitled', see below). If parse is invoked with the -dict=>1 option, then a Dictionary object is created for each data_ identifier found.

Next, the method populates the data structure of each DataBlock or Dictionary object. The parsed data may be queried or accessed by object methods of the STAR::DataBlock and STAR::Dictionary modules. See the documentation for STAR::DataBlock and STAR::Dictionary.

The method always returns an array of objects, even if it contains only one object (if there is only one data_ block in the file).

Internally, the parsed data is stored in a multidimensional hash with keys for data blocks ($d), save blocks ($s), categories ($c), and items ($i). For a file, $s will always be '-', since there are no save blocks in files. For a dictionary, $s will be '-' outside of save_ blocks, and 'CATEGORY' or '_item' inside save_CATEGORY or save__item blocks (capitalization depends on the user's dictionary.) If a file is parsed that contains no data_ identifier, then $d becomes 'untitled'. $c refers to a category, such as _atom_site and $i refers to an item, such as _atom_site.id.

The method may be invoked with an $options string. These options are the following letters which may be concatenated in any order:

  d  writes debugging output to STDERR 
  l  writes program activity log to STDERR

COMMENTS

This module provides no error checking of files or objects, either against the dictionary, or otherwise. While the module is applicable to parsing either a file or a dictionary, dictionary information is not currently used in the parsing of files. 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.

Demeter