kulics / koral

The Koral Programming Language Koral is an experimental compiled language that combines **Go's aggressive escape analysis** with **Swift's Automatic Reference Counting (ARC)**. It targets C to deliver predictable, high-performance memory management without a garbage collector, while keeping the syntax clean and expression-oriented. This repository contains the compiler, standard library, formatter, language documentation, and sample projects. > Status: Koral is in an experimental stage and is not yet production-ready. The Core Idea: ARC + Escape Analysis Most compiled languages make you choose: either you get high-level ergonomics with a tracing garbage collector, or you get manual control with verbose syntax. Koral offers a middle ground: • **Escape Analysis First**: Every allocation is analyzed at compile time. If the compiler can prove that an object does not escape its current scope, it is allocated on the stack. Stack allocation is practically free and completely bypasses ARC overhead. • **ARC for the Rest**: If an object *does* escape, it is allocated on the heap and managed via Automatic Reference Counting. This provides predictable, pause-free performance. Because Koral compiles to C, stack allocations become standard C local variables. The backend compiler can heavily optimize them, often keeping them entirely in CPU registers and optimizing away reference counting operations for local data. Language Highlights • **No GC, No Manual **: Automatic memory management based on reference counting and escape analysis. • **Expression-Oriented**: , , , and blocks all produce values. • **Zero-Cost Abstractions**: Generics with trait constraints and monomorphization. • **Algebraic Data Types**: Structs and unions with exhaustive pattern matching. • **C Interop**: Foreign function interface (FFI) and a C backend for broad platform compatibility. Syntax Quick Tour Everything is an expression Pattern matching built into and Pattern combinators: , , / — Option chaining as keywords Prefix generics Traits and blocks Algebraic data types with implicit member syntax Lazy streams Language Capabilities Type System • Primitive types: , , , – , – , , , • Structs (product types): • Unions (sum types / tagged enums): • Type aliases: • Generic types and functions: , • Function types: — • Reference types: , , Control Flow • expressions (with pattern matching via ) • loops (with pattern matching via ) • loops over any • expressions for exhaustive pattern matching • for deterministic cleanup • , , , Pattern Matching • Wildcard ( ), literal, variable binding, comparison ( , ) • Struct/Pair/union destructuring (including nested) • Logical patterns: , , Traits and Generics • Trait definitions with inheritance: • Generic trait declarations use prefix generic syntax: • Implementations via blocks • Trait objects for runtime polymorphism: • Operator overloading through algebraic traits ( , , , , , etc.) Functions and Lambdas • Top-level and generic functions • Lambda expressions: • Closures with captured variables • Literals: strings use ; rune literals use (default , can infer to in explicit byte context) • Duration suffix literals: , , , , , • Pair literal: (equivalent to ) • Collection literals: • List: (defaults to when no explicit type context exists) • Set: • Map: • Empty literal requires explicit type context (e.g. ) • String interpolation: • Multiline string literals: with Swift-style indentation stripping Memory Management • Automatic reference counting with copy-on-write semantics • Escape analysis for stack vs. heap allocation decisions • Weak references ( ) for breaking reference cycles • for deterministic resource cleanup Reference creation rules (current semantics): • requires to be a mutable lvalue ( binding or reachable mutable field). • on immutable bindings or rvalues is rejected by the compiler. • Use for owned heap references from literals/temporaries (e.g. , ). Module System • Module merging ( , ) • Module imports ( , , ) • Member imports ( , ) • Alias imports ( , ) • Batch imports ( , ) • Access control: , (default), • Direct construction requires constructor field visibility at call site; non-public fields should be initialized via public factory methods • Submodule entry file must match directory name: (not ) • Module entry file basename must match • Module symbols in code use PascalCase path segments (for example, file is imported as ) • In std submodules, symbols declared as in root are default-visible; no redundant is required for those root exports • follows first-letter case matching: uppercase target -> uppercase alias, lowercase target -> lowercase alias • Type aliases must start with an uppercase letter ( ) FFI • for binding C functions • for opaque or layout-compatible C types • for linking external libraries Standard Library Overview The standard library ( ) ships with the compiler and is loaded automatically unless is specified. Commonly used pieces: • Core types: , , , , • Collections: , , • Error flow: , , , • Runtime and system modules: , , , , , , • Utility modules: , , , Minimal examples: For full module-by-module API documentation, see . Repository Layout • — Swift compiler project ( , ) • — self-hosting compiler implementation and bootstrap tests • — standard library modules and runtime C files • — language and developer documentation • — formatter implementation and tests • — example projects • — ad-hoc language playground and cases Prerequisites • Swift toolchain (for building ) • A C compiler in ( recommended) On Windows, ensure is available from terminal: Build from Source Run the Compiler Common Options • : output directory (default: input file directory) • : compile without loading • / : print escape analysis diagnostics (Go-style; or higher level currently same output) Test Run in : Documentation • Language Guide (English) • 语言文档（中文） • Grammar (BNF) • Compiler Developer Guide Standard Library Resolution ( ) If cannot find du…