@gram-data/tree-sitter-gram 0.2.6 → 0.2.7

package/README.md

@@ -3,34 +3,93 @@
 A [tree-sitter](https://tree-sitter.github.io/tree-sitter/) grammar 
 for [gram](https://gram-data.github.io) notation.
 
-Gram is a subject-based notation for structured data.
+## About Gram
 
-If this is an object:
-```
-{
-  "name":"Andreas",
-  "roles":["author"]
+Gram is a pattern-based notation for structured data.
+
+### Patterns and Subjects
+
+A **pattern** is a generic data structure with a value and nested elements:
+
+```ts
+interface Pattern<V> {
+  value: V;
+  elements: Pattern<V>[];
 }
 ```
 
-Implicitly the object is a person. To become a subject, the implicit
-information can be explicit.
+Gram patterns are always `Pattern<Subject>` — patterns where values are **subjects**.
+A **subject** is content combining an optional identifier, labels, and/or a record of properties.
+
+### Pattern Elements
+
+The `gram_pattern` (top-level structure) consists of a sequence of patterns. Syntactically, `subject_pattern`, `node_pattern`, `relationship_pattern`, and `annotated_pattern` are peers.
 
-As a subject:
+They correlate to the underlying data structure based on the number of elements:
+
+- **Node Pattern** `()`: A pattern with **0 elements**.
+- **Annotated Pattern** `@a (b)`: A pattern with **1 element**.
+- **Relationship Pattern** `(a)-->(b)`: A pattern with **2 elements**.
+- **Subject Pattern** `[ s | ... ]`: A pattern with an **arbitrary number of elements**.
+
+#### Path Flattening
+
+A path is a flattened tree of relationships. For example:
+
+```gram
+(a)-[r1]->(b)-[r2]->(c) 
+// is equivalent to:
+[ | [r1 | (a), (b)], [r2 | (b),(c)] ]
 ```
-(:Person {
-  name: "Andreas",
-  roles: ["author"]
-})
+
+#### Subject Pattern Notation
+
+The subject pattern notation uses `[ subject | elements ]` to explicitly show pattern structure:
+
+```gram
+// A team with members as elements
+[devrel:Team {name: "Developer Relations"} | abk, adam, alex]
+
+// A simple atomic pattern (no elements)
+[:Person {name: "Andreas", roles: ["author"]}]
 ```
 
-Gram files support comments using `//` syntax for line-based and end-of-line comments:
+#### Node Notation (Syntactic Sugar)
+
+Parentheses `( subject )` provide familiar graph node syntax:
+
+```gram
+()                           // Empty node
+(a)                          // Node with identifier
+(a:Person)                   // Node with identifier and label
+(a:Person {name: "Alice"})   // Node with identifier, label, and properties
 ```
+
+#### Relationship Notation (Syntactic Sugar)
+
+Arrows connect nodes to express graph relationships:
+
+```gram
+// Path notation for graph relationships
+(a:Person)-[:KNOWS]->(b:Person)
+
+// Subject Pattern notation can contain path patterns
+[social:Graph | 
+  (a:Person {name: "Alice"}),
+  (b:Person {name: "Bob"}),
+  (a)-[:KNOWS]->(b)
+]
+```
+
+### Comments
+
+Gram files support comments using `//` syntax:
+```gram
 // This is a line comment
 (hello)-->(world)  // End-of-line comment
 ```
 
-Learn more about `gram` at the [gram-data github org](https://github.com/gram-data) notation.
+Learn more about `gram` at the [gram-data github org](https://github.com/gram-data).
 
 ## Editor Support
 

package/editors/README.md

@@ -25,7 +25,7 @@ The Zed integration provides full syntax highlighting and language support for G
 
 **Features:**
 - Syntax highlighting for all Gram constructs
-- Bracket matching for `()`, `[]`, and `{}`
+- Subject Pattern matching for `()`, `[]`, and `{}`
 - Automatic file type detection for `.gram` files
 - Proper indentation handling
 

package/editors/zed/README.md

@@ -5,7 +5,7 @@ A [Zed](https://zed.dev) extension providing syntax highlighting and language su
 ## Features
 
 - **Syntax Highlighting**: Full syntax highlighting for all Gram constructs including subjects, nodes, relationships, and data types
-- **Bracket Matching**: Automatic matching for `()`, `[]`, and `{}`
+- **Subject Pattern Matching**: Automatic matching for `()`, `[]`, and `{}`
 - **File Type Detection**: Automatic recognition of `.gram` files
 - **Smart Indentation**: Proper indentation handling for nested structures
 
@@ -53,7 +53,7 @@ Once installed, the extension automatically provides syntax highlighting for any
 })
 
 // Relationships between nodes
-(alice:Person {name: "Alice"})->(bob:Person {name: "Bob"})
+(alice:Person {name: "Alice"})-->(bob:Person {name: "Bob"})
 
 // Complex subject with annotations
 @type("Employee")
@@ -80,7 +80,7 @@ Once installed, the extension automatically provides syntax highlighting for any
 
 The extension provides highlighting for:
 
-- **Brackets**: `[...]` and `[:type ...]` bracket notation (containing subjects)
+- **Subject Patterns**: `[...]` and `[:type ...]` subject pattern notation (containing subjects)
 - **Nodes**: `(...)` parentheses
 - **Relationships**: `->`, `--`, `<-`, `<-->`, etc.
 - **Strings**: Single, double, and backtick quoted strings

package/editors/zed/extension.toml

@@ -1,6 +1,6 @@
 id = "gram"
 name = "Gram Language Support"
-version = "0.2.6"
+version = "0.2.7"
 schema_version = 1
 authors = ["Gram Data Contributors"]
 description = "Support for Gram notation - a subject-oriented notation for structured data"
@@ -8,4 +8,4 @@ description = "Support for Gram notation - a subject-oriented notation for struc
 # path = "grammars/tree-sitter-gram"
 [grammars.gram]
 repository = "https://github.com/gram-data/tree-sitter-gram"
-rev = "7385463cf814f2e880e99c3e1372b4c0765820ad"
+rev = "a702c249d589daca07380db66c54bcf497d71a38"

package/editors/zed/languages/gram/highlights.scm

@@ -23,7 +23,7 @@
     "::"
 ] @operator
 
-; Brackets and delimiters
+; Subject Patterns and delimiters
 [
     "["
     "]"
@@ -49,7 +49,7 @@
 ; Annotation keys
 (annotation key: (symbol) @attribute)
 
-; Bracket notation (special highlighting)
+; Subject Pattern notation (special highlighting)
 (subject_pattern) @type
 
 ; Node with labels

package/grammar.js

@@ -7,16 +7,17 @@ module.exports = grammar({
   ],
 
   rules: {
-    // top-level rule, forming an outer pattern shaped like `[ record | sequence-of-top-level-elements ]`
-    gram: ($) => seq(field("root", optional($.record)), repeat($.annotated_pattern)),
+    gram_pattern: ($) => seq(field("root", optional($.record)), repeat($._top_level_pattern)),
+
+    _top_level_pattern: ($) => choice($.annotated_pattern, $.subject_pattern,$.node_pattern, $.relationship_pattern),
 
-    // top-level elements are annotated patterns shaped like `[annotation-record | pattern-elements]`
     annotated_pattern: ($) =>
       seq(
-        field("annotations", optional($.annotations)),
-        field("elements", commaSep1($._annotated_pattern_element)),
+        // field("annotations", optional($.annotations)),
+        field("annotations", $.annotations),
+        field("elements", choice($.subject_pattern, $._path_pattern)),
       ),
-    _annotated_pattern_element: ($) => choice($.subject_pattern, $._path_pattern),
+    // _annotated_pattern_element: ($) => choice($.subject_pattern, $._path_pattern),
 
     subject_pattern: ($) =>
       seq(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gram-data/tree-sitter-gram",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "description": "subject-oriented notation for structured data",
   "homepage": "https://gram-data.github.io",
   "repository": {

package/queries/highlights.scm

@@ -23,7 +23,7 @@
     "::"
 ] @operator
 
-; Brackets and delimiters
+; Subject Patterns and delimiters
 [
     "["
     "]"
@@ -49,7 +49,7 @@
 ; Annotation keys
 (annotation key: (symbol) @attribute)
 
-; Bracket notation (special highlighting)
+; Subject Pattern notation (special highlighting)
 (subject_pattern) @type
 
 ; Node with labels

package/src/grammar.json

@@ -2,7 +2,7 @@
   "$schema": "https://tree-sitter.github.io/tree-sitter/assets/schemas/grammar.schema.json",
   "name": "gram",
   "rules": {
-    "gram": {
+    "gram_pattern": {
       "type": "SEQ",
       "members": [
         {
@@ -25,11 +25,32 @@
           "type": "REPEAT",
           "content": {
             "type": "SYMBOL",
-            "name": "annotated_pattern"
+            "name": "_top_level_pattern"
           }
         }
       ]
     },
+    "_top_level_pattern": {
+      "type": "CHOICE",
+      "members": [
+        {
+          "type": "SYMBOL",
+          "name": "annotated_pattern"
+        },
+        {
+          "type": "SYMBOL",
+          "name": "subject_pattern"
+        },
+        {
+          "type": "SYMBOL",
+          "name": "node_pattern"
+        },
+        {
+          "type": "SYMBOL",
+          "name": "relationship_pattern"
+        }
+      ]
+    },
     "annotated_pattern": {
       "type": "SEQ",
       "members": [
@@ -37,62 +58,29 @@
           "type": "FIELD",
           "name": "annotations",
           "content": {
-            "type": "CHOICE",
-            "members": [
-              {
-                "type": "SYMBOL",
-                "name": "annotations"
-              },
-              {
-                "type": "BLANK"
-              }
-            ]
+            "type": "SYMBOL",
+            "name": "annotations"
           }
         },
         {
           "type": "FIELD",
           "name": "elements",
           "content": {
-            "type": "SEQ",
+            "type": "CHOICE",
             "members": [
               {
                 "type": "SYMBOL",
-                "name": "_annotated_pattern_element"
+                "name": "subject_pattern"
               },
               {
-                "type": "REPEAT",
-                "content": {
-                  "type": "SEQ",
-                  "members": [
-                    {
-                      "type": "STRING",
-                      "value": ","
-                    },
-                    {
-                      "type": "SYMBOL",
-                      "name": "_annotated_pattern_element"
-                    }
-                  ]
-                }
+                "type": "SYMBOL",
+                "name": "_path_pattern"
               }
             ]
           }
         }
       ]
     },
-    "_annotated_pattern_element": {
-      "type": "CHOICE",
-      "members": [
-        {
-          "type": "SYMBOL",
-          "name": "subject_pattern"
-        },
-        {
-          "type": "SYMBOL",
-          "name": "_path_pattern"
-        }
-      ]
-    },
     "subject_pattern": {
       "type": "SEQ",
       "members": [

package/src/node-types.json

@@ -5,7 +5,7 @@
     "fields": {
       "annotations": {
         "multiple": false,
-        "required": false,
+        "required": true,
         "types": [
           {
             "type": "annotations",
@@ -14,13 +14,9 @@
         ]
       },
       "elements": {
-        "multiple": true,
+        "multiple": false,
         "required": true,
         "types": [
-          {
-            "type": ",",
-            "named": false
-          },
           {
             "type": "node_pattern",
             "named": true
@@ -249,7 +245,7 @@
     "fields": {}
   },
   {
-    "type": "gram",
+    "type": "gram_pattern",
     "named": true,
     "root": true,
     "fields": {
@@ -271,6 +267,18 @@
         {
           "type": "annotated_pattern",
           "named": true
+        },
+        {
+          "type": "node_pattern",
+          "named": true
+        },
+        {
+          "type": "relationship_pattern",
+          "named": true
+        },
+        {
+          "type": "subject_pattern",
+          "named": true
         }
       ]
     }