molframe-cif 0.5.2

PDBx/mmCIF reading and writing for molframe
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

# molframe-cif

PDBx/mmCIF parsing, interpretation, and writing.

The central design decision in this crate is to keep **syntax** separate from **structural meaning**. A CIF document records what the file said; lowering determines what those categories mean as a molecular structure.

```mermaid
flowchart LR
    Bytes["mmCIF bytes"] --> Lexer["Lexer"]
    Lexer --> Parser["Parser"]

    Parser --> Document["Lossless Document"]
    Document --> Lower["Structural lowering"]
    Lower --> Structure["molframe-core Structure"]

    Parser --> Direct["Direct / projected reader"]
    Direct --> Structure

    Document --> Preserve["Preserving writer"]
    Structure --> Canonical["Canonical projection"]
    Preserve --> Output["mmCIF"]
    Canonical --> Output
```

## Architecture

The crate provides two complementary read paths:

**Document path**  
Preserves ordering and categories, including information MolFrame does not interpret. This is appropriate for document tooling and loss-aware round trips.

**Structural path**  
Projects the categories required for molecular structure into the shared `Structure` representation. Direct and projected readers can avoid materializing an unnecessary complete document.

Interpretive decisions live in the lowering layer, where ambiguities can become diagnostics rather than parser guesses.

Writing follows the same separation: callers can preserve document-level information or construct a deterministic canonical structural projection.