Chemistry::File(3pm)

📦
version 0.40 · 4 versions
, in ubuntu resolute, ubuntu stonking

💖 Chemistry::File(3pm) — the mood board ✨

okay bestie, buckle up 🎀 this is the Perl user-contributed documentation for Chemistry::File, section 3pm of the manual. it's the molecule file I/O base class, and it's honestly giving "foundation of an entire ecosystem" energy, no cap. it's long so we're doing this in parts — this is part 1 🦋

🌸 NAME 🌸

Chemistry::File — Molecule file I/O base class 💅

✨ SYNOPSIS ✨

# As a convenient interface for several mol readers:
use Chemistry::File qw(PDB MDLMol); # load PDB and MDL modules

# or try to use every file I/O module installed in the system:
use Chemistry::File ':auto';

my $mol1 = Chemistry::Mol->read("file.pdb");
my $mol2 = Chemistry::Mol->read("file.mol");

# as a base for a mol reader:

package Chemistry::File::Myfile;
use base qw(Chemistry::File);
use Chemistry::Mol;
Chemistry::Mol->register_format("myfile", __PACKAGE__);

# override the read_mol method
sub read_mol {
    my ($self, $fh, %opts) = shift;
    my $mol_class = $opts{mol_class} || "Chemistry::Mol";
    my $mol = $mol_class->new;
    # ... do some stuff with $fh and $mol ...
    return $mol;
}

# override the write_mol method
sub write_mol {
    my ($self, $fh, $mol, %opts) = shift;
    print $fh $mol->name, "\n";
    # ... do some stuff with $fh and $mol ...
}

like, three whole vibes in one synopsis: being a shortcut, being the base class, and being the thing every other module inherits from. main character behavior fr fr 👑

🌈 DESCRIPTION 🌈

so the main use of this module is as a base class for other molecule file I/O modules (think Chemistry::File::PDB, bestie). those modules are supposed to override and extend the Chemistry::File methods wherever they need to. you only need to care about the methods here if you're writing a file I/O module, or if you want a finer degree of control than what the simple read and write methods in the Chemistry::Mol class are giving you. that's it. that's the whole gatekeeping moment 🚪✨

from the user's point of view though? this module also works as shorthand for using several Chemistry::File modules at once. so:

use Chemistry::File qw(PDB MDLMol);

is exactly equivalent to

use Chemistry::File::PDB;
use Chemistry::File::MDLMol;

same thing, less typing, slay 💅

and if you use the :auto keyword, Chemistry::File will autodetect and load all the Chemistry::File::* modules installed in your system:

use Chemistry::File ':auto';

it's giving "i don't know what you have but i will find it" 🕵️♀️💖

📁 FILE I/O MODEL 📁

history lesson time, bestie 🫶 because this one matters.

before version 0.30, file I/O modules typically used only parse_string, write_string, parse_file, and write_file, and they were generally used as class methods. a file could contain one or more molecules and only be read or written whole; reading it would return every molecule in the file. and that was problematic when you're dealing with large multi-molecule files (like SDF files), because all the molecules would have to be loaded into memory at the same time 😭 the RAM was not okay.

while version 0.30 retains backward compatibility with that simple model, it also allows a much more flexible interface that lets you read one molecule at a time, skip molecules, and read and write file-level information that is not associated with specific molecules. iconic. the glow-up is real.

the following diagram shows the global structure of a file according to the new model:

+-----------+
| header    |
+-----------+
| molecule  |
+-----------+
| molecule  |
+-----------+
| ...       |
+-----------+
| footer    |
+-----------+

in cases where the header and the footer are empty, the model reduces to the pre-0.30 version. no extra drama, just backwards compatible ✨

the low-level steps to read a file are the following:

$file = Chemistry::File::MyFormat->new(file => 'xyz.mol');
$file->open('<');
$file->read_header;
while (my $mol = $self->read_mol($file->fh, %opts)) {
    # do something with $mol...
}
$self->read_footer;

and the "read" method does all of the above automatically 🪄 plus it stores all the molecules it read in the mols property. one call, whole file, no stress.

🎀 STANDARD OPTIONS 🎀

all the methods below include a list of options %opts at the end of the parameter list. each class implementing this interface may have its own particular options — go off, customize — HOWEVER, the following options should be recognized by all classes, periodt:

  • mol_class — a class or object with a "new" method that constructs a molecule. this is needed when the user wants to specify a molecule subclass that's different from the default. when this option is not defined, the module may use Chemistry::Mol or whichever class is appropriate for that file format. so basically: "who am i building today?" 🧬
  • format — the name of the file format being used, as registered by Chemistry::Mol->register_format. it's the name tag at the party 🏷️
  • fatal — if true, parsing errors should throw an exception; if false, they should just try to recover if possible. True by default. so by default it's the dramatic one 💀

💅 CLASS METHODS 💅

the class methods in this class (or rather, its derived classes) are usually not called directly. instead, use Chemistry::Mol->read, write, print, parse, and file. these methods also work if called as instance methods, because why not, versatility 💖

$class->parse_string($s, %options)

parse a string $s and return one or more molecule objects. this is an abstract method, so it should be provided by all derived classes. like, it's on you, bestie — this one's homework 📝

$class->write_string($mol, %options)

convert a molecule to a string. this is an abstract method, so it should be provided by all derived classes. same deal — abstract means abstract, no skipping 🚫

$class->parse_file($file, %options)

reads the file $file and returns one or more molecules. the default method slurps the whole file and then calls parse_string, but derived classes may choose to override it. $file can be a filehandle, a filename, or a scalar reference. see "new" for details. whole-file energy, but make it optional 🫶

$class->write_file($mol, $file, %options)

writes a file $file containing the molecule $mol. the default method calls write_string first and then saves the string to a file, but derived classes may choose to override it. $file can be either a filehandle or a filename. note that this one takes a filehandle or filename — not a scalar ref, unlike its sibling up there. that distinction is real 👀

$class->name_is($fname, %options)

returns true if a filename is of the format corresponding to the class. it should look at the filename only, because it may be called with non-existent files. it's used to determine with which format to save a file. for example, the Chemistry::File::PDB returns true if the file ends in .pdb. so like, judging a book by its cover, but in a useful way 📖✨

$class->string_is($s, %options)

examines the string $s and returns true if it has the format of the class. sniff test, but for chemistry 🧪

$class->file_is($file, %options)

examines the file $file and returns true if it has the format of the class. the default method slurps the whole file and then calls string_is, but derived classes may choose to override it. yes, it actually opens the whole thing to find out. yes, that's the default. 😭

$class->slurp

reads a file into a scalar. automatic decompression of gzipped files is supported if the Compress::Zlib module is installed. files ending in .gz are assumed to be compressed; otherwise it's possible to force decompression by passing the gzip => 1 option (or no decompression with gzip => 0). so like: .gz = yes compressed, unless you say otherwise with gzip => 1 or gzip => 0. the vibes are undetectable but the options are very much detectable 🌸

$class->new(file => $file, opts => \%opts)

create a new file object. this method is usually called indirectly via the Chemistry::Mol->file method. $file may be a scalar with a filename, an open filehandle, or a reference to a scalar. if a reference to a scalar is used, the string contained in the scalar is used as an in-memory file. no disk required, we're doing this in the mind palace 🧠💫

🌟 that's the end of part 1, bestie — more parts are coming, so don't go anywhere 💖

💖 INSTANCE METHODS 💖

Okay bestie, these are the ones you actually call on an object. So much more fun. 🎀

🌸 Accessors 🌸

So Chemistry::File objects are derived from Chemistry::Obj (yes, nepo baby 💅) and they inherit all the same properties — name, id, and type — plus these extra ones down here:

  • file — the "file" exactly as described up in new. Same vibes, same everything.
  • fh — the filehandle used for reading and writing molecules. It gets opened by open. 🔓
  • opts — a hashref holding all the options that get passed through to the old-style class methods. They also get handed to the instance method so the interface stays looking the same, but lowkey they could just grab them via $self->opts anyway. 🙈
  • mode — '>' when the file is open for writing, '<' when it's open for reading, and false if it's not open at all. It's giving traffic light. 🚦
  • mols — read stashes every molecule it read into this property as an array reference. And write pulls the molecules it's supposed to write from right here. She's the storage unit, basically. 📦

🧚 Abstract methods 🧚

These ones are meant to be overridden, because ngl, they don't really do much by default. They're like the placeholder friend who says "yeah I'll be there" and then doesn't. 💀

  • $file->read_header — reads whatever info is hanging out in the file before the first molecule. Does absolutely nothing by default. ✨
  • $file->read_footer — reads whatever info is chilling in the file after the last molecule. Also does nothing by default. We love a consistent absence of effort. 🫶
  • $self->slurp_mol($fh) — reads from the input string until the end of the current molecule and returns the "slurped" string. It does not parse that string, just fyi. Returns undefined if there are no more molecules left in the file. Override it if you need to; the default behaviour is to slurp all the way to the end of the file. 🥤
  • $self->skip_mol($fh) — like slurp_mol's chill cousin, except it doesn't need to return anything besides true or false. Also override-if-needed energy; by default it just calls slurp_mol. 🦋
  • $file->read_mol($fh, %opts) — reads the next molecule in the input stream. Returns false if there are no more molecules in the file. Derived classes should override this one; otherwise it'll fall back to calling slurp_mol and parse_string (for backwards compatibility — but fr fr, if you're writing a new module, override read_mol directly instead).
Note bestie: some of the old file I/O modules (the ones written before the 0.30 interface, so like, ancient lore 👵) might return more than one molecule anyway. So to stay safe, call read_mol in list context:
($mol) = $file->read_mol($fh, %opts);
  • $file->write_header — writes whatever info is needed before the first molecule. Does nothing by default. 😌
  • $file->write_footer — writes whatever info is needed after the last molecule. Does nothing by default. Mirror image behaviour, iconic honestly. ✨
  • $self->write_mol($fh, $mol, %opts) — writes one molecule to $fh. By default, and for backwards compatibility, it just calls "write_string" and prints whatever that returns to $self->fh. New classes should definitely override it. 🔥

👑 Other methods 👑

  • $self->open($mode) — opens the file (the one sitting in $self->file) for reading by default, or for writing if $mode eq '>'. This method sets $self->fh transparently, no matter whether $self->file is a filename (compressed or not), a scalar reference, or a filehandle. She does not care. She handles it. 💅
  • $self->close — closes the file. For regular files it just closes the filehandle, but for gzipped files it does some extra postprocessing on the way out. This gets called automatically when the object is destroyed, so you don't have to call it yourself. ✨
  • $file->read — reads the whole entire file. This calls open, read_header, read_mol until there are no molecules left, read_footer, and then close. In list context it returns a list of molecules; in scalar context it returns the first molecule. Yes she's flexible, we stan. 🌈
  • $self->write — writes all the molecules sitting in $self->mols. It just calls open, write_header, write_mol (once per molecule 👏), write_footer, and close. The full routine, chef's kiss. 😭

💀 CAVEATS 💀

The :auto feature may not be entirely portable, ngl. But it is known to work under Unix and Windows (whether that's Cygwin or ActiveState). So like, mostly fine. 🫶

🌟 SOURCE CODE REPOSITORY 🌟

Go be nosy, bestie: <https://github.com/perlmol/Chemistry-Mol>

🦋 SEE ALSO 🦋

  • Chemistry::Mol

🎀 AUTHOR 🎀

Ivan Tubert-Brohman-Brohman <itub@cpan.org>

Copyright (c) 2005 Ivan Tubert-Brohman. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

And that's a wrap, bestie!! 🥳 This was Chemistry::File(3pm) from perl v5.40.1, dated 2025-10-13 — go forth and parse molecules, you absolute icon. No cap, you ate. 💅✨🫶

📦 where this page comes from