Intrinsics Reference

This page documents every @intrinsic the Gruel compiler recognizes. It is generated from the [gruel-intrinsics] registry (see ADR-0050); any changes must be made in Rust, not here.

Quick Reference

Intrinsic	Kind	Category	Preview	Unchecked	Summary
`@dbg`	expr	Debug & Diagnostics	—	—	Print values to stderr with a trailing newline.
`@panic`	expr	Debug & Diagnostics	—	—	Abort the program with an optional message.
`@assert`	expr	Debug & Diagnostics	—	—	Check a boolean condition; panic if false.
`@compile_error`	expr	Compile-time Reflection	—	—	Emit a compile-time error.
`@cast`	expr	Type Casts	—	—	Numeric type conversion.
`@read_line`	expr	I/O	—	—	Read one line from stdin.
`@parse_i32`	expr	String Parsing	—	—	Parse a String into i32.
`@parse_i64`	expr	String Parsing	—	—	Parse a String into i64.
`@parse_u32`	expr	String Parsing	—	—	Parse a String into u32.
`@parse_u64`	expr	String Parsing	—	—	Parse a String into u64.
`@random_u32`	expr	Random Numbers	—	—	Uniform random 32-bit integer.
`@random_u64`	expr	Random Numbers	—	—	Uniform random 64-bit integer.
`@size_of`	type	Compile-time Reflection	—	—	Size of a type in bytes.
`@align_of`	type	Compile-time Reflection	—	—	Alignment of a type in bytes.
`@type_name`	type	Compile-time Reflection	—	—	Name of a type as a comptime string.
`@type_info`	type	Compile-time Reflection	—	—	Reflective info about a type.
`@field`	expr	Compile-time Reflection	—	—	Access a field by comptime-known name.
`@import`	expr	Compile-time Reflection	—	—	Import another source file (placeholder).
`@target_arch`	expr	Target Platform	—	—	Compile target CPU architecture.
`@target_os`	expr	Target Platform	—	—	Compile target operating system.
`@ptr_read`	expr	Raw Pointers	—	yes	Load a value through a raw pointer.
`@ptr_write`	expr	Raw Pointers	—	yes	Store a value through a raw mutable pointer.
`@ptr_offset`	expr	Raw Pointers	—	yes	Pointer arithmetic by element count.
`@ptr_to_int`	expr	Raw Pointers	—	yes	Convert a pointer to its integer address.
`@int_to_ptr`	expr	Raw Pointers	—	yes	Construct a pointer from an integer address.
`@null_ptr`	expr	Raw Pointers	—	yes	A null pointer of the inferred type.
`@is_null`	expr	Raw Pointers	—	yes	Test whether a pointer is null.
`@ptr_copy`	expr	Raw Pointers	—	yes	Bulk copy between pointers.
`@raw`	expr	Raw Pointers	—	yes	Take a const pointer to an lvalue.
`@raw_mut`	expr	Raw Pointers	—	yes	Take a mutable pointer to an lvalue.
`@syscall`	expr	System Calls	—	yes	Direct OS system call.
`@range`	expr	Iteration	—	—	Iterable range for `for`-loops.
`@test_preview_gate`	expr	Preview / Meta	test_infra	—	Test hook for the preview-feature gate.

Debug & Diagnostics

`@dbg`

@dbg(v1, v2, ...) prints each argument separated by spaces, then a newline. Accepts integers, bools, and String values.

Examples:

@dbg(42, true, "hello")

`@panic`

@panic() or @panic("message") terminates the program. Diverges (returns Never).

Examples:

@panic("unreachable")

`@assert`

@assert(cond) panics with a diagnostic if cond is false. Elided in release builds (future work).

Examples:

@assert(x > 0)

Type Casts

`@cast`

@cast(x) converts between integer and/or float types. The target type is inferred from context.

Examples:

let y: i64 = @cast(x);

I/O

`@read_line`

@read_line() returns a String containing the next line from standard input, without the trailing newline.

Runtime symbol: __gruel_read_line

Examples:

let line = @read_line();

String Parsing

`@parse_i32`

@parse_i32(s) parses s as a signed 32-bit integer. Panics on invalid input.

Runtime symbol: __gruel_parse_i32

Examples:

let n: i32 = @parse_i32(line);

`@parse_i64`

@parse_i64(s) parses s as a signed 64-bit integer. Panics on invalid input.

Runtime symbol: __gruel_parse_i64

Examples:

let n: i64 = @parse_i64(line);

`@parse_u32`

@parse_u32(s) parses s as an unsigned 32-bit integer. Panics on invalid input.

Runtime symbol: __gruel_parse_u32

Examples:

let n: u32 = @parse_u32(line);

`@parse_u64`

@parse_u64(s) parses s as an unsigned 64-bit integer. Panics on invalid input.

Runtime symbol: __gruel_parse_u64

Examples:

let n: u64 = @parse_u64(line);

Random Numbers

`@random_u32`

@random_u32() returns a uniformly distributed u32 from the runtime PRNG.

Runtime symbol: __gruel_random_u32

Examples:

let r = @random_u32();

`@random_u64`

@random_u64() returns a uniformly distributed u64 from the runtime PRNG.

Runtime symbol: __gruel_random_u64

Examples:

let r = @random_u64();

Compile-time Reflection

`@compile_error`

@compile_error("msg") aborts compilation with the given message. Useful for unreachable comptime branches.

Examples:

@compile_error("unsupported target")

`@size_of`

@size_of(T) returns sizeof(T) as i32, evaluated at compile time.

Examples:

@size_of(i64)

`@align_of`

@align_of(T) returns the required alignment of T as i32, evaluated at compile time.

Examples:

@align_of(i64)

`@type_name`

@type_name(T) returns the canonical name of T as a comptime-known string.

Examples:

@type_name(i64) // "i64"

`@type_info`

@type_info(T) returns a comptime struct describing T (kind, fields, variants, ...).

Examples:

@type_info(MyStruct)

`@field`

@field(value, "name") reads the named field of value, with the name resolved at compile time.

Examples:

@field(s, "x")

`@import`

@import("path") — planned module-system hook; currently accepted by the compiler as a placeholder.

Examples:

@import("utils.gruel")

Target Platform

`@target_arch`

@target_arch() returns a variant of the built-in Arch enum.

Examples:

if @target_arch() == Arch::Aarch64 { ... }

`@target_os`

@target_os() returns a variant of the built-in Os enum.

Examples:

if @target_os() == Os::Linux { ... }

Raw Pointers

`@ptr_read`

@ptr_read(p) dereferences p: ptr const T or ptr mut T and returns T. Requires an unchecked block.

Requires: unchecked { ... } block

Examples:

unchecked { let v = @ptr_read(p); }

`@ptr_write`

@ptr_write(p, v) writes v through p: ptr mut T. Requires an unchecked block.

Requires: unchecked { ... } block

Examples:

unchecked { @ptr_write(p, 42); }

`@ptr_offset`

@ptr_offset(p, n) advances p by n * sizeof(*p) bytes. Requires an unchecked block.

Requires: unchecked { ... } block

Examples:

unchecked { let q = @ptr_offset(p, 3); }

`@ptr_to_int`

@ptr_to_int(p) returns the address of p as u64. Requires an unchecked block.

Requires: unchecked { ... } block

Examples:

unchecked { let a = @ptr_to_int(p); }

`@int_to_ptr`

@int_to_ptr(addr) reinterprets addr: u64 as a pointer. Target pointer type is inferred from context. Requires an unchecked block.

Requires: unchecked { ... } block

Examples:

unchecked { let p: ptr mut u8 = @int_to_ptr(addr); }

`@null_ptr`

@null_ptr() returns a pointer whose address is zero; the pointer type is inferred from context. Requires an unchecked block.

Requires: unchecked { ... } block

Examples:

unchecked { let p: ptr const u8 = @null_ptr(); }

`@is_null`

@is_null(p) returns true iff p's address is zero. Requires an unchecked block.

Requires: unchecked { ... } block

Examples:

unchecked { if @is_null(p) { ... } }

`@ptr_copy`

@ptr_copy(dst, src, n) copies n elements of the pointee type from src to dst via LLVM memcpy. Requires an unchecked block.

Requires: unchecked { ... } block

Examples:

unchecked { @ptr_copy(dst, src, 16); }

`@raw`

@raw(place) returns ptr const T pointing to place. Requires an unchecked block.

Requires: unchecked { ... } block

Examples:

unchecked { let p = @raw(x); }

`@raw_mut`

@raw_mut(place) returns ptr mut T pointing to place. Requires an unchecked block.

Requires: unchecked { ... } block

Examples:

unchecked { let p = @raw_mut(x); }

System Calls

`@syscall`

@syscall(num, arg1, ...) issues a raw syscall. Takes the syscall number plus up to 6 arguments; returns i64. Requires an unchecked block.

Requires: unchecked { ... } block

Examples:

unchecked { let ret = @syscall(1, 1, buf, n); }

Iteration

`@range`

@range(end), @range(start, end), or @range(start, end, step) produces an iterable over integers.

Examples:

for i in @range(0, 10) { ... }

Preview / Meta

`@test_preview_gate`

@test_preview_gate() exists solely to verify that the preview-feature gating mechanism works. Always gated behind --preview test_infra.

Preview gate: --preview test_infra (ADR-0005)