From 4033d859fd1eb8a8622fad5a0429aa43ed3160b9 Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Sun, 17 Aug 2025 23:41:20 +0300 Subject: [PATCH 1/6] Add Hypercode Syntax Specification (BNF) and update Hypercode syntax links to correct relative path. --- EBNF/Hypercode_Syntax.md | 121 +++++++++++++++++++++++++++++++++++++++ RFC/Hypercode.md | 4 +- 2 files changed, 123 insertions(+), 2 deletions(-) create mode 100644 EBNF/Hypercode_Syntax.md diff --git a/EBNF/Hypercode_Syntax.md b/EBNF/Hypercode_Syntax.md new file mode 100644 index 0000000..f3aa9bd --- /dev/null +++ b/EBNF/Hypercode_Syntax.md @@ -0,0 +1,121 @@ +# Hypercode Syntax Specification (BNF) + +**Status:** Draft + +**Version:** 0.1 + +**Date:** July 12, 2025 + +**Author:** Egor Merkushev + +**Licence:** 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" + ::= (one or more spaces or tabs) + ::= "\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: + - EBNF 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/) From dbb59330e7fa45f9801e888bb6e6b92eb36c7cf0 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 25 Nov 2025 19:00:24 +0000 Subject: [PATCH 2/6] Initial plan From c3a9078b98612f38cc06461b8fa289e1814b098b Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Tue, 25 Nov 2025 23:40:42 +0300 Subject: [PATCH 3/6] Update EBNF/Hypercode_Syntax.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- EBNF/Hypercode_Syntax.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EBNF/Hypercode_Syntax.md b/EBNF/Hypercode_Syntax.md index f3aa9bd..9c84c2d 100644 --- a/EBNF/Hypercode_Syntax.md +++ b/EBNF/Hypercode_Syntax.md @@ -8,7 +8,7 @@ **Author:** Egor Merkushev -**Licence:** MIT +**License:** MIT ## Overview From 18e5e4c4c6bd5c50abfd78dd3984543fe7bbfeab Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Tue, 25 Nov 2025 23:41:13 +0300 Subject: [PATCH 4/6] Update EBNF/Hypercode_Syntax.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- EBNF/Hypercode_Syntax.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EBNF/Hypercode_Syntax.md b/EBNF/Hypercode_Syntax.md index 9c84c2d..9bd8f29 100644 --- a/EBNF/Hypercode_Syntax.md +++ b/EBNF/Hypercode_Syntax.md @@ -115,7 +115,7 @@ Root * Initial public draft of the Hypercode grammar in BNF. * Describes core structural elements: command, class, ID, indentation-based hierarchy. * Includes: - - EBNF grammar for `.hc` files + - BNF grammar for `.hc` files - Visual AST example - Positive and negative test cases - Notes on scope and grammar limitations From 65788e60cb2d204c7a9c2b2448307bacc2f925a3 Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Tue, 25 Nov 2025 23:41:47 +0300 Subject: [PATCH 5/6] Update EBNF/Hypercode_Syntax.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- EBNF/Hypercode_Syntax.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EBNF/Hypercode_Syntax.md b/EBNF/Hypercode_Syntax.md index 9bd8f29..145bce8 100644 --- a/EBNF/Hypercode_Syntax.md +++ b/EBNF/Hypercode_Syntax.md @@ -20,7 +20,7 @@ The goal is to provide an unambiguous reference for tool developers, parser auth ```bnf ::= { } - ::= [] + ::= [] [] ::= [] [] ::= "." ::= "#" From 9dd324a0bf7efa525ef4e24d4a926dc4b2f65c2f Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Tue, 25 Nov 2025 23:42:23 +0300 Subject: [PATCH 6/6] Update EBNF/Hypercode_Syntax.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- EBNF/Hypercode_Syntax.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/EBNF/Hypercode_Syntax.md b/EBNF/Hypercode_Syntax.md index 145bce8..0f04439 100644 --- a/EBNF/Hypercode_Syntax.md +++ b/EBNF/Hypercode_Syntax.md @@ -29,7 +29,11 @@ The goal is to provide an unambiguous reference for tool developers, parser auth ::= { | | "_" | "-" } ::= "A" | ... | "Z" | "a" | ... | "z" ::= "0" | ... | "9" - ::= (one or more spaces or tabs) + ::= | + ::= { } + ::= { } + ::= " " + ::= "\t" ::= "\n" ```