Traqula Documentation

The Traqula framework enables a modular definition of parsers, transformers and generators. This documentation documents Traqula's core design decisions, spanning outside the SPARQL query language to other structured languages. Traqula does currently NOT support streaming parsing, making it ill-suited for creating a parser for large data files.

Architecture Overview

Traqula is organized as a monorepo with two categories of packages:

@traqula/core                  ← Builder pattern framework (ParserBuilder,
│                                 GeneratorBuilder, IndirBuilder, LexerBuilder,
│                                 Transformers, AST types)
│
├─ @traqula/chevrotain          ← Chevrotain wrapper (ESM + CJS)
│
├─ @traqula/rules-sparql-1-1    ← SPARQL 1.1 grammar rules, AST types, factory
│   ├─ @traqula/rules-sparql-1-2     ← Extends 1.1 for SPARQL 1.2
│   └─ @traqula/rules-sparql-1-1-adjust  ← Extends 1.1 with ADJUST function
│
├─ @traqula/algebra-transformations-1-1  ← AST-to-algebra transformation utilities
│   └─ @traqula/algebra-transformations-1-2
│
└─ Engines (pre-built configurations):
    ├─ @traqula/parser-sparql-1-1, 1-2, 1-1-adjust
    ├─ @traqula/generator-sparql-1-1, 1-2
    └─ @traqula/algebra-sparql-1-1, 1-2
Copy

Core provides the builder infrastructure. Rules packages define grammar rules and AST types for specific languages. Engines are ready-to-use parser/generator/transformer configurations built from those rules.

Dependent projects typically import an engine's builder (e.g., sparql12ParserBuilder) and extend it with custom rules using addRule(), patchRule(), and deleteRule().

Guides

Getting started

If you want to use Traqula's engines, learn more in their respective READMEs in the engines directory.

If you want to extend or create your own parsers, generators, or transformers, start here:

1. Guidelines for dependent projects — best practices for TypeScript, typing, and builder usage
2. Create a parser
3. AST structure
4. Create a generator
5. Create a transformer

Modifying existing components

1. Modify a parser
2. Modify a generator
3. Modify a transformer

Migration guides

When migrating from SPARQL.JS or SPARQLAlgebra.js:

1. Migration guide SPARQL.JS
2. Migration guide SPARQLAlgebra.js

Reference

• Design decisions
• Transformation catalogue
• API documentation (TypeDoc)

---

A query language transpiler framework for JavaScript

This repository is a monorepo containing multiple packages. Traqula is a highly flexible framework for parsing, transforming and generating structured languages, with an initial focus on the SPARQL query language. Traqula achieves this by shipping default configurations as engines which can easily be modified by builders found in the core package of Traqula.

Traqula maintains a few engines (default parser, transformer, and generator configurations) built on top of its own code packages:

• For SPARQL 1.1: a parser, generator, and algebra transformer.
• For SPARQL 1.2: a parser, generator, and algebra transformer.
• For SPARQL 1.1 + ADJUST function: a parser, the generator and transformers of SPARQL1.1 also work here.

Documentation

To use Traqula's engines, learn more in their respective READMEs as linked to above. In order to create or modify the parsers, transformers and generators to your desire, we provide dedicated documentation pages. If you are building a project that depends on Traqula, see the guidelines for dependent projects. Additionally, a documentation website is generated based on the source code's documentation: https://comunica.github.io/traqula/. The source code itself is available on GitHub.

License

This software is written by Jitse De Smet.

This code is released under the MIT license.