diff --git a/EBNF/Hypercode_Syntax.md b/EBNF/Hypercode_Syntax.md new file mode 100644 index 0000000..0f04439 --- /dev/null +++ b/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 + ::= { } + ::= [] [] + ::= [] [] + ::= "." + ::= "#" + ::= { } + ::= + + ::= { | | "_" | "-" } + ::= "A" | ... | "Z" | "a" | ... | "z" + ::= "0" | ... | "9" + ::= | + ::= { } + ::= { } + ::= " " + ::= "\t" + ::= "\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 diff --git a/RFC/Hypercode.md b/RFC/Hypercode.md index f1bde57..ceaf144 100644 --- a/RFC/Hypercode.md +++ b/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/)