JECH Programming Language

📖 Read this in other languages: English | Português (Brasil)

Ever wondered how Python, JavaScript, or PHP actually work under the hood?

JECH is a programming language built from scratch to teach you exactly that — in a clear, documented, and accessible way.

---

🎯 Who Is This For?

You're a developer who:

• ✅ Knows Python, JavaScript, or PHP
• ✅ Writes code every day
• ✅ Wonders "how does print() actually work?"
• ❌ Has never touched C or compilers
• ❌ Doesn't know what "bytecode" means
• ❌ Thinks "lexer" sounds intimidating

Perfect! JECH was built specifically for you.

---

🤔 What Problem Does JECH Solve?

The Problem

You know how to use Python:

print("Hello")
x = 10
if x > 5:
    print(x)

But you have no idea how Python actually executes this. It's magic! ✨

The Solution

JECH shows you exactly how it works, step by step:

Your Code → Tokenizer → Parser → AST → Bytecode → VM → Output
   📝          🔤         🧱      🌳       🔧       ⚡      ✨

Every stage is:

• ✅ Documented with examples
• ✅ Explained in terms you already know
• ✅ Visible - you can see it happen
• ✅ Modular - each piece is independent

---

🚀 Quick Start (5 minutes)

1. Install

git clone https://github.com/yourusername/jech
cd jech
make

2. Try the REPL (Interactive Mode)

./build/jech

>>> keep x = 10;
>>> say(x);
10

>>> keep name = "JECH";
>>> say(name);
JECH

>>> keep numbers = [1, 2, 3];
>>> say(numbers[0]);
1

It's like Python's interactive mode!

3. Run a Program

./build/jech examples/17_arrays_basic.jc

---

📖 Learn How Languages Work

For Python Developers

You know this:

print("Hello")

JECH shows you this happens:

1. Tokenizer breaks it into: [print] [(] ["Hello"] [)] 
2. Parser understands: "This is a print statement"
3. Compiler generates: OP_PRINT "Hello"
4. VM executes: Output "Hello" to screen

Same process Python uses! (CPython does exactly this)

For JavaScript Developers

You know this:

const x = 10;
console.log(x);

JECH shows you:

• How V8 tokenizes your code
• How the parser builds an AST
• How bytecode is generated
• How the VM executes it

Same principles, different syntax!

For PHP Developers

You know this:

$x = 10;
echo $x;

JECH reveals:

• How Zend Engine processes your code
• How opcodes are generated
• How the executor runs them

Same architecture!

---

🎓 Learning Path

Level 1: Use It (Start Here!)

Goal: Get comfortable with JECH syntax

# Try the REPL
./build/jech

# Run examples
./build/jech examples/01_hello_world.jc
./build/jech examples/17_arrays_basic.jc

Time: 15 minutes
Docs: Language Features

---

Level 2: Understand the Concepts

Goal: Learn how languages work (no C required!)

Read: For Beginners Guide

This guide explains:

• What is a tokenizer? (with Python analogies)
• What is a parser? (with JavaScript examples)
• What is bytecode? (like Python's .pyc files)
• What is a VM? (like CPython)

Time: 30 minutes
Prerequisites: None! Just curiosity

---

Level 3: See It In Action

Goal: Watch code transform through each stage

Read: Architecture Overview

Follow a single line of code:

say("Hello");

Through all 5 stages:

1. Tokenizer → [say] [(] ["Hello"] [)] [;]
2. Parser → SAY_STATEMENT
3. AST → SAY_NODE { value: "Hello" }
4. Bytecode → OP_SAY "Hello"
5. VM → print("Hello")

Time: 45 minutes
Prerequisites: Level 2

---

Level 4: Deep Dive into Components

Goal: Understand each component in detail

Read:

• Tokenizer - How code becomes tokens
• Parser - How tokens become structure
• AST - How structure becomes trees
• Bytecode - How trees become instructions
• VM - How instructions become execution

Time: 2-3 hours
Prerequisites: Level 3

---

Level 5: Contribute

Goal: Add features, fix bugs, improve docs

Read: Contributing Guide

You can contribute even without knowing C:

• Write example programs
• Improve documentation
• Report bugs
• Suggest features
• Write tests

Time: Ongoing
Prerequisites: Enthusiasm!

---

🧠 Language Features

Variables

keep x = 10;
keep name = "João";
keep active = true;

say(x);        // 10
say(name);     // João
say(active);   // true

Like: Python's x = 10, JavaScript's const x = 10, PHP's $x = 10

---

Arrays

keep numbers = [1, 2, 3, 4, 5];
keep names = ["Alice", "Bob", "Charlie"];
keep mixed = [42, "text", true];

say(numbers[0]);  // 1
say(names[1]);    // Bob
say(mixed[2]);    // true

Like: Python lists, JavaScript arrays, PHP arrays

---

Conditionals

keep age = 20;

when (age > 18) {
    say("Adult");
}
else {
    say("Minor");
}

Like: Python's if, JavaScript's if, PHP's if

---

Output

say("Hello, World!");
say(42);
say(true);
say(myVariable);
say(myArray[0]);

Like: Python's print(), JavaScript's console.log(), PHP's echo

---

🏗️ Architecture (The Magic Revealed)

The Pipeline

Every line of code goes through 5 stages:

┌─────────────┐
│ Source Code │  say("Hello");
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  Tokenizer  │  [say] [(] ["Hello"] [)] [;]
└──────┬──────┘
       │
       ▼
┌─────────────┐
│   Parser    │  SAY_STATEMENT { value: "Hello" }
└──────┬──────┘
       │
       ▼
┌─────────────┐
│     AST     │  SAY_NODE → "Hello"
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  Bytecode   │  [OP_SAY "Hello"]
└──────┬──────┘
       │
       ▼
┌─────────────┐
│     VM      │  Execute: print "Hello"
└──────┬──────┘
       │
       ▼
    Output: Hello

Real-World Comparison

This is exactly how Python works:

JECH Stage	Python Equivalent	What It Does
Tokenizer	tokenize module	Breaks code into pieces
Parser	ast.parse()	Validates syntax
AST	ast.AST	Creates tree structure
Bytecode	.pyc files	Compiles to instructions
VM	CPython	Executes instructions

Mind blown? 🤯 Now you know how Python works!

---

🧪 Testing & Quality

JECH has 70 automated tests covering:

• ✅ Tokenizer (32 assertions)
• ✅ Parser (25 assertions)
• ✅ VM (6 assertions)
• ✅ Integration (7 assertions)

Run Tests

./run_tests.sh

Pre-Commit Hooks

Automatically run tests before every commit:

./install_hooks.sh

Like: Python's pytest, JavaScript's jest, PHP's PHPUnit

---

📚 Documentation

For Beginners (Start Here!)

• For Beginners Guide ⭐
  • No C knowledge required
  • Uses Python/JavaScript analogies
  • Explains every concept simply

Architecture

• Architecture Overview
  • Complete pipeline explanation
  • Visual diagrams
  • Step-by-step examples

Components (Deep Dive)

• Tokenizer - Lexical analysis
• Parser - Syntax analysis
• AST - Tree structures
• Bytecode - Compilation
• VM - Execution

Contributing

• Contributing Guide
• Setup Guide
• Test Documentation

---

💡 Why JECH?

Educational

Learn how your favorite languages work:

• Python (CPython)
• JavaScript (V8, SpiderMonkey)
• PHP (Zend Engine)
• Ruby (YARV)

All use the same principles JECH demonstrates!

Transparent

Every stage is visible:

# See tokens
./build/jech --debug-tokens myfile.jc

# See AST
./build/jech --debug-ast myfile.jc

# See bytecode
./build/jech --debug-bytecode myfile.jc

Practical

Real features:

• ✅ Variables
• ✅ Arrays
• ✅ Conditionals
• ✅ REPL
• ✅ Error messages
• ✅ Type system (coming soon)

Simple

Small codebase:

• ~3,000 lines of C
• Well-documented
• Modular design
• Easy to understand

---

🎯 Project Goals

Primary Goal: Education

JECH exists to teach how programming languages work. Every design decision prioritizes clarity over performance.

Secondary Goal: Inspiration

Show that building a language is achievable. You don't need a PhD or 10 years of C experience.

Non-Goal: Production Use

JECH is not meant to replace Python, JavaScript, or PHP. It's a learning tool.

---

💖 The Story Behind JECH

JECH was created as:

1. A learning journey - Understanding how languages work
2. A teaching tool - Sharing that knowledge with others
3. A tribute - To my sons Jonathan Edwards and Charles Haddon (J-E-C-H)

It's built with love, for learners, by a learner.

---

🤝 Contributing

We welcome contributions from developers of all experience levels!

You Can Help By:

• 📝 Writing example programs
• 📖 Improving documentation
• 🐛 Reporting bugs
• 💡 Suggesting features
• 🧪 Writing tests
• 🌍 Translating docs

No C experience required!

See CONTRIBUTING.md for details.

---

📊 Project Stats

• Language: C
• Lines of Code: ~3,000
• Tests: 70 (100% passing)
• Documentation: 6 detailed guides
• Examples: 22 programs
• Contributors: Growing!

---

🗺️ Roadmap

✅ Completed

• Tokenizer
• Parser
• AST
• Bytecode compiler
• Virtual Machine
• Variables
• Arrays
• Conditionals
• REPL
• Comprehensive tests
• Documentation

🚧 In Progress

• Functions
• Loops
• Type system
• Standard library

🔮 Future

• Garbage collection
• Optimization passes
• JIT compilation
• Package manager

See roadmap.md for details.

---

📖 Learn More

Recommended Reading Order

1. For Beginners - Start here!
2. Architecture - See the big picture
3. Tokenizer - First stage
4. Parser - Second stage
5. VM - Final stage

External Resources

• Crafting Interpreters - Excellent book
• CPython Internals - How Python works
• V8 Blog - How JavaScript works

---

⚖️ License

JECH is free and open-source software licensed under the Apache 2.0 License.

---

🙏 Acknowledgments

• Python - For inspiration and design patterns
• Crafting Interpreters - For educational approach
• The community - For feedback and contributions

---

Ready to learn how languages work?

Get Started | Documentation | Contribute

Made with ❤️ for curious developers