Hypercode Syntax Specification

.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

EBNF/Hypercode_Syntax.md

@@ -0,0 +1,127 @@
+# 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>   ::= <command> <newline> [<block>]
+<command>        ::= <identifier> [<class>] [<id>]
+<class>          ::= "." <identifier>
+<id>             ::= "#" <identifier>
+<block>          ::= <INDENT> { <command-line> } <DEDENT>
+<identifier>     ::= <letter> { <letter> | <digit> | "_" | "-" }
+<letter>         ::= "A" | ... | "Z" | "a" | ... | "z"
+<digit>          ::= "0" | ... | "9"
+<newline>        ::= "\n"
+<INDENT>         ::= (synthetic token emitted by the lexer when <indent> depth increases)
+<DEDENT>         ::= (synthetic token emitted by the lexer when <indent> depth decreases)
+<indent>         ::= <spaces> | <tabs>
+<spaces>         ::= <space> { <space> }
+<tabs>           ::= <tab> { <tab> }
+<space>          ::= " "
+<tab>            ::= "\t"
+```
+
+## 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).
+- Indentation is significant (off-side rule): a nested `<block>` must be indented deeper than its parent `<command-line>`. The lexer reads each line's leading `<indent>`, tracks it on an indentation stack, and emits the synthetic `<INDENT>` / `<DEDENT>` 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
+
+- 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

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

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

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/)