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.