From 4033d859fd1eb8a8622fad5a0429aa43ed3160b9 Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Sun, 17 Aug 2025 23:41:20 +0300 Subject: [PATCH 1/9] 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/9] 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/9] 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/9] 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/9] 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/9] 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" ``` From 5f41e3fcf1cd8d4d6241b2f26ca8355f3e14d76b Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Mon, 1 Jun 2026 21:37:13 +0300 Subject: [PATCH 7/9] Resolve indentation ambiguity in BNF block rule via INDENT/DEDENT Builds on the prior whitespace formalization in this PR. The rule still duplicated indentation: both and each 's described the same leading whitespace, which is the ambiguity raised in review and cannot express that a child must be indented deeper than its parent. Align the BNF with the existing ANTLR grammar (HypercodeParser.g4 / HypercodeLexer.g4): - drop from - define with synthetic / tokens - remove the now-unused ; keep the // rules as the lexer-level definition of indentation whitespace - document the off-side rule and lexer-driven indentation in Notes Co-Authored-By: Claude Opus 4.8 --- EBNF/Hypercode_Syntax.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/EBNF/Hypercode_Syntax.md b/EBNF/Hypercode_Syntax.md index 0f04439..cf03b7f 100644 --- a/EBNF/Hypercode_Syntax.md +++ b/EBNF/Hypercode_Syntax.md @@ -20,21 +20,22 @@ The goal is to provide an unambiguous reference for tool developers, parser auth ```bnf ::= { } - ::= [] [] + ::= [] ::= [] [] ::= "." ::= "#" - ::= { } - ::= + + ::= { } ::= { | | "_" | "-" } ::= "A" | ... | "Z" | "a" | ... | "z" ::= "0" | ... | "9" + ::= "\n" + ::= (synthetic token emitted by the lexer when depth increases) + ::= (synthetic token emitted by the lexer when depth decreases) ::= | ::= { } ::= { } ::= " " ::= "\t" - ::= "\n" ``` ## 2. Example Input @@ -104,6 +105,7 @@ Root - Identifiers must not contain whitespace or special symbols. - Indentation must be consistent (e.g., 2 or 4 spaces, or tabs—but not mixed). +- Indentation is significant (off-side rule): a nested `` must be indented deeper than its parent ``. The lexer reads each line's leading ``, tracks it on an indentation stack, and emits the synthetic `` / `` tokens when the depth increases or decreases. Because this context-sensitive relationship cannot be expressed in pure BNF, indentation handling is delegated to the lexer (see `HypercodeLexer.g4`). - No support for inline attributes or arguments in `.hc` files (these belong in `.hcs`). ## 6. Future Work From 1a5328e39b54f4e660dedb7490170a0e53b7bc94 Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Mon, 1 Jun 2026 21:46:30 +0300 Subject: [PATCH 8/9] Add CI workflow running the grammar test suite Add .github/workflows/ci.yml: on every pull_request (and push to main), set up JDK 17 and run `make -C EBNF test-all`, giving PRs an actual status check instead of manual local verification. Also fix a latent Makefile bug that the workflow depends on: the `build` target referenced $(ANTLR_JAR) but did not depend on the download target, so `make test-all` failed on a clean checkout even though the README promises the jar is fetched automatically. Add $(ANTLR_JAR) as a prerequisite of `build`. Co-Authored-By: Claude Opus 4.8 --- .github/workflows/ci.yml | 22 ++++++++++++++++++++++ EBNF/Makefile | 2 +- 2 files changed, 23 insertions(+), 1 deletion(-) create mode 100644 .github/workflows/ci.yml diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..52d78fb --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,22 @@ +name: CI + +on: + pull_request: + push: + branches: [main] + +jobs: + grammar-tests: + name: Hypercode grammar tests + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Set up JDK + uses: actions/setup-java@v4 + with: + distribution: temurin + java-version: '17' + + - name: Run grammar test suite + run: make -C EBNF test-all diff --git a/EBNF/Makefile b/EBNF/Makefile index 6367420..3e572e4 100644 --- a/EBNF/Makefile +++ b/EBNF/Makefile @@ -26,7 +26,7 @@ all: run $(ANTLR_JAR): curl -O $(ANTLR_URL) -build: +build: $(ANTLR_JAR) java -Xmx500M -cp "$(ANTLR_JAR)" org.antlr.v4.Tool HypercodeLexer.g4 HypercodeParser.g4 javac -cp ".:$(ANTLR_JAR)" Hypercode*.java javac -cp ".:$(ANTLR_JAR)" Main.java From bc9d5230723e8c4eca2649146c568f908cb0eecb Mon Sep 17 00:00:00 2001 From: Egor Merkushev Date: Mon, 1 Jun 2026 21:49:15 +0300 Subject: [PATCH 9/9] Fix stale paths and clone URL in EBNF/README.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The ANTLR playground lives in EBNF/, not examples/antlr/ — update the Quick Start cd target and the directory-layout heading. Also correct the clone URL org from 0AL to the actual remote 0al-spec. Co-Authored-By: Claude Opus 4.8 --- EBNF/README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/EBNF/README.md b/EBNF/README.md index 233b1c0..784973d 100644 --- a/EBNF/README.md +++ b/EBNF/README.md @@ -13,8 +13,8 @@ This subproject provides a minimal interactive environment for experimenting wit ## Quick Start ```bash -git clone https://github.com/0AL/Hypercode.git -cd Hypercode/examples/antlr +git clone https://github.com/0al-spec/Hypercode.git +cd Hypercode/EBNF make run ``` @@ -28,7 +28,7 @@ The first `make run` will automatically: ## 📁 Directory Layout ``` -examples/antlr/ +EBNF/ ├── HypercodeLexer.g4 # ANTLR4 lexer grammar (tokens, indentation) ├── HypercodeParser.g4 # ANTLR4 parser grammar (commands, blocks) ├── example.hc # Sample Hypercode input file