🌟 O²L Programming Language

O²L is a modern object-oriented programming language that balances pure object-oriented design with practical programming constructs. Built with C++23, O²L eliminates primitives and null values while providing essential control flow like while loops, comprehensive arithmetic operations, and extensive string manipulation capabilities for real-world programming needs.

📚 Complete Documentation | 🚀 Getting Started Guide | 📖 Language Reference

🆕 Latest Features

• 🧬 Recursive Nested Generics: Support for complex nested types like Map<Text, List<Int>> in all variable, constant, property, record, and protocol declarations.
• 📚 Enhanced Collections: Over 30 new methods for List, Map, and Set including sorting, slicing, bulk operations, and advanced set theory functions (union, intersection, difference, etc.).
• 🔗 Enhanced Foreign Function Interface (FFI): Complete FFI system with advanced type support, SQLite integration, and comprehensive C library interoperability
• 🌐 HTTP Client Library: Complete http.client library with 30+ methods, multipart file upload, platform-specific implementations (Windows/Linux/macOS), and cross-platform libcurl fallback
• 🔄 JSON Library: Revolutionary json library with 30+ methods including auto-detection parsing, fixed path navigation bug, and seamless native Map/List integration
• 🌐 URL Library: Complete url library with 26 methods for URL parsing, construction, manipulation, and validation
• 🔄 Regular Expressions: Complete regexp library with 12 methods for pattern matching, text searching, and string manipulation
• 🔀 Control Flow Enhancement: else if syntax support for complex conditional logic with proper AST chaining
• 🛑 Break Statements: break statement for early exit from while loops, enabling search patterns and safety limits
• ⏭️ Continue Statements: continue statement for skipping iterations in while loops, perfect for filtering and validation
• 📏 Text Length Method: Text.length() method for string length calculation with full type integration
• 📐 Math Library: Comprehensive mathematical functions library with 40+ methods including trigonometry, logarithms, statistics, and constants (import math)
• ✨ Comprehensive Text Methods: 54 string manipulation methods including case conversion, search, validation, formatting, and advanced utilities
• 🔄 Variable Mutability: Method-scope variables are mutable while object properties remain immutable
• 🧠 Logical Operators: Full &&, ||, ! support with proper precedence and short-circuit evaluation
• 📁 Filesystem Operations: Complete system.fs module for file/directory management
• 🔗 Expression Enhancements: Parentheses support for complex expression grouping
• 🧪 Complete Test Suite: 532 comprehensive tests covering all language features with Google Test framework

---

🧠 Philosophy & Design Vision

Everything is an Object

In O²L, there are no primitives. Numbers, booleans, strings—everything is an object with methods and behaviors. This creates a unified, consistent programming model where all values follow the same patterns. For example, Text objects provide 50 comprehensive methods for manipulation, validation, and formatting, treating strings as first-class objects rather than simple data.

Immutability by Design

All objects in O²L are immutable. Once created, an object's state cannot be changed. This eliminates entire classes of bugs related to shared mutable state, race conditions, and unexpected side effects.

Selective Procedural Constructs

O²L adopts a pragmatic approach by supporting essential control flow like while loops for iteration alongside object-oriented patterns. This enables practical programming while maintaining the language's object-centric philosophy through iterators and method dispatch.

Elimination of Null

There are no null pointers or undefined values. Optional values are handled through explicit Optional<T> types, making null-pointer exceptions impossible and forcing developers to handle all cases explicitly.

Behavior-Driven Architecture

Rather than thinking in terms of data structures and algorithms, O²L encourages thinking in terms of objects that collaborate to solve problems. Each object has clear responsibilities and well-defined interfaces.

---

🚀 Quick Start

macOS Installation (Homebrew)

The easiest way to install O²L on macOS:

# Add the O²L tap
brew tap zombocoder/o2l

# Install O²L
brew install o2l

# Verify installation
o2l --version

# Create your first project
mkdir my-project && cd my-project
o2l-pkg init
o2l run src/main.obq

Manual Installation

For other platforms or if you want to build from source:

Looking at your CMakeLists.txt, the only external dependency you need to install is libffi (with pkg-config support).

Required Libraries

• libffi → Used for the Foreign Function Interface (src/Runtime/FFI/...).

  • On Ubuntu/Debian:

    sudo apt-get install libffi-dev pkg-config

  • On Fedora:

    sudo dnf install libffi-devel pkg-config

  • On Arch Linux:

    sudo pacman -S libffi pkgconf

  • On macOS (Homebrew):

    brew install libffi pkg-config

  • On Windows (MSYS2/MinGW):

    pacman -S mingw-w64-x86_64-libffi pkg-config

Optional / System-Provided

• dl (dynamic linking) → usually provided by CMAKE_DL_LIBS on Linux/macOS.
• ws2_32, wininet → provided by Windows SDK, no need to install separately.

Build Dependencies

• A C++23-capable compiler:

  • GCC ≥ 12
  • Clang ≥ 15
  • MSVC ≥ 19.40 (Visual Studio 2022 17.10)

• CMake ≥ 3.20

Build from Source

# Clone the repository
git clone https://github.com/zombocoder/o2l.git
cd o2l

# Build the interpreter (Linux/macOS)
mkdir build && cd build
cmake ..
make

# Build the interpreter (Windows - MSVC)
# Open "Developer Command Prompt for VS 2022"
mkdir build && cd build
cmake -G Ninja .. -DCMAKE_BUILD_TYPE=Release
ninja

Creating a New O²L Project

O²L provides a powerful package manager tool o2l-pkg to scaffold and manage projects:

# Create project directory
mkdir my-project
cd my-project

# Initialize the O²L project
o2l-pkg init

# Run your project
o2l run src/main.obq

Project Structure

The o2l-pkg init command generates a complete project structure:

my-project/
├── .o2l/                     # Package manager directory
│   ├── lib/                  # Downloaded libraries
│   └── cache/                # Build cache
├── src/
│   ├── calc/
│   │   └── Calculator.obq    # Calculator module
│   ├── greeters/
│   │   └── BasicGreeter.obq  # Greeter module
│   ├── tests/
│   │   ├── calc/
│   │   │   └── CalculatorTest.obq
│   │   ├── greeters/
│   │   │   └── GreeterTest.obq
│   │   └── main_test.obq     # Test runner
│   └── main.obq              # Entry point
├── o2l.toml                  # Project configuration
└── .gitignore                # Git ignore rules

Package Manager Commands

# Initialize new project in current directory
o2l-pkg init

# Create new objects with namespace structure
o2l-pkg create com.mycompany.utils Utils
o2l-pkg create data.models User

# List installed libraries
o2l-pkg list

# Clean cache directory
o2l-pkg clean

# Show help
o2l-pkg help

Running Your Project

Use the standard o2l command to run your programs:

# Run main program
o2l run src/main.obq

# Run all tests
o2l run src/tests/main_test.obq

# Run specific tests
o2l run src/tests/calc/CalculatorTest.obq
o2l run src/tests/greeters/GreeterTest.obq

# Run with arguments
o2l run src/main.obq arg1 arg2

Project Configuration (o2l.toml)

The initialization process creates an interactive configuration:

[package]
name = "my-project"
version = "0.1.0"
description = "An O²L project"
authors = ["Your Name <your.email@example.com>"]

[dependencies]
# Libraries added with o2l-pkg add will appear here
# collections = "latest"
# com.example.math = "1.2.0"

Your First Program

Create hello.obq:

import system.io

Object Greeter {
    property message: Text

    constructor(greeting: Text) {
        this.message = greeting
    }

    @external method greet(name: Text): Text {
        io.print("%s, %s!", this.message, name)
        return this.message
    }
}

Object Main {
    method main(): Int {
        greeter: Greeter = new Greeter("Hello")
        greeter.greet("World")
        return 0
    }
}

Run it:

o2l run hello.obq
# Output: Hello, World!

🌏 Philosophy in Practice

Why No If Statements?

Traditional if statements lead to complex branching logic. O²L encourages object-based dispatch:

Traditional approach:

if (user.getType() == UserType.ADMIN) {
    // admin logic
} else if (user.getType() == UserType.REGULAR) {
    // regular logic
} else {
    // guest logic
}

O²L approach:

Protocol UserHandler {
    method handleRequest(): Text
}

Object AdminHandler: UserHandler {
    @external method handleRequest(): Text {
        return "Admin access granted"
    }
}

Object RegularHandler: UserHandler {
    @external method handleRequest(): Text {
        return "Regular access granted"
    }
}

Why No Null?

Null values are a major source of runtime errors. O²L eliminates them entirely:

# Instead of nullable values, use explicit optional types
# This forces developers to handle all cases explicitly

Object UserService {
    @external method findUser(id: Int): Optional<User> {
        # Return Optional.empty() if not found
        # Return Optional.of(user) if found
    }

    @external method processUser(id: Int): Text {
        userOpt: Optional<User> = this.findUser(id)
        if (userOpt.isPresent()) {
            user: User = userOpt.get()
            return "Processing: " + user.getName()
        }
        return "User not found"
    }
}

Why Immutability?

Immutable objects eliminate entire categories of bugs:

• No concurrent modification exceptions
• No unexpected state changes
• Easier to reason about program behavior
• Natural thread safety
• Cleaner APIs with predictable behavior

---

🛤️ Roadmap

Last updated: 2026-10-27.

Current Version (0.1.0)

• ✅ Full object-oriented language
• ✅ Enums, Records, Protocols
• ✅ Method visibility control
• ✅ System I/O and environment access
• ✅ Generic Collections: List<T>, Map<K,V>, and Set<T> with type safety, methods, and iterators
• ✅ Command Line Arguments: Full system.os.args() and system.os.argc() support following C/C++ conventions
• ✅ Iterator Enhancements: All iterators support index() method for current position tracking
• ✅ 128-bit Integer Support: Long type with extended precision
• ✅ Comprehensive Type System: Int, Long, Float, Double with automatic promotion
• ✅ While Loops: Practical iteration with ListIterator and RepeatIterator support
• ✅ Break Statements: Early exit from while loops for search patterns and safety limits
• ✅ Continue Statements: Skip iterations in while loops for filtering and validation patterns
• ✅ Modulo Operator: Full arithmetic completeness with % operator for all numeric types
• ✅ System Utilities: system.utils module with RepeatIterator for controlled repetition
• ✅ Error Handling System: Complete throw/try/catch/finally with Result<T,E> and Error types
• ✅ FFI System: Foreign Function Interface with libffi integration, advanced type support, and SQLite integration
• ✅ Built-in Testing: import testing assertion library, used by the tests that o2l-pkg init generates
• ✅ Comprehensive test suite with full coverage
• ✅ Debug mode and error reporting

New in 0.1.0 (2026-10-27)

• ✅ Collections (2026-04, #8): 30+ new List, Map and Set methods (sorting, slicing, bulk and set operations), recursive nested generics such as Map<Text, List<Int>>, and a MapIterator fix
• ✅ Text API (2026-04, #11): substring() with Python-style slices, charAt() with negative indexes, contains(), trimStart() and trimEnd()
• ✅ Windows Support (2026-04, #13): builds and runs with MSVC 2022 and Clang, with a Windows CI job
• ✅ Aegis Foundation (2026-04, #14): compiler (AST reflection), binary (ByteBuffer binary I/O) and bit (bit intrinsics) objects, and hex literals
• ✅ Green Threads (2026-05, #10, #15): spawn, Channel, a built-in sleep(ms) that suspends only the calling coroutine, and a background I/O thread pool
• ✅ Compound Assignment (2026-10, #18): +=, -=, *=, /= and %=
• ✅ Fixes (2026-10): INT_MIN / -1 raises an error instead of crashing (#16); isEmpty() and empty() work on every collection (#19); Map.containsKey() resolves (#20); type annotations may continue on the next line (#21); a failing main() reports its error once (#22); regression test for suspending inside a while body (#23)

Planned Features

• 📦 Module System: Package management and namespaces
• ⚡ Bytecode Compiler: Improve performance
• 🌐 WebAssembly: Run O²L in browsers
• 📊 Advanced Generic Types: Optional<T> and further parameterized types (recursive nested generics shipped in 2026-04)
• 🔄 Async/Await: async/await syntax (cooperative concurrency with spawn and Channel shipped in 2026-05)

---

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Development Setup

git clone https://github.com/zombocoder/o2l.git
cd o2l
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Debug
make

Running Tests

# Run all 532 tests (Linux/macOS)
cd build
make test

# Run all 532 tests (Windows)
cd build
ctest -C Release

# Run specific test suites
cd build/tests
./o2l_tests --gtest_filter="TextMethodTest.*"      # Text method tests
./o2l_tests --gtest_filter="MathLibraryTest.*"     # Math library tests
./o2l_tests --gtest_filter="JsonLibraryTest.*"     # JSON library tests (16 tests)
./o2l_tests --gtest_filter="HttpClientLibraryTest.*" # HTTP client tests (24 tests)
./o2l_tests --gtest_filter="RuntimeTest.*"         # Runtime and collections tests
./o2l_tests --gtest_filter="IntegrationTest.*"     # End-to-end integration tests
./o2l_tests --gtest_filter="LexerTest.*"           # Lexer and tokenization tests
./o2l_tests --gtest_filter="ParserTest.*"          # Parser and AST tests
./o2l_tests --gtest_filter="RegexpLibraryTest.*"   # Regular expression tests
./o2l_tests --gtest_filter="UrlLibraryTest.*"      # URL library tests
./o2l_tests --gtest_filter="FFISimplifiedTest.*"     # FFI basic types and operations tests
./o2l_tests --gtest_filter="FFILibraryTest.*"        # FFI library functions and integrations tests
./o2l_tests --gtest_filter="ElseIfAndLengthTest.*" # else if and Text.length() tests

# Test coverage summary:
# ✅ 532 total tests in 29 suites - All passing
# 📝 27 Lexer tests - Token parsing, keywords, operators
# 🌲 32 Parser tests - AST generation, syntax validation
# ⚡ 44 Runtime tests - Value types, collections, iterators
# 🔌 20 Protocol tests - Interface compliance and signature validation
# 🚀 38 Integration tests - End-to-end execution
# ✨ 13 Text method tests - All 54 string methods including length()
# 📏 12 Math library tests - All mathematical functions and constants
# 🔄 JSON Library - 16 comprehensive tests covering parsing, path navigation, validation, and native collection integration
# 🌐 HTTP Client - 24 extensive tests covering all HTTP methods, authentication, file operations, and error handling
# 🖥️ 29 HTTP server tests - HTTP server library
# 🔄 14 Regular expression tests - Complete regexp library functionality
# 🌐 43 URL library tests - Complete URL manipulation and validation
# 🔀 14 Control flow tests - else if syntax and Text.length() method
# 🛑 16 Loop control tests - break and continue
# 🔄 42 Type conversion tests - Comprehensive conversion methods with error handling
# 📊 33 Extended system tests - DateTime, filesystem paths, and OS integration
# 🔗 17 FFI tests - Basic types, library calls, and CArray.fromList()
# 📚 16 Collection tests - List/Map/Set extensions and nested generics
# ➕ 14 Compound assignment tests - +=, -=, *=, /= and %=
# 🧵 31 Concurrency tests - Scheduler, spawn, channels, sleep, and resume logic
# 🧪 18 Testing library tests - The `import testing` assertions
# 🧹 19 Formatter tests - o2l-fmt

Code Style

• Follow modern C++23 practices
• Use clear, descriptive names
• Include comprehensive tests for new features
• Document public APIs

---

📄 License

O²L is released under the Apache License 2.0.

---

🙏 Acknowledgments

O²L draws inspiration from:

• Smalltalk: Pure object-oriented design
• Java: Familiar syntax and structure
• Rust: Memory safety and immutability
• Haskell: Functional programming concepts
• Kotlin: Modern language design

---

☎️ Support & Community

• 🐞 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📖 Documentation: Wiki
• 📧 Contact: o2l@zombocoder.com

---

"In O²L, every value is an object, every action is a method call, and every program is a symphony of collaborating objects." 🎼