Ryo Reference

Variables & Mutability #

Bindings are introduced without a keyword — just a name and a value. They are immutable by default. The compiler infers the type from the initializer; you may also write an explicit annotation.

fn main():
	name = "Alice"          # inferred as str, immutable
	count: int = 10         # explicit type annotation
	mut total = 0           # mutable variable
	total = total + count

	# name = "Bob"          # error: cannot assign to immutable binding

• name = expr — immutable, type inferred.
• name: Type = expr — immutable, explicit type.
• mut name = expr — mutable; may be reassigned.

Primitive Types #

Ryo has a small set of primitive types. Today int is always 64-bit signed and float is always 64-bit IEEE 754. Float literals take the usual decimal and scientific forms (3.14, 1.23e-10, 1e5) and may use underscore separators (1_000.5).

Integers & Arithmetic #

Integer literals may use underscores for readability (1_000_000) and the standard 0x, 0o, 0b prefixes. Division between two integers truncates toward zero, like Python's //.

fn main():
	print(int_to_str(7 / 2))     # 3  — integer division truncates
	print(int_to_str(7 % 2))     # 1  — remainder
	print(int_to_str(0xFF))      # 255 — hex literal

	mut counter = 0
	counter += 10                # compound assignment
	counter -= 3
	print(int_to_str(counter))   # 7

Booleans & Logic #

The bool type has two values, true and false, produced by comparison operators. Logical operators and, or, and not are words, not symbols, and and/or short-circuit.

fn is_valid(x: int) -> bool:
	return x > 0 and x < 100

fn check_access(is_admin: bool, is_owner: bool) -> bool:
	return is_admin or is_owner

Strings #

The str type is an owned, heap-allocated UTF-8 string. A binding is read-only unless declared mut. Concatenate with +.

fn main():
	mut greeting = "Hello"
	greeting = greeting + ", World!"
	print(greeting)              # Hello, World!

	print("tab\there\n")        # escape sequences
	print("quote: \"hi\"\n")

Escape Sequences

Slices

s[start:end] yields a strview — a read-only, zero-copy view into the string's buffer. Shorthands: s[start:], s[:end], s[:]. Bounds are byte offsets; they panic at creation when out of range, reversed (start > end), or not on a UTF-8 boundary. Views are non-escaping: they can't be returned or stored past the current function, and the owner is frozen while a view is live. Views also pass to ordinary str parameters — a call-scoped re-borrow, no copy.

When viewed data must outlive the call — returned, stored, or moved — str(view) materializes an owned str copy (allocates + copies). It is never implicit: x: str = view stays a type error, while x: str = str(view) is the explicit fix. Materializing where the free re-borrow already suffices — or copying data that never escapes and whose source is never mutated — draws warning W0003 (RedundantMaterialize).

fn main():
	s: str = "hello world"
	print(s[0:5])      # hello
	print(s[6:])       # world
	print(s[:5])       # hello

	word = s[0:5]      # word: strview — a view, no copy
	print(word)

Bounds are byte offsets, not character indices — slicing inside a multi-byte character panics at creation:

fn main():
	s: str = "héllo"
	print(s[0:1])      # h — byte 0 is a boundary
	print(s[1:2])      # panics: byte 2 falls inside 'é' (bytes 1–2)

Scanning for ASCII delimiters (spaces, commas, newlines) byte-wise is always safe — UTF-8 never reuses ASCII bytes inside a multi-byte character. Character-level access comes from explicit decoding APIs (.chars(), planned), never from indexing.

Bytes

bytes is the binary sibling of str: an owned, heap-allocated, contiguous byte buffer. Literals use the b"..." prefix and accept the full \xNN escape range. Slicing yields a bytesview — the same zero-copy, non-escaping projection as strview, but with no UTF-8 boundary rule, so scalar indexing (b[i]) is allowed. Bridging to text is explicit: raw.to_str() validates UTF-8; text.to_bytes() makes an owned copy; text.as_bytes() is the zero-copy mirror — a bytesview over the string's UTF-8 bytes, with the usual view rules (non-escaping, freezes the owner while live). Choosing between them: reach for as_bytes() when you only read the bytes within the current scope (scanning, parsing, hashing); reach for to_bytes() when the bytes must outlive the call or become an owned, mutable buffer that diverges from the string. A to_bytes() copy that is never mutated and never escapes draws warning W0004 (RedundantToBytes) — the compiler's nudge toward as_bytes(). Concatenate with +, append a byte with bytes_push(&b, x); printing renders the escaped b"..." form.

fn main():
	raw = b"\x01\x02\x03"
	header = raw[0:2]             # bytesview — a view, no copy
	print(int_to_str(header[0]))  # 1

	mut buf = b"\x00"
	bytes_push(&buf, 255)
	buf = buf + raw
	print(buf)                    # b"\0\xff\x01\x02\x03"

Structs #

Structs are user-defined composite types with named fields. Declare one with struct and an indented field list; construct values with brace syntax — Point{x=1.0, y=2.0} — naming every field (no defaults). Field access is by name: p.x. By convention, struct names use PascalCase.

struct Point:
	x: float
	y: float

struct Rectangle:
	width: float
	height: float

fn area(rect: Rectangle) -> float:
	return rect.width * rect.height

fn main():
	p = Point{x=1.0, y=2.0}
	print(float_to_str(p.x))          # 1.0

	r = Rectangle{width=10.0, height=5.0}
	print(float_to_str(area(r)))      # 50.0

	mut q = Point{x=0.0, y=0.0}
	q.x = 7.0                         # field assignment needs `mut`
	print(float_to_str(q.x))          # 7.0

Field Access & Mutation

Copy vs. Move

A struct whose fields are all Copy types (numbers, booleans) is itself Copy — assignment duplicates it, and both sides stay usable. A struct that owns a non-Copy field (like str) moves on assignment: the old binding is dead afterward, and destruction recurses into the fields, freeing each owned buffer exactly once. Partial moves are rejected — you can't move a single field out of a struct.

struct Person:
	name: str
	age: int

fn main():
	p = Person{name="alice", age=30}
	q = p                  # moves — p is no longer usable
	print(q.name)          # alice
	print(int_to_str(q.age))  # 30

Printing & Equality

Every struct has an always-on Debug representation mirroring the literal syntax: print(p) writes Point{x=1.0, y=2.0}, nested structs render recursively, and primitives print bare (print(42), print(3.14), print(true)). Printing borrows the value — it stays fully usable afterwards.

Memberwise == / != is opt-in via #[derive(Eq)] on the struct definition; every field must be Eq-capable, and float fields use IEEE == (a struct holding NaN never equals itself). #[repr(C)] pins field layout to declaration order with standard C padding — the hook for future FFI.

#[derive(Eq)]
#[repr(C)]
struct Point:
	x: float
	y: float

fn main():
	p = Point{x=1.0, y=2.0}
	print(p)                          # Point{x=1.0, y=2.0}
	print(p == Point{x=1.0, y=2.0})   # true
	print(p != Point{x=3.0, y=4.0})   # true

Enums #

Enums — sum types, tagged unions — are user-defined types that hold exactly one of several named variants, each of which may carry data. Declare one with enum and an indented variant list. A variant takes one of three shapes: unit (Red), tuple (Circle(float)), or named fields (Rectangle(width: float, height: float)).

enum Color:
	Red
	Green
	Blue

enum Shape:
	Circle(float)
	Rectangle(width: float, height: float)
	Dot

fn main():
	c = Color.Green
	print(c)                              # Color.Green
	print(Shape.Circle(5.0))              # Shape.Circle(5.0)
	s = Shape.Rectangle{width=1.0, height=2.0}
	print(s)              # Shape.Rectangle{width=1.0, height=2.0}
	print(Shape.Dot)                      # Shape.Dot

Forms

Printing & Equality

Every enum has an always-on Debug representation mirroring construction syntax: print(c) writes Color.Green, tuple payloads render in parens (Result.Success(5)), named payloads in braces (Shape.Rectangle{width=1.0, height=2.0}). Printing borrows the value.

Variant-aware == / != is opt-in via #[derive(Eq)] on the enum definition (attributes attach to the definition, not to individual variants). Values compare equal when the variant matches and every payload field is equal — str payloads by content, floats by IEEE ==. Without the derive, == is a compile-time error.

An enum value owns the data in its active variant, so it follows the struct ownership rules: an enum holding a non-Copy payload (like str) moves on assignment, and the payload is destroyed with the value.

#[derive(Eq)]
enum Result:
	Success(int)
	Error(message: str)

fn main():
	r = Result.Success(5)
	print(r == Result.Success(5))             # true
	print(r != Result.Error{message="boom"})  # true

Anonymous Structs & Tuples #

Ryo has exactly one ad-hoc grouping type — the anonymous struct. Tuples are positional sugar over it: (17, "alice") is the same value as {0=17, 1="alice"}, one structural type, not two. Reach for an anonymous shape when data is local and transient (multi-return, unpacking); once a shape crosses a boundary or carries domain meaning, give it a name.

fn divmod(a: int, b: int) -> {q: int, r: int}:
	return {q=a / b, r=a % b}

struct Point:
	x: int
	y: int

fn main():
	# one shape crosses the boundary; two ways to take it apart
	(q, r) = divmod(17, 5)        # positional: binds in field order
	print(q)                      # 3
	{quot, _} = divmod(17, 5)     # named: quot = q, r is dropped
	print(quot)                   # 3

	pair = (17, "alice")          # sugar for {0=17, 1="alice"}
	print(pair.0)                 # 17
	print(pair)                   # (17, "alice")

	point = Point{x=q, y=r}       # graduation: explicit construction
	assert((1, 2) == (1, 2), "structural equality, no opt-in")
	print(divmod(17, 5))          # {q=3, r=2}

Forms

Printing & Equality

Debug rendering is always on and mirrors the literal syntax: all-positional shapes print in paren sugar — (3, 1), (3,) — while any named field switches to braces — {x=1, y=2} — with str fields quoted. == / != compare memberwise with no opt-in whenever every field type is Eq-capable; float fields use IEEE ==, so a shape containing NaN never equals itself.

Diagnostics

Pattern Matching #

match is an expression that tests a value (the scrutinee) against a list of patterns and yields the first arm whose pattern matches. Arms are tried in written order, the first match wins, and the compiler checks both coverage and arm types at compile time — an unhandled case is an error, not a runtime surprise.

enum Shape:
	Circle(radius: float)
	Rectangle(width: float, height: float)
	Dot

fn area(s: Shape) -> float:
	return match s:
		Shape.Circle(r): 3.14159 * r * r
		Shape.Rectangle(w, h): w * h
		Shape.Dot: 0.0

fn describe(n: int) -> str:
	return match n:
		0: "zero"
		42: "the answer"
		_: "just a number"

fn main():
	print(area(Shape.Circle{radius=1.0}))               # 3.14159
	print(area(Shape.Rectangle{width=3.0, height=4.0}))  # 12.0
	print(describe(42))                                 # the answer

Patterns

Exhaustiveness

Every possible value of the scrutinee must be covered. Enums need an arm per variant, bool needs both literals, and int / str / anonymous-struct scrutinees always need a _: arm. Incomplete coverage is E0129 — the error names the missing variants. Because arms run in written order, an arm that can never execute (anything after _:, or a duplicate of an earlier literal) is W0005, not a silent dead branch.

Ownership

A payload bind of a non-Copy field moves the payload out of the scrutinee — on that arm's path the value is consumed whole, shell included, and unbound fields that own memory are dropped when the arm starts. Matching a borrowed scrutinee (match &opt:) still allows Copy binds, but a by-move bind of a non-Copy field is E0133: match an owned value instead, or bind _ and read the field another way.

Diagnostics

Control Flow #

Ryo uses Python-style colons and indentation. There are if/elif/else, while, and for loops, plus break and continue.

fn classify(n: int) -> str:
	if n > 0:
		return "positive"
	elif n == 0:
		return "zero"
	else:
		return "negative"

fn main():
	mut i = 3
	while i > 0:
		print("countdown\n")
		i -= 1

	# range(start, end) is half-open: 0, 1, 2, 3, 4
	for j in range(0, 5):
		print(int_to_str(j))

The for loop iterates a half-open integer range produced by range(start, end): it yields start through end - 1.

Functions #

Functions are declared with fn. Parameters carry explicit type annotations; the return type follows the parameter list after ->. Omit the return type for a function that returns nothing (void). By convention, functions and variables use snake_case.

# Two int inputs, returns int.
fn add(x: int, y: int) -> int:
	return x + y

# No return value — return type omitted.
fn greet(name: str):
	print("Hi, " + name)

fn main():
	result = add(3, 4)
	greet("Ryo")

Operators #

Operator precedence follows the usual mathematical rules. Parentheses group sub-expressions.

# Multiplication and division bind tighter than + and -.
result = 1 + 7 * (3 - 4) / 2     # = 1 + (7 * -1 / 2) = 1 + (-3) = -2

Built-in Functions #

These are available in every file without an import — the Prelude.

Ownership Lite #

Ryo is memory-safe without a garbage collector and without lifetime annotations. Every binding owns its value; how a function receives an argument is declared once, on the parameter, and the compiler enforces the rules. The design is inspired by Rust's borrow checker and Mojo's eager destruction.

There are three parameter modes, chosen by a keyword between the colon and the type:

One rule ties them together: call sites are sigil-free for every mode except the mutable borrow, which takes a & at the call site to make mutation explicit. The signature does the rest.

Borrow Modes in Practice #

Immutable borrow (default)

A plain parameter is borrowed read-only. The caller keeps the value and can use it again afterwards.

fn read_text(text: str):
	# text is implicitly borrowed — read-only
	print(text)

fn main():
	mut message = "Hello"
	read_text(message)        # implicit borrow
	print(message)            # message still usable

Mutable borrow (inout + &)

An inout parameter may be mutated by the callee. The caller passes it with an explicit & so every mutation is visible at the call site.

fn mutate_text(inout text: str):
	text = text + ", mutated"

fn main():
	mut message = "Hello"
	mutate_text(&message)    # explicit & at the call site
	print(message)            # Hello, mutated

Move (move)

A move parameter takes ownership. After the call, the caller's binding is dead — reading it is a compile error. Inside the callee the value is dropped at its last use, not at return (unless it moves it onward).

fn take_text(move text: str):
	modified = text + ", owned"
	# text's last use — it is dropped here, before the print
	print(modified)

fn main():
	message = "Hello"
	take_text(message)        # ownership moves into take_text

	# print(message)          # compile error: `message` was moved

The Seven Rules #

Every ownership diagnostic is an instance of seven formal rules from the spec (§5.3):

Why No GC, Ever #

All of the ownership ceremony buys one thing: deterministic destruction. Every value's resources — heap buffers, sockets, file handles — are released at a point the compiler can see: at last use, or at the end of the scope. There is no garbage collector to pause your program, no finalizer running late, no refcount traffic on the hot path. And because borrows are scoped to a single call, most of the fights people have with Rust's borrow checker simply never happen.

Where Ownership Lite Draws the Line #

Honesty time: the same rules that delete the lifetime vocabulary also forbid one fundamental capability — a borrow that outlives the call it was created in. It can't be returned, stored, or sent anywhere. Four shapes of programs are unbuildable in the safe model because of exactly that one sentence — and for each, here's what's enforced in the compiler today versus what's already written into the spec as the planned way out:

Enforced today the compiler rejects this code right now. Spec'd · in progress designed and specified, but not yet implemented — the blocker is named on each card.

Not on this list: disjoint field borrows, borrowed graph edges, interior mutability. Those change how you write the program — split the call, use IDs, opt into shared[T] — never whether you can. Every application has a mechanical rewrite; there is always an escape hatch for the rest.

What's Next #

Ryo is pre-alpha. The features below are specified and on the roadmap but not yet implemented — they do not compile today. This list tracks the largest items.

For the full picture, see the Language Specification and the Implementation Roadmap.