# NanoC

> NanoC (alpha, breaking changes expected) is an indentation-based frontend that translates to plain C11. Unmarked C passes through. Compile: `nanoc run file.nc`.

Syntax card: https://nanolanguages.github.io/NanoC/llms-full.txt

## Pages

- [Home](https://nanolanguages.github.io/NanoC/): NanoC translates indentation-based code, macros and compile-time programs into plain readable C11. No runtime, no garbage collector. Alpha.
- [Install](https://nanolanguages.github.io/NanoC/install/): Install the NanoC compiler: clone, build with any C11 compiler, install to ~/.local. Editor support for VS Code, Vim, Neovim, Emacs and more.
- [Tour](https://nanolanguages.github.io/NanoC/tour/): See NanoC in five minutes: functions, locals, control flow, structs, macros and translate-time code, each with the C it produces.
- [Guide](https://nanolanguages.github.io/NanoC/guide/): Learn NanoC in nine short lessons: hello world, functions, control flow, records, preprocessor, raw C, macros, translate-time code and output.
- [Hello](https://nanolanguages.github.io/NanoC/guide/hello/): NanoC is a programmable frontend for C. Runtime constructs become ordinary C with no mandatory runtime, VM, garbage collector or hidden allocation. The C...
- [Functions](https://nanolanguages.github.io/NanoC/guide/functions/): Zero-argument functions can omit parentheses: f get i32. Parameters are always name-first: f clamp(x,lo,hi: i32) i32, or f mix(x: i32, y: f64). Bare...
- [Controls](https://nanolanguages.github.io/NanoC/guide/controls/): Indentation uses spaces. A body must be deeper than its header, siblings align, and dedents must match an enclosing level. Canonical formatting uses two...
- [Records](https://nanolanguages.github.io/NanoC/guide/records/): Types are NanoC type words (i8 to i64, u8 to u64, f32, f64, bool, char, str, size, ptr), prefix pointers such as next: *Node, and record, enum or typedef...
- [Preprocessor](https://nanolanguages.github.io/NanoC/guide/preprocessor/): Preprocessor sigils emit directives for the C preprocessor; NanoC never evaluates their conditions. Indentation closes conditional chains with endif, with...
- [Raw C](https://nanolanguages.github.io/NanoC/guide/raw/): C headers, libraries, functions, pointers, arrays, structs, unions, enums, typedefs, function pointers and platform APIs remain available. Includes do not...
- [Macros](https://nanolanguages.github.io/NanoC/guide/macros/): @m transforms NanoC tokens; it is separate from emitted $ C preprocessor definitions. Captures use $name; typed capture kinds include ident, tokens and...
- [Translate time](https://nanolanguages.github.io/NanoC/guide/tt/): @tt runs translate-time programs before C is emitted. Use dynamic values, functions, lists, strings, quote and emit, or transform source with rewrite and...
- [Output](https://nanolanguages.github.io/NanoC/guide/output/): nanoc c file.nc -o file.c writes deterministic readable C; --emit mini compacts non-raw C. --line-directives emits C #line markers where available. C...
- [Language](https://nanolanguages.github.io/NanoC/language/): The NanoC language by topic: types, functions, control flow, translate-time programs and C interoperability, with the current and target syntax.
- [Types](https://nanolanguages.github.io/NanoC/language/types/): NanoC types are the sized types i8 to i64, u8 to u64, f32, f64, bool, char, str, size and ptr. Mapping and inference rules.
- [Functions](https://nanolanguages.github.io/NanoC/language/functions/): How NanoC declares functions: f name(args) type, shared parameter types, implicit final results, early returns and the new compact signatures.
- [Control flow](https://nanolanguages.github.io/NanoC/language/control-flow/): Branches and loops in NanoC use C semantics with indentation instead of braces. Early returns, break and continue words, and if as an expression.
- [@tt](https://nanolanguages.github.io/NanoC/language/tt/): Use @tt to run small programs while NanoC translates, compute tables, generate declarations with emit and quote, and transform source until it is stable.
- [C interop](https://nanolanguages.github.io/NanoC/language/c-interop/): NanoC keeps C available: includes, libc and your own libraries work unchanged, raw C islands with @c, and the new backtick inline C.
- [Examples](https://nanolanguages.github.io/NanoC/examples/): Sixteen NanoC programs from hello world to generic vectors and compile-time tables, each with the generated C and the real program output.
- [Hello, world](https://nanolanguages.github.io/NanoC/examples/hello/): The smallest NanoC program: an include, a function without braces and an implicit result.
- [FizzBuzz](https://nanolanguages.github.io/NanoC/examples/fizzbuzz/): Classic FizzBuzz with early returns, elif chains and a const char pointer result.
- [Loops and Collatz](https://nanolanguages.github.io/NanoC/examples/loops/): for and while loops with break and continue words, plus a Collatz step counter.
- [Compact C](https://nanolanguages.github.io/NanoC/examples/compact/): Preprocessor chains, defines, early returns and conditional blocks without braces.
- [Structs and enums](https://nanolanguages.github.io/NanoC/examples/records/): Enums, structs, arrays of records and a function returning a double.
- [Fixed-width types](https://nanolanguages.github.io/NanoC/examples/types/): Fixed-width integers, inttypes formats, a struct shorthand and gcd.
- [Linked list](https://nanolanguages.github.io/NanoC/examples/linked_list/): A singly linked list with malloc and free, written with compact pointer syntax.
- [Sorting with callbacks](https://nanolanguages.github.io/NanoC/examples/sort_callbacks/): qsort with a comparison function pointer over an array of structs.
- [Bitset sieve](https://nanolanguages.github.io/NanoC/examples/bitset/): A sieve of Eratosthenes over a bit array using function-like defines.
- [Token macros](https://nanolanguages.github.io/NanoC/examples/macros/): Hygienic-style token templates: max, clamp and generated getter functions.
- [Generic vector](https://nanolanguages.github.io/NanoC/examples/vector_macro/): One macro generates a typed growable vector per element type: generics without a runtime.
- [Scoped cleanup](https://nanolanguages.github.io/NanoC/examples/cleanup/): A with-file block macro that always closes the file: RAII in one macro.
- [Compile-time table](https://nanolanguages.github.io/NanoC/examples/translate_time/): A table of squares computed by the compiler with a translate-time program.
- [Prime table at translate time](https://nanolanguages.github.io/NanoC/examples/prime_table/): The compiler sieves the primes below 60 and emits a constant array and a count.
- [Enum and name table](https://nanolanguages.github.io/NanoC/examples/enum_names/): An enum and its string table generated from one list, so they cannot drift apart.
- [C interop](https://nanolanguages.github.io/NanoC/examples/interop/): Raw C islands next to NanoC code: call libm and your own C helper functions.
- [Reference](https://nanolanguages.github.io/NanoC/builtins/): Reference for every NanoC translate-time builtin: signature, phase, description and a verified example for emit, replace, split, push, read, exec and more.
- [emit](https://nanolanguages.github.io/NanoC/builtins/emit/): Appends C text or a token list to the generated output at the place of the translate-time program.
- [str](https://nanolanguages.github.io/NanoC/builtins/str/): Converts any value (number, list, boolean) to its text form.
- [tokens](https://nanolanguages.github.io/NanoC/builtins/tokens/): Splits NanoC or C text into tokens and returns the token list.
- [ident](https://nanolanguages.github.io/NanoC/builtins/ident/): Checks that text is a valid C identifier and returns it; use it before pasting generated names.
- [fresh](https://nanolanguages.github.io/NanoC/builtins/fresh/): Returns a new unique identifier derived from a hint, for generated temporaries.
- [len](https://nanolanguages.github.io/NanoC/builtins/len/): Length of text in bytes or of a list in items.
- [range](https://nanolanguages.github.io/NanoC/builtins/range/): List of integers from start (default 0) up to but excluding end; also the loop form `for i 0..8`.
- [replace](https://nanolanguages.github.io/NanoC/builtins/replace/): Replaces every occurrence of a substring.
- [rename](https://nanolanguages.github.io/NanoC/builtins/rename/): Renames an identifier token without touching longer names that merely contain it.
- [find](https://nanolanguages.github.io/NanoC/builtins/find/): Index of the first occurrence of a substring, or -1 when absent.
- [contains](https://nanolanguages.github.io/NanoC/builtins/contains/): True when the text contains the substring.
- [split](https://nanolanguages.github.io/NanoC/builtins/split/): Splits text at a separator into a list of strings.
- [join](https://nanolanguages.github.io/NanoC/builtins/join/): Joins a list of strings with a separator.
- [slice](https://nanolanguages.github.io/NanoC/builtins/slice/): Substring or sub-list from start up to an optional end.
- [push](https://nanolanguages.github.io/NanoC/builtins/push/): Returns a new list with the value appended; lists are values, so assign the result.
- [lex](https://nanolanguages.github.io/NanoC/builtins/lex/): Low-level lexer: like tokens but keeps spelling details for source transforms.
- [source](https://nanolanguages.github.io/NanoC/builtins/source/): Returns the current NanoC source text being translated.
- [rewrite](https://nanolanguages.github.io/NanoC/builtins/rewrite/): Replaces the whole source with new text; the pipeline repeats until the text stops changing.
- [again](https://nanolanguages.github.io/NanoC/builtins/again/): Requests one more expansion cycle even when the text did not change.
- [pass](https://nanolanguages.github.io/NanoC/builtins/pass/): The current expansion pass number, starting at 1.
- [get](https://nanolanguages.github.io/NanoC/builtins/get/): Reads a persistent key from the translation state, with a default for missing keys.
- [put](https://nanolanguages.github.io/NanoC/builtins/put/): Stores a persistent key in the translation state; later passes and tools can read it.
- [eval](https://nanolanguages.github.io/NanoC/builtins/eval/): Runs a text as a translate-time program in the current scope; the basis of tool libraries.
- [fail](https://nanolanguages.github.io/NanoC/builtins/fail/): Stops translation with a diagnostic and a nonzero exit; the message is shown with the source line.
- [assert](https://nanolanguages.github.io/NanoC/builtins/assert/): Fails with a diagnostic unless the condition holds; the message is optional.
- [log](https://nanolanguages.github.io/NanoC/builtins/log/): Prints a message to the compiler log (and into the JSON report of `--check`).
- [read](https://nanolanguages.github.io/NanoC/builtins/read/): Reads a text file; paths are relative to the working directory.
- [exists](https://nanolanguages.github.io/NanoC/builtins/exists/): True when a path exists.
- [env](https://nanolanguages.github.io/NanoC/builtins/env/): Reads an environment variable, or an empty string when unset.
- [file](https://nanolanguages.github.io/NanoC/builtins/file/): The spelling of the input file name as given on the command line.
- [path](https://nanolanguages.github.io/NanoC/builtins/path/): The resolved input path when the source comes from a file.
- [line](https://nanolanguages.github.io/NanoC/builtins/line/): The source line of the translate-time call.
- [name](https://nanolanguages.github.io/NanoC/builtins/name/): The enclosing runtime function name, or empty at file scope.
- [cycle](https://nanolanguages.github.io/NanoC/builtins/cycle/): The current one-based expansion cycle.
- [target](https://nanolanguages.github.io/NanoC/builtins/target/): The selected C standard, or c++17 when compiling with `--cpp`.
- [write](https://nanolanguages.github.io/NanoC/builtins/write/): Writes a text file atomically through a same-directory temporary file; host effect, rejected by `--check`.
- [mkdir](https://nanolanguages.github.io/NanoC/builtins/mkdir/): Creates a directory and its parents; host effect, rejected by `--check`.
- [remove](https://nanolanguages.github.io/NanoC/builtins/remove/): Removes a file; host effect, rejected by `--check`.
- [run](https://nanolanguages.github.io/NanoC/builtins/run/): Runs a program with an argument list and returns a list of status, stdout and stderr; no shell involved.
- [exec](https://nanolanguages.github.io/NanoC/builtins/exec/): Like run but returns only stdout and fails the translation on a nonzero exit.
- [sh](https://nanolanguages.github.io/NanoC/builtins/sh/): Runs a shell command and returns a list of status, stdout and stderr.
- [Playground](https://nanolanguages.github.io/NanoC/playground/): Edit NanoC and watch the real compiler, running as WebAssembly in your browser, produce C as you type. Share a link to your code.
- [Prompt](https://nanolanguages.github.io/NanoC/prompt/): Type what you want to build and copy a compact prompt that teaches any LLM NanoC: a short syntax card plus your idea. Runs locally in the page.
- [Compare](https://nanolanguages.github.io/NanoC/compare/): A short, honest comparison of NanoC with C, Zig, Rust and Nim: output, syntax, compile-time code, C interop and runtime.
- [Alpha](https://nanolanguages.github.io/NanoC/alpha/): NanoC is alpha software: syntax and behavior change between releases. Current version 0.7.0-alpha, what is stable, what is moving, and the changelog.