Bak Language

Current status:

• The Go implementation in pkg/ and cmd/ is the supported compiler.
• src/std contains the Bak standard library sources used by examples and tests.
• The compatibility and release direction is tracked in docs/.

Purpose: concise overview of Bak syntax, tooling, and project direction.

Audience: compiler contributors, language learners, and repo maintainers.

Contract note: this README is introductory, not normative. The frozen compatibility contract lives in docs/CORE_LANGUAGE_SPEC.md. The change policy for the language surface lives in docs/LANGUAGE_STABILITY_POLICY.md. If this README conflicts with either document, the spec and stability policy win.

Language Status

Bak is operating under a frozen v0.1 language line.

• Stable language semantics are defined only by docs/CORE_LANGUAGE_SPEC.md.
• The Go implementation in pkg/ and cmd/ is the compiler/runtime of record.
• Backend divergence on the frozen surface should be treated as a bug, not as “different modes”.

---

Lexical Structure

• Comments: // single-line, /* ... */ block.
• Identifiers: ASCII letters, digits, _, not starting with a digit.
• Keywords: package, import, pub, func, mut, var, const, struct, enum, impl, return, switch, case, break, continue, if, else, Result, Ok, Err, panic, defer.
• Literals: integers (123), floats (1.5), char 'a', string "hello", bool true/false.

File Structure & Packages

• Every source file should start with a package declaration, e.g. package main.
• Import other packages with Go-like package paths:

import "std/http"
import vec "std/collections/vec"

• Unaliased imports bind to the imported file's package declaration.
• pub marks exported declarations.

Basic Program

package main

func main() -> (void) {
    println("Hello, bak")
    return void
}

Types

• Primitive: int, int32, int64, float32, float64, bool, char, string.
• Structs and enums are the primary composite types.
• Result<T, E> is used for optional and fallible results.
• Type aliases: type Name = string.

Variables & Mutability

• Immutable by default (explicit type required if not inferred, but explicit separation is standard):

var x: int = 5

• Mutable:

mut var i: int = 0
i = i + 1

• Ignore unused vars by prefixing with _.

Multiple Return Values

Bak supports multiple return values and destructuring assignments using var (...).

func div_mod(a: int, b: int) -> (int, int) {
    return a / b, a % b
}

var (q, r) = div_mod(10, 3)

Functions

func add(a: int, b: int) -> (int) {
    return a + b
}

• Use pub func to export.
• Prefix unused parameters with _ to silence warnings.
• Explicit return types are required. use -> (void) for void functions.

Ownership & Borrowing (Core Model)

• Values passed by value are moved (ownership transferred) unless type is treated as Copy by the compiler (e.g. primitives).
• Borrow with &T, mutable borrow with &mut T.

v1 Restrictions:

• Functions cannot return borrowed values (lifetime analysis is strictly lexical).
• Structs cannot contain borrowed references as fields.

Example (move):

func consume(v: Vec<int,_>) -> (int) { return v.len() }

var nums: Vec<int,_> = Vec.from([1,2,3])
var n: int = consume(nums) // nums moved
// using nums here is an error (use of moved value)

Example (borrow):

func borrow_len(v: &Vec<int,_>) -> (int) { return v.len() }

var nums: Vec<int,_> = Vec.from([1,2,3])
var n: int = borrow_len(&nums) // nums not moved

Structs & Methods

pub struct Person {
    pub name: string
    age: int
}

impl Person as p {
    func greet() -> (string) { return p.name }
    mut func set_name(n: string) -> (void) { p.name = n }
}

Enums

enum E { A, B }
pub enum F { X, Y }

Control Flow

• if / else as usual.
• while loops supported.
• switch / case syntax.

switch value {
    case E.A { ... }
    case E.B { ... }
}

Defer

Use defer to schedule a block to run when the surrounding function returns.

func process() -> (void) {
    var f: File = open("file.txt")
    defer { f.close() }
    // ... work
}

panic("message") aborts execution after running deferred blocks.

Pattern Matching

Switch statements support simple value matching and destructuring of Result types.

var result: Result<int, string> = Ok(10)

switch result {
    case Ok(val) {
        println("Got value: ", val)
    }
    case Err(err) {
        println("Got error: ", err)
    }
}

Standard Library

Selected std packages and examples:

• path / filepath: path utilities. Example: examples/path_example.bak.
• crypto: FNV-1a hash + RNG. Example: examples/crypto_example.bak.
• encoding/json: JSON build/parse + pretty printing. Example: examples/json_example.bak.
• http: client + server helpers. Examples: examples/http_client_example.bak, examples/http_server_example.bak.
• log: colorful, configurable logging. Example: examples/log_example.bak.

Collections

• Vec<T,_> used for vector/array-like containers. Construct via Vec.new() or Vec.from([...]).
• Methods: push, pop, len.
• Indexing: v[i].

Result

• Ok(val) / Err(err)
• Use unwrap() to extract values (panics if invalid) or switch to handle safely.
• Option<T> / Some / None are legacy constructs and are rejected on the frozen v0.1 user surface.

Diagnostics & Best Practices

• Common diagnostics: UnusedField, UnusedFunc, E0503 (unused variable), use of moved value.
• To silence unused-variable warnings, prefix with _.
• Prefer borrows (&T) for read-only access to large structures.
• Export only the minimal pub API surface.

Project Direction

Bak is developed as a Go-implemented language toolchain:

• use go build -o bak ./cmd/bak to build the compiler,
• use bak run, bak check, and bak build for normal project work,
• treat src/std as the Bak standard library source tree,
• keep compiler/runtime/tooling correctness ahead of new syntax.

Stability Notes

• Prefer the frozen v0.1 surface for examples, libraries, and tests.
• Bak does not expose experimental user-facing features in the stable line; unsupported syntax should be rejected with diagnostics.
• Project manifest support is not part of the current stable CLI surface.

Tooling

• bak run, bak check, bak build, bak test, bak doctor, bak explain, and bak repl are the current CLI commands.
• bakfmt formats Bak source files.
• baklint reports style and correctness findings.

See:

• docs/STABLE_LANGUAGE.md
• docs/CORE_LANGUAGE_SPEC.md
• docs/LANGUAGE_STABILITY_POLICY.md
• docs/BACKEND_CONFORMANCE.md
• docs/PACKAGE_BOUNDARIES.md
• docs/EXAMPLES.md
• docs/STDLIB_STABLE_V0.1.md
• docs/STDLIB_PHASE3.md
• docs/STDLIB_COLLECTIONS_STRINGS_PATH.md
• docs/TRUST_MODEL.md