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.

COPYRIGHT

       A full copyright statement is provided with the distribution Copyright (c) 2000 University of California,
       San Diego

SEE ALSO

       STAR::DataBlock, STAR::Dictionary.