Hypercode Syntax Specification

EBNF/Hypercode_Syntax.md

@@ -0,0 +1,125 @@
+# Hypercode Syntax Specification (BNF)
+
+**Status:** Draft
+
+**Version:** 0.1
+
+**Date:** July 12, 2025
+
+**Author:** Egor Merkushev
+
+**License:** MIT
+
+## Overview
+
+This document defines the formal syntax of the Hypercode `.hc` file format using a Backus–Naur Form (BNF) grammar.
+
+The goal is to provide an unambiguous reference for tool developers, parser authors, and implementers of Hypercode engines.
+
+## 1. BNF Grammar
+
+```bnf
+<hypercode>      ::= { <command-line> }
+<command-line>   ::= [<indent>] <command> <newline> [<block>]
+<command>        ::= <identifier> [<class>] [<id>]
+<class>          ::= "." <identifier>
+<id>             ::= "#" <identifier>
+<block>          ::= <indent-block> { <command-line> }
+<indent-block>   ::= <indent>+
+<identifier>     ::= <letter> { <letter> | <digit> | "_" | "-" }
+<letter>         ::= "A" | ... | "Z" | "a" | ... | "z"
+<digit>          ::= "0" | ... | "9"
+<indent>         ::= <spaces> | <tabs>
+<spaces>         ::= <space> { <space> }
+<tabs>           ::= <tab> { <tab> }
+<space>          ::= " "
+<tab>            ::= "\t"
+<newline>        ::= "\n"
+```
+
+## 2. Example Input
+
+```hypercode
+App
+  Logger.console
+  Database.pooled#primary-db
+    Connect
+    Migrate
+  WebServer#main
+    Listen
+    RegisterRoutes
+      HealthCheck.public
+      GetUsers.private
+```
+
+## 3. AST Representation (Indented)
+
+```
+App
+├── Logger (class: console)
+├── Database (class: pooled, id: primary-db)
+│   ├── Connect
+│   └── Migrate
+└── WebServer (id: main)
+    ├── Listen
+    └── RegisterRoutes
+        ├── HealthCheck (class: public)
+        └── GetUsers (class: private)
+```
+
+## 4. Test Cases
+
+### ✅ Valid
+
+#### Case 1: Simple nesting
+
+```hypercode
+Service
+  SubService
+    Task
+```
+
+#### Case 2: With class and id
+
+```hypercode
+Worker.task#main
+```
+
+### ❌ Invalid
+
+#### Case 3: Misaligned indentation
+
+```hypercode
+Root
+   Sub  ← inconsistent indent (3 spaces?)
+```
+
+#### Case 4: Invalid identifier
+
+```hypercode
+@bad#id
+```
+
+## 5. Notes
+
+- Identifiers must not contain whitespace or special symbols.
+- Indentation must be consistent (e.g., 2 or 4 spaces, or tabs—but not mixed).
+- No support for inline attributes or arguments in `.hc` files (these belong in `.hcs`).
+
+## 6. Future Work
+
+- Define EBNF with optional comments, arguments, and macro support.
+- Add parser conformance test suite.
+- Define formal AST schema (YAML or JSON).
+
+## 7. Change Log
+
+**Version 0.1** (2025-07-12)
+
+* Initial public draft of the Hypercode grammar in BNF.
+* Describes core structural elements: command, class, ID, indentation-based hierarchy.
+* Includes:
+  - BNF grammar for `.hc` files
+  - Visual AST example
+  - Positive and negative test cases
+  - Notes on scope and grammar limitations

RFC/Hypercode.md

@@ -41,7 +41,7 @@ Hypercode aims to solve this by:
 
 The Hypercode paradigm is built on three main components:
 
-*  **Hypercode (`.hc` file):** A file describing the application's logical structure using simple, indentation-based hierarchy. It contains abstract commands or entities. It is analogous to an HTML document's structure. See [Hypercode Syntax Specification](./hypercode-syntax.md) for the formal grammar of `.hc` files.
+*  **Hypercode (`.hc` file):** A file describing the application's logical structure using simple, indentation-based hierarchy. It contains abstract commands or entities. It is analogous to an HTML document's structure. See [Hypercode Syntax Specification](../EBNF/Hypercode_Syntax.md) for the formal grammar of `.hc` files.
 
 *  **Hypercode Cascade Sheet (`.hcs` file):** A YAML-like file that defines how to interpret and configure the commands in the Hypercode file. It uses selectors to target commands and apply configurations. It is analogous to a CSS stylesheet.
 
@@ -250,7 +250,7 @@ The specification assumes that the resolution and execution engine is trusted. N
 
 ## 11. References
 
-* [Hypercode Syntax Specification (BNF)](https://github.com/0al/hypercode/hypercode-syntax.md)
+* [Hypercode Syntax Specification (BNF)](../EBNF/Hypercode_Syntax.md)
 * [W3C CSS 2.1 Specification](https://www.w3.org/TR/CSS21/)
 * [YAML 1.2 Spec (OASIS)](https://yaml.org/spec/1.2/)
 * [Spring Framework: Dependency Injection](https://docs.spring.io/spring-framework/reference/core/beans/)