🚀 Zed Programming Language

Zed is a modern, dynamic programming language built for fun, learning, and productivity. Created by Mazell Smack-Dubose, Zed features a complete implementation with both interpreter and compiler modes, backed by a sophisticated virtual machine with 80+ bytecode instructions.

---

📖 Table of Contents

• ✨ Key Features
• 🚀 Quick Start
• 📚 Examples
• 🏗️ Building from Source
• 💻 Usage
• 🧪 Testing
• 🏛️ Architecture
• 📊 Performance
• 🎯 Development Status
• 📄 License
• 🤝 Contributing
• 👤 Author

---

✨ Key Features

🎯 Dual Execution Modes

• 🔍 Interpreter Mode: Direct AST interpretation perfect for development, debugging, and interactive programming
• ⚡ Compiler Mode: High-performance bytecode compilation with VM execution optimized for production use

💡 Modern Language Features

• Variables & Types: Dynamic typing with strong type checking
• Arithmetic: Full operator support (+, -, *, /, %, **) with proper precedence
• Comparisons: Complete comparison operators (==, !=, <, >, <=, >=)
• Logic: Boolean operators (and, or, not) with short-circuiting
• Bitwise: Full bitwise operations (&, |, ^, ~, <<, >>)
• Control Flow: Comprehensive flow control (if/elif/else, while, for loops)
• Functions: First-class functions with parameters, return values, and closures
• Data Structures: Rich built-in types (lists, dictionaries, sets)
• Advanced: List comprehensions, pattern matching (match/case), break/continue

🛠️ Rich Built-in Library

• I/O: print() for console output
• Introspection: len(), type() for runtime inspection
• Iteration: range() for generating sequences
• Conversion: str(), int(), float(), bool() for type conversion
• Math: min(), max() for numerical operations

🖥️ Advanced Virtual Machine

• Architecture: Stack-based bytecode execution engine
• Instructions: 80+ specialized opcodes for optimal performance
• Memory: Sophisticated call frame and upvalue management
• Debugging: Professional disassembler with execution profiling
• Error Handling: Comprehensive error reporting and recovery
• Statistics: Built-in execution timing and memory usage tracking

---

🚀 Quick Start

Prerequisites

• C++17 compatible compiler (GCC 7+, Clang 5+, MSVC 2017+)
• CMake 3.10 or higher
• Make or Ninja build system

Installation

# Clone the repository
git clone https://github.com/PlangoDev/zed-lang.git
cd zed-lang

# Build the project
./build.sh

# Run your first Zed program
./build/zed examples/hello.zed

Hello World in 30 seconds

1. Create a file hello.zed:

   print("Hello, World!")
   print("Welcome to Zed programming!")
   

2. Run it:

   ./build/zed hello.zed

3. See the magic ✨

---

📚 Examples

🎆 Comprehensive Demo

Explore all of Zed's features with our comprehensive example:

./build/zed examples/comprehensive_demo.zed

🎲 Interactive Game

Try our number guessing game:

./build/zed examples/number_guessing_game.zed

📊 Data Analysis

See Zed's data processing capabilities:

./build/zed examples/data_analysis.zed

Code Samples

🔢 Variables and Data Types

name = "Zed"
version = 2.0
is_awesome = True
numbers = [1, 2, 3, 4, 5]
person = {"name": "Alice", "age": 30}

print("Language: " + name)
print("Version: " + str(version))
print("Type: " + type(name))

🔄 Control Flow

# Conditional logic
score = 85
if score >= 90:
    grade = "A"
elif score >= 80:
    grade = "B"
else:
    grade = "C"

# Loops
for i in range(5):
    print("Count: " + str(i))

while score > 0:
    print("Score: " + str(score))
    score = score - 10

⚙️ Functions and Closures

def fibonacci(n):
    if n <= 1:
        return n
    return fibonacci(n-1) + fibonacci(n-2)

def make_multiplier(factor):
    def multiplier(x):
        return x * factor
    return multiplier

double = make_multiplier(2)
result = double(fibonacci(10))
print("Result: " + str(result))

📊 Data Processing

data = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]

# List comprehensions
squares = [x * x for x in data]
evens = [x for x in data if x % 2 == 0]

print("Squares: " + str(squares))
print("Even numbers: " + str(evens))

# Pattern matching
def describe_number(n):
    match n % 2:
        case 0:
            return "even"
        case 1:
            return "odd"
        case _:
            return "unknown"

for num in range(5):
    print(str(num) + " is " + describe_number(num))

---

🏗️ Building from Source

Manual Build

# Create build directory
mkdir build && cd build

# Configure with CMake
cmake ..

# Build the project
make -j$(nproc)

# Optional: Install system-wide
sudo make install

Alternative: Use Build Script

# Use the provided build script (recommended)
./build.sh

# This automatically:
# - Creates build directory
# - Runs CMake configuration
# - Compiles with optimizations
# - Sets up examples

Build Options

# Debug build
cmake -DCMAKE_BUILD_TYPE=Debug ..

# Release build (default)
cmake -DCMAKE_BUILD_TYPE=Release ..

# Enable additional debugging
cmake -DZED_DEBUG=ON ..

---

💻 Usage

Command Line Interface

Basic Execution

# Interactive REPL mode
./build/zed

# Run a Zed file with interpreter
./build/zed script.zed

# Run with compiler + VM (faster)
./build/zed -c script.zed

Advanced Options

# Compile to bytecode file
./build/zed -c -o script.zbc script.zed

# Execute bytecode file
./build/zed script.zbc

# Debug mode with detailed output
./build/zed -d script.zed

# Show bytecode disassembly
./build/zed --disasm script.zed

# Performance profiling
./build/zed --profile script.zed

Interactive Mode (REPL)

$ ./build/zed
Zed Programming Language v2.0
Created by Mazell Smack-Dubose
>>> x = 42
>>> print("The answer is " + str(x))
The answer is 42
>>> def greet(name): return "Hello, " + name
>>> greet("World")
"Hello, World"
>>> exit()

---

🧪 Testing

Automated Testing

# Run all tests (recommended)
./build.sh && ./run_tests.sh

# Run unit tests only
make -C build && ./build/run_tests

# Run language feature tests
./build/zed tests/test_functions.zed
./build/zed tests/test_data_structures.zed
./build/zed tests/test_control_flow.zed

Manual Testing

# Test interpreter mode
./build/zed examples/comprehensive_demo.zed

# Test compiler mode
./build/zed -c examples/data_analysis.zed

# Test bytecode generation and execution
./build/zed -c -o test.zbc examples/fibonacci.zed
./build/zed test.zbc

Performance Benchmarks

# Run performance tests
./build/zed --profile examples/comprehensive_demo.zed

# Compare interpreter vs compiler performance
time ./build/zed examples/fibonacci.zed
time ./build/zed -c examples/fibonacci.zed

---

🏛️ Architecture

Core Components

Component	File	Description
🔤 Lexer	src/lexer.cpp	Tokenization with Python-style indentation handling
🌳 Parser	src/parser.cpp	Recursive descent parser generating comprehensive AST
📊 AST	src/ast.cpp	Abstract syntax tree nodes for all language constructs
🔄 Interpreter	src/interpreter.cpp	Tree-walking interpreter with environment management
⚡ Compiler	src/compiler.cpp	AST → Bytecode compilation with optimization passes
🖥️ Virtual Machine	src/vm.cpp	Stack-based VM with comprehensive instruction set
💾 Value System	src/value.cpp	Dynamic typing system supporting all Zed data types

Execution Pipeline

graph LR
    A[Source Code] --> B[Lexer]
    B --> C[Parser]
    C --> D[AST]
    D --> E{Mode?}
    E -->|Interpreter| F[Tree Walker]
    E -->|Compiler| G[Bytecode Generator]
    G --> H[Virtual Machine]
    F --> I[Result]
    H --> I

Loading

Bytecode Instruction Set

Zed's VM supports 80+ specialized instructions organized into categories:

🔢 Arithmetic Operations

• ADD, SUB, MUL, DIV, MOD, POW, NEG

⚡ Bitwise Operations

• BIT_AND, BIT_OR, BIT_XOR, BIT_NOT, BIT_LSHIFT, BIT_RSHIFT

🧠 Logical Operations

• LOGICAL_AND, LOGICAL_OR, LOGICAL_NOT

📊 Comparison Operations

• CMP, CMP_NE, CMP_LE, CMP_GE, IS, IN

🎯 Control Flow

• JMP, JZ (Jump if Zero), JNZ (Jump if Not Zero)

💾 Variable Management

• LOAD_LOCAL, STORE_LOCAL, LOAD_GLOBAL, STORE_GLOBAL

⚙️ Function Handling

• CALL, CALL_BUILTIN, RET, YIELD

📋 Data Structure Operations

• LIST_NEW, DICT_NEW, SET_NEW, DICT_SET, SET_ADD

🔍 Indexing and Slicing

• INDEX_GET, INDEX_SET, SLICE

🔄 Iterator Support

• ITER_NEW, ITER_NEXT, ITER_DONE

📚 Stack Management

• POP, DUP, SWAP, ROT

---

📊 Performance

Execution Modes Comparison

Mode	Speed	Use Case	Memory	Debugging
🔍 Interpreter	Moderate	Development, debugging, interactive use	Lower	Excellent
⚡ Compiler + VM	Fast	Production, batch processing	Higher	Good

Benchmarks

• Startup Time: < 10ms for simple programs
• Fibonacci(30): ~2.1s (interpreted), ~0.8s (compiled)
• Data Processing: 50K+ operations/second
• Memory Footprint: ~5MB base, +1MB per 10K variables

---

🎯 Development Status

✅ Completed Features

• ✅ Core Language: All fundamental language constructs
• ✅ Type System: Dynamic typing with runtime type checking
• ✅ Control Flow: Complete conditional and loop support
• ✅ Functions: First-class functions with closures
• ✅ Data Structures: Lists, dictionaries, sets with full operations
• ✅ Advanced Features: List comprehensions, pattern matching
• ✅ Virtual Machine: Complete 80+ instruction VM
• ✅ Error Handling: Comprehensive error reporting
• ✅ CLI Interface: Professional command-line interface
• ✅ Testing Suite: Extensive test coverage
• ✅ Documentation: Complete API and usage documentation
• ✅ Build System: Cross-platform CMake build

🔄 Ongoing Development

• 🔄 Language Server Protocol (LSP) support
• 🔄 VS Code Extension improvements
• 🔄 Standard Library expansion
• 🔄 Package System design
• 🔄 WebAssembly compilation target

🎯 Future Plans

• 🎯 Module System for better code organization
• 🎯 Foreign Function Interface (FFI) for C/C++ integration
• 🎯 Concurrent Programming with async/await
• 🎯 Just-In-Time (JIT) compilation
• 🎯 Interactive Debugger

---

📄 License

MIT License - See LICENSE file for details.

Zed is free and open-source software. Feel free to use, modify, and distribute it according to the MIT License terms.

---

🤝 Contributing

We welcome contributions! Here's how you can help:

Getting Started

1. Fork the repository
2. Clone your fork: git clone https://github.com/YOUR_USERNAME/zed-lang.git
3. Create a feature branch: git checkout -b feature/amazing-feature
4. Build and test: ./build.sh && ./run_tests.sh

Development Guidelines

• 📝 Follow the existing code style
• ✅ Add tests for new features
• 📚 Update documentation as needed
• 🧪 Ensure all tests pass before submitting
• 💬 Write clear commit messages

Contribution Areas

• 🐛 Bug fixes and improvements
• ✨ New language features
• 📚 Documentation improvements
• 🧪 Test coverage expansion
• 🎨 Example programs and tutorials
• 🛠️ Development tools and IDE support

See CONTRIBUTING.md for detailed contribution guidelines.

---

👤 Author

Zed Programming Language is created and maintained by:

Mazell Smack-Dubose

• 🌐 GitHub: @PlangoDev
• 📧 Project: zed-lang

Why Zed?

Zed was built as a fun project to explore programming language design and implementation. It combines modern language features with educational value, making it perfect for:

• 🎓 Learning programming language concepts
• 🧪 Experimenting with new ideas
• 📚 Teaching compiler and interpreter design
• 🚀 Building small to medium projects

---

🚀 Zed Programming Language
A modern, dynamic language built for fun and productivity

"Programming should be fun, expressive, and educational."
— Mazell Smack-Dubose, Creator of Zed

---

Made with ❤️ by Mazell Smack-Dubose • GitHub • Get Started • Examples