@gram-data/tree-sitter-gram 0.1.6

package/README.md

@@ -0,0 +1,61 @@
+# Gram - a lightweight, flexible graph notation
+
+Gram describes the structure and content of graphs, without semantics. 
+
+A graph is composed from a sequence of patterns, where each pattern
+is a sequence of graph elements.
+
+## Graph elements - nodes
+
+The smallest graph pattern is an empty node. 
+```
+()
+```
+
+Nodes may include properties using classic curly-braces-styled notation. This expression
+is like an anonymous object that appears inside some other data structure, perhaps a list
+like `const people = [{name:ABK}]`:
+
+```
+({name:"ABK"})
+```
+
+Nodes may self-identify themselves. This is like an object that is aware of the variable
+name you've given it in a programming language -- `const abk = {name:"ABK"}`
+```
+(abk {name:"ABK"})
+```
+
+Or, the identity could be considered the representative value of the node as in these examples:
+```
+(1), (true), (`heir to the Iron Throne`)
+```
+
+Nodes may also provide labels to associate with other nodes. This is like having an 
+introspectable object in a programming language -- `const abk:Person = {name:"ABK"}`:
+```
+(abk:Person {name:"ABK"}), (michael:Person {name:"Michael"})
+```
+
+It's ok to use multiple labels, which could be subsets, singletons, or intersections:
+```
+(abk:Person:Author {name:"ABK"}), (one:Person:King:Fictional {name: "John Snow"}),
+(drogon:Dragon:Fictional {name:"Drogon"})
+```
+
+
+## FAQ
+
+- Annotation vs self-loop?
+
+  Q: What is the difference between an annotation and a self-loop? 
+  A: An annotation provides extra information about a single target, while a self-loop provides 
+  information about a source,target pair where either the source or target may have been different,
+  but happen to be the same. 
+
+  For example, `@physics("rigid")(a:Player)` annotates a player entity with information for the physics subsystem.
+  The information is particular to the player and not about how the player relates to itself. 
+
+  As a self-loop, `(a:Player)-[:MESSAGE]->(a:Player)` is a message a player sent to themselves that could've
+  been sent to another player. The message has a specific source and target, which happen to be the same.
+

package/binding.gyp

@@ -0,0 +1,30 @@
+{
+  "targets": [
+    {
+      "target_name": "tree_sitter_gram_binding",
+      "dependencies": [
+        "<!(node -p \"require('node-addon-api').targets\"):node_addon_api_except",
+      ],
+      "include_dirs": [
+        "src",
+      ],
+      "sources": [
+        "bindings/node/binding.cc",
+        "src/parser.c",
+        # NOTE: if your language has an external scanner, add it here.
+      ],
+      "conditions": [
+        ["OS!='win'", {
+          "cflags_c": [
+            "-std=c11",
+          ],
+        }, { # OS == "win"
+          "cflags_c": [
+            "/std:c11",
+            "/utf-8",
+          ],
+        }],
+      ],
+    }
+  ]
+}

package/bindings/node/binding.cc

@@ -0,0 +1,20 @@
+#include <napi.h>
+
+typedef struct TSLanguage TSLanguage;
+
+extern "C" TSLanguage *tree_sitter_gram();
+
+// "tree-sitter", "language" hashed with BLAKE2
+const napi_type_tag LANGUAGE_TYPE_TAG = {
+    0x8AF2E5212AD58ABF, 0xD5006CAD83ABBA16
+};
+
+Napi::Object Init(Napi::Env env, Napi::Object exports) {
+    exports["name"] = Napi::String::New(env, "gram");
+    auto language = Napi::External<TSLanguage>::New(env, tree_sitter_gram());
+    language.TypeTag(&LANGUAGE_TYPE_TAG);
+    exports["language"] = language;
+    return exports;
+}
+
+NODE_API_MODULE(tree_sitter_gram_binding, Init)

package/bindings/node/binding_test.js

@@ -0,0 +1,9 @@
+/// <reference types="node" />
+
+const assert = require("node:assert");
+const { test } = require("node:test");
+
+test("can load grammar", () => {
+  const parser = new (require("tree-sitter"))();
+  assert.doesNotThrow(() => parser.setLanguage(require(".")));
+});

package/bindings/node/index.d.ts

@@ -0,0 +1,28 @@
+type BaseNode = {
+  type: string;
+  named: boolean;
+};
+
+type ChildNode = {
+  multiple: boolean;
+  required: boolean;
+  types: BaseNode[];
+};
+
+type NodeInfo =
+  | (BaseNode & {
+      subtypes: BaseNode[];
+    })
+  | (BaseNode & {
+      fields: { [name: string]: ChildNode };
+      children: ChildNode[];
+    });
+
+type Language = {
+  name: string;
+  language: unknown;
+  nodeTypeInfo: NodeInfo[];
+};
+
+declare const language: Language;
+export = language;

package/bindings/node/index.js

@@ -0,0 +1,7 @@
+const root = require("path").join(__dirname, "..", "..");
+
+module.exports = require("node-gyp-build")(root);
+
+try {
+  module.exports.nodeTypeInfo = require("../../src/node-types.json");
+} catch (_) {}

package/grammar.js

@@ -0,0 +1,251 @@
+module.exports = grammar({
+  name: 'gram',
+
+  rules: {
+
+    gram: $ => seq(
+      field('root', optional($.record)), 
+      repeat($.pattern)
+    ),
+
+    pattern: $ => seq(optional(repeat($.annotation)), commaSep1($._patternComponent)),
+
+    _patternComponent: $ => choice(
+      $.subject,
+      $._path
+    ),
+
+    subject: $ => seq("[", optional($._attributes), optional(field("association", $._association)),"]"),
+
+    annotation: $ => prec(9999,seq(
+      "@", 
+      field('key', $.symbol),
+      "(",
+      field('value', $._value),
+      ")"
+    )),
+    
+    _path: $ => choice(
+      $.relationship,
+      $.node
+    ),
+
+    node: $ => seq("(", optional($._attributes),")"),
+
+    relationship: $ => seq(field("left", $.node), field("value", $._relationship_value), field("right", $._path)),
+
+    _association: $ => choice($.membership, $.ordering),
+    
+    membership: $ => seq(
+      "|", 
+      optional(seq(optional(field("labels", $.labels)), optional(field("record", $.record)), "|")), 
+      commaSep1($.member)),
+
+    ordering: $ => seq(
+      "-", 
+      optional(seq("[", optional(field("labels", $.labels)), optional(field("record", $.record)), "]-")), ">", 
+      commaSep1($.member)),
+
+    _reference: $ => $._value,
+
+    member: $ => seq(
+      optional(repeat($.annotation)), 
+      choice(
+        $._reference,
+        $._patternComponent
+      ),
+    ),
+
+    _attributes: $ => choice(
+      choice(field("identifier", $._value), field("labels", $.labels), field("record", $.record)), 
+      seq(field("identifier", $._value), field("labels", $.labels)),
+      seq(field("identifier", $._value), field("record", $.record)),
+      seq(field("labels", $.labels), field("record", $.record)),
+      seq(field("identifier", $._value), field("labels", $.labels), field("record", $.record))
+    ),
+
+    _value: $ => choice(
+      $.symbol,
+      $._numeric_literal,
+      $._string_literal,
+      $.range,
+      $.math_symbol,
+      $.greek,
+      $.pictograph
+    ),
+
+    labels: $ => repeat1($.label),
+
+    label: $ => seq(field("binder", $.binder), $.symbol),
+
+    binder: $ => choice(token(":"), token("::"), token("@")),
+
+    record: $ => seq("{", commaSep($.property), "}"),
+
+    property: $ => seq(
+      field('key', $.symbol),
+      field('binder', $.binder),
+      field('value', $._value),
+      optional(field('cardinality', choice('!', '?', '*', '+')))
+    ),
+
+    symbol: $ => token(/[a-zA-Z_][0-9a-zA-Z_.\-]*/),
+
+    greek: $ => token(/[\u03B1-\u03C9\u0391-\u03A9]/),
+    math_symbol: $ => token(/\p{Other_Math}/),
+    pictograph: $ => token(/[\u2650-\u26FF]/),
+
+    range: $ => choice(
+      seq(field("lower", $._numeric_literal), "..", field("upper", $._numeric_literal)),
+      seq(field("lower", $._numeric_literal), "..."),
+      seq("...", field("upper", $._numeric_literal))
+    ),
+
+    _numeric_literal: $ => choice(
+      $.integer,
+      $.decimal,
+      $.hexadecimal,
+      $.octal,
+      $.measurement
+    ),
+
+    integer: $ => {
+      const integer = /-?(0|[1-9]\d*)/;      
+      return token(integer);
+    },
+
+    decimal: $ => {
+      const decimal = /-?(0|[1-9]\d*)\.\d+/;      
+      return token(decimal);
+    },
+
+    hexadecimal: $ => {
+      const hexadecimal = /0x[0-9a-fA-F]+/;      
+      return token(hexadecimal);
+    },
+
+    octal: $ => {
+      const octal = /0[0-7]+/;      
+      return token(octal);
+    },
+
+    measurement: $ => {
+      // /-?(?:[0-9]|[1-9][0-9]+)(?:\.[0-9]+)?[a-zA-Z]+\b(?!@)/
+      const measurement = /-?(0|[1-9]\d*)([a-zA-Z]+)/;      
+      return token(measurement);
+    },
+
+    _string_literal: $ => choice(
+      $.single_quoted_string,
+      $.double_quoted_string,
+      $.backticked_string,
+      $.tagged_string,
+      $.fenced_string
+    ),
+
+    single_quoted_string: $ => {
+      const quoted = /'(\\['bfnrt/\\]|[^'\n])*'/;      
+      return token(quoted);
+    },
+
+    double_quoted_string: $ => {
+      const quoted = /"(\\["bfnrt/\\]|[^"\n])*"/;      
+      return token(quoted);
+    },
+
+    backticked_string: $ => {
+      const quoted = /`(\\[`bfnrt/\\]|[^`\n])*`/;      
+      return token(quoted);
+    },
+
+    tagged_string: $ => {
+      const tagged = /[a-zA-Z][0-9a-zA-Z_.@]*`[^`\n]*`/;      
+      return token(tagged);
+    },
+
+    fenced_string: $ => {
+      const fenced = /```(\\[`bfnrt/\\]|[^`])*```/;      
+      return token(fenced);
+    },
+
+    _relationship_value: $ => choice(
+      $.single_undirected,
+      $.single_bidirectional,
+      $.single_right,
+      $.single_left,
+      $.double_undirected,
+      $.double_bidirectional,
+      $.double_right,
+      $.double_left,
+      $.squiggle_undirected,
+      $.squiggle_bidirectional,
+      $.squiggle_right,
+      $.squiggle_left,
+    ),
+      
+    single_undirected: $ => seq("-", optional(seq("[", $._attributes, "]")), "-"),
+    single_bidirectional: $ => seq("<-", optional(seq("[", $._attributes, "]")), "->"),
+    single_right: $ => seq("-", optional(seq("[", $._attributes, "]")), "->"),
+    single_left: $ => seq("<-", optional(seq("[", $._attributes, "]")), "-"),
+
+    double_undirected: $ => seq("=", optional(seq("[", $._attributes, "]")), "="),
+    double_bidirectional: $ => seq("<=", optional(seq("[", $._attributes, "]")), "=>"),
+    double_right: $ => seq("=", optional(seq("[", $._attributes, "]")), "=>"),
+    double_left: $ => seq("<=", optional(seq("[", $._attributes, "]")), "="),
+
+    squiggle_undirected: $ => seq("~", optional(seq("[", $._attributes, "]")), "~"),
+    squiggle_bidirectional: $ => seq("<~", optional(seq("[", $._attributes, "]")), "~>"),
+    squiggle_right: $ => seq("~", optional(seq("[", $._attributes, "]")), "~>"),
+    squiggle_left: $ => seq("<~", optional(seq("[", $._attributes, "]")), "~"),
+  }
+});
+
+/**
+ * Creates a rule to match one or more of the rules separated by a comma
+ *
+ * @param {RuleOrLiteral} rule
+ *
+ * @return {SeqRule}
+ *
+ */
+function commaSep1(rule) {
+  return seq(rule, repeat(seq(',', rule)));
+}
+
+/**
+ * Creates a rule to optionally match one or more of the rules separated by a comma
+ *
+ * @param {RuleOrLiteral} rule
+ *
+ * @return {ChoiceRule}
+ *
+ */
+function commaSep(rule) {
+  return optional(commaSep1(rule));
+}
+
+
+/**
+ * Creates a rule to match one or more of the rules separated by a colon
+ *
+ * @param {RuleOrLiteral} rule
+ *
+ * @return {SeqRule}
+ *
+ */
+function colonSep1(rule) {
+  return seq(rule, repeat(seq(':', rule)));
+}
+
+
+/**
+ * Creates a rule to match one or more of the rules separated by another rule
+ *
+ * @param {RuleOrLiteral} rule
+ *
+ * @return {SeqRule}
+ *
+ */
+function ruleSep1(rule, separator) {
+  return seq(rule, repeat(seq(separator, rule)));
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@gram-data/tree-sitter-gram",
+  "private": false,
+  "version": "0.1.6",
+  "description": "subject-oriented notation for structured data",
+  "main": "bindings/node",
+  "types": "bindings/node",
+  "scripts": {
+    "install": "node-gyp-build",
+    "prestart": "tree-sitter build --wasm",
+    "start": "tree-sitter playground",
+    "test": "node --test bindings/node/*_test.js"
+  },
+  "keywords": [],
+  "files": [
+    "grammar.js",
+    "binding.gyp",
+    "prebuilds/**",
+    "bindings/node/*",
+    "queries/*",
+    "src/**"
+  ],
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "node-gyp-build": "^4.8.2",
+    "node-addon-api": "^8.1.0"
+  },
+  "peerDependencies": {
+    "tree-sitter": "^0.21.0"
+  },
+  "peerDependenciesMeta": {
+    "tree_sitter": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "eslint": "^9.12.0",
+    "node-gyp": "^10.2.0",
+    "prebuildify": "^6.0.1",
+    "tree-sitter-cli": "^0.24.2"
+  },
+  "tree-sitter": [
+    {
+      "scope": "source.gram",
+      "file-types": [
+        "gram"
+      ]
+    }
+  ]
+}