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/Hypercode_Syntax.md b/EBNF/Hypercode_Syntax.md new file mode 100644 index 0000000..cf03b7f --- /dev/null +++ b/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 + ::= { } + ::= [] + ::= [] [] + ::= "." + ::= "#" + ::= { } + ::= { | | "_" | "-" } + ::= "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" +``` + +## 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 `` 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 + +- 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/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 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 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/)