Traqula parser engine for SPARQL 1.1

Traqula Sparql 1.1 is a SPARQL 1.1 query parser for TypeScript.

Installation

npm install @traqula/parser-sparql-1-1

or

yarn add @traqula/parser-sparql-1-1

Import

Either through ESM import:

import { Parser } from '@traqula/parser-sparql-1-1';

or CJS require:

const Parser = require('@traqula/parser-sparql-1-1').Parser;

Usage

This package contains a Parser that is able to parse SPARQL 1.1 queries:

const parser = new Parser();
const abstractSyntaxTree = parser.parse('SELECT * { ?s ?p ?o }');

Note that a single parser cannot parse multiple queries in parallel.

The package also contains multiple parserBuilders. These builders can be used either to consume to a parser, or to usage as a starting point for your own grammar.

Note: it is essential that you reuse created parser to the full extent. Traqula builds on top of Chevrotain, an amazing project that allows for the definition of parsers within JavaScript, since the definition of the parser is part of the program, so is the optimization of our parser. Everytime you create a parser, the grammar optimizations need to be computed again.

Configuration

Optionally, the following parameters can be set in the Parsers defaultContext:

• dataFactory: A custom RDFJS DataFactory to construct terms and triples. (Default: require('@rdfjs/data-model'))
• skipValidation: Can be used to disable the validation that used variables in a select clause are in scope. (Default: false)

AstFactory and AstTransformer

Traqula provides two tools to help you manipulate an AST. The AstFactory helps you create AST nodes and validate the type of node using type predicates. When creating nodes, the first argument will always be a SourceLocation, in case you are not using round tripping, you can just provide F.gen().

The transformer is a strongly typed generic yet optimized tree transformer. The AstTransformer is a type specified TransformerSubTyped and can be used as is on the Ast Nodes.

import { Parser } from '@traqula/parser-sparql-1-1';
import { AstTransformer, AstFactory } from '@traqula/rules-sparql-1-1';
const query = `SELECT * { ?s ?p ?o }`;
const parser = new Parser();
const F = new AstFactory();
const transformer = new AstTransformer();

const ast = parser.parse(query);
// expand variables s p and o to their long names:
// SELECT * { ?subject ?predicate ?object }
transformer.transformNodeSpecific<'unsafe', typeof ast>(ast, {}, {
  // Something of type 'term'
  term: {
    // With subtype 'variable'
    variable: {
      transform: (variable) => {
        const newName = {
          's': 'subject',
          'p': 'predicate',
          'o': 'object'
        }[variable.value];
        return F.termVariable(newName ?? variable.value, F.gen());
      }
    }
  }
});

[!note] The transformer will return a safe version of the node by default, meaning it will return the ast node, but say the values for all keys are unknown since they could have been replaced by any new value in the course of performing the transformation. To just get the type of the node you provide the generic 'unsafe'. Likewise the returned value of the transform function is unknown unless you call unsafe and provide the expected type.

Collecting round tripping information

The generated AST is constructed such that it allows for round tripping. This means that a parsed query string produces an AST that, when generated from provides exactly the same query string. By default, though, the configured lexer does not collect enough information to enable this because it comes at a small slowdown (see our report). Simply provide the following configuration to the parser, a astFactory that handles source information, and a lexerConfig that states location information should be collected:

import { AstFactory } from '@traqula/rules-sparql-1-1';
import { adjustParserBuilder, adjustLexerBuilder, Parser } from '@traqula/parser-sparql-1-1';
const sourceTrackingAstFactory = new AstFactory();
const sourceTrackingParser = new Parser({
  defaultContext: { astFactory: sourceTrackingAstFactory },
  lexerConfig: { positionTracking: 'full' },
});