# Wuffs the Language The Wuffs project is both a programming language and a standard library written in that programming language (and then e.g. transpiled to C). For more details on the latter, see the [Wuffs the Library](/doc/wuffs-the-library.md) document. As for Wuffs the Language, it is an imperative C-like *memory-safe* language that should look roughly familiar to somebody versed in one of C, C++, Go, Java, JavaScript, Rust, etc. The major differentiating features are: - [Facts](/doc/note/facts.md) and compile-time [assertions](/doc/note/assertions.md). - Type [refinements](/doc/glossary.md#refinement-type). - [Coroutines](/doc/note/coroutines.md) and an [effects](/doc/note/effects.md) system. The `!` and `?` exclamation and question marks denote impure and coroutine effects. - No way to dynamically allocate or free [memory](/doc/note/memory-safety.md). Minor features or restrictions include: - Nullable and non-nullable pointers, spelled `nptr T` and `ptr T`. - Integrated [I/O](/doc/note/io-input-output.md). - [Iterate loops](/doc/note/iterate-loops.md). - Public vs private API is marked with the `pub` and `pri` keywords. Visibility boundaries are at the package level, unlike C++ or Java's type level. - No variable shadowing. All local variables must be declared before any other statements in a function body. - Like Go, semi-colons can be omitted. Similarly, the `()` parentheses around an `if` or `while` condition are optional, but the `{}` curly braces are mandatory. There is no 'dangling else' ambiguity. - Labeled jumps look like `break.loopname` and `continue.loopname`, for a matching `while.loopname`. The `while.loopname`'s closing curly brace must be followed by `endwhile.loopname`. - A `while true` loop's block may use double-curly braces: `{{` and `}}`. The formatter will not add an indent to the code inside the block. This is useful when using `while true {{ etc; break; etc; break }}` to simulate what would be a (forwards) `goto` in other languages' straight-line code. Wuffs code is formatted by the [`wuffsfmt`](https://godoc.org/github.com/google/wuffs/cmd/wuffsfmt) program. ## Types Types read from left to right: `ptr array[100] base.u32` is a non-null pointer to a 100-element array of unsigned 32-bit integers. Types can also be [refined](/doc/glossary.md#refinement-type). ## Structs Structs are a list of fields, enclosed in parentheses: `struct foo(x: base.u32, y: base.u32)`, possibly extended (by a `+`) with a second list of [optionally initialized](/doc/note/initialization.md#partial-zero-initialization) fields. The struct name, `foo`, may be followed by a question mark `?`, which means that its methods may be [coroutines](/doc/note/coroutines.md). ## Functions All functions are methods (with an implicit `this` argument). There are no free-standing functions. Function definitions read from left to right. `func foo.bar(x: base.u32, y: base.u32) base.u32` is a function (a method on the `foo` struct type) that takes two `base.u32`s and returns a `base.u32`. Each argument must be named at the call site. It is `m = f.bar(x: 10, y: 20)`, not `m = f.bar(10, 20)`. ## Operators There is no operator precedence. A bare `a * b + c` is an invalid expression. You must explicitly write either `(a * b) + c` or `a * (b + c)`. Some binary operators (`+`, `*`, `&`, `|`, `^`, `and`, `or`) are also associative: `(a + b) + c` and `a + (b + c)` are equivalent, and can be spelled `a + b + c`. The logical operators, `&&` and `||` and `!` in C, are spelled `and` and `or` and `not` in Wuffs. Not-equals is spelled `<>`, as the `!` exclamation mark is reserved for impure effects. Expressions involving the standard arithmetic operators (e.g. `*`, `+`), will not compile if overflow is possible. Some of these operators have alternative 'tilde' forms (e.g. `~mod*`, `~sat+`) which provide [modular](/doc/glossary.md#modular-arithmetic) and [saturating](/doc/glossary.md#saturating-arithmetic) arithmetic. By definition, these never overflow. The `as` operator, e.g. `x as T`, converts an expression `x` to the type `T`. ## Strings There is no string type. There are [arrays and slices](/doc/note/slices-arrays-and-tables.md) of bytes (`base.u8`s), but bear in mind that Wuffs code cannot [allocate or free memory](/doc/note/memory-safety.md). Double-quoted literals like `"#bad checksum"` are actually [statuses](/doc/note/statuses.md), [axiom names](/doc/note/assertions.md) or a `use "std/foo"` package name. Single-quoted literals are actually numerical constants. For example, `'A'` and `'\t'` are equivalent to `0x41` and `0x09`. These literals are not restricted to a single ASCII byte or even a single Unicode code point, and can decode to multiple bytes when finished with a `be` or `le` endianness suffix. For example, `'\x01\x02'be` is equivalent to `0x0102`. Similarly, `'\u0394?'le` (which can also be written `'Δ?'le`) is equivalent to `0x3F94CE`, because the UTF-8 encodings of U+0394 GREEK CAPITAL LETTER DELTA and U+003F QUESTION MARK (the ASCII `?`) is `(0xCE, 0x94)` and `(0x3F)`. Double-quoted literals cannot contain backslashes, as they'd be an unnecessary complication. Single-quoted literals can contain backslash-escapes, as they are often compared with arbitrary binary data. For example, where other programming languages would check if JPEG data starts with the magic _string_ `"\xFF\xD8"`, Wuffs would check if its opening 2 bytes, read as a little-endian `base.u16`, is a _number_ that equals `'\xFF\xD8'le`. ## Introductory Example A simple Wuffs the Language program, unrelated to Wuffs the Library, is discussed in [/hello-wuffs-c](/hello-wuffs-c).