{"id":42797696,"url":"https://github.com/z-libs/Zen-C","last_synced_at":"2026-02-09T16:01:03.282Z","repository":{"id":331904480,"uuid":"1132223692","full_name":"z-libs/Zen-C","owner":"z-libs","description":"Write like a high-level language, run like C.","archived":false,"fork":false,"pushed_at":"2026-02-02T23:24:55.000Z","size":1205,"stargazers_count":3674,"open_issues_count":26,"forks_count":168,"subscribers_count":40,"default_branch":"main","last_synced_at":"2026-02-03T02:52:02.191Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://www.zenc-lang.org/","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/z-libs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-11T15:08:19.000Z","updated_at":"2026-02-03T02:30:22.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/z-libs/Zen-C","commit_stats":null,"previous_names":["z-libs/zen-c"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/z-libs/Zen-C","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/z-libs%2FZen-C","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/z-libs%2FZen-C/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/z-libs%2FZen-C/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/z-libs%2FZen-C/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/z-libs","download_url":"https://codeload.github.com/z-libs/Zen-C/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/z-libs%2FZen-C/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29271848,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-09T13:47:44.167Z","status":"ssl_error","status_checked_at":"2026-02-09T13:47:43.721Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-30T02:00:22.779Z","updated_at":"2026-02-09T16:01:03.251Z","avatar_url":"https://github.com/z-libs.png","language":"C","readme":"\u003cdiv align=\"center\"\u003e\n  \u003cp\u003e\n    \u003ca href=\"README.md\"\u003eEnglish\u003c/a\u003e •\n    \u003ca href=\"translations/README_RU.md\"\u003eРусский\u003c/a\u003e •\n    \u003ca href=\"translations/README_ZH_CN.md\"\u003e简体中文\u003c/a\u003e •\n    \u003ca href=\"translations/README_ZH_TW.md\"\u003e繁體中文\u003c/a\u003e •\n    \u003ca href=\"translations/README_ES.md\"\u003eEspañol\u003c/a\u003e •\n    \u003ca href=\"translations/README_IT.md\"\u003eItaliano\u003c/a\u003e •\n    \u003ca href=\"translations/README_PT_BR.md\"\u003ePortuguês Brasileiro\u003c/a\u003e\n  \u003c/p\u003e\n\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003ch1\u003eZen C\u003c/h1\u003e\n  \u003ch3\u003eModern Ergonomics. Zero Overhead. Pure C.\u003c/h3\u003e\n  \u003cbr\u003e\n  \u003cp\u003e\n    \u003ca href=\"#\"\u003e\u003cimg src=\"https://img.shields.io/badge/build-passing-brightgreen\" alt=\"Build Status\"\u003e\u003c/a\u003e\n    \u003ca href=\"#\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-MIT-blue\" alt=\"License\"\u003e\u003c/a\u003e\n    \u003ca href=\"#\"\u003e\u003cimg src=\"https://img.shields.io/github/v/release/z-libs/Zen-C?label=version\u0026color=orange\" alt=\"Version\"\u003e\u003c/a\u003e\n    \u003ca href=\"#\"\u003e\u003cimg src=\"https://img.shields.io/badge/platform-linux-lightgrey\" alt=\"Platform\"\u003e\u003c/a\u003e\n  \u003c/p\u003e\n  \u003cp\u003e\u003cem\u003eWrite like a high-level language, run like C.\u003c/em\u003e\u003c/p\u003e\n\u003c/div\u003e\n\n\u003chr\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003cp\u003e\n    \u003cb\u003e\u003ca href=\"#overview\"\u003eOverview\u003c/a\u003e\u003c/b\u003e •\n    \u003cb\u003e\u003ca href=\"#community\"\u003eCommunity\u003c/a\u003e\u003c/b\u003e •\n    \u003cb\u003e\u003ca href=\"#quick-start\"\u003eQuick Start\u003c/a\u003e\u003c/b\u003e •\n    \u003cb\u003e\u003ca href=\"#language-reference\"\u003eLanguage Reference\u003c/a\u003e\u003c/b\u003e •\n    \u003cb\u003e\u003ca href=\"#standard-library\"\u003eStandard Library\u003c/a\u003e\u003c/b\u003e •\n    \u003cb\u003e\u003ca href=\"#tooling\"\u003eToolchain\u003c/a\u003e\u003c/b\u003e\n  \u003c/p\u003e\n\u003c/div\u003e\n\n---\n\n## Overview\n\n**Zen C** is a modern systems programming language that compiles to human-readable `GNU C`/`C11`. It provides a rich feature set including type inference, pattern matching, generics, traits, async/await, and manual memory management with RAII capabilities, all while maintaining 100% C ABI compatibility.\n\n## Community\n\nJoin the discussion, share demos, ask questions, or report bugs in the official Zen C Discord server!\n\n- Discord: [Join here](https://discord.com/invite/q6wEsCmkJP)\n\n---\n\n## Index\n\n\u003ctable align=\"center\"\u003e\n  \u003ctr\u003e\n    \u003cth width=\"50%\"\u003eGeneral\u003c/th\u003e\n    \u003cth width=\"50%\"\u003eLanguage Reference\u003c/th\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd valign=\"top\"\u003e\n      \u003cul\u003e\n        \u003cli\u003e\u003ca href=\"#overview\"\u003eOverview\u003c/a\u003e\u003c/li\u003e\n        \u003cli\u003e\u003ca href=\"#community\"\u003eCommunity\u003c/a\u003e\u003c/li\u003e\n        \u003cli\u003e\u003ca href=\"#quick-start\"\u003eQuick Start\u003c/a\u003e\u003c/li\u003e\n        \u003cli\u003e\u003ca href=\"#standard-library\"\u003eStandard Library\u003c/a\u003e\u003c/li\u003e\n        \u003cli\u003e\u003ca href=\"#tooling\"\u003eTooling\u003c/a\u003e\u003c/li\u003e\n        \u003cli\u003e\u003ca href=\"#compiler-support--compatibility\"\u003eCompiler Support \u0026 Compatibility\u003c/a\u003e\u003c/li\u003e\n        \u003cli\u003e\u003ca href=\"#contributing\"\u003eContributing\u003c/a\u003e\u003c/li\u003e\n        \u003cli\u003e\u003ca href=\"#attributions\"\u003eAttributions\u003c/a\u003e\u003c/li\u003e\n      \u003c/ul\u003e\n    \u003c/td\u003e\n    \u003ctd valign=\"top\"\u003e\n      \u003cul\u003e\n        \u003cli\u003e\u003ca href=\"#1-variables-and-constants\"\u003e1. Variables \u0026 Constants\u003c/a\u003e\u003c/li\u003e\n        \u003cli\u003e\u003ca href=\"#2-primitive-types\"\u003e2. Primitive Types\u003c/a\u003e\u003c/li\u003e\n        \u003cli\u003e\u003ca href=\"#3-aggregate-types\"\u003e3. Aggregate Types\u003c/a\u003e\u003c/li\u003e\n        \u003cli\u003e\u003ca href=\"#4-functions--lambdas\"\u003e4. Functions \u0026 Lambdas\u003c/a\u003e\u003c/li\u003e\n        \u003cli\u003e\u003ca href=\"#5-control-flow\"\u003e5. Control Flow\u003c/a\u003e\u003c/li\u003e\n        \u003cli\u003e\u003ca href=\"#6-operators\"\u003e6. Operators\u003c/a\u003e\u003c/li\u003e\n        \u003cli\u003e\u003ca href=\"#7-printing-and-string-interpolation\"\u003e7. Printing \u0026 Interpolation\u003c/a\u003e\u003c/li\u003e\n        \u003cli\u003e\u003ca href=\"#8-memory-management\"\u003e8. Memory Management\u003c/a\u003e\u003c/li\u003e\n        \u003cli\u003e\u003ca href=\"#9-object-oriented-programming\"\u003e9. Object Oriented Programming\u003c/a\u003e\u003c/li\u003e\n        \u003cli\u003e\u003ca href=\"#10-generics\"\u003e10. Generics\u003c/a\u003e\u003c/li\u003e\n        \u003cli\u003e\u003ca href=\"#11-concurrency-asyncawait\"\u003e11. Concurrency\u003c/a\u003e\u003c/li\u003e\n        \u003cli\u003e\u003ca href=\"#12-metaprogramming\"\u003e12. Metaprogramming\u003c/a\u003e\u003c/li\u003e\n        \u003cli\u003e\u003ca href=\"#13-attributes\"\u003e13. Attributes\u003c/a\u003e\u003c/li\u003e\n        \u003cli\u003e\u003ca href=\"#14-inline-assembly\"\u003e14. Inline Assembly\u003c/a\u003e\u003c/li\u003e\n        \u003cli\u003e\u003ca href=\"#15-build-directives\"\u003e15. Build Directives\u003c/a\u003e\u003c/li\u003e\n        \u003cli\u003e\u003ca href=\"#16-keywords\"\u003e16. Keywords\u003c/a\u003e\u003c/li\u003e\n        \u003cli\u003e\u003ca href=\"#17-c-interoperability\"\u003e17. C Interoperability\u003c/a\u003e\u003c/li\u003e\n      \u003c/ul\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n---\n\n## Quick Start\n\n### Installation\n\n```bash\ngit clone https://github.com/z-libs/Zen-C.git\ncd Zen-C\nmake\nsudo make install\n```\n\n### Portable Build (APE)\n\nZen C can be compiled as an **Actually Portable Executable (APE)** using [Cosmopolitan Libc](https://github.com/jart/cosmopolitan). This produces a single binary (`.com`) that runs natively on Linux, macOS, Windows, FreeBSD, OpenBSD, and NetBSD on both x86_64 and aarch64 architectures.\n\n**Prerequisites:**\n- `cosmocc` toolchain (must be in your PATH)\n\n**Build \u0026 Install:**\n```bash\nmake ape\nsudo env \"PATH=$PATH\" make install-ape\n```\n\n**Artifacts:**\n- `out/bin/zc.com`: The portable Zen-C compiler. Includes the standard library embedded within the executable.\n- `out/bin/zc-boot.com`: A self-contained bootstrap installer for setting up new Zen-C projects.\n\n**Usage:**\n```bash\n# Run on any supported OS\n./out/bin/zc.com build hello.zc -o hello\n```\n\n### Usage\n\n```bash\n# Compile and run\nzc run hello.zc\n\n# Build executable\nzc build hello.zc -o hello\n\n# Interactive Shell\nzc repl\n```\n\n### Environment Variables\n\nYou can set `ZC_ROOT` to specify the location of the Standard Library (standard imports like `import \"std/vec.zc\"`). This allows you to run `zc` from any directory.\n\n```bash\nexport ZC_ROOT=/path/to/Zen-C\n```\n\n---\n\n## Language Reference\n\n### 1. Variables and Constants\n\nZen C distinguishes between compile-time constants and runtime variables.\n\n#### Manifest Constants (`def`)\nValues that exist only at compile-time (folded into code). Use these for array sizes, fixed configuration, and magic numbers.\n\n```zc\ndef MAX_SIZE = 1024;\nlet buffer: char[MAX_SIZE]; // Valid array size\n```\n\n#### Variables (`let`)\nStorage locations in memory. Can be mutable or read-only (`const`).\n\n```zc\nlet x = 10;             // Mutable\nx = 20;                 // OK\n\nlet y: const int = 10;  // Read-only (Type qualified)\n// y = 20;              // Error: cannot assign to const\n```\n\n\u003e [!TIP]\n\u003e **Type Inference**: Zen C automatically infers types for initialized variables. It compiles to C23 `auto` on supported compilers, or GCC's `__auto_type` extension otherwise.\n\n### 2. Primitive Types\n\n| Type | C Equivalent | Description |\n|:---|:---|:---|\n| `int`, `uint` | `int32_t`, `uint32_t` | 32-bit signed/unsigned integer |\n| `c_char`, `c_uchar` | `char`, `unsigned char` | C char / unsigned char (Interop) |\n| `c_short`, `c_ushort` | `short`, `unsigned short` | C short / unsigned short (Interop) |\n| `c_int`, `c_uint` | `int`, `unsigned int` | C int / unsigned int (Interop) |\n| `c_long`, `c_ulong` | `long`, `unsigned long` | C long / unsigned long (Interop) |\n| `c_long_long`, `c_ulong_long` | `long long`, `unsigned long long` | C long long / unsigned long long (Interop) |\n| `I8` .. `I128` or `i8` .. `i128` | `int8_t` .. `__int128_t` | Signed fixed-width integers |\n| `U8` .. `U128` or `u8` .. `u128` | `uint8_t` .. `__uint128_t` | Unsigned fixed-width integers |\n| `isize`, `usize` | `ptrdiff_t`, `size_t` | Pointer-sized integers |\n| `byte` | `uint8_t` | Alias for U8 |\n| `F32`, `F64` or `f32`, `f64`  | `float`, `double` | Floating point numbers |\n| `bool` | `bool` | `true` or `false` |\n| `char` | `char` | Single character |\n| `string` | `char*` | C-string (null-terminated) |\n| `U0`, `u0`, `void` | `void` | Empty type |\n| `iN` (for example, `i256`) | `_BitInt(N)` | Arbitrary bit-width signed integer (C23) |\n| `uN` (for example, `u42`) | `unsigned _BitInt(N)` | Arbitrary bit-width unsigned integer (C23) |\n\n\u003e [!IMPORTANT]\n\u003e **Best Practices for Portable Code**\n\u003e\n\u003e - Use **Portable Types** (`int`, `uint`, `i64`, `u8`, etc.) for all pure Zen C logic. `int` is guaranteed to be 32-bit signed on all architectures.\n\u003e - Use **C Interop Types** (`c_int`, `c_char`, `c_long`, ``c_ulong``, ``c_long_long``, ``c_ulong_long``) **only** when interacting with C libraries (FFI). Their size varies by platform and C compiler (e.g. `c_long` size differs between Windows and Linux).\n\u003e - Use `isize` and `usize` for array indexing and memory pointer arithmetic.\n\n### 3. Aggregate Types\n\n#### Arrays\nFixed-size arrays with value semantics.\n```zc\ndef SIZE = 5;\nlet ints: int[SIZE] = [1, 2, 3, 4, 5];\nlet zeros: [int; SIZE]; // Zero-initialized\n```\n\n#### Tuples\nGroup multiple values together, access elements by index.\n```zc\nlet pair = (1, \"Hello\");\nlet x = pair.0;  // 1\nlet s = pair.1;  // \"Hello\"\n```\n\n**Multiple Return Values**\n\nFunctions can return tuples to provide multiple results:\n```zc\nfn add_and_subtract(a: int, b: int) -\u003e (int, int) {\n    return (a + b, a - b);\n}\n\nlet result = add_and_subtract(3, 2);\nlet sum = result.0;   // 5\nlet diff = result.1;  // 1\n```\n\n**Destructuring**\n\nTuples can be destructured directly into variables:\n```zc\nlet (sum, diff) = add_and_subtract(3, 2);\n// sum = 5, diff = 1\n```\n\nTyped tuple destructuring allows explicit type annotations:\n```zc\nlet (a: string, b: u8) = (\"hello\", 42);\nlet (x, y: i32) = (1, 2);  // Mixed: x inferred, y explicit\n```\n\n#### Structs\nData structures with optional bitfields.\n```zc\nstruct Point {\n    x: int;\n    y: int;\n}\n\n// Struct initialization\nlet p = Point { x: 10, y: 20 };\n\n// Bitfields\nstruct Flags {\n    valid: U8 : 1;\n    mode:  U8 : 3;\n}\n```\n\n\u003e [!NOTE]\n\u003e Structs use [Move Semantics](#move-semantics--copy-safety) by default. Fields can be accessed via `.` even on pointers (Auto-Dereference).\n\n#### Opaque Structs\nYou can define a struct as `opaque` to restrict access to its fields to the defining module only, while still allowing the struct to be allocated on the stack (size is known).\n\n```zc\n// In user.zc\nopaque struct User {\n    id: int;\n    name: string;\n}\n\nfn new_user(name: string) -\u003e User {\n    return User{id: 1, name: name}; // OK: Inside module\n}\n\n// In main.zc\nimport \"user.zc\";\n\nfn main() {\n    let u = new_user(\"Alice\");\n    // let id = u.id; // Error: Cannot access private field 'id'\n}\n```\n\n#### Enums\nTagged unions (Sum types) capable of holding data.\n```zc\nenum Shape {\n    Circle(float),      // Holds radius\n    Rect(float, float), // Holds width, height\n    Point               // No data\n}\n```\n\n#### Unions\nStandard C unions (unsafe access).\n```zc\nunion Data {\n    i: int;\n    f: float;\n}\n```\n\n#### Type Aliases\nCreate a new name for an existing type.\n```zc\nalias ID = int;\nalias PointMap = Map\u003cstring, Point\u003e;\n```\n\n#### Opaque Type Aliases\nYou can define a type alias as `opaque` to create a new type that is distinct from its underlying type outside of the defining module. This provides strong encapsulation and type safety without the runtime overhead of a wrapper struct.\n\n```zc\n// In library.zc\nopaque alias Handle = int;\n\nfn make_handle(v: int) -\u003e Handle {\n    return v; // Implicit conversion allowed inside module\n}\n\n// In main.zc\nimport \"library.zc\";\n\nfn main() {\n    let h: Handle = make_handle(42);\n    // let i: int = h; // Error: Type validation failed\n    // let h2: Handle = 10; // Error: Type validation failed\n}\n```\n\n### 4. Functions \u0026 Lambdas\n\n#### Functions\n```zc\nfn add(a: int, b: int) -\u003e int {\n    return a + b;\n}\n\n// Named arguments supported in calls\nadd(a: 10, b: 20);\n```\n\n\u003e **Note**: Named arguments must strictly follow the defined parameter order. `add(b: 20, a: 10)` is invalid.\n\n#### Const Arguments\nFunction arguments can be marked as `const` to enforce read-only semantics. This is a type qualifier, not a manifest constant.\n\n```zc\nfn print_val(v: const int) {\n    // v = 10; // Error: Cannot assign to const variable\n    println \"{v}\";\n}\n```\n\n#### Default Arguments\nFunctions can define default values for trailing arguments. These can be literals, expressions, or valid Zen C code (like struct constructors).\n```zc\n// Simple default value\nfn increment(val: int, amount: int = 1) -\u003e int {\n    return val + amount;\n}\n\n// Expression default value (evaluated at call site)\nfn offset(val: int, pad: int = 10 * 2) -\u003e int {\n    return val + pad;\n}\n\n// Struct default value\nstruct Config { debug: bool; }\nfn init(cfg: Config = Config { debug: true }) {\n    if cfg.debug { println \"Debug Mode\"; }\n}\n\nfn main() {\n    increment(10);      // 11\n    offset(5);          // 25\n    init();             // Prints \"Debug Mode\"\n}\n```\n\n#### Lambdas (Closures)\nAnonymous functions that can capture their environment.\n```zc\nlet factor = 2;\nlet double = x -\u003e x * factor;  // Arrow syntax\nlet full = fn(x: int) -\u003e int { return x * factor; }; // Block syntax\n```\n\n#### Raw Function Pointers\nZen C supports raw C function pointers using the `fn*` syntax. This allows seamless interop with C libraries that expect function pointers without closure overhead.\n\n```zc\n// Function taking a raw function pointer\nfn set_callback(cb: fn*(int)) {\n    cb(42);\n}\n\n// Function returning a raw function pointer\nfn get_callback() -\u003e fn*(int) {\n    return my_handler;\n}\n\n// Pointers to function pointers are supported (fn**)\nlet pptr: fn**(int) = \u0026ptr;\n```\n\n#### Variadic Functions\nFunctions can accept a variable number of arguments using `...` and the `va_list` type.\n```zc\nfn log(lvl: int, fmt: char*, ...) {\n    let ap: va_list;\n    va_start(ap, fmt);\n    vprintf(fmt, ap); // Use C stdio\n    va_end(ap);\n}\n```\n\n### 5. Control Flow\n\n#### Conditionals\n```zc\nif x \u003e 10 {\n    print(\"Large\");\n} else if x \u003e 5 {\n    print(\"Medium\");\n} else {\n    print(\"Small\");\n}\n\n// Ternary\nlet y = x \u003e 10 ? 1 : 0;\n\n// If-Expression (for complex conditions)\nlet category = if (x \u003e 100) { \"huge\" } else if (x \u003e 10) { \"large\" } else { \"small\" };\n```\n\n#### Pattern Matching\nPowerful alternative to `switch`.\n```zc\nmatch val {\n    1         =\u003e { print \"One\" },\n    2 || 3    =\u003e { print \"Two or Three\" },    // OR with ||\n    4 or 5    =\u003e { print \"Four or Five\" },    // OR with 'or'\n    6, 7, 8   =\u003e { print \"Six to Eight\" },    // OR with comma\n    10 .. 15  =\u003e { print \"10 to 14\" },        // Exclusive range (Legacy)\n    10 ..\u003c 15 =\u003e { print \"10 to 14\" },        // Exclusive range (Explicit)\n    20 ..= 25 =\u003e { print \"20 to 25\" },        // Inclusive range\n    _         =\u003e { print \"Other\" },\n}\n\n// Destructuring Enums\nmatch shape {\n    Shape::Circle(r)   =\u003e { println \"Radius: {r}\" },\n    Shape::Rect(w, h)  =\u003e { println \"Area: {w*h}\" },\n    Shape::Point       =\u003e { println \"Point\" },\n}\n```\n\n#### Reference Binding\nTo inspect a value without taking ownership (moving it), use the `ref` keyword in the pattern. This is essential for types that implement Move Semantics (like `Option`, `Result`, non-Copy structs).\n\n```zc\nlet opt = Some(NonCopyVal{...});\nmatch opt {\n    Some(ref x) =\u003e {\n        // 'x' is a pointer to the value inside 'opt'\n        // 'opt' is NOT moved/consumed here\n        println \"{x.field}\"; \n    },\n    None =\u003e {}\n}\n```\n\n#### Loops\n```zc\n// Range\nfor i in 0..10 { ... }      // Exclusive (0 to 9)\nfor i in 0..\u003c10 { ... }     // Exclusive (Explicit)\nfor i in 0..=10 { ... }     // Inclusive (0 to 10)\nfor i in 0..10 step 2 { ... }\n\n// Iterator (Vec or custom Iterable)\nfor item in vec { ... }\n\n// Iterate over fixed-size arrays directly\nlet arr: int[5] = [1, 2, 3, 4, 5];\nfor val in arr {\n    // val is int\n    println \"{val}\";\n}\n\n// While\nwhile x \u003c 10 { ... }\n\n// Infinite with label\nouter: loop {\n    if done { break outer; }\n}\n\n// Repeat N times\nfor _ in 0..5 { ... }\n```\n\n#### Advanced Control\n```zc\n// Guard: Execute else and return if condition is false\nguard ptr != NULL else { return; }\n\n// Unless: If not true\nunless is_valid { return; }\n```\n\n### 6. Operators\n\nZen C supports operator overloading for user-defined structs by implementing specific method names.\n\n#### Overloadable Operators\n\n| Category | Operator | Method Name |\n|:---|:---|:---|\n| **Arithmetic** | `+`, `-`, `*`, `/`, `%` | `add`, `sub`, `mul`, `div`, `rem` |\n| **Comparison** | `==`, `!=` | `eq`, `neq` |\n| | `\u003c`, `\u003e`, `\u003c=`, `\u003e=` | `lt`, `gt`, `le`, `ge` |\n| **Bitwise** | `\u0026`, `\\|`, `^` | `bitand`, `bitor`, `bitxor` |\n| | `\u003c\u003c`, `\u003e\u003e` | `shl`, `shr` |\n| **Unary** | `-` | `neg` |\n| | `!` | `not` |\n| | `~` | `bitnot` |\n| **Index** | `a[i]` | `get(a, i)` |\n| | `a[i] = v` | `set(a, i, v)` |\n\n\u003e **Note on String Equality**:\n\u003e - `string == string` performs **value comparison** (equivalent to `strcmp`).\n\u003e - `char* == char*` performs **pointer comparison** (checks memory addresses).\n\u003e - Mixed comparisons (e.g. `string == char*`) default to **pointer comparison**.\n\n**Example:**\n```zc\nimpl Point {\n    fn add(self, other: Point) -\u003e Point {\n        return Point{x: self.x + other.x, y: self.y + other.y};\n    }\n}\n\nlet p3 = p1 + p2; // Calls p1.add(p2)\n```\n\n#### Syntactic Sugar\n\nThese operators are built-in language features and cannot be overloaded directly.\n\n| Operator | Name | Description |\n|:---|:---|:---|\n| `\\|\u003e` | Pipeline | `x \\|\u003e f(y)` desugars to `f(x, y)` |\n| `??` | Null Coalescing | `val ?? default` returns `default` if `val` is NULL (pointers) |\n| `??=` | Null Assignment | `val ??= init` assigns if `val` is NULL |\n| `?.` | Safe Navigation | `ptr?.field` accesses field only if `ptr` is not NULL |\n| `?` | Try Operator | `res?` returns error if present (Result/Option types) |\n\n**Auto-Dereference**:\nPointer field access (`ptr.field`) and method calls (`ptr.method()`) automatically dereference the pointer, equivalent to `(*ptr).field`.\n\n### 7. Printing and String Interpolation\n\nZen C provides versatile options for printing to the console, including keywords and concise shorthands.\n\n#### Keywords\n\n| Keyword | Description |\n|:---|:---|\n| `print \"...\"` | Prints to `stdout` without a trailing newline. |\n| `println \"...\"` | Prints to `stdout` **with** a trailing newline. |\n| `eprint \"...\"` | Prints to `stderr` without a trailing newline. |\n| `eprintln \"...\"` | Prints to `stderr` **with** a trailing newline. |\n\n#### Shorthands\n\nZen C allows you to use string literals directly as statements for quick printing:\n\n| Syntax | Equivalent | Description |\n|:---|:---|:---|\n| `\"Hz\"` | `println \"Hz\"` | Prints to `stdout` with newline. |\n| `\"Hz\"..` | `print \"Hz\"` | Prints to `stdout` without newline. |\n| `!\"Err\"` | `eprintln \"Err\"` | Prints to `stderr` with newline. |\n| `!\"Err\"..` | `eprint \"Err\"` | Prints to `stderr` without newline. |\n\n#### String Interpolation (F-strings)\n\nYou can embed expressions directly into string literals using `{}` syntax. This works with all printing methods and string shorthands.\n\n```zc\nlet x = 42;\nlet name = \"Zen\";\nprintln \"Value: {x}, Name: {name}\";\n\"Value: {x}, Name: {name}\"; // shorthand println\n```\n\n**Escaping Braces**: Use `{{` to produce a literal `{` and `}}` for a literal `}`:\n\n```zc\nlet json = \"JSON: {{\\\"key\\\": \\\"value\\\"}}\";\n// Output: JSON: {\"key\": \"value\"}\n```\n\n#### Input Prompts (`?`)\n\nZen C supports a shorthand for prompting user input using the `?` prefix.\n\n- `? \"Prompt text\"`: Prints the prompt (without newline) and waits for input (reads a line).\n- `? \"Enter age: \" (age)`: Prints prompt and scans input into the variable `age`.\n    - Format specifiers are automatically inferred based on variable type.\n\n```zc\nlet age: int;\n? \"How old are you? \" (age);\nprintln \"You are {age} years old.\";\n```\n\n### 8. Memory Management\n\nZen C allows manual memory management with ergonomic aids.\n\n#### Defer\nExecute code when the current scope exits. Defer statements are executed in LIFO (last-in, first-out) order.\n```zc\nlet f = fopen(\"file.txt\", \"r\");\ndefer fclose(f);\n```\n\n\u003e [!WARNING]\n\u003e To prevent undefined behavior, control flow statements (`return`, `break`, `continue`, `goto`) are **not allowed** inside a `defer` block.\n\n#### Autofree\nAutomatically free the variable when scope exits.\n```zc\nautofree let types = malloc(1024);\n```\n\n#### Resource Semantics (Move by Default)\nZen C treats types with destructors (like `File`, `Vec`, or malloc'd pointers) as **Resources**. To prevent double-free errors, resources cannot be implicitly duplicated.\n\n- **Move by Default**: Assigning a resource variable transfers ownership. The original variable becomes invalid (Moved).\n- **Copy Types**: Types without destructors may opt-in to `Copy` behavior, making assignment a duplication.\n\n**Diagnostics \u0026 Philosophy**:\nIf you see an error \"Use of moved value\", the compiler is telling you: *\"This type owns a resource (like memory or a handle) and blindly copying it is unsafe.\"*\n\n\u003e [!NOTE]\n\u003e **Contrast:** Unlike C/C++, Zen C does not implicitly duplicate resource-owning values.\n\n**Function Arguments**:\nPassing a value to a function follows the same rules as assignment: resources are moved unless passed by reference.\n\n```zc\nfn process(r: Resource) { ... } // 'r' is moved into function\nfn peek(r: Resource*) { ... }   // 'r' is borrowed (reference)\n```\n\n**Explicit Cloning**:\nIf you *do* want two copies of a resource, make it explicit:\n\n```zc\nlet b = a.clone(); // Calls the 'clone' method from the Clone trait\n```\n\n**Opt-in Copy (Value Types)**:\nFor small types without destructors:\n\n```zc\nstruct Point { x: int; y: int; }\nimpl Copy for Point {} // Opt-in to implicit duplication\n\nfn main() {\n    let p1 = Point { x: 1, y: 2 };\n    let p2 = p1; // Copied. p1 stays valid.\n}\n```\n\n#### RAII / Drop Trait\nImplement `Drop` to run cleanup logic automatically.\n```zc\nimpl Drop for MyStruct {\n    fn drop(self) {\n        self.free();\n    }\n}\n```\n\n### 9. Object Oriented Programming\n\n#### Methods\nDefine methods on types using `impl`.\n```zc\nimpl Point {\n    // Static method (constructor convention)\n    fn new(x: int, y: int) -\u003e Self {\n        return Point{x: x, y: y};\n    }\n\n    // Instance method\n    fn dist(self) -\u003e float {\n        return sqrt(self.x * self.x + self.y * self.y);\n    }\n}\n```\n\n**Self Shorthand**: In methods with a `self` parameter, you can use `.field` as shorthand for `self.field`:\n```zc\nimpl Point {\n    fn dist(self) -\u003e float {\n        return sqrt(.x * .x + .y * .y);  // Equivalent to self.x, self.y\n    }\n}\n```\n\n#### Primitive Methods\nZen C allows you to define methods on primitive types (like `int`, `bool`, etc.) using the same `impl` syntax.\n\n```zc\nimpl int {\n    fn abs(self) -\u003e int {\n        return *self \u003c 0 ? -(*self) : *self;\n    }\n}\n\nlet x = -10;\nlet y = x.abs(); // 10\nlet z = (-5).abs(); // 5 (Literals supported)\n```\n\n#### Traits\nDefine shared behavior.\n```zc\nstruct Circle { radius: f32; }\n\ntrait Drawable {\n    fn draw(self);\n}\n\nimpl Drawable for Circle {\n    fn draw(self) { ... }\n}\n\nlet circle = Circle{};\nlet drawable: Drawable = \u0026circle;\n```\n\n#### Standard Traits\nZen C includes standard traits that integrate with language syntax.\n\n**Iterable**\n\nImplement `Iterable\u003cT\u003e` to enable `for-in` loops for your custom types.\n\n```zc\nimport \"std/iter.zc\"\n\n// Define an Iterator\nstruct MyIter {\n    curr: int;\n    stop: int;\n}\n\nimpl MyIter {\n    fn next(self) -\u003e Option\u003cint\u003e {\n        if self.curr \u003c self.stop {\n            self.curr += 1;\n            return Option\u003cint\u003e::Some(self.curr - 1);\n        }\n        return Option\u003cint\u003e::None();\n    }\n}\n\n// Implement Iterable\nimpl MyRange {\n    fn iterator(self) -\u003e MyIter {\n        return MyIter{curr: self.start, stop: self.end};\n    }\n}\n\n// Use in Loop\nfor i in my_range {\n    println \"{i}\";\n}\n```\n\n**Drop**\n\nImplement `Drop` to define a destructor that runs when the object goes out of scope (RAII).\n\n```zc\nimport \"std/mem.zc\"\n\nstruct Resource {\n    ptr: void*;\n}\n\nimpl Drop for Resource {\n    fn drop(self) {\n        if self.ptr != NULL {\n            free(self.ptr);\n        }\n    }\n}\n```\n\n\u003e [!IMPORTANT]\n\u003e **Note:** If a variable is moved, `drop` is NOT called on the original variable. It adheres to [Resource Semantics](#resource-semantics-move-by-default).\n\n**Copy**\n\nMarker trait to opt-in to `Copy` behavior (implicit duplication) instead of Move semantics. Used via `@derive(Copy)`.\n\n\u003e [!CAUTION]\n\u003e **Rule:** Types that implement `Copy` must not define a destructor (`Drop`).\n\n```zc\n@derive(Copy)\nstruct Point { x: int; y: int; }\n\nfn main() {\n    let p1 = Point{x: 1, y: 2};\n    let p2 = p1; // Copied! p1 remains valid.\n}\n```\n\n**Clone**\n\nImplement `Clone` to allow explicit duplication of resource-owning types.\n\n```zc\nimport \"std/mem.zc\"\n\nstruct MyBox { val: int; }\n\nimpl Clone for MyBox {\n    fn clone(self) -\u003e MyBox {\n        return MyBox{val: self.val};\n    }\n}\n\nfn main() {\n    let b1 = MyBox{val: 42};\n    let b2 = b1.clone(); // Explicit copy\n}\n```\n\n#### Composition\nUse `use` to embed other structs. You can either mix them in (flatten fields) or name them (nest fields).\n\n```zc\nstruct Entity { id: int; }\n\nstruct Player {\n    // Mixin (Unnamed): Flattens fields\n    use Entity;  // Adds 'id' to Player directly\n    name: string;\n}\n\nstruct Match {\n    // Composition (Named): Nests fields\n    use p1: Player; // Accessed via match.p1\n    use p2: Player; // Accessed via match.p2\n}\n```\n\n### 10. Generics\n\nType-safe templates for Structs and Functions.\n\n```zc\n// Generic Struct\nstruct Box\u003cT\u003e {\n    item: T;\n}\n\n// Generic Function\nfn identity\u003cT\u003e(val: T) -\u003e T {\n    return val;\n}\n\n// Multi-parameter Generics\nstruct Pair\u003cK, V\u003e {\n    key: K;\n    value: V;\n}\n```\n\n### 11. Concurrency (Async/Await)\n\nBuilt on pthreads.\n\n```zc\nasync fn fetch_data() -\u003e string {\n    // Runs in background\n    return \"Data\";\n}\n\nfn main() {\n    let future = fetch_data();\n    let result = await future;\n}\n```\n\n### 12. Metaprogramming\n\n#### Comptime\nRun code at compile-time to generate source or print messages.\n```zc\ncomptime {\n    // Generate code at compile-time (written to stdout)\n    println \"let build_date = \\\"2024-01-01\\\";\";\n}\n\nprintln \"Build Date: {build_date}\";\n```\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e🔧 Helper Functions\u003c/b\u003e\u003c/summary\u003e\n\nSpecial functions available inside `comptime` blocks for code generation and diagnostics:\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003cth\u003eFunction\u003c/th\u003e\n\u003cth\u003eDescription\u003c/th\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e\u003ccode\u003eyield(str)\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003eExplicitly emit generated code (alternative to \u003ccode\u003eprintf\u003c/code\u003e)\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e\u003ccode\u003ecode(str)\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003eAlias for \u003ccode\u003eyield()\u003c/code\u003e - clearer intent for code generation\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e\u003ccode\u003ecompile_error(msg)\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e❌ Halt compilation with a fatal error message\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e\u003ccode\u003ecompile_warn(msg)\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003e⚠️ Emit a compile-time warning (allows compilation to continue)\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n**Example:**\n```zc\ncomptime {\n    compile_warn(\"Generating optimized code...\");\n    \n    let ENABLE_FEATURE = 1;\n    if (ENABLE_FEATURE == 0) {\n        compile_error(\"Feature must be enabled!\");\n    }\n    \n    // Use code() with raw strings for clean generation\n    code(r\"let FEATURE_ENABLED = 1;\");\n}\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eBuild Metadata\u003c/b\u003e\u003c/summary\u003e\n\nAccess compiler build information at compile-time:\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003cth\u003eConstant\u003c/th\u003e\n\u003cth\u003eType\u003c/th\u003e\n\u003cth\u003eDescription\u003c/th\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e\u003ccode\u003e__COMPTIME_TARGET__\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003estring\u003c/td\u003e\n\u003ctd\u003ePlatform: \u003ccode\u003e\"linux\"\u003c/code\u003e, \u003ccode\u003e\"windows\"\u003c/code\u003e, or \u003ccode\u003e\"macos\"\u003c/code\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e\u003ccode\u003e__COMPTIME_FILE__\u003c/code\u003e\u003c/td\u003e\n\u003ctd\u003estring\u003c/td\u003e\n\u003ctd\u003eCurrent source filename being compiled\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n**Example:**\n```zc\ncomptime {\n    // Platform-specific code generation\n    println \"let PLATFORM = \\\"{__COMPTIME_TARGET__}\\\";\";\n}\n\nprintln \"Running on: {PLATFORM}\";\n```\n\u003c/details\u003e\n\n\u003e **💡 Tip:** Use raw strings (`r\"...\"`) in comptime to avoid escaping braces: `code(r\"fn test() { return 42; }\")`. Otherwise, use `{{` and `}}` to escape braces inside regular strings.\n\n\n#### Embed\nEmbed files as specified types.\n```zc\n// Default (Slice_char)\nlet data = embed \"assets/logo.png\";\n\n// Typed Embed\nlet text = embed \"shader.glsl\" as string;    // Embbed as C-string\nlet rom  = embed \"bios.bin\" as u8[1024];     // Embed as fixed array\nlet wav  = embed \"sound.wav\" as u8[];        // Embed as Slice_u8\n```\n\n#### Plugins\nImport compiler plugins to extend syntax.\n```zc\nimport plugin \"regex\"\nlet re = regex! { ^[a-z]+$ };\n```\n\n#### Generic C Macros\nPass preprocessor macros through to C.\n\n\u003e **Tip**: For simple constants, use `def` instead. Use `#define` when you need C-preprocessor macros or conditional compilation flags.\n\n```zc\n#define MAX_BUFFER 1024\n```\n\n### 13. Attributes\n\nDecorate functions and structs to modify compiler behavior.\n\n| Attribute | Scope | Description |\n|:---|:---|:---|\n| `@must_use` | Fn | Warn if return value is ignored. |\n| `@deprecated(\"msg\")` | Fn/Struct | Warn on usage with message. |\n| `@inline` | Fn | Hint compiler to inline. |\n| `@noinline` | Fn | Prevent inlining. |\n| `@packed` | Struct | Remove padding between fields. |\n| `@align(N)` | Struct | Force alignment to N bytes. |\n| `@constructor` | Fn | Run before main. |\n| `@destructor` | Fn | Run after main exits. |\n| `@unused` | Fn/Var | Suppress unused variable warnings. |\n| `@weak` | Fn | Weak symbol linkage. |\n| `@section(\"name\")` | Fn | Place code in specific section. |\n| `@noreturn` | Fn | Function does not return (e.g. exit). |\n| `@pure` | Fn | Function has no side effects (optimization hint). |\n| `@cold` | Fn | Function is unlikely to be executed (branch prediction hint). |\n| `@hot` | Fn | Function is frequently executed (optimization hint). |\n| `@export` | Fn/Struct | Export symbol (visibility default). |\n| `@global` | Fn | CUDA: Kernel entry point (`__global__`). |\n| `@device` | Fn | CUDA: Device function (`__device__`). |\n| `@host` | Fn | CUDA: Host function (`__host__`). |\n| `@comptime` | Fn | Helper function available for compile-time execution. |\n| `@derive(...)` | Struct | Auto-implement traits. Supports `Debug`, `Eq` (Smart Derive), `Copy`, `Clone`. |\n| `@ctype(\"type\")` | Fn Param | Overrides generated C type for a parameter. |\n| `@\u003ccustom\u003e` | Any | Passes generic attributes to C (e.g. `@flatten`, `@alias(\"name\")`). |\n\n#### Custom Attributes\n\nZen C supports a powerful **Custom Attribute** system that allows you to use any GCC/Clang `__attribute__` directly in your code. Any attribute that is not explicitly recognized by the Zen C compiler is treated as a generic attribute and passed through to the generated C code.\n\nThis provides access to advanced compiler features, optimizations, and linker directives without needing explicit support in the language core.\n\n#### Syntax Mapping\nZen C attributes are mapped directly to C attributes:\n- `@name` → `__attribute__((name))`\n- `@name(args)` → `__attribute__((name(args)))`\n- `@name(\"string\")` → `__attribute__((name(\"string\")))`\n\n#### Smart Derives\n\nZen C provides \"Smart Derives\" that respect Move Semantics:\n\n- **`@derive(Eq)`**: Generates an equality method that takes arguments by reference (`fn eq(self, other: T*)`).\n    - When comparing two non-Copy structs (`a == b`), the compiler automatically passes `b` by reference (`\u0026b`) to avoid moving it.\n    - Recursive equality checks on fields also prefer pointer access to prevent ownership transfer.\n\n### 14. Inline Assembly\n\nZen C provides first-class support for inline assembly, transpiling directly to GCC-style extended `asm`.\n\n#### Basic Usage\nWrite raw assembly within `asm` blocks. Strings are concatenated automatically.\n```zc\nasm {\n    \"nop\"\n    \"mfence\"\n}\n```\n\n#### Volatile\nPrevent the compiler from optimizing away assembly that has side effects.\n```zc\nasm volatile {\n    \"rdtsc\"\n}\n```\n\n#### Named Constraints\nZen C simplifies the complex GCC constraint syntax with named bindings.\n\n```zc\n// Syntax: : out(variable) : in(variable) : clobber(reg)\n// Uses {variable} placeholder syntax for readability\n\nfn add_five(x: int) -\u003e int {\n    let result: int;\n    asm {\n        \"mov {x}, {result}\"\n        \"add $5, {result}\"\n        : out(result)\n        : in(x)\n        : clobber(\"cc\")\n    }\n    return result;\n}\n```\n\n| Type | Syntax | GCC Equivalent |\n|:---|:---|:---|\n| **Output** | `: out(variable)` | `\"=r\"(variable)` |\n| **Input** | `: in(variable)` | `\"r\"(variable)` |\n| **Clobber** | `: clobber(\"rax\")` | `\"rax\"` |\n| **Memory** | `: clobber(\"memory\")` | `\"memory\"` |\n\n\u003e **Note:** When using Intel syntax (via `-masm=intel`), you must ensure your build is configured correctly (for example, `//\u003e cflags: -masm=intel`). TCC does not support Intel syntax assembly.\n\n### 15. Build Directives\n\nZen C supports special comments at the top of your source file to configure the build process without needing a complex build system or Makefile.\n\n| Directive | Arguments | Description |\n|:---|:---|:---|\n| `//\u003e link:` | `-lfoo` or `path/to/lib.a` | Link against a library or object file. |\n| `//\u003e lib:` | `path/to/libs` | Add a library search path (`-L`). |\n| `//\u003e include:` | `path/to/headers` | Add an include search path (`-I`). |\n| `//\u003e framework:` | `Cocoa` | Link against a macOS framework. |\n| `//\u003e cflags:` | `-Wall -O3` | Pass arbitrary flags to the C compiler. |\n| `//\u003e define:` | `MACRO` or `KEY=VAL` | Define a preprocessor macro (`-D`). |\n| `//\u003e pkg-config:` | `gtk+-3.0` | Run `pkg-config` and append `--cflags` and `--libs`. |\n| `//\u003e shell:` | `command` | Execute a shell command during the build. |\n| `//\u003e get:` | `http://url/file` | Download a file if specific file does not exist. |\n\n#### Features\n\n**1. OS Guarding**\nPrefix directives with an OS name to apply them only on specific platforms.\nSupported prefixes: `linux:`, `windows:`, `macos:` (or `darwin:`).\n\n```zc\n//\u003e linux: link: -lm\n//\u003e windows: link: -lws2_32\n//\u003e macos: framework: Cocoa\n```\n\n**2. Environment Variable Expansion**\nUse `${VAR}` syntax to expand environment variables in your directives.\n\n```zc\n//\u003e include: ${HOME}/mylib/include\n//\u003e lib: ${ZC_ROOT}/std\n```\n\n#### Examples\n\n```zc\n//\u003e include: ./include\n//\u003e lib: ./libs\n//\u003e link: -lraylib -lm\n//\u003e cflags: -Ofast\n//\u003e pkg-config: gtk+-3.0\n\nimport \"raylib.h\"\n\nfn main() { ... }\n```\n\n### 16. Keywords\n\nThe following keywords are reserved in Zen C.\n\n#### Declarations\n`alias`, `def`, `enum`, `fn`, `impl`, `import`, `let`, `module`, `opaque`, `struct`, `trait`, `union`, `use`\n\n#### Control Flow\n`async`, `await`, `break`, `catch`, `continue`, `defer`, `else`, `for`, `goto`, `guard`, `if`, `loop`, `match`, `return`, `try`, `unless`, `while`\n\n#### Special\n`asm`, `assert`, `autofree`, `comptime`, `const`, `embed`, `launch`, `ref`, `sizeof`, `static`, `test`, `volatile`\n\n#### Constants\n`true`, `false`, `null`\n\n#### C Reserved\nThe following identifiers are reserved because they are keywords in C11:\n`auto`, `case`, `char`, `default`, `do`, `double`, `extern`, `float`, `inline`, `int`, `long`, `register`, `restrict`, `short`, `signed`, `switch`, `typedef`, `unsigned`, `void`, `_Atomic`, `_Bool`, `_Complex`, `_Generic`, `_Imaginary`, `_Noreturn`, `_Static_assert`, `_Thread_local`\n\n#### Operators\n`and`, `or`\n\n### 17. C Interoperability\n\nZen C offers two ways to interact with C code: **Trusted Imports** (Convenient) and **Explicit FFI** (Safe/Precise).\n\n#### Method 1: Trusted Imports (Convenient)\n\nYou can import a C header directly using the `import` keyword with the `.h` extension. This treats the header as a module and assumes all symbols accessed through it exist.\n\n```zc\n//\u003e link: -lm\nimport \"math.h\" as c_math;\n\nfn main() {\n    // Compiler trusts correctness; emits 'cos(...)' directly\n    let x = c_math::cos(3.14159);\n}\n```\n\n\u003e **Pros**: Zero boilerplate. Access everything in the header immediately.\n\u003e **Cons**: No type safety from Zen C (errors caught by C compiler later).\n\n#### Method 2: Explicit FFI (Safe)\n\nFor strict type checking or when you don't want to include the text of a header, use `extern fn`.\n\n```zc\ninclude \u003cstdio.h\u003e // Emits #include \u003cstdio.h\u003e in generated C\n\n// Define strict signature\nextern fn printf(fmt: char*, ...) -\u003e c_int;\n\nfn main() {\n    printf(\"Hello FFI: %d\\n\", 42); // Type checked by Zen C\n}\n```\n\n\u003e **Pros**: Zen C ensures types match.\n\u003e **Cons**: Requires manual declaration of functions.\n\n#### `import` vs `include`\n\n- **`import \"file.h\"`**: Registers the header as a named module. Enables implicit access to symbols (for example, `file::function()`).\n- **`include \u003cfile.h\u003e`**: Purely emits `#include \u003cfile.h\u003e` in the generated C code. Does not introduce any symbols to the Zen C compiler; you must use `extern fn` to access them.\n\n\n---\n\n## Standard Library\n\nZen C includes a standard library (`std`) covering essential functionality.\n\n[Browse the Standard Library Documentation](docs/std/README.md)\n\n### Key Modules\n\n\u003cdetails\u003e\n\u003csummary\u003eClick to see all Standard Library modules\u003c/summary\u003e\n\n| Module | Description | Docs |\n| :--- | :--- | :--- |\n| **`std/vec.zc`** | Growable dynamic array `Vec\u003cT\u003e`. | [Docs](docs/std/vec.md) |\n| **`std/string.zc`** | Heap-allocated `String` type with UTF-8 support. | [Docs](docs/std/string.md) |\n| **`std/queue.zc`** | FIFO queue (Ring Buffer). | [Docs](docs/std/queue.md) |\n| **`std/map.zc`** | Generic Hash Map `Map\u003cV\u003e`. | [Docs](docs/std/map.md) |\n| **`std/fs.zc`** | File system operations. | [Docs](docs/std/fs.md) |\n| **`std/io.zc`** | Standard Input/Output (`print`/`println`). | [Docs](docs/std/io.md) |\n| **`std/option.zc`** | Optional values (`Some`/`None`). | [Docs](docs/std/option.md) |\n| **`std/result.zc`** | Error handling (`Ok`/`Err`). | [Docs](docs/std/result.md) |\n| **`std/path.zc`** | Cross-platform path manipulation. | [Docs](docs/std/path.md) |\n| **`std/env.zc`** | Process environment variables. | [Docs](docs/std/env.md) |\n| **`std/net/`** | TCP, UDP, HTTP, DNS, URL. | [Docs](docs/std/net.md) |\n| **`std/thread.zc`** | Threads and Synchronization. | [Docs](docs/std/thread.md) |\n| **`std/time.zc`** | Time measurement and sleep. | [Docs](docs/std/time.md) |\n| **`std/json.zc`** | JSON parsing and serialization. | [Docs](docs/std/json.md) |\n| **`std/stack.zc`** | LIFO Stack `Stack\u003cT\u003e`. | [Docs](docs/std/stack.md) |\n| **`std/set.zc`** | Generic Hash Set `Set\u003cT\u003e`. | [Docs](docs/std/set.md) |\n| **`std/process.zc`** | Process execution and management. | [Docs](docs/std/process.md) |\n\n\u003c/details\u003e\n\n---\n\n## Tooling\n\nZen C provides a built-in Language Server and REPL to enhance the development experience.\n\n### Language Server (LSP)\n\nThe Zen C Language Server (LSP) supports standard LSP features for editor integration, providing:\n\n*   **Go to Definition**\n*   **Find References**\n*   **Hover Information**\n*   **Completion** (Function/Struct names, Dot-completion for methods/fields)\n*   **Document Symbols** (Outline)\n*   **Signature Help**\n*   **Diagnostics** (Syntax/Semantic errors)\n\nTo start the language server (typically configured in your editor's LSP settings):\n\n```bash\nzc lsp\n```\n\nIt communicates via standard I/O (JSON-RPC 2.0).\n\n### REPL\n\nThe Read-Eval-Print Loop allows you to experiment with Zen C code interactively.\n\n```bash\nzc repl\n```\n\n#### Features\n\n*   **Interactive Coding**: Type expressions or statements for immediate evaluation.\n*   **Persistent History**: Commands are saved to `~/.zprep_history`.\n*   **Startup Script**: Auto-loads commands from `~/.zprep_init.zc`.\n\n#### Commands\n\n| Command | Description |\n|:---|:---|\n| `:help` | Show available commands. |\n| `:reset` | Clear current session history (variables/functions). |\n| `:vars` | Show active variables. |\n| `:funcs` | Show user-defined functions. |\n| `:structs` | Show user-defined structs. |\n| `:imports` | Show active imports. |\n| `:history` | Show session input history. |\n| `:type \u003cexpr\u003e` | Show the type of an expression. |\n| `:c \u003cstmt\u003e` | Show the generated C code for a statement. |\n| `:time \u003cexpr\u003e` | Benchmark an expression (runs 1000 iterations). |\n| `:edit [n]` | Edit command `n` (default: last) in `$EDITOR`. |\n| `:save \u003cfile\u003e` | Save the current session to a `.zc` file. |\n| `:load \u003cfile\u003e` | Load and execute a `.zc` file into the session. |\n| `:watch \u003cexpr\u003e` | Watch an expression (re-evaluated after every entry). |\n| `:unwatch \u003cn\u003e` | Remove a watch. |\n| `:undo` | Remove the last command from the session. |\n| `:delete \u003cn\u003e` | Remove command at index `n`. |\n| `:clear` | Clear the screen. |\n| `:quit` | Exit the REPL. |\n| `! \u003ccmd\u003e` | Run a shell command (e.g. `!ls`). |\n\n---\n\n\n## Compiler Support \u0026 Compatibility\n\nZen C is designed to work with most C11 compilers. Some features rely on GNU C extensions, but these often work in other compilers. Use the `--cc` flag to switch backends.\n\n```bash\nzc run app.zc --cc clang\nzc run app.zc --cc zig\n```\n\n### Test Suite Status\n\n\u003cdetails\u003e\n\u003csummary\u003eClick to view Compiler Support details\u003c/summary\u003e\n\n| Compiler | Pass Rate | Supported Features | Known Limitations |\n|:---|:---:|:---|:---|\n| **GCC** | **100% (Full)** | All Features | None. |\n| **Clang** | **100% (Full)** | All Features | None. |\n| **Zig** | **100% (Full)** | All Features | None. Uses `zig cc` as a drop-in C compiler. |\n| **TCC** | **~70% (Basic)** | Basic Syntax, Generics, Traits | No `__auto_type`, No Intel ASM, No Nested Functions. |\n\n\u003c/details\u003e\n\n\u003e [!TIP]\n\u003e **Recommendation:** Use **GCC**, **Clang**, or **Zig** for production builds. TCC is excellent for rapid prototyping due to its compilation speed but misses some advanced C extensions Zen C relies on for full feature support.\n\n### Building with Zig\n\nZig's `zig cc` command provides a drop-in replacement for GCC/Clang with excellent cross-compilation support. To use Zig:\n\n```bash\n# Compile and run a Zen C program with Zig\nzc run app.zc --cc zig\n\n# Build the Zen C compiler itself with Zig\nmake zig\n```\n\n### C++ Interop\n\nZen C can generate C++-compatible code with the `--cpp` flag, allowing seamless integration with C++ libraries.\n\n```bash\n# Direct compilation with g++\nzc app.zc --cpp\n\n# Or transpile for manual build\nzc transpile app.zc --cpp\ng++ out.c my_cpp_lib.o -o app\n```\n\n#### Using C++ in Zen C\n\nInclude C++ headers and use raw blocks for C++ code:\n\n```zc\ninclude \u003cvector\u003e\ninclude \u003ciostream\u003e\n\nraw {\n    std::vector\u003cint\u003e make_vec(int a, int b) {\n        return {a, b};\n    }\n}\n\nfn main() {\n    let v = make_vec(1, 2);\n    raw { std::cout \u003c\u003c \"Size: \" \u003c\u003c v.size() \u003c\u003c std::endl; }\n}\n```\n\n\u003e [!NOTE]\n\u003e The `--cpp` flag switches the backend to `g++` and emits C++-compatible code (uses `auto` instead of `__auto_type`, function overloads instead of `_Generic`, and explicit casts for `void*`).\n\n#### CUDA Interop\n\nZen C supports GPU programming by transpiling to **CUDA C++**. This allows you to leverage powerful C++ features (templates, constexpr) within your kernels while maintaining Zen C's ergonomic syntax.\n\n```bash\n# Direct compilation with nvcc\nzc run app.zc --cuda\n\n# Or transpile for manual build\nzc transpile app.zc --cuda -o app.cu\nnvcc app.cu -o app\n```\n\n#### CUDA-Specific Attributes\n\n| Attribute | CUDA Equivalent | Description |\n|:---|:---|:---|\n| `@global` | `__global__` | Kernel function (runs on GPU, called from host) |\n| `@device` | `__device__` | Device function (runs on GPU, called from GPU) |\n| `@host` | `__host__` | Host function (explicit CPU-only) |\n\n#### Kernel Launch Syntax\n\nZen C provides a clean `launch` statement for invoking CUDA kernels:\n\n```zc\nlaunch kernel_name(args) with {\n    grid: num_blocks,\n    block: threads_per_block,\n    shared_mem: 1024,  // Optional\n    stream: my_stream   // Optional\n};\n```\n\nThis transpiles to: `kernel_name\u003c\u003c\u003cgrid, block, shared, stream\u003e\u003e\u003e(args);`\n\n#### Writing CUDA Kernels\n\nUse Zen C function syntax with `@global` and the `launch` statement:\n\n```zc\nimport \"std/cuda.zc\"\n\n@global\nfn add_kernel(a: float*, b: float*, c: float*, n: int) {\n    let i = thread_id();\n    if i \u003c n {\n        c[i] = a[i] + b[i];\n    }\n}\n\nfn main() {\n    def N = 1024;\n    let d_a = cuda_alloc\u003cfloat\u003e(N);\n    let d_b = cuda_alloc\u003cfloat\u003e(N); \n    let d_c = cuda_alloc\u003cfloat\u003e(N);\n    defer cuda_free(d_a);\n    defer cuda_free(d_b);\n    defer cuda_free(d_c);\n\n    // ... init data ...\n    \n    launch add_kernel(d_a, d_b, d_c, N) with {\n        grid: (N + 255) / 256,\n        block: 256\n    };\n    \n    cuda_sync();\n}\n```\n\n#### Standard Library (`std/cuda.zc`)\nZen C provides a standard library for common CUDA operations to reduce `raw` blocks:\n\n```zc\nimport \"std/cuda.zc\"\n\n// Memory management\nlet d_ptr = cuda_alloc\u003cfloat\u003e(1024);\ncuda_copy_to_device(d_ptr, h_ptr, 1024 * sizeof(float));\ndefer cuda_free(d_ptr);\n\n// Synchronization\ncuda_sync();\n\n// Thread Indexing (use inside kernels)\nlet i = thread_id(); // Global index\nlet bid = block_id();\nlet tid = local_id();\n```\n\n\n\u003e [!NOTE]\n\u003e **Note:** The `--cuda` flag sets `nvcc` as the compiler and implies `--cpp` mode. Requires the NVIDIA CUDA Toolkit.\n\n### C23 Support\n\nZen C supports modern C23 features when using a compatible backend compiler (GCC 14+, Clang 14+, TCC (partial)).\n\n- **`auto`**: Zen C automatically maps type inference to standard C23 `auto` if `__STDC_VERSION__ \u003e= 202300L`.\n- **`_BitInt(N)`**: Use `iN` and `uN` types (e.g., `i256`, `u12`, `i24`) to access C23 arbitrary-width integers.\n\n### Objective-C Interop\n\nZen C can compile to Objective-C (`.m`) using the `--objc` flag, allowing you to use Objective-C frameworks (like Cocoa/Foundation) and syntax.\n\n```bash\n# Compile with clang (or gcc/gnustep)\nzc app.zc --objc --cc clang\n```\n\n#### Using Objective-C in Zen C\n\nUse `include` for headers and `raw` blocks for Objective-C syntax (`@interface`, `[...]`, `@\"\"`).\n\n```zc\n//\u003e macos: framework: Foundation\n//\u003e linux: cflags: -fconstant-string-class=NSConstantString -D_NATIVE_OBJC_EXCEPTIONS\n//\u003e linux: link: -lgnustep-base -lobjc\n\ninclude \u003cFoundation/Foundation.h\u003e\n\nfn main() {\n    raw {\n        NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];\n        NSLog(@\"Hello from Objective-C!\");\n        [pool drain];\n    }\n    println \"Zen C works too!\";\n}\n```\n\n\u003e [!NOTE]\n\u003e **Note:** Zen C string interpolation works with Objective-C objects (`id`) by calling `debugDescription` or `description`.\n\n---\n\n## Contributing\n \n We welcome contributions! Whether it's fixing bugs, adding documentation, or proposing new features.\n \n Please see [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines on how to contribute, run tests, and submit pull requests.\n\n---\n \n ## Security\n \n For security reporting instructions, please see [SECURITY.md](SECURITY.md).\n \n ---\n \n ## Attributions\n\nThis project uses third-party libraries. Full license texts can be found in the `LICENSES/` directory.\n\n*   **[cJSON](https://github.com/DaveGamble/cJSON)** (MIT License): Used for JSON parsing and generation in the Language Server.\n*   **[zc-ape](https://github.com/OEvgeny/zc-ape)** (MIT License): The original Actually Portable Executable port of Zen-C by [Eugene Olonov](https://github.com/OEvgeny).\n*   **[Cosmopolitan Libc](https://github.com/jart/cosmopolitan)** (ISC License): The foundational library that makes APE possible.\n\n---\n\n\u003cdiv align=\"center\"\u003e\n  \u003cp\u003e\n    Copyright © 2026 Zen C Programming Language.\u003cbr\u003e\n    Start your journey today.\n  \u003c/p\u003e\n  \u003cp\u003e\n    \u003ca href=\"https://discord.com/invite/q6wEsCmkJP\"\u003eDiscord\u003c/a\u003e •\n    \u003ca href=\"https://github.com/z-libs/Zen-C\"\u003eGitHub\u003c/a\u003e •\n    \u003ca href=\"CONTRIBUTING.md\"\u003eContribute\u003c/a\u003e\n  \u003c/p\u003e\n\u003c/div\u003e\n","funding_links":[],"categories":["Uncategorized","C"],"sub_categories":["Uncategorized"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fz-libs%2FZen-C","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fz-libs%2FZen-C","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fz-libs%2FZen-C/lists"}