purescript-grasp

What is Grasp?

Grasp, short for GRAph Specification Processor, allows you to:

• Specify graphs in a super concise format.
• Export graph structure to many other formats.
• Leave formatting (layout, colouring, etc.) to other tools, such as GraphViz.

Some points of comparison to give you an idea:

	grasp	GraphViz	mermaid
syntax	concise	a bit faffy at times
semantics	anything	visual
nodes and edges have	optional type annotations	visual markup
export to	anything; see export formats	graphics formats
higher graphs (edges between edges)	TODO	no
styling rules	in separate CSS-like file	part of graph	in same file

Examples

Syntax is inspired by both GraphViz and Cypher:

# concise node and edge syntax

a -> b
b -> c; c -> d
d, e, f -> g

# labeled edges

1 -succ-> 2

# type annotations

x:A -f-> y:B
y -g:G-> z

# function application syntax

x -f(x)-> y
x -> f(x)
x:A -f(x)-> y:B

Note that we only describe graph structure above, along with various labels and annotations. Grasp provides a separate CSS-like styling language:

x11 { shape: point; xlabel: x11 }
x12 { shape: point }
y11 { shape: point }
f11 { shape: box; label: f; background: purple; }

So, like HTML and CSS, Grasp and its styling language allow you to decouple the styling from the structure. This has many advantages over the coupled approach that something like GraphViz allows. Although the styling language is mostly at a proof of concept stage for now, it does work, and it does allow you to specify some useful styling attributes.

Export formats

Work on implementing these is ongoing:

• [X] GraphViz
• [X] PlantUML sequence diagram
• [ ] Datalog, Prolog, other logic programming languages
• [ ] Cypher (Neo4j and others)
• [ ] JSON
• [ ] CSV
• [ ] Markdown
• [ ] org-table
• [ ] vis.js

Usage

Install:

npm install && bower install

Build:

npm run build

Run:

cat example/test1.grasp | node cli/grasp.js

Test:

npm run test

Bundle:

npm run build
npm run bundle

Features and roadmap

• [X] graph structure markup language (no styling is a feature!)
• [X] separate stylesheets
  • [X] CSS-like stylesheets (toy implementation for now)
• [X] comma syntax: a,b,c -> d, e for hypergraphs and / or multigraphs
• [X] type syntax? a:A - b:B -> c:C
• [X] function application syntax: x -> f(x) -> y
• [ ] higher graphs (arrows between arrows)
• [ ] ports (could be used for string diagrams, among others)
• [ ] comments
• [ ] transitive syntax? a -> b -> c -> d
• [ ] reverse and bidirectional arrows?
• [ ] allow (back)slash in node / edge labels? (handy for paths and URLs)?
• [ ] quoted node / edge labels?
• [ ] dash as part of identifiers (but without conflicts or ambiguities)
• [ ] question mark as part of identifiers?
• [ ] node / edge ids? maybe using hash mark?
• [ ] allow references: graph transformations, styling, comments, legend, etc
• [ ] output ranges of parsed symbols, i.e. start and end line and column numbers