lispgram 0.10.0

package/LISPGRAM_GRAMMAR.md

@@ -0,0 +1,568 @@
+Here’s a clean **Lispgram surface-language grammar spec** for the user-friendly lispy language that compiles to NCF.
+
+## Lispgram grammar
+
+Lispgram is a small lispy language with three main surface forms:
+
+* **tree forms** for nodes and parent/child structure
+* **arrow forms** for arrows between nodes
+* **layout forms** for non-semantic renderer intent
+
+A document may be either:
+
+* a sequence of forms, or
+* wrapped in a top-level `(lispgram ...)`
+
+Both shapes are accepted by `parseDocument(source)` in `src/layers/01-surface/parse.js`.
+
+Important: label/field braces are a **suffix on the same token** as the id.
+
+- ✅ `(somenode{"hi"})`
+- ❌ `(somenode {"hi"})`
+
+Whitespace between the id and `{...}` splits them into separate forms/tokens and is not valid attributed-ref syntax.
+
+## EBNF
+
+```ebnf
+document        = { ws_or_comment , form } , ws_or_comment
+                | "(" , "lispgram" , { ws_or_comment , form } , ws_or_comment , ")" ;
+
+form            = tree_form | arrow_form | layout_form ;
+
+tree_form       = "(" , ws ,
+                  node_ref ,
+                  { ws , tree_item } ,
+                  ws , ")" ;
+
+tree_item       = node_ref | tree_form ;
+
+arrow_form      = "(" , ws ,
+                  "->" , ws ,
+                  edge_ref , ws ,
+                  endpoint , ws ,
+                  endpoint ,
+                  ws , ")" ;
+
+endpoint        = node_ref | vector ;
+
+layout_form     = "(" , ws , ("$layout" | "$metalayout") ,
+                  { ws , s_expression } ,
+                  ws , ")" ;
+
+vector          = "[" , ws ,
+                  node_ref ,
+                  { ws , node_ref } ,
+                  ws , "]" ;
+
+node_ref        = atom_ref | string_ref | attributed_ref ;
+edge_ref        = atom_ref | string_ref | attributed_ref ;
+
+attributed_ref
+                = atom_ref , "{" , label_text , "}"
+                | atom_ref , "{" , label_text , field_map , "}"
+                | atom_ref , "{" , field_map , "}" ;
+                (* no whitespace is allowed between atom_ref and the opening "{" *)
+
+field_map       = "{" , field_pair , { ws , field_pair } , "}" ;
+field_pair      = field_key , ws , field_value ;
+field_key       = field_value ;
+field_value     = quoted_string | number | boolean | atom_ref ;
+
+label_text      = quoted_string | bare_label ;
+
+atom_ref        = atom_token ;
+string_ref      = quoted_string ;
+atom_token      = atom_char , { atom_char } ;
+atom_char       = any_char_except_ws_or_paren_or_bracket_or_brace ;
+
+bare_label      = { any_char_except_brace_or_newline } ;
+number          = integer | float ;
+boolean         = "true" | "false" ;
+
+quoted_string   = '"' , { string_char } , '"' ;
+
+string_char     = any_char_except_quote_or_backslash
+                | "\" , '"' 
+                | "\" , "\" 
+                | "\" , "n"
+                | "\" , "r"
+                | "\" , "t" ;
+
+ws              = { " " | "\t" | "\r" | "\n" } ;
+comment         = ";" , { any_char_except_newline } ;
+ws_or_comment   = ws | comment ;
+```
+
+
+---
+
+### Layout metadata
+
+```lispgram
+($layout
+  (same-row [A B])
+  (view product :product P :factors [A B] :test-object X)
+  (attach-at-boundary h :from Ω :to P :boundary C :side left)
+  (parallel-to-boundary q :from M :to N :boundary C :side left))
+```
+
+Self-loops are not authored as layout directives. Declare an ordinary arrow whose source and target are the same, e.g. `(-> loopP P P)`, and the route layer will autodetect a loop.
+
+`$layout` and `$metalayout` are surface metadata. They are preserved through NCF as top-level `(layout ...)` forms, are intentionally omitted from the official semantic core, and lower into the constraint-layout engine when rendered.
+
+`$metalayout` remains accepted for older arrow-like layout clauses such as `(-> $samerow [A B C])`; new work should prefer `$layout` relative constraints and template views.
+
+## Meaning of each form
+
+### 1. Node declaration
+
+```lispgram
+(P)
+```
+
+Ensures node `P` exists.
+
+Default label is the node id, so this behaves like:
+
+* id = `P`
+* label = `P`
+
+Example:
+
+```lispgram
+(A)
+(B)
+```
+
+Creates two nodes: `A`, `B`.
+
+---
+
+### 2. Node with label
+
+```lispgram
+(P{hi})
+```
+
+Ensures node `P` exists with label `hi`.
+
+Example:
+
+```lispgram
+(P{Person})
+(Q{"Hello world"})
+```
+
+Creates:
+
+* node `P` labeled `Person`
+* node `Q` labeled `Hello world`
+
+Use quotes when the label contains spaces.
+
+---
+
+### 3. Parent with children
+
+```lispgram
+(X Y Z)
+```
+
+Means:
+
+* `X` exists
+* `Y` exists and is a child of `X`
+* `Z` exists and is a child of `X`
+
+Example:
+
+```lispgram
+(Folder File1 File2)
+```
+
+`Folder` is the container, `File1` and `File2` are inside it.
+
+---
+
+### 4. Nested parent structure
+
+```lispgram
+(X Y (Z P))
+```
+
+Means:
+
+* `Y` is a child of `X`
+* `Z` is a child of `X`
+* `P` is a child of `Z`
+
+Example:
+
+```lispgram
+(App Header (Body Sidebar))
+```
+
+This gives:
+
+* `Header` inside `App`
+* `Body` inside `App`
+* `Sidebar` inside `Body`
+
+---
+
+### 5. Chained nesting
+
+```lispgram
+(X (Y (Z P)))
+```
+
+Means:
+
+* `Y` is a child of `X`
+* `Z` is a child of `Y`
+* `P` is a child of `Z`
+
+Example:
+
+```lispgram
+(World (Continent (Country City)))
+```
+
+This creates a straight nesting chain.
+
+---
+
+### 6. Arrow between two nodes
+
+```lispgram
+(-> e A B)
+```
+
+Creates arrow `e` from `A` to `B`.
+
+If `A` or `B` do not already exist, they are created automatically.
+
+Example:
+
+```lispgram
+(-> f Login Dashboard)
+```
+
+Creates:
+
+* node `Login`
+* node `Dashboard`
+* arrow `f` from `Login` to `Dashboard`
+
+---
+
+### 7. Arrow with label
+
+```lispgram
+(-> e{hi} A B)
+```
+
+Creates arrow `e` from `A` to `B` with label `hi`.
+
+Example:
+
+```lispgram
+(-> auth{"sign in"} User Session)
+```
+
+Creates arrow `auth` labeled `sign in`.
+
+---
+
+### 8. Fan-out arrow
+
+```lispgram
+(-> e A [B C D])
+```
+
+Means one source, many targets.
+
+This expands to multiple concrete arrows. Each concrete arrow keeps the visible label `e`; generated carrier ids are compiler-private NCF details, not user-facing labels:
+
+* `e` from `A` to `B`
+* `e` from `A` to `C`
+* `e` from `A` to `D`
+
+Example:
+
+```lispgram
+(-> send Server [Client1 Client2 Client3])
+```
+
+---
+
+### 9. Fan-in arrow
+
+```lispgram
+(-> e [A B C] D)
+```
+
+Means many sources, one target.
+
+This expands to multiple concrete arrows. Each concrete arrow keeps the visible label `e`:
+
+* `e` from `A` to `D`
+* `e` from `B` to `D`
+* `e` from `C` to `D`
+
+Example:
+
+```lispgram
+(-> collect [Sensor1 Sensor2 Sensor3] Database)
+```
+
+---
+
+## Full examples
+
+### Minimal document
+
+```lispgram
+(A)
+(B)
+(-> f A B)
+```
+
+### With grouping
+
+```lispgram
+(App Header Footer)
+(App (Main Sidebar))
+(-> nav Header Main)
+(-> info Sidebar Footer)
+```
+
+### With top-level wrapper
+
+```lispgram
+(lispgram
+  (A{Start})
+  (B{End})
+  (-> flow A B))
+```
+
+### Mixed hierarchy and arrows
+
+```lispgram
+(lispgram
+  (System
+    API
+    (UI Button Panel)
+    (DB Table))
+
+  (-> req UI API)
+  (-> read API DB)
+  (-> write API DB)
+  (-> click Button API))
+```
+
+### Fan-out and fan-in
+
+```lispgram
+(lispgram
+  (Hub)
+  (A)
+  (B)
+  (C)
+  (D)
+
+  (-> out Hub [A B C])
+  (-> in [A B C] D))
+```
+
+---
+
+## Semantic rules
+
+These are the intended compile-time rules.
+
+### Auto-creation
+
+Any node mentioned in a tree or arrow form is created if it does not already exist.
+
+Example:
+
+```lispgram
+(-> f X Y)
+```
+
+Creates `X` and `Y` automatically.
+
+### Labels and fields
+
+A node or arrow may be given a label with `{...}`. The label is stored as `data.label`.
+
+Example:
+
+```lispgram
+(A{Alpha})
+(-> e{"goes to"} A B)
+```
+
+A node or arrow may also carry arbitrary data fields. The compact form puts the label first, followed by a field map:
+
+```lispgram
+(A{Person { color blue rank 2 active true }})
+(-> e{maps { color purple weight 2 }} A B)
+```
+
+The fully explicit form is a field map only. This is equivalent to the compact node example above:
+
+```lispgram
+(A{{ label Person color blue rank 2 active true }})
+```
+
+Bare atom values are strings, numbers parse as numbers, and `true` / `false` parse as booleans. Quoted strings may be used when values contain spaces:
+
+```lispgram
+(A{{ label "Person Account" color "deep blue" rank 2 }})
+```
+
+If no label is provided, the id is used as the default label. A later explicit label overrides that earlier implicit id-based label. Labels are display-only; ids are the referenceable names.
+
+Example:
+
+```lispgram
+(lispgram
+  (-> e A B)
+  (A{hi}))
+```
+
+This gives node `A` the label `hi`, not `A`.
+
+This is rejected because the shorthand label conflicts with the explicit `label` field:
+
+```lispgram
+(A{Person { label Account }})
+```
+
+### Unique ids and arrow groups
+
+Node ids must be unique among nodes.
+
+Arrow ids are referenceable names. Reusing an arrow id creates an implicit arrow group: each occurrence is a distinct concrete arrow with the same visible label. Referencing that repeated id as an endpoint fans over the whole group.
+
+```lispgram
+(-> e A B)
+(-> e C D)
+(-> meta e X)
+```
+
+The `meta` arrow above expands over both concrete `e` arrows.
+
+If you need finer-grained control while keeping the same visible label, use distinct ids with explicit labels:
+
+```lispgram
+(-> e1{e} A B)
+(-> e2{e} C D)
+(-> meta e1 X)
+```
+
+Here `e1` and `e2` both display as `e`, but `meta` refers only to `e1`.
+
+### Parenting
+
+A node may have at most one parent.
+
+This is valid:
+
+```lispgram
+(X Y)
+```
+
+This should be rejected:
+
+```lispgram
+(X Y)
+(Z Y)
+```
+
+because `Y` would have two parents.
+
+### Repeated references
+
+Referring to the same node multiple times is allowed.
+
+Example:
+
+```lispgram
+(A)
+(-> f A B)
+(-> g B A)
+```
+
+### Conflicting labels and fields
+
+This should be treated as an error:
+
+```lispgram
+(A{One})
+(A{Two})
+```
+
+because node `A` gets two different explicit labels. An explicit label may override an earlier implicit id-based label, but two different explicit labels still conflict. The same rule applies to explicit non-label fields, such as `color` or `rank`.
+
+---
+
+## Lexical notes
+
+### Comments
+
+A semicolon starts a comment to the end of the line.
+
+```lispgram
+; this is a comment
+(A)
+(-> f A B) ; inline comment
+```
+
+### Whitespace
+
+Whitespace is ignored except as a separator.
+
+So these are equivalent:
+
+```lispgram
+(A B C)
+```
+
+```lispgram
+(
+  A
+  B
+  C
+)
+```
+
+### Reserved tokens
+
+`->` is reserved only in list-head position where it denotes an arrow form.
+
+`lispgram` is special only as an optional top-level wrapper head. As a plain atom elsewhere, it is parsed like any other identifier.
+
+### Labels with spaces
+
+Prefer quoted labels when they contain spaces:
+
+```lispgram
+(Node{"Hello world"})
+(-> e{"edge label"} A B)
+```
+
+---
+
+## Practical summary
+
+The language has only four ideas:
+
+* `(A)` → create a node
+* `(A B C)` → make `B` and `C` children of `A`
+* `(-> e A B)` → create an arrow from `A` to `B`
+* `[A B C]` inside an arrow → fan-in or fan-out
+