🐟 Olhanense Compiler

A fully functional multi-phase compiler and stack-based virtual machine for Olhanense — a programming language based on the Portuguese coastal dialect of Olhão (Algarve).

---

What is Olhanense?

Olhanense is an imperative scripting language where every keyword is derived from the traditional coastal dialect of Olhão, Portugal.

Instead of standard keywords like while, if, or print, Olhanense uses authentic regional expressions:

• tas_a_nora ("you're in trouble") instead of while
• bota_ca_pra_fora ("throw it out") instead of print
• xaringado ("prickly / fixed") instead of const
• olha_la_moh ("look here mate") to open the program, and hades ("see you later") to close it.

Source files use the .moh extension.

---

Language Keywords & Specification

Feature	Olhanense keyword	Standard equivalent
Program start	olha_la_moh	main() {
Program end	hades	}
Variable declaration	moce nome = valor;	var x = 5;
Constant declaration	xaringado nome = valor;	const x = 5;
Function declaration	funcao f(a, b) / chama_o_moce	function f(a, b)
Return statement	retorna expr;	return expr;
Array literal	["sardinha", "choco"]	["sardinha", "choco"]
Array access / assign	redes[0] / redes[0] = "choco"	redes[0] / redes[0] = "choco"
String concatenation	"Peixe: " + count	"Peixe: " + count
Block start	agarra	{
Block end	larga	}
Print	bota_ca_pra_fora(expr);	print(expr);
Print (alias)	manda_boca(expr);	print(expr);
Conditional	bira_por_aqui(cond)	if (cond)
Else	senao_levas	else
While loop	tas_a_nora(cond)	while (cond)
For loop	para_cada (moce i em 1..10)	for (let i = 1; i <= 10; i++)
Increment	id mais_um_copo;	id++;
Try block	tenta_la	try
Catch block	chama_o_dabe	catch
Exception throw	berro	throw
Input (stdin)	xiba_te()	readLine()
Boolean True	verdade	true
Boolean False	petronga	false
Null value	nicles	null
Equality	eh_chapado	==
Inequality	nada_a_ber	!=
Greater than	maior_que_o_boji	>
Less than	menor_que_a_sardinha	<
Greater or equal	maior_ou_chapado	>=
Less or equal	menor_ou_chapado	<=

Data Types (dynamically inferred): integer, string, bool, array, nicles (null)

---

Sample Program (tests/teste.moh)

olha_la_moh
    moce peixe = 10;
    xaringado limite = 0;

    // Count down from 10 to 1
    tas_a_nora (peixe maior_que_o_boji limite) agarra
        bota_ca_pra_fora(peixe);
        peixe = peixe - 1;
    larga

    // Try / catch block
    tenta_la agarra
        bira_por_aqui (peixe eh_chapado 0) agarra
            bota_ca_pra_fora("Acabou o peixe!");
        larga
    larga
    chama_o_dabe agarra
        bota_ca_pra_fora("Houve berro na lota!");
    larga

hades

Output:

10
9
8
7
6
5
4
3
2
1
Acabou o peixe!

---

Compiler Architecture

The compiler pipeline is built in Java 17 using ANTLR 4:

flowchart TD
    subgraph Compiler ["Olhanense Compiler Pipeline"]
        A[".moh File"] --> B["Lexer (ANTLR 4)"]
        B --> C["Parser (ANTLR 4)"]
        C --> D["TypeChecker (Semantic Analysis)"]
        D --> E["Bytecode Generator (ParseTreeVisitor)"]
    end

    E --> F[("bytecodes.bc")]
    F --> G["Olhanense VM (Stack Engine)"]

Loading

Component Breakdown

• Lexer & Parser (src/Olhanense/): Generated by ANTLR 4 from src/Olhanense.g4. Uses a custom MyErrorListener for separate syntax/lexical error reporting.
• Type Checker (src/TypeChecker/): Annotates parse tree nodes with inferred types (INTEGER, STRING, BOOL, ARRAY, NULL), checks for undeclared identifiers, prevents mutation of xaringado constants, and validates operator compatibility.
• Code Generator (src/CodeGenerator/): Traverses the annotated parse tree and produces compact VM instructions along with a constant pool for literals.
• Virtual Machine (src/VM/): A stack-based execution engine with memory management for global variables, an operand stack, and a dedicated exception handler stack for tenta_la/chama_o_dabe blocks.

---

Project Structure

olhanense-compiler/
├── lib/
│   └── antlr-4.13.2-complete.jar   # ANTLR 4 runtime library
├── tests/                          # Test scripts
│   ├── teste.moh                   # Sample program
│   ├── exemplo.moh                 # Additional test program
│   ├── test_arrays.moh             # Array tests
│   ├── test_for.moh                # For loop tests
│   ├── test_func.moh               # Function tests
│   └── test_sconcat.moh            # String concatenation tests
├── src/                            # Compiler & VM source code
│   ├── Olhanense.g4                # ANTLR 4 grammar specification
│   ├── OlhanenseCompileAndRun.java # CLI compiler entry point
│   ├── MyErrorListener.java        # Custom ANTLR error collector
│   ├── Olhanense/                  # Generated Lexer, Parser, Visitors
│   ├── SymbolTable/                # Symbol table & scope metadata
│   ├── TypeChecker/                # Type inference & semantic analysis
│   ├── CodeGenerator/              # Bytecode emitter & constant pool
│   └── VM/                         # Stack VM, opcodes, instruction set
├── .gitignore                      # Git exclusion rules
└── README.md                       # Documentation

---

Building & Running

Follow these steps to generate the ANTLR parser, compile the Java source code, and run an Olhanense program:

1. Generate ANTLR Parser & Lexer

The generated ANTLR files (src/Olhanense/) are excluded from version control. Generate them from src/Olhanense.g4 using:

java -jar lib/antlr-4.13.2-complete.jar -package Olhanense -visitor -o src/Olhanense src/Olhanense.g4

2. Compile Java Sources

Compile all Java sources (including the generated ANTLR classes) into the out/ directory:

javac -cp "lib/antlr-4.13.2-complete.jar" -encoding UTF-8 -d out $(find src -name "*.java")

3. Run an Olhanense Script

Run any .moh script through the Olhanense compiler & VM:

java -cp "out:lib/antlr-4.13.2-complete.jar" OlhanenseCompileAndRun tests/teste.moh

Debug Flags

Flag	Description
-trace	Prints step-by-step VM execution (Instruction Pointer, OpCode, Stack state)
-bytes	Dumps the constant pool, disassembled assembly, and raw hex bytecodes

# Detailed execution trace
java -cp "out:lib/antlr-4.13.2-complete.jar" OlhanenseCompileAndRun tests/teste.moh -trace

---

Future Plans & Roadmap

• Interactive Web Playground: A web-based IDE with real-time compilation, live execution, and interactive SVG parse tree visualization (inspired by IntelliJ's ANTLR previewer).
• VS Code Extension: Syntax highlighting (.moh) and code snippets extension.
• Compiling to Native / C: A backend that emits C code or LLVM IR for native execution without JVM.

---

Contributing

Contributions, bug reports, and feature improvements are welcome!

To contribute:

1. Fork the repository.
2. Create your feature branch (git checkout -b feature/my-new-feature).
3. Commit your changes (git commit -m 'Add some feature').
4. Push to the branch (git push origin feature/my-new-feature).
5. Open a Pull Request (PR) detailing your changes.

---

Author

@rodrigolinhas

License

This project is licensed under the MIT License. Feel free to use, modify, and distribute it.

---

Made with 🐟 and saudade from the Algarve