STAR::Parser(3pm)

💖 STAR::Parser 💖

okay bestie, welcome to the Perl extension for parsing STAR compliant files (with no nested loops) — that's the NAME, and she's serving exactly what she says on the tin 🌸

✨ Version ✨

This documentation refers to version 0.59 of this module. yes, we're old money, we're vintage, we're iconic 💅

---

🌈 SYNOPSIS 🌈

use STAR::Parser;

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

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

---

🦋 DESCRIPTION 🦋

okay so STAR::Parser is one of several related Perl modules for parsing STAR compliant files — think CIF and mmCIF files, the whole vibe 🌟 Currently, these modules include STAR::Parser, STAR::DataBlock, STAR::Dictionary, STAR::Writer, STAR::Checker, and STAR::Filter. the squad fr fr 👑

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 — meaning only one level of loop is supported, that's the boundary, no cap 🚧

So when you parse a file, you get back an array of DataBlock objects (one for each data_ entry in the file) 💖 The class STAR::DataBlock contains object methods for these objects, and STAR::DataBlock is automatically accessible through STAR::Parser. Main character energy, honestly ✨

When you parse a dictionary (which you signal with the -dict=>1 parameter), you get back an array of Dictionary objects instead. And plot twist: STAR::Dictionary is a sub-class of STAR::DataBlock 🎀 the family tree is thriving.

The methods of this module and the accompanying modules (STAR::DataBlock, STAR::Checker, etc.) support "named parameters" style for passing arguments. And here's the tea: 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, bestie, because examples are everything 💜:

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];

So here's what this method is actually doing, step by step 🧚

First, it searches the file and creates a DataBlock object for each data_ identifier found in the file. And 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 instead. glow up 🔥

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 (which is what happens if there's only one data_ block in the file). consistency queen 👑

Internally, the parsed data is stored in a multidimensional hash with keys for data blocks ($d), save blocks ($s), categories ($c), and items ($i) 💅 Let's break it down:

• 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, so watch out, iykyk).
• If a file is parsed that contains no data_ identifier, then $d becomes 'untitled'.
• $c refers to a category, such as _atom_site.
• $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 💀

ngl, we gotta be real here: 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. so like, it's not abandoned, it's just living in another module's house 🏠✨

---

🌸 AUTHOR 🌸

Wolfgang Bluhm, mail@wbluhm.com — legend behaviour, we stan 🫶

🌈 Acknowledgments 🌈

Thanks to Phil Bourne, Helge Weissig, Anne Kuller, Doug Greer, Michele Bluhm, and others for support, help, and comments. the group chat came THROUGH 💖

---

💜 COPYRIGHT 💜

A full copyright statement is provided with the distribution.

Copyright (c) 2000 University of California, San Diego.

---

⭐ SEE ALSO ⭐

STAR::DataBlock, STAR::Dictionary. go read them next, bestie, they're the sequel 📖✨

---

and that's the whole page, no notes 💅 this lil doc was brought to you by perl v5.18.1 and dated 2004-04-08 — vintage diva behaviour, ate and left no crumbs 👑🎀💖