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