Pangrm

Pangrm /ˈpæn.ɡræm/ — The universal graph model converter Inspired by Pandoc, Pangrm lets you convert graph-based models across diverse formats — reliably, reproducibly, and type-safely.

What is Pangrm?

Pangrm is a Haskell-based library and CLI tool for converting graph models from one format to another.

The name Pangrm stands for Pan (universal) + GRM (GRAph Model), reflecting its core purpose:

Universal graph model conversion.¹

Just like Pandoc provides universal document conversion, Pangrm aims to do the same for graph-based modeling formats — such as .dot, .bpmn, .archimate, and more.

Why Pangrm?

• Modeling tools are fragmented.
• Formats are incompatible.
• Round-trip conversion is error-prone.

With Pangrm – The universal graph model converter, graph model processing is intended to become as seamless and versatile as Pandoc made it for documents.

Pangrm provides:

• 🧩 Modular architecture — Easily plug in new formats (cf. How to Add a New Pangrm Format
• ✅ Type safety — Every conversion step is typed and verifiable
• 🔁 Roundtrip capability — Parse → Unify → Render (back and forth)
• 📦 CLI & Library — Use it as a developer or in pipelines
• 🧪 Comprehensive test suite — Roundtrip fidelity and edge-case safety
• 🔗 Inspired by Pandoc² — Familiar concepts, stricter semantics

Supported Formats

Pangrm currently supports parsing and writing the following formats:

Tag	Format
dot	The GraphViz file format
cql	Cypher, Neo4j's declarative query language
puml	The PlantUML file format
mxg	The MXGraph file format
amx	The OpenGroup ArchiMate Model Exchange file format
ldif	The SAP LeanIX LeanIX Data Interchange file format
bpmn	The OMG Business Process Model and Notation file format
archimate	The ArchiMate Tool proprietary file format

More formats can be added via a clean extension mechanism.

How It Works

       [Reader]      [Writer]

         Text         Text
          ↓            ↑
      [inject]      [render]
          ↓            ↑
      AST Format    AST Format
          ↓            ↑
       [unify]      [eject]
          ↓            ↑
      [Graph as unified IR]

Pangrm converts from textual input (→ format-specific AST → unified graph IR → format-specific AST) → textual output ...and back again. Every supported format must implement both a Reader and a Writer interface. In other words, a Pangrm format must adhere to its defining property: it must be normalizable — i.e., both readable and writable.

Installation

You'll need GHC and Cabal.

Clone the Repository

git clone https://github.com/normenmueller/pangrm.git
cd ./pangrm

Build & Install using make (recommended)

make

This will:

1. Clean old builds
2. Build the core lib (pangrm) and CLI (pangrm-cli)
3. Run tests
4. Install both via Cabal

Manual Build (without Make)

cabal update
cabal clean

Then:

cd lib/
cabal build --enable-tests
cabal test
cabal install
cd ../cli/
cabal build --enable-tests
cabal test
cabal install

✅ Pangrm is now ready to use!

Usage

Pangrm consists of two components:

• pangrm-lib — the core graph modeling library
• pangrm-cli — the CLI tool

Example:

pangrm --from ldif --to cql --input example.ldif --output example.cql

To see all options:

pangrm --help

Contributing

We welcome contributions!

Guidelines

• Follow idiomatic Haskell style & run hlint

• Write tests for new features Before submitting:

  cabal test --enable-tests

• Document public interfaces

• Prefer total functions and safe types

• Work on feature branches and open PRs when ready.

Protected trunk branch

The trunk branch is protected:

• No one (not even maintainers) can push directly to trunk.
• All changes must go through a Pull Request (PR) with at least one review.
• Only squash merges are allowed to ensure a linear, clean commit history.
• Force-push and branch deletion are blocked.

This guarantees stability, traceability, and a clear audit trail for all changes.

Format Plugin Example

To add a new format:

1. Define your format
2. Implement your format specific Reader and Writer
3. Register your format in the Pangrm registry
4. Test your format normalization

See extending Pangrm for details.

FAQ

Q: Is Pangrm a GUI modeling tool?

A: No. Pangrm is a backend tool. Think of it like Pandoc, but for graph models.

Q: Can Pangrm handle lossy formats like images or SVG?

A: No, Pangrm is about structural conversion of graph models — not visual layout fidelity.

Q: How does Pangrm ensure roundtrip safety?

A: By relying on the "normalizable" nature of Pangrm formats — each format is both readable and writable, enabling safe roundtrips.

License

See LICENSE © 2025 nemron

Made with ❤️ in Haskell.

Footnotes

1. Also cf. Pangrm Terminology ↩

2. Pangrm owes significant conceptual inspiration to Pandoc, particularly its modular format architecture, reader/writer abstraction, and normalized intermediate representation. Sincere thanks to John MacFarlane and contributors for their foundational work. ↩