README.md

metadata

title: GAL Compiler
emoji: 🌱
colorFrom: green
colorTo: yellow
sdk: docker
pinned: false

GAL Compiler

GAL Compiler is a web-based compiler and interpreter for the GAL (Grow A Language) programming language. It includes a browser editor, lexical analysis, LL(1) syntax analysis, AST building, semantic validation, intermediate-code generation, program execution, and an optional Gemini-powered AI assistant.

Live app:

https://clarkoer-gal.hf.space/

Features

• Lexical analysis with token table output
• LL(1) parser using CFG, FIRST, FOLLOW, and PREDICT sets
• AST builder and semantic validation
• Runtime interpreter for root(), functions, variables, arrays, loops, conditionals, input, and output
• Web editor with syntax highlighting and run modes
• Socket.IO execution for interactive water() input
• Optional AI chatbot using Gemini with offline fallback help

Project Structure

my GAL code/
  Backend/
    server.py              Flask + Socket.IO API entry point
    lexer/                 Scanner, tokens, delimiters, lexical errors
    parser/                LL(1) parser and AST builder
    cfg/                   Grammar, FIRST sets, PREDICT sets
    semantic/              Semantic analyzer
    interpreter/           Runtime interpreter
    ai/                    Gemini prompt and fallback chatbot replies
  UI/
    index.html             Browser interface
    main.js                Editor actions and API calls
    style.pixel.css        UI styling
  requirements.txt         Python dependencies
  start.ps1                Windows PowerShell starter
  start.bat                Windows Command Prompt starter
  Dockerfile               Hugging Face Spaces / Docker deployment

Requirements

• Python 3.10 or newer is recommended.
• Git, if cloning from GitHub.
• A browser such as Chrome, Edge, or Firefox.
• Optional: Gemini API key for the AI assistant.

The backend dependencies are listed in requirements.txt:

flask
flask-socketio
flask-cors
eventlet
google-genai
sentence-transformers
numpy

Local Setup on Windows

Option A: One-command start

PowerShell:

powershell -ExecutionPolicy Bypass -File .\start.ps1

Command Prompt:

start.bat

The script creates .venv, activates it, installs requirements.txt, sets PORT=5000 when no port is provided, and starts Backend/server.py.

Then open:

http://localhost:5000

Option B: Manual start

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
python Backend/server.py

Then open:

http://localhost:5000

Local Setup on macOS or Linux

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
python Backend/server.py

Then open:

http://localhost:5000

Environment Variables

The system reads environment variables directly from the operating system. It does not automatically load a .env file.

Variable	Required	Purpose	Default
PORT	No	Backend server port	5000 locally, 7860 in Docker
DEBUG	No	Enables Flask debug mode when set to True	False
GEMINI_API_KEY	No	Enables Gemini AI chatbot mode	empty / fallback mode

Set Gemini API Key on Windows PowerShell

$env:GEMINI_API_KEY="your_gemini_api_key_here"
python Backend/server.py

Set Gemini API Key on Command Prompt

set GEMINI_API_KEY=your_gemini_api_key_here
python Backend\server.py

Set Gemini API Key on macOS or Linux

export GEMINI_API_KEY="your_gemini_api_key_here"
python Backend/server.py

Do not commit your real API key to GitHub.

If GEMINI_API_KEY is missing, the compiler still runs. The AI chatbot will use the local fallback replies instead of Gemini.

Hugging Face Spaces Setup

This repository uses Docker for Hugging Face Spaces. The Space reads the port from the Dockerfile:

PORT=7860

To enable Gemini on Hugging Face:

1. Open your Hugging Face Space.
2. Go to Settings.
3. Open Repository secrets.
4. Add this secret:

GEMINI_API_KEY=your_gemini_api_key_here

5. Restart or rebuild the Space.

Without this secret, the compiler still works, but the chatbot returns fallback answers.

Running the System

When the server starts successfully, it prints API endpoints similar to:

Server running at http://0.0.0.0:5000
POST http://localhost:5000/api/lex
POST http://localhost:5000/api/parse
POST http://localhost:5000/api/semantic
POST http://localhost:5000/api/icg
POST http://localhost:5000/api/chat
Socket.IO: run_code

Open the browser at:

http://localhost:5000

The Flask backend serves the UI folder directly, so you do not need a separate frontend server.

API Endpoints

All main compiler endpoints receive JSON.

Health Check

GET /api/health

Returns a simple server status response.

Lexical Analysis

POST /api/lex
Content-Type: application/json

{
  "source_code": "root() { reclaim; }"
}

Returns lexer tokens and lexical errors.

Syntax Analysis

POST /api/parse
Content-Type: application/json

{
  "source_code": "root() { reclaim; }"
}

Runs lexer first, then LL(1) parser.

Semantic Analysis

POST /api/semantic
Content-Type: application/json

{
  "source_code": "root() { seed x = 1; reclaim; }"
}

Runs lexer, parser, AST builder, and semantic validator.

Intermediate Code Generation

POST /api/icg
Content-Type: application/json

{
  "source_code": "root() { seed x = 1; reclaim; }"
}

Runs the compiler stages needed for intermediate-code generation.

Full Run / Execution

POST /api/run
Content-Type: application/json

{
  "source_code": "root() { plant(\"Hello Garden!\"); reclaim; }"
}

Runs the full non-interactive pipeline:

source code -> lexer -> parser/builder -> semantic analyzer -> interpreter

AI Chat

POST /api/chat
Content-Type: application/json

{
  "message": "How do I create an array?",
  "session_id": "default",
  "editor_code": ""
}

If GEMINI_API_KEY is set, this uses Gemini. If not, it uses the local fallback AI responses.

Clear AI Chat Session

POST /api/chat/clear
Content-Type: application/json

{
  "session_id": "default"
}

Clears the stored chat history for that session.

Socket.IO Runtime Events

Interactive execution uses Socket.IO so water() input can pause and resume.

Event	Direction	Purpose
connect	browser -> server	Opens a runtime session
disconnect	browser -> server	Ends a runtime session
run_code	browser -> server	Runs source code interactively
output	server -> browser	Sends plant() output or runtime messages
input_required	server -> browser	Requests input for water()
capture_input	browser -> server	Sends user input back to interpreter
execution_complete	server -> browser	Tells UI the run finished

Quick Start GAL Program

Paste this into the editor and click Run:

root() {
    seed x = 10;
    seed y = 5;
    seed sum;

    sum = x + y;

    plant("Sum:", sum);
    reclaim;
}

Expected output:

Sum: 15

Interactive Input Example

root() {
    seed a;
    seed b;
    seed sum;

    plant("Enter first number:");
    water(a);

    plant("Enter second number:");
    water(b);

    sum = a + b;
    plant("Sum:", sum);

    reclaim;
}

When the program reaches water(a) or water(b), the UI asks for input.

Language Overview

Common GAL keywords:

GAL keyword	Meaning
root	Main function
pollinate	Function declaration
reclaim	Return / end function
seed	Integer type
tree	Double/float type
leaf	Character type
vine	String type
branch	Boolean type
plant	Output
water	Input
spring	If
bud	Else-if
wither	Else
cultivate	For loop
grow	While loop
tend	Do-while loop
harvest	Switch
variety	Case
soil	Default
prune	Break
skip	Continue
bundle	Struct-like type
fertile	Constant

Troubleshooting

Could not connect to server

Make sure the backend is running:

python Backend/server.py

Then open:

http://localhost:5000

If you opened the UI with VS Code Live Server on another port, the UI will try to call:

http://localhost:5000

So the Flask backend must still be running on port 5000.

Port already in use

Use another port:

PowerShell:

$env:PORT="5001"
python Backend/server.py

Command Prompt:

set PORT=5001
python Backend\server.py

Then open:

http://localhost:5001

PowerShell script cannot run

Use:

powershell -ExecutionPolicy Bypass -File .\start.ps1

Gemini chatbot only gives fallback answers

Check that the key is set in the same terminal where the server starts:

echo $env:GEMINI_API_KEY

Then restart:

python Backend/server.py

Dependencies fail to install

Upgrade pip and reinstall:

python -m pip install --upgrade pip
python -m pip install -r requirements.txt

Hugging Face push rejected because of binary files

Large generated PDFs or binary files should not be pushed directly to Hugging Face unless the Space/repository uses Git LFS or Xet storage. Keep source files, code, and small documentation in Git, and avoid committing large generated artifacts when possible.