This page describes Ritchie as the current compiler implements it, one topic per section. It is the language capsule of the Ritchie Skill, the description coding agents learn Ritchie from, so it is compact: every sentence is a rule you can rely on, and a rule the compiler enforces names the diagnostic it reports, such as syntax.unexpected-token.
Every example is a complete program. To run one, install the compiler, save the example as example.ri and run rcrun example.ri, or paste it into the Playground.
Program basics
- Source files use the
.riextension, and comments are//and/* ... */. An executable has onemain()with no parameters, no result, and no error list. - Newlines end statements, and semicolons separate statements on one line. A statement continues onto the next line only inside parentheses, square brackets, or the braces of a construction, so a line break beside a binary operator needs enclosing parentheses.
- Values and functions start lowercase, one-letter ones too, so
Int N = 1is rejected withname.unexpected-class. Types and services start uppercase and contain a lowercase letter, as in@Db, and constants are all uppercase with at least two characters, such asMAX_N. - Every variable and constant is declared with its type, as in
String DIGITS = "0123", notDIGITS = "0123". Module level declares constants of any type, such as[String: Int] RANK, but no variables, so a lowercase name there is rejected withname.unexpected-class. - Boolean operators are
and,or, andnot, andandandorskip the right operand when the left decides, as ini < n and xs[i] > 0.&&,||,!x,++, and--do not exist; writen += 1. - Precedence, tightest first: member access, call, index; unary
-;*/%;+-;??;<<=>>=;==!=;not;and;or;c ? a : b, which does not nest. A chain such asa < b <= cholds when each neighbouring pair holds, and one that mixes<and>forms is rejected. print(v)writesvand a line break to standard output, andlog(v)to standard error.- A local variable that is not read is a compile error; a loop variable or a parameter may stay unread.
- Keywords cannot be names, locals included:
and any break case contract continue create else embed exhaustive false for handle if in is match none not or resume return self then true unique where.
Variables and functions
Int LIMIT = 42
double(Int value) -> Int { return value * 2 }
pair() -> (Int, Bool) { return 1, true }
greet(String name, String greeting = "hello") -> String {
return f"{greeting} {name}"
}
main() {
Int total = double(LIMIT)
Int left, right = 1, 2
Int n, Bool ok = pair()
Int later
later = left + right
String who = greet(name: "ada")
print(f"{total} {n} {ok} {later} {who}")
}
A call written as a statement discards its results. A declaration binds every
result, so Int n = pair() is rejected with variable.arity, and each of its
variables, _ too, must be read. A variable must be assigned on every path
before it is read. Arguments are all positional or all named.
Function types are written (Int, Int) -> Int. A closure is written with
=> and captures copies of the variables it uses:
apply(Int x, (Int) -> Int f) -> Int { return f(x) }
main() {
Int offset = 10
(Int) -> Int add = x => x + offset
print(apply(1, add))
print(apply(2, x => x * x))
(Int, Int) -> Int plus = (a, b) => a + b
print(plus(3, 4))
}
Numbers
Intis 64-bit.Int8,Int16, andInt32widen to wider integers. Integer/truncates toward zero,%takes the dividend's sign, and division by zero raisesDivisionByZero!.Floatis binary64.printand an f-string slot write the shortest text that reads back as the same value, so198.0prints198and0.1 + 0.2prints0.30000000000000004, in exponent form from an exponent of 6 or below -4, as in1.5e+07and1e-05.Decimalis exact decimal arithmetic that keeps the written scale. A literal with a fraction part, such as0.00, is aDecimalwhere aDecimalis required and aFloatotherwise: afterDecimal a = 1.20,print(a + 3.400)prints4.600,Decimal b = 1.25 * 3.00holds3.7500, andprint(1.20 + 3.400)prints theFloat4.6.- Integers, Floats, and Decimals do not mix in arithmetic or comparisons,
so convert with
Float.fromInt(n),Decimal.fromInt(n), orInt.fromFloat(x), which truncates toward zero. - A
Byteholds 0 to 255.Byte.fromInt(n)andInt.fromByte(b)convert,Byte[].fromString(s)gives the UTF-8 bytes ofs, andString.fromBytes(bs)decodes them, raisingMalformed!for invalid UTF-8.
Conditions, match, and loops
grade(Int score) -> String {
match {
case score >= 90 => { return "A" }
any => { return "C" }
}
}
main() {
print(grade(85))
}
if c { } else if d { } else { } takes no parentheses. A match with a
subject compares it with each case value, such as a literal or a constant,
and one without tries each case condition, in order. The first selected arm
runs, in braces, and any is the remainder. A match that lists every enum
member does not count as returning on every path, so when its arms return,
write the last member as any.
main() {
for i in range(3) { print(i) } // 0, 1, 2
for i in range(2, 8, 3) { print(i) } // 2, 5
for x in [10, 20] { print(x) }
for k, v in ["a": 1] { print(f"{k}={v}") }
Int n = 0
for n < 3 { n += 1 }
outer: for r in range(3) {
for c in range(3) {
if r + c == 3 { break outer }
}
}
}
for { } loops until break. break and continue, also in a match
arm, act on the innermost loop, and break name or continue name act on
the loop labelled name:.
Structs, methods, and enums
Point {
Int x
Int y = 0
}
Point.shift(Int dx) {
self.x += dx
}
Figure { CIRCLE, SQUARE }
main() {
Point p = Point { x: 1 }
p.shift(4)
print(p)
Figure s = Figure.SQUARE
match s {
case Figure.CIRCLE => { print("round") }
case Figure.SQUARE => { print("square") }
}
print(s)
}
This prints Point { x: 5, y: 0 } first and SQUARE last. A method that
uses self may change its receiver when that is a variable, a field, or an
element, so counters[i].advance() updates the array. A method without
self is called through its type, as in Point.origin(). Assigning,
passing, or returning a struct copies it. A struct contains itself only
through a nullable field, an array, or a dictionary, such as
Node? next = none.
Arrays
main() {
Int[] xs = [3, 1, 2]
xs = append(xs, 4)
xs[0] = 9
print(xs[1:3])
print(sort(xs))
}
Array operations are free functions: count, contains, indexOf (an
Int?), first and last (nullable), append, insert(xs, i, v),
removeAt(xs, i), concat, reverse, sort, and fill(v, n). No array
function changes its argument, so sort(xs) alone does nothing: write
xs = sort(xs) and xs = append(xs, v). An empty literal [] needs a
declared type. grid[r][c] = 0 assigns one element of an Int[][].
Int[3] holds exactly 3 elements and is a type apart from Int[], which
its slice k[0:3] is. A module constant Int[] MISS = [-1] acts as an
Int[1] in a handler arm, append, and ==, so bind
Int[] miss = MISS first. Slices xs[lo:hi] are half-open, and
indexing out of range raises OutOfRange!. map, filter, reduce,
sum, find, and sortBy do not exist, and + and += do not apply to
arrays.
An index or key in an assignment target is a variable or its field, a
literal, or +, -, or * of them. Any other, such as an element or its
field, a slice, /, %, an f-string, or a call such as toLower(w), as in
d[f[0]] = 1, is rejected with assignment.fallible-operand, so bind it to
a variable first. A read takes any index or key.
Assigning an element or entry, also through self, and assigning the result
of append, concat, insert, removeAt, or remove to the same
variable, field, element, or entry change the value in place, as in
xs = removeAt(xs, count(xs) - 1) and d[k] = append(d[k], v), and
for i in range(n) builds no array. A function copies an array or
dictionary parameter at each call only when it assigns to it, and the caller
sees the change only through a returned value. A slice and s = f"{s}..."
copy the whole value, so repeating them on a large value takes quadratic
time: collect strings in an array for join.
Strings
main() {
String[] names = []
for name in split("usr/local/bin", "/") {
names = append(names, replace(name, "l", "L"))
}
print(join(reverse(names), " < "))
String word = "hello"
Int at, Bool found = indexOf(word, "l")
print(f"{at} {found} {count(word)} {word[1:3]}")
}
- String operations are free functions that take the string first:
count,isEmpty,contains,startsWith,endsWith,indexOf,toUpperandtoLower, which also convert non-ASCII letters,trim,replace(s, old, new),split(s, sep), andjoin(parts, sep).splitkeeps empty fields:split("a b", " ")is["a", "", "b"], andsplit("", " ")is[""]. - An f-string slot cannot contain a string literal, so
f"{join(xs, "/")}"is rejected withinterpolation.unterminated: bindString sep = "/"first. Doubled braces write a literal brace.+does not join strings. - Positions and counts are UTF-8 bytes.
s[i]is rejected, and a slice whose start or end falls inside a character raisesInvalidStringBoundary!: forString s = "é!",count(s)is 3,s[0:1]raises it, ands[2:3]is!.split(s, "")gives the characters,["é", "!"], whosecountis 2. <,>,==, andsortorder strings by their UTF-8 bytes, so"Z" < "a"and"é" > "z".- Quoted strings take escapes such as
\n,\t, and\", and a backtick string is raw and may span lines. Int.fromString(s)accepts a sign and digits, so"075"gives75, and raisesMalformed!for other text, such as" 5".
Dictionaries and nullable values
main() {
[String: Int] ages = ["ada": 36]
String[] f = split("lin 41", " ")
String who = f[0]
ages[who] = Int.fromString(f[1]) // not ages[f[0]]
ages["ada"] = (ages.get("ada") ?? 0) + 1
print(ages["ada"])
Int? maybe = ages.get("bo")
if maybe {
print(maybe)
} else {
print("absent")
}
}
[K: V] is a dictionary and [:] is an empty one. d[k] raises
MissingKey! for a missing key, d.get(k) returns V?, and has, keys,
values, remove, and count are free functions. Iteration and keys
have no fixed order. T? holds a T or none; test it with if x or
x != none before using it as T. A test that leaves the function, such as
if v == none { return -1 }, narrows v to T for the rest of the
function, so a later v ?? 0 is rejected there.
Errors
Low! { Int n }
High! {}
check(Int n) -> Int {
if n < 0 { return Low! { n: n } }
if n > 9 { return High! }
return n
}
main() {
Int a = check(-2) handle Low! e => e.n * 10
Int b = check(20) handle {
Low! => 0
High! => 99
}
print(f"{a} {b}")
for n in [1, -1, 50] {
Int c = check(n) handle {
Low! => continue
High! => break
}
print(c)
}
print(check(-5))
}
Returning an error value raises it, also from main or a function without a
result, and a function's result type stays the success type. A function may
list its errors after the result with |, as in -> Int | Low! | High! or
-> none | Low!, and a function without a list may raise any error. A list
names every declared error type that can leave the function, its callees'
included, and no other (contract.undeclared-error,
contract.unraised-error), and a function that calls a function value cannot
have one. A function that returns nothing ends with a bare return or at its
end, and return none is rejected.
Built-in errors, such as OutOfRange!, MissingKey!, Malformed!,
LengthMismatch!, and the remote failures, form a catalog: declaring one
is rejected with name.reserved-name, no error list may name one, and
constructing one is rejected with error.catalog-construction except
under rcc --debug.
handle follows the whole statement it protects, not an argument or other
part of it, on the line where that statement ends. An arm replaces the
statement's whole value, such as the new xs of xs = append(xs, f(n)),
or runs continue, break, or return, return E! in an arm raises
another error, as in Low! => return High!, and E! e binds the error
when the arm reads it. A block arm, such as
Low! e => { print(e.n); continue }, supplies a replacement value by ending
with resume value. A handler after a block or a loop, with handle on the
line of the closing brace, protects each statement inside, so after an arm
that completes, the block continues with its next statement, and continue
and break in an arm of for x in xs { ... } handle { ... } act on that
loop. A variable that a protected statement assigns has a value after it
only when every arm that completes assigns it too, even when it held a
value before.
Type aliases
Name = Type at module level gives a type a second name. An array of a
function type needs an alias, as in Step = (Int) -> Int and
Step[] steps = [x => x + 1]. A nullable function value such as Step?
cannot be tested, compared with none, or called, so pass a function with
the default behavior instead.
Services
A service is declared as @Name {}, and its methods have no self, take
defaults and list errors like a function, and are called as
@Name.method(...). Their parameters and results are built-in types,
structs and enums that have a method whose name does not start with _, and
arrays and dictionaries of them; any other type is rejected with
service.boundary-type. Over HTTP a struct is a JSON object of its fields
and an enum the name of its member, as in "GREEN".
Clock, durations, and random numbers
A Duration literal is an integer with a unit, ns, us, ms, s, m,
h, or d, such as 1500ms; 1.5s is rejected.
r::Clock.sleep(300ms) suspends the caller, and
r::Clock.time() returns the current DateTime. DateTime.fromUnix(n) is
the instant n seconds after 1970-01-01 UTC, which prints as
2026-03-02T11:00:00Z, and t.withOffset(330m) prints the same instant as
2026-03-02T16:30:00+05:30. t + d adds a Duration, t - u gives one, and
n * 1s makes one, which prints its nonzero parts, as in 1d9h30m or
505ms33us, and 0s for zero. Dividing two durations gives a Float, so
Int.fromFloat(d / 1ms) is the count of milliseconds.
A Date is written and printed as d2026-03-02 and a Time of day as
t23:30:00.5, and f"{d}"[1:] drops the letter. A Time wraps at
midnight under + and - of a Duration, t01:00:00 - t23:30:00 is
-22h30m, and t23:30:00.until(t01:00:00) is 1h30m. A Date has
addDays(n), addYears(n), daysUntil(other), an Int, and
addMonths(n), which gives d2026-02-28 for d2026-01-31.addMonths(1).
For a date's parts y, m, and d, the month's first day is
Date f = d0001-01-01.addYears(y - 1).addMonths(m - 1), its length
f.daysUntil(f.addMonths(1)) bounds a valid d, and the date is
f.addDays(d - 1).
r::Random g = r::Random.seed(s) makes a generator whose draws are the
same for the same Byte[32] s, and r::Random.new() makes an unseeded one.
g.range(lo, hi) draws an Int in [lo, hi),
g.ratio() a Float in [0, 1), and g.bits() a 64-bit BitSet, which
prints as 0x and 16 lowercase hexadecimal digits and can key a
dictionary. A literal such as 0 is a BitSet where one is required.
Assigning or passing a generator copies it, so a helper that draws returns
it, as in -> (Int, r::Random), or draws through a struct field as
self.g. Byte[32] s = fill(Byte.fromInt(0), 32) makes a seed.
Remote failures and the time budget
The runtime can fail a service call with a catalog error:
Unavailable!, Rejected!, Conflict!, Unmodified!, and Cancelled! mean
the call changed nothing, and Unverified! means a write may or may not have
happened. This example constructs Unavailable! itself to stand in for a
failing service, so it runs only as rcrun --debug.
@Weather {}
@Weather.reading(String station, Duration d) -> Int {
if station == "north" { return Unavailable! }
r::Clock.sleep(d)
return 3
}
main() {
Int a = @Weather.reading("north", 0ms) handle Unavailable! => -1
Int c = @Weather.reading("west", 2500ms) handle Cancelled! => -2
print(f"{a} {c}")
}
Every program runs under a time budget, 2000 ms by default, which limits
its service calls; other code, such as an r::Clock.sleep in main,
continues past it. RITCHIE_ENTRY_BUDGET_MS sets it for a run, and the
program text cannot set or read it. A service call starts only within the
first 70 percent of the budget, and a later one fails at once with
Cancelled!. A started call without a response when the budget ends fails
with Cancelled!, not Unverified!. Enforce time limits through this
budget and its errors, not by timing calls.
Futures
A call of a service method starts where it is written, and the program waits for its result at the first use of the value.
- Storing a result in a variable or an array element, or appending it to an
array, does not wait when the target has the result's type, but a
T?target for aTresult waits.count(xs)of an array of results does not wait either. Every other use waits, such as a dictionary entry, a field, arithmetic,if, an argument of another call, andprint. - A use waits for its call and every call started before it, and so does a call of a function value. So of two failed calls the program sees the earlier one, and a loop whose body starts a call and also uses its result or calls a function value runs its calls in sequence. Collect the results in an array in one loop and use them in a second loop.
- A local routine whose body calls services, writes no output, has no
forloop withoutin, and does not call itself, also through other routines, starts at its call in the same way, so a routine for one item, which may use its results and handle their failures, can be called for every item and the calls run together. - A call's failure is raised at the call's statement, and only a handler
there catches it; an arm on a later use that nothing else selects is
rejected with
handle.dead-arm. - A handler whose arms are each a literal, a constant, or a variable, such
as
handle Low! => 0, or only return one, as inhandle Low! => { return 0 }, does not wait, so a stored marker can stand for a failure. Any other arm, such as an f-string, waits. - Leaving a routine waits for every call written before the exit and cancels every call written after it.
- A call with a side effect also starts early, so to start a call only after
an earlier call has succeeded, use the earlier result first, as in an
if.
Low!
@Gauge {}
@Gauge.level(Int id) -> Int | Low! {
r::Clock.sleep(50ms)
if id == 9 { return Low! }
return id
}
@Gauge.trend(Int lv) -> Int { r::Clock.sleep(50ms); return lv * 2 }
reading(Int id) -> Int | Low! {
Int lv = @Gauge.level(id)
Int tr = @Gauge.trend(lv)
return lv + tr
}
main() {
Int[] sums = []
for id in [1, 2, 3] {
sums = append(sums, reading(id))
}
Int total = 0
for s in sums { total += s }
print(total)
Int bad = reading(9) handle Low! => -1
print(bad)
}
Projects and modules
A project is a directory with NAME.ritchie.toml, whose [modules] table
maps each module to its directory, as in stock = "stock". Every .ri file
under that directory belongs to the module, and at most one module declares
main. rcc with no file, run in the project directory, writes NAME, or
NAME.run when a service is declared.
:: reaches another module, as in stock::Item.find("pen"),
stock::Missing! e, and stock::@Depot.level("pen"). Only a type with a
method whose name does not start with _, those methods, an error type and
its fields, and a service cross modules. Fields, struct literals, free
functions, and constants are rejected in another module with
module.unpublished-member. A served method's path names its module, as in
/stock/Depot/level.
Known defects
The current compiler departs from the language in these forms, so write the alternative.
- An enum that gives values to some members only crashes
rcc, so give values to every member or to none. - A struct field cannot hold a function, but
rccaccepts one and can fail to build the program, so pass a function as a parameter or keep it in a variable, an array, or a dictionary.
