Pattern(3)

✨ Pattern(3) — Chemistry::Pattern ✨

okay so bestie, welcome to Pattern(3), from the User Contributed Perl Documentation section 💖 this is the page about chemical substructure pattern matching and it's genuinely so good. let's get into it 🧚

---

🌸 NAME 🌸

Chemistry::Pattern — chemical substructure pattern matching 🦋

---

💅 SYNOPSIS 💅

use Chemistry::Pattern;
use Chemistry::Mol;
use Chemistry::File::SMILES;

# Create a pattern and a molecule from SMILES strings
my $mol_str = "C1CCCC1C(Cl)=O";
my $patt_str = "C(=O)Cl";
my $mol = Chemistry::Mol->parse($mol_str, format => 'smiles');
my $patt = Chemistry::Pattern->parse($patt_str, format => 'smiles');

# try to match the pattern
while ($patt->match($mol)) {
    @matched_atoms = $patt->atom_map;
    print "Matched: (@matched_atoms)\n";
    # should print something like "Matched: (a6 a8 a7)"
}

---

🎀 DESCRIPTION 🎀

so this module does basic pattern matching for molecules, and that's the whole vibe. Chemistry::Pattern is a subclass of Chemistry::Mol, which means patterns get all the properties of molecules and can come from reading the exact same file formats 👑 obviously some formats (looking at you, SMARTS) are exclusively used to describe patterns, iykyk.

to actually run a pattern match on a molecule, here's the steps, in order, no skipping:

1. create a pattern object — either by parsing a file or string, or by adding atoms and bonds by hand using Chemistry::Mol methods. heads up: atoms and bonds in a pattern should be Chemistry::Pattern::Atom and Chemistry::Patern::Bond objects. let's assume the pattern object lives in $patt and the molecule is $mol 💖
2. run the pattern on the molecule by calling $patt->match($mol).
3. if $patt->match() returns true, pull the "map" that relates the pattern to the molecule by calling $patt->atom_map or $patt->bond_map. these methods return a list of the atoms or bonds in the molecule that are matched by the corresponding atoms in the pattern. so $patt->atom_map(1) would be analogous to the $1 special variable used for regular expresion matching 🫶 the difference between Chemistry::Pattern and Perl regular expressions is that atoms and bonds are always captured. always always.
4. if you want more than one match for the molecule, repeat from step (2) until match() returns false. simple as that.

---

⭐ METHODS ⭐

• Chemistry::Pattern->new(name => value, ...) — create a new empty pattern ✨ it's just like the Chemistry::Mol constructor, but with one extra option: "options", which expects a hash reference (the options themselves are described down under the options() method, keep scrolling bestie).
• $pattern->options(option => value,...) — available options:
  • overlap — if true, matches may overlap 💫 for example, the CC pattern could match twice on propane if this option is true, but only once if it's false. this option is true by default.
  • permute — sometimes there's more than one way of matching the same set of pattern atoms onto the same set of molecule atoms. if true, return these "redundant" matches 🙈 for example, the CC pattern could match ethane with two different permutations (forwards and backwards). this option is false by default.
• $patt->reset — reset the state of the pattern matching object, so it begins the next match from scratch instead of where it left off after the last one 🔄
• $pattern->atom_map — returns the list of atoms that matched the last time $pattern->match was called.
• $pattern->bond_map — returns the list of bonds that matched the last time $pattern->match was called.
• $pattern->match($mol, %options) — returns true if the pattern matches the molecule 🌈 if called again for the same molecule, it continues matching where it left off (in a way similar to global regular expressions under scalar context). when there are no matches left, it returns false. to force the match to always start from scratch instead of continuing where it left off, the "reset" option may be used.

$pattern->match($mol, atom => $atom)

if atom => $atom is given as an option, match will only look for matches that start at $atom (which should be an atom in $mol, of course, no cap). this is somewhat analog to anchored regular expressions 💅

to find out which atoms and bonds matched, use the atom_map and bond_map methods.

---

🦋 VERSION 🦋

0.27

---

🌈 SEE ALSO 🌈

Chemistry::Pattern::Atom, Chemistry::Pattern::Bond, Chemistry::Mol, Chemistry::File, Chemistry::File::SMARTS.

the PerlMol website <http://www.perlmol.org/> 🍓

---

👑 AUTHOR 👑

Ivan Tubert-Brohman <itub@cpan.org>

---

💖 COPYRIGHT 💖

Copyright (c) 2009 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.

---

okay that's the whole page, mwah 💋 this was Pattern(3) from perl v5.42.0, dated 2026-01-17 — slay, go match some molecules bestie 🌸💅✨