diagramo 0.2.0 → 0.5.0

package/DIAGRAMO_GRAMMAR.md

@@ -0,0 +1,479 @@
+Here’s a clean **Diagramo surface-language grammar spec** for the user-friendly lispy language that compiles to NCF.
+
+## Diagramo grammar
+
+Diagramo is a small lispy language with two main forms:
+
+* **tree forms** for nodes and parent/child structure
+* **arrow forms** for arrows between nodes
+
+A document may be either:
+
+* a sequence of forms, or
+* wrapped in a top-level `(diagramo ...)`
+
+## EBNF
+
+```ebnf
+document        = { ws_or_comment , form } , ws_or_comment
+                | "(" , "diagramo" , { ws_or_comment , form } , ws_or_comment , ")" ;
+
+form            = tree_form | arrow_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 ;
+
+vector          = "[" , ws ,
+                  node_ref ,
+                  { ws , node_ref } ,
+                  ws , "]" ;
+
+node_ref        = symbol | labeled_symbol ;
+edge_ref        = symbol | labeled_symbol ;
+
+labeled_symbol  = symbol , "{" , label_text , "}" ;
+
+label_text      = quoted_string | bare_label ;
+
+symbol          = initial_char , { symbol_char } ;
+
+initial_char    = letter | "_" ;
+symbol_char     = letter | digit | "_" | "-" | "." ;
+
+bare_label      = { any_char_except_brace_or_newline } ;
+
+quoted_string   = '"' , { string_char } , '"' ;
+
+string_char     = any_char_except_quote_or_backslash
+                | "\" , '"' 
+                | "\" , "\" 
+                | "\" , "n"
+                | "\" , "t" ;
+
+ws              = { " " | "\t" | "\r" | "\n" } ;
+comment         = ";" , { any_char_except_newline } ;
+ws_or_comment   = ws | comment ;
+```
+
+## Meaning of each form
+
+### 1. Node declaration
+
+```diagramo
+(P)
+```
+
+Ensures node `P` exists.
+
+Default label is the node id, so this behaves like:
+
+* id = `P`
+* label = `P`
+
+Example:
+
+```diagramo
+(A)
+(B)
+```
+
+Creates two nodes: `A`, `B`.
+
+---
+
+### 2. Node with label
+
+```diagramo
+(P{hi})
+```
+
+Ensures node `P` exists with label `hi`.
+
+Example:
+
+```diagramo
+(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
+
+```diagramo
+(X Y Z)
+```
+
+Means:
+
+* `X` exists
+* `Y` exists and is a child of `X`
+* `Z` exists and is a child of `X`
+
+Example:
+
+```diagramo
+(Folder File1 File2)
+```
+
+`Folder` is the container, `File1` and `File2` are inside it.
+
+---
+
+### 4. Nested parent structure
+
+```diagramo
+(X Y (Z P))
+```
+
+Means:
+
+* `Y` is a child of `X`
+* `Z` is a child of `X`
+* `P` is a child of `Z`
+
+Example:
+
+```diagramo
+(App Header (Body Sidebar))
+```
+
+This gives:
+
+* `Header` inside `App`
+* `Body` inside `App`
+* `Sidebar` inside `Body`
+
+---
+
+### 5. Chained nesting
+
+```diagramo
+(X (Y (Z P)))
+```
+
+Means:
+
+* `Y` is a child of `X`
+* `Z` is a child of `Y`
+* `P` is a child of `Z`
+
+Example:
+
+```diagramo
+(World (Continent (Country City)))
+```
+
+This creates a straight nesting chain.
+
+---
+
+### 6. Arrow between two nodes
+
+```diagramo
+(-> e A B)
+```
+
+Creates arrow `e` from `A` to `B`.
+
+If `A` or `B` do not already exist, they are created automatically.
+
+Example:
+
+```diagramo
+(-> f Login Dashboard)
+```
+
+Creates:
+
+* node `Login`
+* node `Dashboard`
+* arrow `f` from `Login` to `Dashboard`
+
+---
+
+### 7. Arrow with label
+
+```diagramo
+(-> e{hi} A B)
+```
+
+Creates arrow `e` from `A` to `B` with label `hi`.
+
+Example:
+
+```diagramo
+(-> auth{"sign in"} User Session)
+```
+
+Creates arrow `auth` labeled `sign in`.
+
+---
+
+### 8. Fan-out arrow
+
+```diagramo
+(-> e A [B C D])
+```
+
+Means one source, many targets.
+
+This expands to multiple arrows:
+
+* `e_1` from `A` to `B`
+* `e_2` from `A` to `C`
+* `e_3` from `A` to `D`
+
+Example:
+
+```diagramo
+(-> send Server [Client1 Client2 Client3])
+```
+
+---
+
+### 9. Fan-in arrow
+
+```diagramo
+(-> e [A B C] D)
+```
+
+Means many sources, one target.
+
+This expands to:
+
+* `e_1` from `A` to `D`
+* `e_2` from `B` to `D`
+* `e_3` from `C` to `D`
+
+Example:
+
+```diagramo
+(-> collect [Sensor1 Sensor2 Sensor3] Database)
+```
+
+---
+
+## Full examples
+
+### Minimal document
+
+```diagramo
+(A)
+(B)
+(-> f A B)
+```
+
+### With grouping
+
+```diagramo
+(App Header Footer)
+(App (Main Sidebar))
+(-> nav Header Main)
+(-> info Sidebar Footer)
+```
+
+### With top-level wrapper
+
+```diagramo
+(diagramo
+  (A{Start})
+  (B{End})
+  (-> flow A B))
+```
+
+### Mixed hierarchy and arrows
+
+```diagramo
+(diagramo
+  (System
+    API
+    (UI Button Panel)
+    (DB Table))
+
+  (-> req UI API)
+  (-> read API DB)
+  (-> write API DB)
+  (-> click Button API))
+```
+
+### Fan-out and fan-in
+
+```diagramo
+(diagramo
+  (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:
+
+```diagramo
+(-> f X Y)
+```
+
+Creates `X` and `Y` automatically.
+
+### Labels
+
+A node or arrow may be given a label with `{...}`.
+
+Example:
+
+```diagramo
+(A{Alpha})
+(-> e{"goes to"} A B)
+```
+
+If no label is provided, the id is used as the default label.
+
+### Unique ids
+
+Node ids must be unique among nodes.
+Arrow ids must be unique among arrows.
+
+Fan expansion reserves generated ids like:
+
+```diagramo
+e_1
+e_2
+e_3
+```
+
+### Parenting
+
+A node may have at most one parent.
+
+This is valid:
+
+```diagramo
+(X Y)
+```
+
+This should be rejected:
+
+```diagramo
+(X Y)
+(Z Y)
+```
+
+because `Y` would have two parents.
+
+### Repeated references
+
+Referring to the same node multiple times is allowed.
+
+Example:
+
+```diagramo
+(A)
+(-> f A B)
+(-> g B A)
+```
+
+### Conflicting labels
+
+This should be treated as an error:
+
+```diagramo
+(A{One})
+(A{Two})
+```
+
+because node `A` gets two different labels.
+
+---
+
+## Lexical notes
+
+### Comments
+
+A semicolon starts a comment to the end of the line.
+
+```diagramo
+; this is a comment
+(A)
+(-> f A B) ; inline comment
+```
+
+### Whitespace
+
+Whitespace is ignored except as a separator.
+
+So these are equivalent:
+
+```diagramo
+(A B C)
+```
+
+```diagramo
+(
+  A
+  B
+  C
+)
+```
+
+### Reserved tokens
+
+These should be reserved:
+
+* `diagramo`
+* `->`
+
+### Labels with spaces
+
+Prefer quoted labels when they contain spaces:
+
+```diagramo
+(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
+
+If you want, I can next turn this into a package-ready `GRAMMAR.md` file.