# tafia/calamine architecture

> Architecture diagram of the GitHub repository tafia/calamine, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tafia/calamine
- Repository: https://github.com/tafia/calamine

## Overview

Calamine is a read-only Rust library for opening Excel and OpenDocument spreadsheets, exposing worksheet data and Serde deserialization. The principal workflow is caller → workbook-opening API → format-specific parser → worksheet range → optional range deserializer. Format parsers also expose workbook metadata, formulas, styles, tables, hyperlinks, pictures, and VBA where supported. The graph includes the major parser and shared-runtime modules identified by the source index; unsampled implementation details and connections are omitted unless documented or referenced there.

Main entry points: [`src/xlsx/mod.rs`](https://github.com/tafia/calamine/blob/master/src/xlsx/mod.rs) (XLSX Reader), [`src/auto.rs`](https://github.com/tafia/calamine/blob/master/src/auto.rs) (Auto Detection), [`src/xlsb/mod.rs`](https://github.com/tafia/calamine/blob/master/src/xlsb/mod.rs) (XLSB Reader), [`src/xls.rs`](https://github.com/tafia/calamine/blob/master/src/xls.rs) (XLS Reader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Public API"]
  node_public_api["Reader API<br/>[lib.rs]"]
  node_auto_open["Auto Detection<br/>[auto.rs]"]
end

subgraph group_formats["Format Readers"]
  node_xlsx["XLSX Reader<br/>[mod.rs]"]
  node_xlsx_cells["XLSX Cell Reader<br/>[cells_reader.rs]"]
  node_xlsx_styles["XLSX Style Parser<br/>[style_parser.rs]"]
  node_xlsb["XLSB Reader<br/>[mod.rs]"]
  node_xlsb_cells["XLSB Cell Reader<br/>[cells_reader.rs]"]
  node_xls["XLS Reader<br/>[xls.rs]"]
  node_ods["ODS Reader<br/>[ods.rs]"]
end

subgraph group_shared["Shared Parsing"]
  node_cfb["Compound Files<br/>[cfb.rs]"]
  node_attrs["XML Attributes<br/>[attrs.rs]"]
  node_utils["Parsing Utilities<br/>[utils.rs]"]
  node_ole_properties["OLE Properties<br/>[oleps.rs]"]
  node_vba["VBA Projects<br/>[vba.rs]"]
end

subgraph group_outputs["Data and Metadata"]
  node_ranges["Worksheet Ranges<br/>[lib.rs]"]
  node_cell_values["Cell Values<br/>[datatype.rs]"]
  node_formats_data["Number Formats<br/>[formats.rs]"]
  node_styles["Cell Styles<br/>[style.rs]"]
  node_deserializer["Range Deserializer<br/>[de.rs]"]
end

node_caller(("Library Caller"))

node_caller -->|"opens workbook"| node_public_api
node_public_api -->|"supports auto-open"| node_auto_open
node_public_api -->|"requests sheet range"| node_ranges
node_ranges -->|"deserializes range"| node_deserializer
node_auto_open -.->|"dispatches by format"| node_xlsx
node_auto_open -.->|"dispatches by format"| node_xlsb
node_auto_open -.->|"dispatches by format"| node_xls
node_auto_open -.->|"dispatches by format"| node_ods
node_xlsx -->|"uses cell reader"| node_xlsx_cells
node_xlsx -->|"uses style parser"| node_xlsx_styles
node_xlsb -->|"uses cell reader"| node_xlsb_cells
node_xlsx -->|"parses attributes"| node_attrs
node_xlsb -->|"parses attributes"| node_attrs
node_ods -->|"parses attributes"| node_attrs
node_xlsx -->|"classifies number formats"| node_formats_data
node_xls -->|"classifies number formats"| node_formats_data
node_xlsb -->|"classifies number formats"| node_formats_data
node_xlsx -->|"parses styles"| node_styles
node_xlsx_styles -->|"builds style data"| node_styles
node_xlsx_cells -->|"reads XML attributes"| node_attrs
node_xls -->|"reads compound file"| node_cfb
node_xls -->|"reads properties"| node_ole_properties
node_ole_properties -->|"reads compound file"| node_cfb
node_vba -->|"decompresses streams"| node_cfb
node_cfb -->|"uses binary helpers"| node_utils
node_xlsx -->|"exposes VBA project"| node_vba
node_xlsb -->|"exposes VBA project"| node_vba
node_xls -->|"exposes VBA project"| node_vba
node_public_api -->|"exposes cell types"| node_cell_values

click node_public_api "https://github.com/tafia/calamine/blob/master/src/lib.rs"
click node_auto_open "https://github.com/tafia/calamine/blob/master/src/auto.rs"
click node_xlsx "https://github.com/tafia/calamine/blob/master/src/xlsx/mod.rs"
click node_xlsx_cells "https://github.com/tafia/calamine/blob/master/src/xlsx/cells_reader.rs"
click node_xlsx_styles "https://github.com/tafia/calamine/blob/master/src/xlsx/style_parser.rs"
click node_xlsb "https://github.com/tafia/calamine/blob/master/src/xlsb/mod.rs"
click node_xlsb_cells "https://github.com/tafia/calamine/blob/master/src/xlsb/cells_reader.rs"
click node_xls "https://github.com/tafia/calamine/blob/master/src/xls.rs"
click node_ods "https://github.com/tafia/calamine/blob/master/src/ods.rs"
click node_cfb "https://github.com/tafia/calamine/blob/master/src/cfb.rs"
click node_attrs "https://github.com/tafia/calamine/blob/master/src/attrs.rs"
click node_utils "https://github.com/tafia/calamine/blob/master/src/utils.rs"
click node_ole_properties "https://github.com/tafia/calamine/blob/master/src/oleps.rs"
click node_vba "https://github.com/tafia/calamine/blob/master/src/vba.rs"
click node_ranges "https://github.com/tafia/calamine/blob/master/src/lib.rs"
click node_cell_values "https://github.com/tafia/calamine/blob/master/src/datatype.rs"
click node_formats_data "https://github.com/tafia/calamine/blob/master/src/formats.rs"
click node_styles "https://github.com/tafia/calamine/blob/master/src/style.rs"
click node_deserializer "https://github.com/tafia/calamine/blob/master/src/de.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_public_api,node_auto_open toneBlue
class node_xlsx,node_xlsx_cells,node_xlsx_styles,node_xlsb,node_xlsb_cells,node_xls,node_ods toneAmber
class node_cfb,node_attrs,node_utils,node_ole_properties,node_vba toneMint
class node_ranges,node_cell_values,node_formats_data,node_styles,node_deserializer toneRose
class node_caller toneIndigo
```

## Components

### Public API

- [Reader API](https://github.com/tafia/calamine/blob/master/src/lib.rs): `src/lib.rs`
- [Auto Detection](https://github.com/tafia/calamine/blob/master/src/auto.rs): `src/auto.rs`

### Format Readers

- [XLSX Reader](https://github.com/tafia/calamine/blob/master/src/xlsx/mod.rs): `src/xlsx/mod.rs`
- [XLSX Cell Reader](https://github.com/tafia/calamine/blob/master/src/xlsx/cells_reader.rs): `src/xlsx/cells_reader.rs`
- [XLSX Style Parser](https://github.com/tafia/calamine/blob/master/src/xlsx/style_parser.rs): `src/xlsx/style_parser.rs`
- [XLSB Reader](https://github.com/tafia/calamine/blob/master/src/xlsb/mod.rs): `src/xlsb/mod.rs`
- [XLSB Cell Reader](https://github.com/tafia/calamine/blob/master/src/xlsb/cells_reader.rs): `src/xlsb/cells_reader.rs`
- [XLS Reader](https://github.com/tafia/calamine/blob/master/src/xls.rs): `src/xls.rs`
- [ODS Reader](https://github.com/tafia/calamine/blob/master/src/ods.rs): `src/ods.rs`

### Shared Parsing

- [Compound Files](https://github.com/tafia/calamine/blob/master/src/cfb.rs): `src/cfb.rs`
- [XML Attributes](https://github.com/tafia/calamine/blob/master/src/attrs.rs): `src/attrs.rs`
- [Parsing Utilities](https://github.com/tafia/calamine/blob/master/src/utils.rs): `src/utils.rs`
- [OLE Properties](https://github.com/tafia/calamine/blob/master/src/oleps.rs): `src/oleps.rs`
- [VBA Projects](https://github.com/tafia/calamine/blob/master/src/vba.rs): `src/vba.rs`

### Data and Metadata

- [Worksheet Ranges](https://github.com/tafia/calamine/blob/master/src/lib.rs): `src/lib.rs`
- [Cell Values](https://github.com/tafia/calamine/blob/master/src/datatype.rs): `src/datatype.rs`
- [Number Formats](https://github.com/tafia/calamine/blob/master/src/formats.rs): `src/formats.rs`
- [Cell Styles](https://github.com/tafia/calamine/blob/master/src/style.rs): `src/style.rs`
- [Range Deserializer](https://github.com/tafia/calamine/blob/master/src/de.rs): `src/de.rs`

### Other components

- **Library Caller**

## Connections

- Library Caller → Reader API: opens workbook (evidence: `README.md`)
- Reader API → Auto Detection: supports auto-open (evidence: `README.md`)
- Reader API → Worksheet Ranges: requests sheet range (evidence: `README.md`)
- Worksheet Ranges → Range Deserializer: deserializes range (evidence: `README.md`)
- Auto Detection → XLSX Reader: dispatches by format
- Auto Detection → XLSB Reader: dispatches by format
- Auto Detection → XLS Reader: dispatches by format
- Auto Detection → ODS Reader: dispatches by format
- XLSX Reader → XLSX Cell Reader: uses cell reader (evidence: `src/xlsx/mod.rs`)
- XLSX Reader → XLSX Style Parser: uses style parser (evidence: `src/xlsx/mod.rs`)
- XLSB Reader → XLSB Cell Reader: uses cell reader (evidence: `src/xlsb/mod.rs`)
- XLSX Reader → XML Attributes: parses attributes (evidence: `src/xlsx/mod.rs`)
- XLSB Reader → XML Attributes: parses attributes (evidence: `src/xlsb/mod.rs`)
- ODS Reader → XML Attributes: parses attributes (evidence: `src/ods.rs`)
- XLSX Reader → Number Formats: classifies number formats (evidence: `src/xlsx/mod.rs`)
- XLS Reader → Number Formats: classifies number formats (evidence: `src/xls.rs`)
- XLSB Reader → Number Formats: classifies number formats (evidence: `src/xlsb/mod.rs`)
- XLSX Reader → Cell Styles: parses styles (evidence: `src/xlsx/mod.rs`)
- XLSX Style Parser → Cell Styles: builds style data (evidence: `src/xlsx/style_parser.rs`)
- XLSX Cell Reader → XML Attributes: reads XML attributes (evidence: `src/xlsx/cells_reader.rs`)
- XLS Reader → Compound Files: reads compound file (evidence: `src/xls.rs`)
- XLS Reader → OLE Properties: reads properties (evidence: `src/xls.rs`)
- OLE Properties → Compound Files: reads compound file (evidence: `src/oleps.rs`)
- VBA Projects → Compound Files: decompresses streams (evidence: `src/vba.rs`)
- Compound Files → Parsing Utilities: uses binary helpers (evidence: `src/cfb.rs`)
- XLSX Reader → VBA Projects: exposes VBA project (evidence: `src/xlsx/mod.rs`)
- XLSB Reader → VBA Projects: exposes VBA project (evidence: `src/xlsb/mod.rs`)
- XLS Reader → VBA Projects: exposes VBA project (evidence: `src/xls.rs`)
- Reader API → Cell Values: exposes cell types (evidence: `src/lib.rs`)
