sulpher

sulpher

A Cypher-compatible parser written in Go. Parses openCypher 9 queries into an Abstract Syntax Tree (AST).

Features

• Full openCypher 9 reading and writing clause set (MATCH, OPTIONAL MATCH, CREATE, MERGE, SET, DELETE, DETACH DELETE, REMOVE, FOREACH, RETURN, WITH, UNWIND, CALL … YIELD)
• UNION / UNION ALL between query parts
• Pattern matching with node patterns, directed and undirected relationships, multi-label nodes, multiple relationship types (|), and variable-length ranges ([*1..5])
• Graph path functions: shortestPath, allShortestPaths, with path variable assignment (p = shortestPath(…))
• Pratt expression parser handling the full operator precedence hierarchy
• List comprehensions [x IN list WHERE pred | expr], pattern comprehensions, quantifier expressions (ALL, ANY, NONE, SINGLE, FILTER)
• EXISTS subquery predicates
• Case-insensitive keywords (Cypher is case-insensitive for keywords)
• Backtick-quoted identifiers `My Label`
• Named parameters ($param)
• Line/block comment tokenisation (// and /* … */)
• Source-position (line, column) on every token
• Visitor and Inspector utilities for AST traversal

Installation

go get github.com/ha1tch/sulpher

Usage

package main

import (
    "fmt"
    "github.com/ha1tch/sulpher"
)

func main() {
    input := `MATCH (n:Person)-[:KNOWS]->(m:Person) RETURN n.name, m.name`

    query, errors := sulpher.Parse(input)
    if len(errors) > 0 {
        for _, err := range errors {
            fmt.Println("Error:", err)
        }
        return
    }

    fmt.Println(query.String())
}

Supported Syntax

Reading clauses

• MATCH (and OPTIONAL MATCH)
• WITH (with ORDER BY, SKIP, LIMIT, WHERE)
• UNWIND … AS
• CALL … YIELD … WHERE

Writing clauses

• CREATE
• MERGE (with ON CREATE SET and ON MATCH SET)
• SET (property assignment, property merge +=, label addition)
• DELETE / DETACH DELETE
• REMOVE
• FOREACH

Projection

• RETURN (with DISTINCT, ORDER BY, SKIP, LIMIT)
• RETURN *

Composite

• UNION / UNION ALL

Patterns

• Node patterns: (var:Label1:Label2 {prop: val})
• Directed relationship: -[r:TYPE]-> or <-[r:TYPE]-
• Undirected relationship: -[r:TYPE]-
• Multiple types: -[:A|B|C]->
• Variable-length: -[*]->, -[*1..5]->
• Path variables: p = (a)-[:KNOWS]->(b)
• shortestPath(…), allShortestPaths(…)

Expressions

• Arithmetic: +, -, *, /, %, ^
• Comparison: =, <>, <, >, <=, >=
• Logical: AND, OR, XOR, NOT
• String predicates: STARTS WITH, ENDS WITH, CONTAINS, =~ (regex)
• IN, IS NULL, IS NOT NULL, NOT IN
• Property access: n.prop
• Dynamic access / list slice: list[idx], list[from..to]
• Function calls: f(args), f(DISTINCT arg), qualified names apoc.util.sleep(…)
• count(*), count(DISTINCT expr)
• List literals: [1, 2, 3]
• Map literals: {name: 'Alice', age: 30}
• Named parameters: $param
• List comprehension: [x IN list WHERE pred | expr]
• Pattern comprehension: [(a)-[r]->(b) WHERE pred | expr]
• Quantifiers: ALL(x IN list WHERE pred), ANY(…), NONE(…), SINGLE(…)
• EXISTS subquery: EXISTS { MATCH (n) WHERE … }
• CASE (simple and searched)

Project Structure

sulpher/
├── token/          # Token types and keywords
├── lexer/          # Lexical analysis
├── ast/            # Abstract syntax tree nodes
├── parser/         # Recursive descent parser with Pratt expression parsing
├── version/        # Version information package
├── testdata/       # Cypher query samples for integration testing
├── cmd/example/    # Example usage
├── sulpher.go      # Main API
├── VERSION         # Version number (single source of truth)
└── go.mod

Version

Access the library version programmatically:

import "github.com/ha1tch/sulpher/pkg/version"

fmt.Println(version.Version)  // "0.1.0"
fmt.Println(version.Full())   // "sulpher version 0.1.0"

Testing

Run all tests:

go test ./...

Run parser tests verbosely:

go test ./parser -v

Run benchmarks:

go test ./parser -bench=.

Requirements

• Go 1.22 or later

Specification

This parser targets the openCypher 9 specification, with partial coverage of Neo4j Cypher 5 and Cypher 25 extensions.

For a detailed feature-by-feature breakdown across all three language layers, see docs/COMPAT.md.

For the release process and versioning policy, see docs/RELEASE.md.

For a history of changes, see CHANGELOG.md.

License

Copyright (c) 2026 haitch

Licensed under the Apache License, Version 2.0. See LICENSE for the full licence text, or visit https://www.apache.org/licenses/LICENSE-2.0.

Contact

h@ual.li
https://oldbytes.space/@haitchfive