@gram-data/tree-sitter-gram 0.2.5 → 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.5"
+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 = "84ec592d27a13267097d83e94932de3e024ea808"
+rev = "a702c249d589daca07380db66c54bcf497d71a38"

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

@@ -23,7 +23,7 @@
     "::"
 ] @operator
 
-; Brackets and delimiters
+; Subject Patterns and delimiters
 [
     "["
     "]"
@@ -49,15 +49,7 @@
 ; Annotation keys
 (annotation key: (symbol) @attribute)
 
-; Annotations inside relationship arrows
-[
-    (right_arrow annotations: (annotations) @attribute)
-    (left_arrow annotations: (annotations) @attribute)
-    (undirected_arrow annotations: (annotations) @attribute)
-    (bidirectional_arrow annotations: (annotations) @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(
@@ -230,7 +231,6 @@ module.exports = grammar({
           optional(
             seq(
               "[",
-              field("annotations", optional($.annotations)),
               field("subject", optional($._subject)),
               "]",
             ),
@@ -242,7 +242,6 @@ module.exports = grammar({
           optional(
             seq(
               "[",
-              field("annotations", optional($.annotations)),
               field("subject", optional($._subject)),
               "]",
             ),
@@ -254,7 +253,6 @@ module.exports = grammar({
           optional(
             seq(
               "[",
-              field("annotations", optional($.annotations)),
               field("subject", optional($._subject)),
               "]",
             ),
@@ -270,7 +268,6 @@ module.exports = grammar({
           optional(
             seq(
               "[",
-              field("annotations", optional($.annotations)),
               field("subject", optional($._subject)),
               "]",
             ),
@@ -282,7 +279,6 @@ module.exports = grammar({
           optional(
             seq(
               "[",
-              field("annotations", optional($.annotations)),
               field("subject", optional($._subject)),
               "]",
             ),
@@ -294,7 +290,6 @@ module.exports = grammar({
           optional(
             seq(
               "[",
-              field("annotations", optional($.annotations)),
               field("subject", optional($._subject)),
               "]",
             ),
@@ -310,7 +305,6 @@ module.exports = grammar({
           optional(
             seq(
               "[",
-              field("annotations", optional($.annotations)),
               field("subject", optional($._subject)),
               "]",
             ),
@@ -322,7 +316,6 @@ module.exports = grammar({
           optional(
             seq(
               "[",
-              field("annotations", optional($.annotations)),
               field("subject", optional($._subject)),
               "]",
             ),
@@ -334,7 +327,6 @@ module.exports = grammar({
           optional(
             seq(
               "[",
-              field("annotations", optional($.annotations)),
               field("subject", optional($._subject)),
               "]",
             ),
@@ -350,7 +342,6 @@ module.exports = grammar({
           optional(
             seq(
               "[",
-              field("annotations", optional($.annotations)),
               field("subject", optional($._subject)),
               "]",
             ),
@@ -362,7 +353,6 @@ module.exports = grammar({
           optional(
             seq(
               "[",
-              field("annotations", optional($.annotations)),
               field("subject", optional($._subject)),
               "]",
             ),
@@ -374,7 +364,6 @@ module.exports = grammar({
           optional(
             seq(
               "[",
-              field("annotations", optional($.annotations)),
               field("subject", optional($._subject)),
               "]",
             ),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gram-data/tree-sitter-gram",
-  "version": "0.2.5",
+  "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,15 +49,7 @@
 ; Annotation keys
 (annotation key: (symbol) @attribute)
 
-; Annotations inside relationship arrows
-[
-    (right_arrow annotations: (annotations) @attribute)
-    (left_arrow annotations: (annotations) @attribute)
-    (undirected_arrow annotations: (annotations) @attribute)
-    (bidirectional_arrow annotations: (annotations) @attribute)
-]
-
-; Bracket notation (special highlighting)
+; Subject Pattern notation (special highlighting)
 (subject_pattern) @type
 
 ; Node with labels