Quark is a high-level, dynamically-typed language that compiles to optimized C++17.

It is designed to feel readable and expressive like a scripting language, while still producing native binaries that can run fast on data-heavy workloads.

This repository contains the active Go compiler implementation, C++ runtime headers, and smoke/benchmark programs.

Quark is built around five practical goals:

1. Minimal readable syntax with low ceremony.
2. Out of the box performance for data heavy operations.
3. Good compile time guarantees and interop with C++.

1. Language ergonomics and performance are equal, primary goals.
2. Developer productivity and quality-of-life are first-class concerns.
3. Performance should not come at the cost of user-facing complexity.
4. Fail early and fail loudly with clear diagnostics.
5. Less is more for language surface area and syntax.
6. Explicit is better than implicit, especially at boundaries.
7. Prefer boring, reliable defaults over cleverness.

Quark currently supports:

• Indentation-based blocks.
• Functions, lambdas, and closures.
• QEI extern declarations (extern '...', extern fn ... as 'symbol').
• Conditionals, loops, ternary expressions, and pattern matching.
• Explicit result values using ok/err pattern and related helpers.
• Pipelined call style via the pipe operator.
• Method dispatch on strings, lists, dicts, and vectors.
• Multi-file imports and stdlib path imports.

nums = list [1, 2, 3]
nums.push(4)
len(nums)
'hello'.upper()

Pipes chain free-function calls:

'hello'.upper() | println()

Dot syntax serves three purposes: dict key access, method calls, and module-qualified calls.

d = dict { name: 'quark' }
println(d.name)

'hello world'.split(' ') | println()

use 'std/demo_math' as dm
println(dm.add10(5))

Quark is already usable for many small to medium programs and language experiments. It has strict analyzer/runtime checks and a full compile pipeline, but some features are still planned (for example structs/impl blocks and tensor support).

Recent compiler/runtime work introduced several behavior and architecture changes worth calling out:

1. Diagnostics are now severity-aware.

   • Analyzer warnings are shown but non-fatal.
   • Analyzer errors are fatal.
   • Runtime diagnostics use a stable QK-RUNTIME-001 code format with source location when available.

2. Invariants are fail-loud.

   • CallPlan and return-validation invariants are validated before codegen.
   • Unexpected invariant breaches in codegen are treated as internal compiler errors (INV-*) instead of silently degrading behavior.

3. Builtin surface expanded and normalized.

   • Method dispatch is catalog-driven across str, list, dict, and vector.
   • Low-level file primitives are available via _file_open, _file_read, _file_write, _file_close, _file_seek, _file_exists.

4. QEI (extern/native interop) is implemented end-to-end.

   • extern fn call sites use DispatchExtern with native argument adaptation and return wrapping.
   • Free extern functions can be used as first-class values via generated thunks.
   • Runtime-checked extern unboxing now fails loudly on mismatched dynamic input.

5. Scalar/range lowering expanded.

   • Scalar == / != lower to native C++ comparisons when operands are scalar-tiered.
   • if / elseif / while conditions on scalar bools lower directly (skip q_truthy(...)).
   • for i in range(...) lowers to raw C++ loops instead of list-allocation iteration.

6. Call lowering is now metadata-driven.

   • Analyzer emits per-call CallPlans (dispatch mode, arity envelope, runtime symbol, default argument fill).
   • Codegen consumes CallPlans directly rather than re-deriving call semantics.

7. Module/import behavior is stricter and clearer.

   • Module-qualified calls (alias.fn(...)) are resolved in analysis.
   • Loader enforces deterministic import resolution and cycle detection.

For canonical details, use:

• Language behavior: semantics.md
• Syntax and grammar: grammar.md
• Builtins and method catalog surface: stdlib.md
• Compiler/runtime internals: architecture.md
• Diagnostic and invariant code registry: error_codes.md

• Go 1.21+
• clang++ in PATH
• CMake in PATH (for Boehm GC bootstrap)
• Windows, Linux, or macOS

From the repository root:

cd src/core/quark
go build -o quark .

On Windows, if you want an explicit exe file name:

cd src/core/quark
go build -o quark.exe .

quark lex <file>
quark parse <file>
quark check <file>
quark emit <file>
quark build <file> [-o out]
quark run <file> [--debug|-d]

Diagnostics behavior:

• Parser/load/analyzer diagnostics are printed with stable codes.
• Analyzer warnings are displayed but do not fail check, emit, build, or run.
• Analyzer errors fail the command with non-zero exit.
• Invariant failures (INV-* class) are treated as compiler-bug conditions and fail loudly.

Shorthand:

quark program.qrk

This is equivalent to running quark run program.qrk.

cd src/core/quark
./quark run ../../../src/testfiles/smoke_syntax.qrk

Quark vendors Boehm GC under deps/bdwgc. During build/run, the compiler will try to find a built GC library and, if missing, bootstrap it via CMake.

Quoted stdlib imports use the std/... prefix:

use 'std/demo_math' as dm

Stdlib root is resolved in this order:

1. QUARK_STDLIB_ROOT environment variable.
2. Upward search for a directory named stdlib from the source file location.
3. Executable-relative fallbacks (stdlib near the compiler binary).

If you package Quark for production, setting QUARK_STDLIB_ROOT explicitly is the most robust approach.

fn add(x, y) -> x + y
println(add(2, 3))

fn classify(n) ->
    if n < 0:
        'negative'
    elseif n == 0:
        'zero'
    else:
        'positive'

println(classify(10))

fn fib(n) ->
    when n:
        0 -> 0
        1 -> 1
        _ -> fib(n - 1) + fib(n - 2)

println(fib(8))

fn safe_div(a, b) ->
    if b == 0:
        err 'division by zero'
    else:
        ok a / b

when safe_div(10, 2):
    ok value -> println(value)
    err msg -> println(msg)

'  quark  '.trim().upper() | println()

nums = list [1, 2, 3]
nums.push(4)
nums.get(0) | println()
len(nums) | println()

v = vector [1, 2, 3, 4]
w = v + 10
println(sum(w))
println(sum(v > 2))

user = dict { name: 'alex', age: 30 }
println(user.name)

k = 'name'
user.get(k) | println()
user = user.set('city', 'dublin')
println(user.city)

Same-file module:

module math:
    fn square(x) -> x * x

use math as m
println(m.square(9))

File import:

use './lib/helpers' as h
println(h.format_name('Ada'))

Stdlib path import:

use 'std/demo_math' as dm
println(dm.add10(32))

All builtins are globally available; no import is required.

println(to_int('42'))
println(range(1, 5))
'quark'.upper() | println()

vals = list [1, 2, 3]
vals.push(4)
println(sum(vals.to_vector()))

For a deeper narrative and behavior notes, see stdlib.md.

                 Quark Source (.qrk)
                         |
                         v
+-------------------+  tokens  +-------------------+
| Lexer (Go)        | -------> | Parser (Go)       |
| - indentation     |          | - AST             |
| - token stream    |          | - module/use nodes|
+-------------------+          +-------------------+
                                        |
                                        v
                              +-------------------+
                              | Import Loader     |
                              | - file imports    |
                              | - std/ imports    |
                              | - cycle checks    |
                              +-------------------+
                                        |
                                        v
                              +-------------------+
                              | Analyzer (Go)     |
                              | - scopes/types    |
                              | - call plans      |
                              | - diagnostics     |
                              +-------------------+
                                        |
                                        v
                              +-------------------+
                              | Invariants        |
                              | - call plan checks|
                              | - return checks   |
                              +-------------------+
                                        |
                                        v
                              +-------------------+
                              | Codegen (Go)      |
                              | - extern includes |
                              | - dispatch lowering|
                              | -> C++17 source   |
                              +-------------------+
                                        |
                                        v
                              +-------------------+
                              | clang++           |
                              | -O3 + arch flags  |
                              +-------------------+
                                        |
                                        v
                                 Native Executable

• src/core/quark: active Go compiler implementation.
• src/core/quark/runtime/include/quark: header-only runtime.
• deps/bdwgc: vendored Boehm GC source.
• src/testfiles: smoke programs.
• stdlib: repository stdlib modules (used by use 'std/...').

Compiler invocations generated by Quark use:

• C++17 mode.
• O3 optimization.
• Architecture flag on amd64 builds.
• Runtime include path for Quark headers.
• Boehm GC include/lib when GC is enabled.

Quark favors explicit failure:

• Analyzer catches concrete type and arity errors when knowable.
• Runtime checks guard dynamic paths.
• Type/domain violations fail loudly rather than silently returning neutral values.

Documented exceptions:

• .get(idx) on list returns null for out-of-bounds.
• .get(key) on dict returns null for missing keys.

Implemented:

• Full lexer/parser/analyzer/codegen pipeline.
• Closures and function values.
• Pipes, control-flow, pattern matching.
• Lists, dicts, vectors, results.
• Method dispatch on str, list, dict, vector.
• Multi-file imports and stdlib imports.

Planned:

• Structs and impl blocks.
• Tensor type.
• Additional optimizer passes beyond current architecture.

For detailed implementation internals, see architecture.md.

This repository is licensed under the GNU General Public License v3.0.

See LICENSE for the full text.

Third-party dependencies may use different licenses; see their respective license files (for example, deps/bdwgc/LICENSE).