add some READMEs

LICENSE.txt

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright © 2024–now Jitse De Smet
+Comunica Association and Ghent University – imec, Belgium
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

README.md

@@ -1,2 +0,0 @@
-best not unpack the context entry since its contents are reset between parsing runs.
-You should thus only have the context object itself withing your closure.

engines/engine-sparql-1-1-adjust/README.md

@@ -0,0 +1,46 @@
+# TRAQULA parser engine for SPARQL 1.1 + Adjust
+
+TRAQULA Sparql 1.1 Adjust is a SPARQL 1.1 query parser that also parses the [builtin function ADJUST](https://github.com/w3c/sparql-dev/blob/main/SEP/SEP-0002/sep-0002.md) for TypeScript.
+Simple grammar extension of [TRAQULA engine-sparql-1-1](https://github.com/comunica/traqula/tree/main/engines/engine-sparql-1-1)
+
+## Installation
+
+```bash
+npm install @traqula/engine-sparql-1-1
+```
+
+or
+
+```bash
+yarn add @traqula/engine-sparql-1-1
+```
+
+## Import
+
+Either through ESM import:
+
+```javascript
+import { Sparql11AdjustParser } from '@traqula/engine-sparql-1-1-adjust';
+```
+
+_or_ CJS require:
+
+```javascript
+const Sparql11AdjustParser = require('@traqula/engine-sparql-1-1-adjust').Sparql11AdjustParser;
+```
+
+## Usage
+
+This package contains a `Sparql11AdjustParser` that is able to parse SPARQL 1.1 queries including the [builtin function ADJUST](https://github.com/w3c/sparql-dev/blob/main/SEP/SEP-0002/sep-0002.md):
+
+```typescript
+const parser = new Sparql11Parser();
+const abstractSyntaxTree = parser.parse(`
+SELECT ?s ?p (ADJUST(?o, "-PT10H"^^<http://www.w3.org/2001/XMLSchema#dayTimeDuration>) as ?adjusted) WHERE {
+  ?s ?p ?o
+}
+`);
+```
+
+This parser is a simple grammar extension to the [engine-sparql-1-1](https://github.com/comunica/traqula/tree/main/engines/engine-sparql-1-1).
+As such, most, if not all, documentation of that parser holds for this one too.

engines/engine-sparql-1-1-adjust/lib/Sparql11AdjustParser.ts

@@ -1,14 +1,15 @@
 import {Builder, type ImplArgs} from '@traqula/core';
-import { gram } from '@traqula/rules-sparql-1-1-adjust';
+import {gram, lex} from '@traqula/rules-sparql-1-1-adjust';
 import {
   Expression,
-  IriTerm, lex as l,
+  gram as g11,
+  lex as l11,
+  IriTerm,
   PropertyPath,
   SparqlParser as ISparqlParser,
   SparqlQuery
 } from '@traqula/rules-sparql-1-1';
-import { gram as g11 } from '@traqula/rules-sparql-1-1';
-import { sparql11ParserBuilder } from '@traqula/engine-sparql-1-1';
+import {sparql11ParserBuilder} from '@traqula/engine-sparql-1-1';
 import {DataFactory} from "rdf-data-factory";
 import type * as RDF from "@rdfjs/types";
 
@@ -35,8 +36,8 @@ export class Sparql11AdjustParser implements ISparqlParser {
 
   public constructor(context: Partial<ImplArgs['context']> = {}) {
     this.dataFactory = context.dataFactory ?? new DataFactory({ blankNodePrefix: 'g_' });
-    this.parser = sparql11ParserBuilder.consumeToParser({
-      tokenVocabulary: l.sparql11Tokens.build(),
+    this.parser = adjustBuilder.consumeToParser({
+      tokenVocabulary: l11.sparql11Tokens.addBefore(l11.a, lex.BuiltInAdjust).build(),
     }, {
       parseMode: new Set([ g11.canParseVars, g11.canCreateBlankNodes ]),
       ...context,

engines/engine-sparql-1-1-adjust/package.json

@@ -17,6 +17,7 @@
   "files": [
     "lib/**/*.d.ts",
     "lib/**/*.js",
+    "lib/**/*.cjs",
     "lib/**/*.js.map"
   ],
   "engines": {

engines/engine-sparql-1-1-adjust/test/statics.test.ts

@@ -4,7 +4,7 @@ import {positiveTest, importSparql11NoteTests} from "@traqula/test-utils";
 import {DataFactory} from "rdf-data-factory";
 import {BaseQuad} from "@rdfjs/types";
 
-describe('a SPARQL 1.1 parser', () => {
+describe('a SPARQL 1.1 + adjust parser', () => {
   const parser = new Sparql11AdjustParser({ prefixes: { ex: 'http://example.org/' }});
   beforeEach(() => {
     parser._resetBlanks();
@@ -27,4 +27,14 @@ describe('a SPARQL 1.1 parser', () => {
   }
 
   importSparql11NoteTests(parser, new DataFactory<BaseQuad>());
+
+  it('parses ADJUST function', ({expect}) => {
+    const query =  `
+SELECT ?s ?p (ADJUST(?o, "-PT10H"^^<http://www.w3.org/2001/XMLSchema#dayTimeDuration>) as ?adjusted) WHERE {
+  ?s ?p ?o
+}
+`;
+    const res: unknown = parser.parse(query);
+    expect(res).toMatchObject({});
+  })
 });

engines/engine-sparql-1-1/README.md

@@ -0,0 +1,79 @@
+# TRAQULA parser engine for SPARQL 1.1
+
+TRAQULA Sparql 1.1 is a SPARQL 1.1 query parser for TypeScript.
+
+
+## Installation
+
+```bash
+npm install @traqula/engine-sparql-1-1
+```
+
+or
+
+```bash
+yarn add @traqula/engine-sparql-1-1
+```
+
+## Import
+
+Either through ESM import:
+
+```javascript
+import { Sparql11Parser } from '@traqula/engine-sparql-1-1';
+```
+
+_or_ CJS require:
+
+```javascript
+const Sparql11Parser = require('@traqula/engine-sparql-1-1').Sparql11Parser;
+```
+
+## Usage
+
+This package contains a `Sparql11Parser` that is able to parse SPARQL 1.1 queries:
+
+```typescript
+const parser = new Sparql11Parser();
+const abstractSyntaxTree = parser.parse('SELECT * { ?s ?p ?o }');
+```
+
+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.
+
+### Consuming parserBuilder to parser
+
+At the core of TRAQULA, parser are constructed of multiple parser rules that have been consumed by the builder.
+This consumption returns a parser that can parse strings starting from any grammar rule.
+
+The `sparql11ParserBuilder` for example contains both the rules `queryOrUpdate` and `path` (among many others).
+The consumption of `sparql11ParserBuilder` will thus return an object that has function `queryOrUpdate` and `path`.
+Calling those function with a string will cause that string to be parsed using the appropriate rule as a starting rule.
+
+```typescript
+const parser: {
+  queryOrUpdate: (input: string) => SparqlQuery;
+  path: (input: string) => PropertyPath | IriTerm;
+} = sparql11ParserBuilder.consumeToParser({
+  tokenVocabulary: l.sparql11Tokens.build(),
+}, {
+  parseMode: new Set([ gram.canParseVars, gram.canCreateBlankNodes ]),
+  dataFactory: new DataFactory(),
+});
+```
+
+### Constructing a new grammar from an existing one
+
+The builders can also be used to construct new parsers.
+As an example the `triplesBlockParserBuilder` is created by merging the `objectListBuilder` with some new rules. 
+
+## Configuration
+
+Optionally, the following parameters can be set in the `Sparql11Parser` constructor:
+
+* `dataFactory`: A custom [RDFJS DataFactory](http://rdf.js.org/#datafactory-interface) to construct terms and triples. _(Default: `require('@rdfjs/data-model')`)_
+* `baseIRI`:  An initial default base IRI. _(Default: none)_
+* `prefixes`: An initial map of prefixes
+* `skipValidation`: Can be used to disable the validation that used variables in a select clause are in scope.
+

engines/engine-sparql-1-1/package.json

@@ -22,6 +22,7 @@
   "files": [
     "lib/**/*.d.ts",
     "lib/**/*.js",
+    "lib/**/*.cjs",
     "lib/**/*.js.map"
   ],
   "engines": {

engines/engine-sparql-1-2/README.md

@@ -0,0 +1,42 @@
+# TRAQULA parser engine for SPARQL 1.2
+
+TRAQULA Sparql 1.2 is a SPARQL 1.2 query parser for TypeScript.
+It is a grammar extension of [TRAQULA engine-sparql-1-1](https://github.com/comunica/traqula/tree/main/engines/engine-sparql-1-1)
+
+## Installation
+
+```bash
+npm install @traqula/engine-sparql-1-1
+```
+
+or
+
+```bash
+yarn add @traqula/engine-sparql-1-1
+```
+
+## Import
+
+Either through ESM import:
+
+```javascript
+import { Sparql12Parser } from '@traqula/engine-sparql-1-2';
+```
+
+_or_ CJS require:
+
+```javascript
+const Sparql12Parser = require('@traqula/engine-sparql-1-2').Sparql12Parser;
+```
+
+## Usage
+
+This package contains a `Sparql12Parser` that is able to parse SPARQL 1.2 queries:
+
+```typescript
+const parser = new Sparql12Parser();
+const abstractSyntaxTree = parser.parse('SELECT * { ?s ?p ?o }');
+```
+
+This parser is a simple grammar extension to the [engine-sparql-1-1](https://github.com/comunica/traqula/tree/main/engines/engine-sparql-1-1).
+As such, most, if not all, documentation of that parser holds for this one too.

engines/engine-sparql-1-2/package.json

@@ -22,6 +22,7 @@
   "files": [
     "lib/**/*.d.ts",
     "lib/**/*.js",
+    "lib/**/*.cjs",
     "lib/**/*.js.map"
   ],
   "engines": {

package.json

@@ -23,10 +23,6 @@
     "spec:all": "yarn workspaces foreach --all -pt --include \"engines/*\" run spec:all",
     "spec:earl": "yarn workspaces foreach --all -pt --include \"engines/*\" run spec:earl"
   },
-  "dependencies": {
-    "chevrotain": "^11.0.3",
-    "rdf-data-factory": "^2.0.1"
-  },
   "devDependencies": {
     "@rdfjs/types": "^2.0.0",
     "@types/sparqljs": "^3.1.12",