Bedrock Doc

[Aliqyan-21]

documentation of bedrock here.

[vasucp1207]

Initial proposal doc for language

Introduction

Bedrock is an imperative, statically typed systems programming language designed around simplicity, readability, and practicality.

The goal is to provide the control expected from a systems language while removing unnecessary complexity from the programming model.
Memory is managed automatically through a garbage collector or any other memory management technique(not decided yet as there are multiple possible solutions here). For C interoperability use unsafe block is required.

The language intentionally avoids object-oriented programming. Programs are built using procedures, functions, structs, and modules instead of classes or inheritance.

---

Design Goals

The language is built around a few core principles.

• Imperative programming model.
• Static type system.
• Automatic memory management.
• Data-oriented design.
• Explicit low-level control using unsafe when required.
• Compile time meta-programming using comptime.

---

Memory Model

The language uses automatic memory management. Programmers never manually allocate or free ordinary language objects.
Objects created by the language are managed by the runtime and are reclaimed automatically once they become unreachable.

var person = Person(
    name = "Alice",
    age = 24,
)

There is no new, delete, malloc, or free in generic programs.

---

Manual Memory

Manual memory management exists only for cases where programmer needs to interact with,

• C interoperability
• GPU buffers(future case)

These are accessed through the FFI and require explicit management.

extern func malloc(size: usize) -> *u8
extern proc free(ptr: *u8)

unsafe
    var buffer = malloc(4096)
    // ...
    free(buffer)
end

---

Type System

The language uses static typing with compile-time type checking.

Primitive types include:

bool

char
str

i8
i16
i32
i64

u8
u16
u32
u64

f32
f64

usize
isize

Composite types include:

• Structs
• Arrays
• Pointers
• Tagged Enums
• Function types

---

Variables

Variables are declared using var.

var age = 24

If you want a mutable var.

var mut age = 24

Explicit types may also be written.

var age: u32 = 24

Compile-time constants use const.

comptime var PI = 3.141592

---

Type Declarations

All user-defined types begin with the type keyword.

Structs

type Person = struct
    name: str,
    age: u32,
end

Enums

type Person = enum
    age(u8),
    name(str),
end

Using match expression on enums,

match P1
  age(a_num) => // todo,
  name(n_str) => // todo
end

---

Procedures and Functions

The language distinguishes between procedures and functions.

A procedure performs work but does not return a value.

proc greet(name: str)
    io.println(name)
end

no return value (if given then error)

A function returns a value.

func square(x: i32) -> i32
    return x * x
end

alwasy require a return value (if not given then error)

This distinction is intentional and improves readability while reflecting the language's procedural roots.

---

Struct Construction

Structs are constructed using function-like syntax.

var p = Person(
    name = "Alice",
    age = 24,
)

---

Control Flow

Conditional statements use explicit block endings.

if value > 10
    io.println("Large")
else
    io.println("Small")
end

Loops follow the same style.

while running
    update()
end

for i in 0..10
    io.println(i)
end

Every block begins with a keyword and ends with end.

---

Match

Match expressions with tagged enums.

match color
    case Red
      io.println("Red")
    case Green
      io.println("Green")
    case Blue  
      io.println("Blue")
      io.println("Neela")
    else
      io.println("Unknown")
end

Or with integers:

match opcode
  case 0 
    // todo,
  case 1
    // todo,
  else => // todo
end

---

Error Handling

Operations that may fail return an error type, making failure an explicit part of the function's signature.

func open(path: str) -> File!

In the example above, open returns either a valid File or an error.
This approach makes error handling visible at compile time and avoids hidden control flow.

Error Propagation

The language syntax provides a concise way to propagate errors.

func load_config() -> Config!
    var file = try open("config.cfg")
    return try parse(file)
end

• If the operation succeeds, execution continues using the returned value.
• If the operation returns an error, the current function immediately returns that error to its caller.

Conceptually, the following code:

var file = try open("config.cfg")

is equivalent to:

var result = open("config.cfg")

if result is error
    return result
end

var file = result

A function that can fail must explicitly indicate this in its return type.

func read_file(path: str) -> File!

A function that cannot fail simply returns its value.

func square(x: i32) -> i32
    return x * x
end

By making failure explicit, the language encourages developers to acknowledge and handle error conditions rather than allowing them to be silently ignored.

---

Optional Values

Some operations may produce no value without it being considered an error. Such functions return an optional type.

func find_user(id: u32) -> ?User

The return type ?User indicates that the function returns either a valid User or null.

Optional values make the absence of data explicit in the type system while avoiding the need for sentinel values or null pointer checks throughout the language.

---

The orelse Operator

The orelse operator provides a concise way to handle optional values.
If the optional contains a value, that value is returned. Otherwise, the expression following orelse is evaluated.

var user = find_user(id) orelse User(
    name = "Unknown",
    age = 0,
)

• If find_user() returns a User, execution continues normally.
• If it returns null, the return statement is executed immediately.

This allows optional values to be handled without explicit conditional statements.

---

Modules

Modules are imported using the import keyword.

import io
import math
import graphics.window

Each source file represents one module.

---

Visibility

By default, every declaration is private to its defining module. To make a declaration available to other modules, it must be marked with the pub keyword.

Public procedures:

pub proc greet(name: str)
    io.println(name)
end

Public functions:

pub func add(a: i32, b: i32) -> i32
    return a + b
end

Public types:

pub type Person = struct
    name: str,
    age: u32,
end

Constants and variables may also be exported.

pub comptime var VERSION = "0.1"

Members of a struct are also private by default.

Comments

Single-line comments

// This is a comment.

Multi-line comments

/*
  Multiple
  lines.
*/

---

Pointers

The language supports raw pointers.

var ptr: *i32

Address-of:

&value

Dereference:

*ptr

Pointers provide direct memory access when required while remaining explicit.

---

Unsafe

The language is safe by default.

Ordinary language code is protected by the compiler and runtime. Memory for language objects is managed automatically by the garbage collector or any other automatic memory technique, eliminating the need for manual allocation and deallocation in normal programs.

Certain low-level operations, however, cannot be verified or protected by the compiler.
These operations must be performed inside an unsafe block.

unsafe
    // Unsafe operations
end

An unsafe block explicitly indicates that the programmer is taking responsibility for the correctness of the enclosed code.

The presence of an unsafe block serves two purposes:

• It enables low-level operations that are otherwise prohibited.
• It clearly communicates to readers that this section of code requires additional care and review.

Operations permitted within an unsafe block include:

• Manual memory allocation and deallocation.
• Raw pointer dereferencing.
• Pointer arithmetic.
• Calling foreign (C) functions.
• Accessing memory-mapped hardware.
• Low-level memory manipulation.
• Inline assembly (future).

Example:

extern func malloc(size: usize) -> *u8
extern proc free(ptr: *u8)

unsafe
    var buffer = malloc(4096)
    *(buffer + 8) = 42
    free(buffer)
end

Objects created by the language remain managed by the runtime even when referenced
inside an unsafe block.

var person = Person(
    name = "Alice",
    age = 24,
)

unsafe
    var ptr = &person
    // Pointer operations...
end

In the example above, person is still owned by the language memory system.

unsafe simply removes the language's safety guarantees for the enclosed operations.
The responsibility for correctness shifts from the compiler to the programmer.

---

Foreign Function Interface

The language provides direct interoperability with C through the native ABI.

extern proc printf(fmt: *u8, ...)

extern func malloc(size: usize) -> *u8

This allows seamless integration with existing operating system APIs and C/C++ libraries.

---

Example Program

import io

type Person = struct
    name: str,
    age: u32,
end

type Color = enum
    red,
    blue,
    green,
end

func is_adult(p: Person) -> bool
    return p.age >= 18
end

proc greet(p: Person)
    io.print("Hello ")
    io.println(p.name)
end

proc main()
    var user = Person(
        name = "Alice",
        age = 24,
    )

    greet(user)

    if is_adult(user)
        io.println("Adult")
    else
        io.println("Minor")
    end
end

---

Language Philosophy

This language intentionally avoids adding features simply because other languages have them.

Every feature must satisfy three questions:

1. Is it easy to understand?
2. Is it easy to implement?
3. Does it genuinely improve systems programming?

If the answer to any of these questions is no, the feature does not belong in the language.

The language favors clarity over cleverness, explicitness over magic, and practicality over novelty.

The result is a systems programming language that feels familiar without being derivative, modern without being complicated, and powerful without sacrificing readability.

TODOS

• Memory model
• Generics

[Aliqyan-21]

We will need a formal memory model and some blends of different kinds because there's a gap, the gap is data-oriented hot loops, thousands of short-lived objects allocated and dropped every frame
or every batch. The GC has to trace all of them to know what's still alive, every time.

gc heap suppose traces ~10,000 live objects, every frame
but, arena one free() call, done!