This is the compact reference for syntax accepted by Dodo 0.1.6. New to the language? Begin with values and arrays, functions and data types, and control flow. The language specification states the normative rules; the examples and limits here describe the current compiler.
Source-file structure
package main
import "core/slice"
const LIMIT: usize = 3
struct Sample { value: i32 }
fn main() {
values := [10i32, 20, 30]
core.assert_eq(values.len, LIMIT)
match slice.get(&values, 1) {
some(value) => { core.assert_eq(*value, 20i32) },
none => { core.assert(false) },
}
}
Every source file starts with package name, apart from comments and separators.
Top-level declarations are fn, struct, enum, interface, type, const,
and static; imports
make another package’s public names available through a qualifier. There is no
top-level executable statement or automatic init function. See
projects and imports for file discovery and visibility.
Source text and statement boundaries
Source is UTF-8. Identifiers are case-sensitive ASCII letters/underscores followed
by ASCII letters/digits/underscores. Comments use //. Newlines terminate
statements; semicolons also separate statements and three-part loop clauses.
Delimited expressions and expressions continued after an operator accept
newlines. A newline also continues an expression when the next non-newline token
is .; indentation, blank lines, and line comments do not change this rule.
An explicit semicolon ends the expression. Other leading operators do not gain
continuation outside delimited expressions. Braces delimit control-flow bodies;
match arms also accept expressions.
Block comments, raw strings, ordinary character literals, Unicode identifiers,
and a UTF-8 byte-order mark are unsupported. /// is an ordinary line comment.
Reserved keywords are:
package import pub fn struct enum interface type dyn const let return if
else for in break continue match unsafe extern as from static void mut
true false
self, Self, primitive type names, and constructor names have contextual
meanings. stores and requires_plain introduce specialized function contracts
described in container element safety.
Literals and strings
Integer literals support decimal, 0x, 0o, 0b, digit separators, and type
suffixes. Unsuffixed integer literals use contextual types and otherwise default
to isize. Floating literals use decimal fractions/exponents and optional
f32/f64 suffixes; their default is f64. Boolean literals are true and
false. Strings and byte strings have immutable program-lifetime storage.
Strings support the escapes listed below; &str.len counts UTF-8 bytes. String
indexing is rejected; use a byte slice for byte indexing. There is no implicit
string allocation or mandatory NUL terminator.
| Literal | Example | Type or interpretation |
|---|---|---|
| Integer | 42, 42u32, 0xffu8, 0o755, 0b1010 |
Contextual integer; default isize. |
| Float | 1.5, 1e3, 2f32 |
Contextual float; default f64. |
| Boolean | true, false |
bool; no numeric truthiness. |
| Byte | b'A', b'\xFF' |
Exactly one u8. |
| Byte string | b"ABC" |
Shared &[u8] with program-lifetime bytes. |
| String | "Dodo", "\u{1F426}" |
&str, valid UTF-8. |
All quoted literals accept \n, \r, \t, \0, \\, \", \', and
\xHH. Only strings accept \u{...} with one to six hexadecimal digits for a
Unicode scalar value. Byte literals and byte strings require ASCII source
characters or byte escapes. Physical newlines cannot appear inside a literal.
Integer literal magnitude must fit u64; - is a separate prefix operation.
Type syntax
| Syntax | Meaning |
|---|---|
bool |
Boolean value. |
i8, i16, i32, i64; u8, u16, u32, u64 |
Fixed-width signed and unsigned integers. |
isize, usize |
Target-pointer-sized integers. |
f32, f64 |
IEEE binary floating-point values. |
void |
No return value. |
[N]T |
An owned fixed-length array. |
&T, &mut T |
Checked shared or exclusive reference. |
&[T], &mut [T] |
Shared or exclusive slice. |
&str |
Shared UTF-8 string view. |
*const T, *mut T |
Nullable raw pointer. |
Name, package.Name, Name<T, U> |
User-defined struct or enum type, or a type alias. |
(A, B, ...) |
A tuple of two or more elements; (T) only groups T. |
Option<T> |
some(T) or none. |
Result<T, E>, T!E |
ok(T) or err(E). |
MaybeUninit<T> |
Opaque storage for potentially uninitialized T. |
fn(A, B) -> R, fn(A) |
Function pointer; an omitted result means void. |
&dyn fn(A) -> R, &mut dyn fn(A) -> R |
Closure reference that reads, or may modify, captured bindings. |
Self is valid inside a struct declaration and names its current type. Result
shorthand binds outside references and slices: &T!E means Result<&T, E>.
Use the full spelling to make nested type relationships clear. &dyn I and
&mut dyn I refer to a value implementing interface I; see
interfaces. A function pointer’s -> R
extends to the end of the type, so fn() -> u8!E returns Result<u8, E>.
&fn(..) is an ordinary reference to a function pointer.
type Name<T> = Type declares a transparent alias: every use is replaced by the
aliased type before checking, so the alias and the type are interchangeable. An
alias may be pub; its parameters cannot have bounds, aliases cannot form a
cycle, and a public alias cannot expose a private type. An alias of a struct or
enum is accepted in struct literals and patterns, variant paths, and static
function calls. Tuple values are written (a, b) and their elements are read
and assigned with .0, .1, …; digits after . always form a tuple index,
so pair.0.1 is nested access. A tuple is a struct with public fields 0,
1, …: it moves, owns its elements, and has no automatic equality. Tuple
patterns (p, q) nest in every pattern position, and for (a, b) in values,
for &(a, b) in values, and for i, (a, b) in values destructure elements.
See tuples and type aliases.
Closure literals and calls
fn(a: A, b) -> R { body } is a closure literal. Parameter types and the result
type may be omitted where the expected type supplies them; an omitted result
without context is inferred from final expressions and return values, or is
void. The body follows function rules for implicit returns, return, and ?.
A closure on one line with a single expression stays on one line when
formatted; longer bodies are indented like a block.
name(args) calls a local function value instead of a function of the same
name. Other callee expressions are called with ordinary postfix syntax:
(table[i])(x), make()(x), and value.field(x) when value has a
function-valued field and no method of that name. Type arguments apply only
to named generic functions, not to function values.
Operators and evaluation order
From weakest to strongest:
| Precedence | Operators |
|---|---|
| 1 | || |
| 2 | && |
| 3 | | |
| 4 | ^ |
| 5 | & |
| 6 | ==, != |
| 7 | <, <=, >, >= |
| 8 | <<, >> |
| 9 | +, - |
| 10 | *, /, % |
| 11 | as Type |
| 12 | Prefix -, !, ~, *, &, &mut |
| 13 | Calls, .field, [index], subslices, postfix ? and ! |
Parentheses override precedence. Prefix ! negates a Boolean; postfix !
unwraps a Result or panics. & is a shared borrow in prefix position and integer
bitwise AND in binary position. Prefix * dereferences; binary * multiplies.
Binary operators associate left. Operands, call arguments, and literal fields
are evaluated left to right; && and || short-circuit. Compound assignment
evaluates the destination address once, then its previous value, then the right
operand. Numeric operands must have compatible types; there are no implicit
mixed-width conversions between already typed values.
=, +=, -=, *=, /=, %=, &=, |=, ^=, <<=, and >>= are
statements, not expressions. Comparisons do not chain mathematically: use
low <= value && value < high. Equality supports primitive scalars, raw pointers,
and payload-free enums; arbitrary aggregate equality is unavailable. Operators
cannot be overloaded.
Declarations and returns
const LIMIT: usize = 16
struct Point {
x: i32
y: i32
fn magnitude_squared(&self) -> i32 {
self.x * self.x + self.y * self.y
}
}
enum Message { End, Count(value: u32), Pair(u8, u8) }
fn add(left: i32, right: i32) -> i32 {
left + right
}
Canonical bindings, fields, constants, and parameters use name: Type. The earlier
type-first forms remain supported for locals, fields, constants, and enum
payloads. An omitted function return type means void. Struct receivers accept
self, &self, and &mut self; field literals accept same-name shorthand.
Non-void functions return their final expression unless it ends with a semicolon;
final conditionals, matches, and blocks follow the same rule. Explicit return
provides early exits. Void functions retain statement semantics.
All non-void parameter and return types are declared; inference does not derive
function signatures. Struct literals use named fields, enum payloads are
positional, and function arguments are positional. Methods live inside structs;
associated functions omit a receiver and use Type.name(...). See
functions, structs, and enums for complete examples.
Mutable and immutable bindings
| Form | Mutable binding? | Initialization |
|---|---|---|
let value = expression |
No | Required; inferred type. |
let value: T = expression |
No | Required; explicit type. |
value := expression |
Yes | Required; inferred type. |
value: T = expression |
Yes | Explicit type. |
value: T |
Yes | Must initialize on every path before reading. |
const VALUE: T = expression |
No | Compile-time expression required. |
let name = value and let name: Type = value create immutable runtime bindings.
:= and ordinary typed locals remain mutable; const remains compile-time-only.
Immutability prevents reassignment, mutable borrowing of owned storage, and writes
to owned fields/elements. It does not weaken a stored &mut T or mutable slice:
writes through those references remain permitted, including field/index writes.
A moved-from binding is uninitialized for reading until it is reinitialized. See ownership and borrowing for moves, loans, and cleanup.
Generic syntax and inference
Explicit generic calls canonically use f::<T>(); the earlier f<T>() spelling
remains accepted. Types and generic declarations use angle brackets without ::.
Generics are monomorphized. Function calls and struct literals infer omitted
type arguments from arguments, fields, and expected result types. Examples are
identity(42i32), value: i32 = identity(42), and Box{value: 42i32}. some(value)
infers its Option payload. Ambiguous calls require explicit arguments, such as
make::<i32>(); explicit forms remain accepted. Inference follows local expression
context, not later uses of a binding. Function signatures remain declared.
Type parameters may be bounded by interfaces, <T: io.Reader + io.Writer>,
which are checked where the generic declaration is used. Specialization and
separately compiled generic code are not implemented. Recursive expansion is
bounded and diagnosed.
The generics tutorial explains generic structs, associated
functions, interfaces, bounds, and dyn references with executable examples.
Formatting and syntax migration
dodo fmt [FILE|DIRECTORY] migrates historical syntax and applies four-space
indentation and consistent spacing while preserving comments and literal text.
Directory formatting recurses through .dodo files, excluding hidden directories,
target, build, and symlinks. The default input is the current directory.
--check exits 1 for formatting differences and writes nothing; --stdout
previews one file. Input - reads stdin and writes stdout (or checks with
--check). Formatting parses every input before replacing any file, requires no
imports or type checking, and stages replacements for atomic per-file renames.
An unchanged file is not rewritten. Syntax errors leave all inputs untouched.
Legacy forms remain supported in 0.1; removal or warnings belong to a future
announced deprecation after this migration path is available.
See the command-line guide for formatting commands.
Arrays and constants
Array lists infer their length and element type from context or their elements.
Bracket arrays are canonical. A binding annotation supplies explicit types,
as in values: [2]u16 = [1, 2]. A list in any expression can retain its type and
length with ([1, 2]: [2]u16) or ([]: [0]u8). The annotation applies only to
an unannotated bracket list and lowers to the same typed literal as the legacy
[2]u16{1, 2}. The formatter migrates legacy typed literals to that annotated
bracket form, including nested and constant arrays. This preserves element types
and length checks without introducing copying or runtime conversions.
Repeated arrays evaluate their initializer once, even for a zero length, and
require a copyable element. Constant initializers support checked scalar
operators/conversions, strings, arrays, repeated arrays, and struct literals.
They may reference other constants. Package constants permit forward references;
local constants follow lexical scope. Cycles and mutable-static dependencies are
rejected. Array lengths accept integer constant expressions and use the selected
target width. Compile-time function calls are not implemented.
Compiler resource limits
Syntax nesting is bounded to 64 parser levels. Constant dependency depth is bounded to 128; expansion work is bounded to 200,000 nodes. Array lengths must fit the target’s usize and LLVM’s 32-bit element-count limit. Nonzero repeated constant arrays are limited to 1,000,000 elements; zero initialization has a compact representation. These limits produce diagnostics.
Pattern expansion has a separate limit of 4,096 alternatives per pattern and 131,072 coverage work units. See patterns for coverage semantics.
Value-producing blocks
if, match, unsafe, and plain blocks produce values in expression positions.
Every continuing path must yield the same type; at least one value-producing
path is required. Results are transferred before local cleanup. Explicit returns,
propagation, break, and continue retain their surrounding control-flow meaning.
The checker rejects local-storage borrows escaping a value block and preserves
loans from earlier arguments while checking nested blocks.
Ranges and collection loops
for is the only loop keyword. The statement forms are for { ... },
for condition { ... }, for init; condition; step { ... }, and
for item in collection_or_range { ... }. break and continue target the
nearest enclosing loop. There are no labeled loops or loop result values.
See decisions and loops for examples of every form.
for i in start..end captures both integer bounds once and excludes end. Empty
and reversed ranges do not iterate. Loop bindings are fresh, and assigning them
does not change the counter. Ranges have no general value or iterator protocol.
Collection loops still bind shared &T elements or exclusive &mut T elements.
A tuple pattern in place of the element name, for (a, b) in values, binds
references to that element’s fields; for &(a, b) in values copies each bound
field and requires those fields to be copyable.
for &value in values and for index, &value in values explicitly copy a shared
element into a fresh T binding. T must satisfy the ordinary copyability rule;
owned arrays, structs, enums, and mutable references/slices are rejected. Assigning
the copied binding cannot mutate the source. The collection is evaluated once and
stays borrowed for the loop, and copied references retain their borrow dependencies.
The index remains usize. Reference patterns on integer ranges, on the index, or
on mutable iteration are rejected; use a shared reborrow to copy from a mutable
collection view. &mut value binding patterns are not supported.
Slices and bounds
Subslices use &data[start..end] or &mut data[start..end]; bare slicing produces
a shared view. Omitted bounds default to zero and length. Source and bounds are
evaluated once and checked in every optimization profile. The captured source
is reserved while bounds run: they may read it, but cannot move or mutate it.
Exclusive access is established after the bounds. Indexed loans remain
conservative: separate ranges do not prove mutable slices disjoint.
Numeric behavior
Signed integers use two’s complement. isize and usize follow the selected
target’s pointer width. Integer arithmetic and left shifts trap if the result
cannot be represented. Both division and remainder trap for a signed minimum
value and divisor -1, as well as for zero divisors. Shift counts must be
nonnegative and smaller than the value’s bit width. Integer conversions check
range; they do not truncate or wrap. Float-to-integer conversion truncates toward
zero after checking the finite source against the destination’s half-open range
before truncation (-0.5 as u8 traps; 255.75 as u8 is 255).
Integer-to-float conversion rounds directly to the target floating representation,
with identical results for constant and runtime conversions.
Narrowing floats checks finite range, rejecting NaN and infinity. Identity and
widening float casts preserve NaN, infinities, and signed zero in both constant
expressions and runtime code. Floating arithmetic follows LLVM’s IEEE operations
without fast-math flags. Constant
floating arithmetic uses binary64 intermediates and rounds to the expression’s
type at each node. Integer-to-f32 casts round directly to binary32; an explicit
cast through f64 still performs both conversions. Decimal literals are parsed
through binary64. These implementation-defined choices are recorded as ID-FLOAT in
specification Appendix C.
Explicit wrapping operations are core.wrapping_add(a, b),
core.wrapping_sub(a, b), and core.wrapping_mul(a, b), available without an
import. They wrap modulo the operand width, interpreting signed results as
two’s complement. Both arguments and the result have the same integer type;
type inference or ::<T> selects it. Argument expressions still use their
ordinary checked arithmetic. Wrapping calls are not constant expressions.
package main
fn main() {
core.assert_eq(core.wrapping_add(255u8, 1), 0u8)
core.assert_eq(core.wrapping_sub::<u8>(0, 1), 255u8)
core.assert_eq(core.wrapping_mul(127i8, 2), -2i8)
}
Floating-point overflow and division by zero can produce infinity or NaN;
integer traps do not apply to these operations. With NaN, != is true and the
other comparisons are false. Dodo does not provide numeric casts to or from
bool or enum tags. See math for numerical algorithms and functions.
Static storage
Package-level static NAME: T = expression declares immutable storage, and
static mut NAME: T = expression declares mutable storage. Both initializers
must be constant expressions. A call to a constructor, a safe function whose
body only returns a struct literal of its parameters and constants, counts as
one when its arguments are constant: static HITS: atomic.Atomic<u32> = atomic.Atomic.new(0u32). An immutable static that holds a std/sync/atomic
atomic lives in writable memory and is changed through its methods without
unsafe; a const cannot hold an atomic. Static storage lasts for the program and is not
automatically destroyed at exit. A read or write of mutable static storage
requires an explicit unsafe block; the programmer must prevent races and
conflicting aliases. Prefer passing state explicitly or using
synchronization for shared threaded state.
Attributes and unsafe boundaries
| Attribute | Placement and purpose |
|---|---|
@repr(C) |
Struct: C-compatible field order, alignment, and padding. |
@unsafe_send, @unsafe_sync |
unsafe struct: explicit unsafe thread transfer/sharing contract; see threads. |
@test |
Safe nongeneric top-level void function with no parameters; see testing. |
@ignore("reason") |
Test function: skipped unless ignored tests are selected. |
@derive(Json, Row) |
Struct: generate methods for each listed derive. Json adds JSON codecs, see JSON; Row maps SQL rows and parameters, see SQLite. |
@json_name("name") |
Field of a JSON-derived struct: select its external key. |
@json_deny_unknown |
JSON-derived struct: reject unknown fields. |
@db_name("column") |
Field of a Row-derived struct: select its column name. |
@db_flatten |
Field of a Row-derived struct: decode a nested Row-derived struct from the same row. |
@interrupt(VECTOR) |
Private, safe, nongeneric top-level fn name(): the hardware’s handler for VECTOR; see interrupts. |
@link_name("symbol") |
extern "C" prototype: bind symbol instead of the function’s name; several prototypes may bind one symbol with different signatures; see FFI. |
@section("name") |
Function or static: place it in an object file section, and keep it even if unreferenced. |
@align(N) |
Function or static: align it to N bytes, a power of two. |
@inline, @inline(never) |
Function with a body: optimized builds inline it into every caller where possible, or never. |
@cold |
Function with a body: rarely executed; never inlined, and optimized builds treat paths that call it as unlikely. |
@naked |
extern "C" function whose body is one unsafe { asm(...) }: no prologue or epilogue; see naked functions. |
@compiler(print), @compiler(println), and @compiler(printf) are reserved for
bundled printing declarations, and @compiler(pio) for the
PIO assembler in
std/embedded/chip/rp_pio; user packages cannot define them. Other unknown
attributes are errors. There is no general macro or attribute-extension system.
unsafe { ... } permits specific unchecked operations; it does not turn off
type checking, borrow checking, or checked indexing. An unsafe fn requires
callers to satisfy its documented preconditions, and its body still needs
explicit unsafe blocks around unchecked operations. extern "C" fn declares or
defines a C-ABI function. asm("template", operands...) is inline assembly
and needs an unsafe block; unsafe asm(...) at the top level of a file is
global assembly. The complete rules and examples are in
memory and foreign calls.