菜单
Reference for Nolang programming language syntax. Use when working with `.no` files, writing Nolang code, or when the user asks about Nolang syntax, grammar, types, operators, or language features.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Debugging guide for the Nolang compiler/toolchain. Use when fixing parser bugs, formatter bugs, LSP diagnostic issues, or any syntax/semantic error. Provides a test-first workflow: write a minimal failing test first, then fix, then verify by re-running tests. Covers locating tests, building artifacts, and isolating regressions.
Automatically backup the working directory with git stash before any modifications, preventing data loss from agent operations. Use at the start of every conversation or when the user mentions backup, data loss prevention, snapshot, or safe mode.
| name | nolang-syntax |
| description | Reference for Nolang programming language syntax. Use when working with `.no` files, writing Nolang code, or when the user asks about Nolang syntax, grammar, types, operators, or language features. |
x: { ... }){ cond -> body })run / awy)#{c} annotation)#{mac-arm64}, #{linux-amd64}, etc.)Nolang is an experimental systems programming language that adopts a pass-by-reference model and a safe scope model to achieve absolute memory safety. No GC.
// Hello, World!
// No main entry needed
print('Hello, Nolang!')
// Variable declaration
i64
// Function definition
add = (a i64, b i64) (result i64) {
result = a + b
}
// Standard library methods can be called directly
c = math.max(a, b)
// Struct
user {
name str
age i64
}
u = user {
name: 'Alice'
age: 30
}
// Method
user.greet = () {
print('Hello, ' - .name)
}
u.greet()
Download the executable for your platform from GitHub Releases, or install using the following method:
# macOS / Linux
# 1. Download the binary
# 2. Place it in PATH
sudo mv nolang /usr/local/bin/no
Install the Nolang extension from VS Code Marketplace, which provides syntax highlighting, LSP diagnostics, go-to-definition, auto-completion, and more.
| Command | Description |
|---|---|
no version | Print version info |
no init | Initialize repo in current directory |
no new <name> | Create new repo |
no fmt [-w] [-d] <file|dir> | Format source code |
no build [-o <file>] [-cc <s>] [-target <s>] [<file|dir>] | Build (outputs executable) |
no run [-cc <s>] [-target <s>] [<file|dir>] | Build and run main.no |
no test [-cc <s>] [-target <s>] [<file>] | Run tests |
no add <pkg> | Add dependency |
no remove <pkg> | Remove dependency |
no update <pkg> | Update dependency |
no update-all | Update all dependencies |
no list | List dependencies |
no sync | Sync dependencies |
no install [-u] [<pkg>@<version>] | Install binary |
no uninstall <name> | Remove binary |
no pub --token <token> [--registry <url>] | Publish to registry |
# Create new repo
no new test1
# Enter directory
cd test1
# Run directly (auto-builds and executes main.no)
no run
# Build (looks for main.no by default)
no build # Build current directory
no build main.no # Build specified file
no build -o output # Specify output path
no build -cc zig # Use Zig compiler
no build -target x86_64-linux-gnu # Cross-compile (specify target platform)
# Run (build + execute)
no run # Build and execute main.no (must have main.no)
no run -cc zig
no run -target aarch64-macos-gnu
The -target parameter format is <arch>-<os>-<abi>, supporting the following targets:
| Target triple | Description |
|---|---|
x86_64-linux-gnu | Linux x86_64 |
aarch64-linux-gnu | Linux ARM64 |
x86_64-macos-gnu | macOS x86_64 |
aarch64-macos-gnu | macOS ARM64 |
x86_64-windows-gnu | Windows x86_64 |
Automatic platform detection: no build, no run, and no test automatically detect the current host platform and compile for the native target when -target is not specified. No manual target specification needed for daily development:
no run hello.no # Run directly on host
no test # Run tests on host
no build -target aarch64-linux-gnu # Only specify when cross-compiling
The -cc parameter specifies the C compiler backend:
clang (default) — requires LLVM installedzig — requires Zig installed, suitable for cross-compilation# Test all .no files in the test directory
no test
# Run a single test file
no test my-test.no
# Use a specific compiler or target
no test -cc zig
no test -target x86_64-windows-gnu
Testing notes:
# Install the package in the current directory
no install
# Force rebuild (update)
no install -u
# Install a specific version from a remote repository
no install pkg-name@1.0
Installation process:
~/no/bin//usr/local/bin/no uninstall pkg-name
The mod.jsonc file in the project root directory describes project information:
{
"name": "my-project",
"version": "0.1.0",
"description": "A new Nolang project",
"keywords": [],
"author": "",
"email": "",
"organization": "",
"repository": "",
"homepage": "",
"license": "MIT",
"workspace": "",
"mirrors": [],
"dependencies": {
"fmt": "*",
},
"compiler": {
"version": "0.1.0",
},
"output": "./dist",
"ignore": [],
}
# Add dependency (version number can be omitted, no version in repo)
no add pkg-name
# Remove dependency
no remove pkg-name
# Update dependency
no update pkg-name
# Update all dependencies
no update-all
# List dependencies
no list
# Sync dependencies (download and generate lock file)
no sync
Configure mirror addresses in the mirrors array of mod.jsonc to accelerate remote package downloads:
"mirrors": [
"https://mirror.example.com/"
]
Never modify valid, syntactically correct Nolang code — including identifiers, variable declarations, or any other language construct — even if you suspect a parser/compiler issue. If you encounter what appears to be a parsing or tooling error, file a bug report or inform the user; do not change the code.
Base types: byte, bool (lowercase only), char (character type / rune, double-quoted single character, e.g. "中"), str (string type, single-quoted 'hello', or raw string with backticks), i8, i16, i32, i64 (default numeric type, architecture-independent), u8, u16, u32, u64, usize (ffi only), f32, f64
Container types: obj (object), map (map), arr (fixed-length array [n]t), vec (variable-length array []t), slice (slice/view, no independent data structure, must be attached to arr/vec/str)
Special types: * (pointer, FFI #{c} declarations and standard library only), any (any type, standard library only)
Advanced types: bigint, err
Optional (nullable) types: prefix with ? — e.g. ?i64, ?str, ?[]str
Type aliases create a new name for an existing type. Use the equals syntax name = type, supporting single type aliases and multi-type unions.
// Union type: multiple types separated by |
int = i8 | i16 | i32 | i64 | u8 | u16 | u32 | u64
float = f32 | f64
num = int | float
// Single type alias
bytes = []byte
buf = [16]u8
Union types can reference other union types, forming a hierarchy. They can be used for function parameters and return values; the compiler automatically performs monomorphization, generating a separate function version for each member type.
// Parameter type is num union
max = (a ..num) (r num) {
r = a[0]
n = len(a)
i <- [1..n): {
a[i] > r -> r = a[i]
}
}
Detection rules — The equals syntax is recognized as a type alias (not a variable assignment) in the following cases:
name = type | type | ...: Union type (contains |)name = []type: Slice typename = [N]type: Array typename = ?type: Optional typename = known-type: Single type alias, where known-type is a built-in type name or a previously defined type alias name// i64 (default), f64, byte, bool, str can omit type annotation
i = 1
f = 1.0
b = 0x00
name = 'nolang'
flag = true
// Char literal (double-quoted, single rune)
c = "中"
a = "A"
// Raw string (backtick-delimited, multi-line, no escape processing)
sql = `
SELECT id,name
FROM user
WHERE id > 100
`
// Regex literal (JS-style /pattern/flags)
re = /\d+/
re = /hello/gi
re = /[a-z]+/
re = /a\/b/
// Explicit type annotation
a u64 = 10
// If variable name matches type, type annotation can be omitted
i8 = 3
// Default zero value, variable definition does not need prior declaration
u16
// Arr
arr [3] = [1, 2, 3] // i64 array
typed [3]u16 = [1, 2, 3] // typed
a [?]u16 = [1, 2, 3] // auto-inferred length
// Vec
typed []u8 = [1, 2, 3]
// String concatenation uses '-'
greeting = 'hello, ' - name
Nolang supports JavaScript-style regex literals /pattern/flags, which create a compiled regexp instance. The / is disambiguated from division by context-sensitive lexing (same as JavaScript):
= / ( / [ / { / , / : / ; / keywords like return / if) → / starts a regexIDENT, INT, STRING, ) / ] / } etc.) → / is division// is always a line comment (highest priority)# (use) / @ (export) directives → / is a path separator// Regex literal (expression-start position after '=')
re = /\d+/
re2 = /hello/gi
result = match-text(/[a-z]+/, text)
// Division (value-producing position after identifier/literal)
ratio = 100 / 4
x = a / b
Regex literals desugar at codegen into a call to the standard library regexp-compile function (defined in std/regexp.no):
// source
re = /\d+/
// desugars to
re = regexp-compile('\\d+')
Flags (optional, after closing /): g (global), i (case-insensitive), m (multiline), s (dot matches newline). Empty pattern // collides with line comments — use /(?:)/ for an empty match.
Nolang supports three single-line comment markers and one multi-line (block) comment marker:
// — traditional single-line marker (comments to end-of-line); — single-line marker (comments to end-of-line);; <content> — single-line marker (when ;; is followed by content on the same line, comments to end-of-line; same semantics as ;);;\n — multi-line (block) comment: when ;; is immediately followed by a newline (only whitespace allowed in between), it enters multi-line mode until another ;; followed by a newline/EOF is encountered// this is a comment
; this is also a comment, same semantics
;; this is still a single-line comment (no newline after ;;)
x = 1 ; trailing comment, runs to end of line
x = 2 ;; inline single-line comment, same semantics
;;
this is a multi-line (block) comment
it can span multiple lines
until a standalone ;; is encountered
;;
y = 3
;;
the closing ;; must be followed by a newline or EOF
to be recognized as the ending delimiter
;;
One statement per line is still a hard rule — never use commas , to combine multiple statements on one line (semicolons are now comments, so ; can no longer join statements). This applies inside comments too.
; ❌ Wrong: commas combining multiple statements (inside a comment example)
; h0 = 1732584193, h1 = 4023233417
; ❌ Wrong: comma joining statements in real code
; out = from-i64(v), out = from-u64(v)
; ✅ Correct: each statement on its own line
; h0 = 1732584193
; h1 = 4023233417
Multi-line trigger rule: ;; must be followed by only whitespace (spaces/tabs) up to a newline or EOF to enter multi-line mode. If ;; is followed by any non-whitespace character on the same line, it is treated as a single-line comment (to end-of-line). The closing ;; must likewise be followed by a newline or EOF (only whitespace allowed in between). An unterminated multi-line comment runs to EOF.
Marker preservation: the formatter never converts between markers (; ↔ // ↔ ;;). It records the original marker (Comment.Marker) and emits it verbatim, so ; comments stay ;, // stay //, ;;\n ... ;; blocks stay intact (content, including internal newlines, preserved verbatim), and ;; single-line comments stay ;;. no fmt is idempotent for all forms.
Safety: ; / ;; inside string literals (e.g. 'text/plain; charset=utf-8', index-from(';', pos)) and inside // comments is consumed by the lexer's string/comment scanners and never treated as a comment marker.
Variable names, function names, struct names, etc. can start with an underscore, followed by hyphens, letters, and digits; cannot start with a digit, cannot end with a hyphen, and cannot have consecutive hyphens.
Case rules (mandatory):
NO-LANG, MAX-SIZE, HEX-CHARS). Private globals use underscore prefix followed by uppercase (e.g. _NO-LANG, _PRIVATE-CONST). This is a mandatory rule, not a convention. Lowercase top-level variables will be treated as locals by the compiler, causing undefined reference errors.hex-chars, data-len)sha1-block, db-mysql)// ✅ Correct: global data uses uppercase
NO-LANG = 'nolang' // global constant, uppercase
MAX-SIZE = 1024 // global constant
HEX-CHARS = '0123456789abcdef'
// ✅ Private global: underscore prefix + uppercase
_NOLANG = 'nolang' // private global
_PRIVATE-CONST = 42 // private global constant
// ❌ Wrong: global variables must NOT use lowercase
// x = 10 // lowercase global — will cause errors
// foo-bar = 42 // lowercase global — will cause errors
// hello-world = 'Hello World' // lowercase global — will cause errors
// ✅ Local variables (inside functions) use lowercase
// example-fn = () {
// x = 10 // local variable, lowercase — correct
// foo-bar = 42 // local variable, lowercase — correct
// }
Function documentation comments should include full parameter names and types, return parameter names and types. The API summary at the top of a module should also use full signatures (including parameter names, types, return names, types), not abbreviated forms.
// ❌ Wrong: missing types, missing return names
// sha1(data) (hash)
// sha1-block(s, h0..h4)
// ✅ Correct: full param names, types, return names, types
// sha1(data []byte) (hash [20]byte) — full hash
// sha1-block(s []u32, h0 u32, h1 u32, h2 u32, h3 u32, h4 u32) — process single block
// Documentation comments above function definitions should follow the same convention:
// sha1: compute SHA-1 hash
// data []byte: input byte array
// returns hash [20]byte: 20-byte hash value
sha1 = (data []byte) (hash [20]byte) {
...
}
The Nolang standard library provides a rich set of common functionality, including string operations, byte conversions, hash computation, network communication, etc.
Rule: If the standard library already provides corresponding functionality, reimplementing it yourself is not recommended. Developers should carefully review the standard library documentation (see Standard Library Overview below) to avoid reinventing the wheel.
// ❌ Wrong: reimplementing str → []byte conversion
str-to-bytes = (s str) (out []byte) {
n = s.len
i = 0
{
out[i] = s[i]
i = i + 1
} (i < n)
}
// ✅ Correct: use standard library str.to-bytes() method
data []byte = s.to-bytes()
Common standard library replacements:
str.to-bytes() — string to byte array (replaces hand-written str-to-bytes)[]byte.to-str() — byte array to string (replaces hand-written bytes-to-str)[n]t.to-vec() — fixed array to slice ([20]byte → []byte)[]byte.to-hex() / []byte.to-hex-lower() — byte array to hex stringstr.to-i64() / str.to-f64() — string to numberint.to-str() / float.to-str() — number to stringstd/hash/sha1, std/hash/sha256, std/hash/sha512 — hash computation.no filenames (including folder names) use hyphens - to join words, not underscores _.
This is consistent with the naming style of Nolang identifiers such as variable names, function names, and struct names.
✅ string-helper.no, hash-table.no, http-client.no
❌ string_helper.no, hash_table.no, http_client.no
Every non-empty .no source file must end with exactly one trailing newline (i.e. one blank line at the end of the file).
Excluded directories: dist/, vscode-nolang/, node_modules/.
Rationale: a single, consistent EOF newline keeps git diff clean, avoids "no newline at end of file" warnings, and makes concatenation/tooling predictable.
The rule is enforced automatically by the toolchain — there is no separate normalization script:
no fmt (src/cmd/no/main.go, the fmt subcommand) formats files in
place and calls fmt.FormatFile, which guarantees exactly one trailing
newline.textDocument/formatting (src/lsp/server.go,
formatNolangCode → fmt.FormatFile) appends/collapses the EOF newline
automatically when you save or format a .no file in the editor.Implementation lives in src/fmt/formatter.go:
FormatFile(code) formats a complete file and calls ensureTrailingNewline,
which strips all trailing \r/\n (CRLF-safe, multi-blank-line-safe) and
appends a single \n. Empty or unparseable input is returned unchanged so
the formatter never mangles a file it cannot understand.; / ;; are comment markers (implemented 2026-07-17 / 2026-07-18); is a line-comment marker — semantically identical to //, it comments
to end-of-line. The lexer turns ; into a COMMENT token (with Marker=";"),
the parser records Comment.Marker, and the formatter emits the original marker
verbatim.
;;\n ... ;; is a multi-line (block) comment — when ;; is immediately
followed by a newline (only whitespace allowed in between), it enters multi-line
mode. The closing ;; must likewise be followed by a newline or EOF. Everything
between (including newlines) is comment content. A single ; inside the content
does NOT close the block; only a ;; followed by newline/EOF does. If no closing
;; is found, the comment runs to EOF. If ;; is followed by non-whitespace on
the same line, it is a single-line comment (to end-of-line), semantically
identical to ;. The lexer emits one COMMENT token with Marker=";;block"
(multi-line) or Marker=";;" (single-line ;;); the formatter writes the
delimiters verbatim (idempotent). See Comments for the full rules.
Gotcha: cond -> X; Y no longer parses as assignment. With ; a comment, it
means "evaluate X (discard) then a trailing comment ; Y" — X is never
assigned. The correct form is cond -> X = Y (established stdlib pattern in
arr.no, uuid.no, path.no, err.no, assert.no). If you find
cond -> X; Y in source, replace ; with =; do not leave it as a comment.
; / ;; inside string literals (e.g. 'text/plain; charset=utf-8',
index-from(';', pos)) and inside // comments is safe — the lexer's string
and comment scanners consume it, so it never reaches the comment token.
Migration note: before ; became a comment, the repo's .no sources were
made ;-free at the grammar level (zip.no → []byte literals; ws.no 14×
cond -> X; Y → cond -> X = Y; test-tls-part1/2/3.no 15×
cond -> print('…'); return → cond -> { print('…') \n return }). With the
lexer now treating ; as a comment and ;; as a block comment, no real
grammatical ; remains, and the formatter preserves both ; and ;; … ;;
verbatim. Verify with no fmt <file>.
Format(code) is the pure fragment formatter (no trailing newline) used by
unit tests; prefer FormatFile whenever you write a real source file.Functions pass results by modifying input parameters. Nolang functions have the following characteristics:
?t option over (val, ok bool) for functions that may fail or return emptyname type = expr syntax. Parameters with defaults can be omitted at the call site. Default parameters must be the last parameters.System functions allow syntactic sugar return values for user convenience. Since the underlying mechanism still works through input parameters, no new variables are returned, making it internally safe.
add = (a i64, b i64) (result i64) {
result = a + b
}
// Default parameter value
parse-line = (s str, max-fields i64 = 1024) (fields []str) {
...
}
// Both calls are valid:
fields = csv.parse-line(line) // max-fields defaults to 1024
fields = csv.parse-line(line, 256) // max-fields = 256
// Variadic parameters
add3 = (a ..i64) {
}
// Function call
sum = add(1, 2) // sum == 3
// Anonymous function
(a i64) { print(a) }(10)
?t over (val, ok)When a function may fail or return an empty value, prefer the ?t option type over the (val t, ok bool) dual-return pattern.
?t is a tagged enum with three states: ok (has value, implicitly bound), nil (empty), err (error). Normal values are implicitly bound. Use nil when the operation simply cannot find a value, and err(...) when the operation encounters an actual error.
// ❌ Wrong: dual-return pattern
stack.pop = () (val i64, ok bool) {
.n == 0 -> return
val = .data[.n]
ok = true
}
// ✅ Correct: option type (nil for empty, err for errors)
stack.pop = () (val ?i64) {
.n == 0 -> {
val = nil
return
}
val = .data[.n]
}
// ✅ Returning an error
file.read = () (data ?str) {
.fd < 0 -> {
data = err('file not open')
return
}
// ... read data
data = buf
}
Unwrap with match:
val = s.pop()
val: {
nil -> print('empty')
err -> print(it) // it = error message
-> print(it) // it = the value
}
Applicable scenarios:
pop / peek (container may be empty) → ?t (nil = empty)read-line / read-byte (I/O may fail) → ?str / ?i64 (nil = EOF, err = error)lookup / get (key may not exist) → ?t (nil = not found)parse / from-str (input may be invalid) → ?t (nil = empty, err = invalid input)accept / dial (connection may fail) → ?conn (nil = no connection, err = error)nil vs err: use nil when the absence is a normal/expected outcome (empty stack, key not found, EOF); use err('msg') when the absence represents an actual error condition (I/O failure, invalid input, connection refused).
Exception: when a function needs to return multiple independent values (e.g. (name str, value str, ok bool)), the multi-return pattern is acceptable.
Methods attached to a union type (e.g. int, float, num) use type.method = () (results) syntax.
The parser automatically adds a hidden self parameter with the receiver type, so you must not declare the receiver explicitly.
Definition:
// type aliases & union types — equals syntax
// name = type1 | type2 | ... — union of multiple types
// name = type — single type alias
int = i8 | i16 | i32 | i64 | u8 | u16 | u32 | u64
float = f32 | f64
num = int | float
// Single type alias
bytes = []byte
buf = [16]u8
// method definition — NO explicit self parameter, use `.` inside body
num.sign = () (r num) {
{
. > 0 -> r = 1
. < 0 -> r = -1
-> r = 0
}
}
int.to-str = () (out str) {
out = ''
n = .
// ... conversion logic using `n` (not `.` directly after first use)
out.len = len
}
Why method form is preferred here:
self: <type> parameter, enabling GenericUnion detection and monomorphization. is the receiver — cleaner than passing v explicitlyto-str(receiver, out) still works identically via rewriteUnionCallsOld syntax (deprecated, will be removed after version n):
!! { }/! { }/for { }/for cond { }/while cond { }/for i=0,i<n,i++ { }/for i <- [...] { }/for i in [...] { }/match x { }/if/elif/else { }can still be parsed but will output a deprecation warning. Please use the "new style" syntax in the table below.
| Purpose | New syntax | Old (deprecated) |
|---|---|---|
| Infinite loop | { } () | !! { } / ! { } / for { } |
| Conditional loop | { } (cond) | for cond { } / while cond { } |
| Counted loop | { } * n or i <- [0..n): { } | for i=0, i<n, i++ { } |
| Range iteration | i <- [a..b]: { } | for i <- [a..b] { } / for i in [...] |
| Conditional match | x: { ... } | match x { ... } |
| Branch selection | { cond -> body } | if/elif/else { } |
| Skip iteration | continue (temporarily retained) | ** (planned, not yet replaced) |
| Break loop | break (temporarily retained) | * (planned, not yet replaced) |
| Early return | return (temporarily retained) | ... (planned, not yet replaced) |
The new loop syntax puts the body block first, followed by the loop kind suffix:
{ body } () — infinite loop (empty parens){ body } (cond) — conditional loop (condition in parens, checked before each iteration){ body } * N — counted loop (body repeats N times)This "body-first" ordering is intentional: it mirrors how you read the block, and the suffix
unambiguously declares the loop variant. The empty () reads as "loop forever"; (cond) reads
as "loop while condition holds".
// Infinite loop (new style)
{
// body
} ()
// Conditional loop (new style) — condition checked before each iteration
{
i = i + 1
} (i < 5)
// Five iterations
{ } * 5
// When N <= 0 the loop body is skipped (zero or negative count does not execute)
{ } * 0 // skipped
{ } * -3 // skipped
// Range for — interval syntax supports four bracket combinations
i <- [a..b]: { // closed interval: a ≤ i ≤ b
}
i <- (a..b]: { // left-open right-closed: a < i ≤ b
}
i <- [a..b): { // left-closed right-open: a ≤ i < b
}
i <- (a..b): { // open interval: a < i < b
}
i <- [5..0]: { // decreasing — runtime direction detection: start > end → decrement
}
i <- 'abc': { // iterate over each character in the string
}
// Runtime direction detection: when start > end, iteration automatically decrements (step -1).
// All four bracket combinations support decrement:
// [5..1] → 5 4 3 2 1 left-closed right-closed, descending
// (5..1] → 4 3 2 1 left-open right-closed, descending
// [5..1) → 5 4 3 2 left-closed right-open, descending
// (5..1) → 4 3 2 left-open right-open, descending
// (3..0] → 2 1 0 left-open right-closed, descending to zero
// When start <= end, iteration increments as usual (step +1).
// ❌ Explicitly rejected: interval bounds must be integers; nested expressions not supported
// i <- [1.5..5.5]: { } // compile error
// i <- [0..[1..5][0]]: { } // syntax error
// Single if (retained)
x == 1 -> do-something()
// Ternary (retained)
c = flag ? 1 : 2
max = sum > 10 ? sum : 10
i <- [0..10): {
* // break
** // continue
... // return/terminate
}
x: { ... })// Simple form, it is used to get the parameter
x: {
err -> log(it)
nil -> log('nil')
->
do-right-thing(it)
}
// Destructuring form
x: {
err(e) -> log(e)
nil -> log('nil')
val(v) ->
do-right-thing(v)
}
user: {
User{id=1} -> print("admin")
User{name=n} -> print("user: ", n)
-> print("anonymous")
}
score: {
[0..59] -> print("fail")
[60..89] -> print("good")
[90..=100] -> print("excellent")
-> print("invalid score")
}
num: {
1 || 3 || 5 || 7 -> print("small odd number")
2 || 4 || 6 -> print("small even number")
-> print("larger number")
}
// With return value, the last statement/value
result = x: {
1 -> 1
2 -> 2 + 1
-> a + b
}
// Match inside for-in body: executes one match per iteration
i <- [0..10): {
1 -> a = 1
2 -> b = 2
-> c = 0
}
// Multi-line arm body must use braces -> { ... }
x: {
nil -> {
log('nil')
do-cleanup()
return
}
err -> {
log(it)
do-cleanup()
return
}
ok -> print(it)
}
Multi-line arm body rule: When an arm body contains multiple statements, it must be enclosed in braces
-> { ... }. Single-line body can be written directly after->. If a multi-line body does not use braces, theitbinding for option match will not be inserted correctly, causing a compile error.
Match semantics inside for-in:
i <- (a..b]: { 1 -> ... 2 -> ... }executes the match body once for each iteration variablei(1 ->is equivalent toi == 1 ->, etc.). This is syntactic sugar for executing one match per iteration.
// ❌ Avoid: duplicate branch bodies
w = tls-c.send(req)
w: {
nil -> {
tls-c.close()
return
}
err -> {
tls-c.close()
return
}
ok -> n = it
}
// ✅ Shared logic in -> catch-all
w = tls-c.send(req)
w: {
ok -> n = it
-> {
tls-c.close()
return
}
}
// ✅ Or vice versa: name simple branches, complex logic in ->
val: {
nil -> return
err -> log(it)
-> {
n = it
total = total + n
process(n)
}
}
// Single statement — no braces
val: {
ok -> print(it)
-> print('empty or error')
}
// Multiple statements — must use braces
val: {
ok -> {
n = it
total = total + n
}
-> {
log('failed')
return
}
}
// it implicit binding
val: {
ok -> process(it) // it = unwrapped value
err -> log(it) // it = error message string
-> log('empty') // catch-all, handles nil here
}
// ✅ Combined option patterns: nil || err -> body
// Matches when the option is nil OR err, sharing the same body.
val: {
nil || err -> {
cleanup()
return
}
ok -> process(it)
}
// ✅ Also valid: any combination of nil, err, ok joined by ||
val: {
nil || err -> log('failed')
ok -> process(it)
}
{ cond -> body }){
a == 1 -> {
a = 1
b = 2
}
a == 2 || a == 3 -> do-something()
->
c = 0
}
run / awy)Nolang uses run and awy for async concurrency. Async function names must end with -async (no async keyword).
run — start an async thread, returns a task handleawy — wait for the async thread to complete and get the result// Async function definition (name ends with -async)
compute-async = (n i64) (r i64) {
r = n * 2
}
// Basic async call
h = run compute-async(21)
r = awy h // r = 42
// Concurrent tasks
h1 = run compute-async(10)
h2 = run compute-async(20)
r1 = awy h1 // r1 = 20
r2 = awy h2 // r2 = 40
// Inline await
r = awy run compute-async(5) // r = 10
Naming rule: async function names must end with
-async(e.g.compute-async,fetch-data-async). Do not use theasynckeyword.
Functions can return multiple values, received using multi-assignment at the call site:
swap = (a i64, b i64) (x i64, y i64) {
x = b
y = a
}
a, b = swap(5, 3)
// Also valid as a match arm body
val: {
ok -> a, b = parse-pair(it)
-> return
}
Struct definitions and literals must both use multi-line form, with each field on its own line, fields not separated by commas, and no trailing comma.
A struct can implement one or more interfaces by listing them after the struct name. When implementing interfaces from other modules, the interface name must include the module prefix (e.g. sql.db, not db). See Cross-Module Type References.
; Same-module interface: no prefix needed
user json {
name str
age i64
}
; Multiple interfaces
file enter, leave {
path str
}
; Cross-module interface: prefix required
; db, rows, stmt are defined in the sql module
db-mysql sql.db {
fd i64
}
u = user {
name: 'Alice'
age: 30
}
u.name = 'Bob'
u.age = 25
print(u.name)
user.greet = () {
print('Hello, ' - .name)
}
Enum definitions use the same syntax as structs, but with commas between values. Values auto-increment from 0.
// red=0, green=1, blue=2
color {
red,
green,
blue,
}
// This is a special enum, can have types, commas, and aliases
enum-name {
a t,
b u,
c v,
}
// Note this is a regular struct, multiple fields without commas
struct-name {
a t
b u
c v
}
Rule: enum values must always be referenced using qualified form enum-type.value, never as bare names. This prevents naming conflicts and ensures external packages cannot use values directly without qualification.
// ❌ Wrong: bare enum value
kind = null
yes = e.is(io)
// ✅ Correct: qualified form
kind = json-kind.null
yes = e.is(code.io)
Enum types can be used as struct field types, function parameter types, and return value types. Both inside and outside the module that defines the enum, enum values should be referenced using the
enum-type.valueform.
Methods are defined on types, using . to reference the receiver. The receiver does not need to be explicitly declared as a parameter; it is referenced via . inside the method body.
Rules:
type.method format; type must be a previously defined type. inside the method bodyreceiver.method(args) syntaxbool type, not i64matches not match)Examples:
// str method
str.to-upper = () (out str) {
out.len = .len
i = 0
{
c = .[i]
{
c >= 97 && c <= 122 -> out[i] = c - 32
-> out[i] = c
}
i = i + 1
} (i < .len)
}
// char method
char.is-digit = () (result bool) {
result = false
. >= 48 && . <= 57 -> result = true
}
// struct method
user {
name str
age i64
}
user.greet = () {
print('Hello, ' - .name)
}
// Calling methods
s = 'hello'
u = s.to-upper() // receiver.method()
c char = 5
d = c.is-digit() // receiver.method()
u = user{
name: 'Alice'
age: 30
}
u.greet()
Slicing (arr[1..3], vec[1..3], str[1..3]) produces a view into the original data — it does not copy data or create a new independent type. The slice is a lightweight descriptor (pointer + length + capacity) that shares the original buffer:
| Original type | Slice view type | Available methods |
|---|---|---|
arr ([n]t) | []t (vec) | All []t methods (len, push, pop, contains, reverse, clone, fill, to-arr, etc.) |
vec ([]t) | []t (vec) | Same as above |
str | str | All str methods (to-upper, to-lower, index, contains, slice, copy, fill, etc.) |
// arr slice → vec view, shares arr's memory
a [5]u8 = [0, 1, 2, 3, 4]
s = a[1..4] // s is []u8 view into a's buffer
n = s.len // vec.len
// vec slice → vec view, shares vec's memory
v = [10, 20, 30, 40, 50]
s = v[2..] // s is []i64 view
s.reverse(s.len) // vec.reverse
// str slice → str view, shares str's memory
s = 'Hello World'
sub = s[6..] // sub is 'World' view
upper = sub.to-upper() // str.to-upper
// Modifying through a slice affects the original
data = [10, 20, 30, 40, 50]
view = data[1..4] // view = [20, 30, 40]
view[0] = 99 // modifies data[1] too — shared memory
// Get char from string (character, not byte)
str[i]
// Get element from arr, vec
arr[i]
vec[i]
// Get value from map
map[str]
The standard library uses a consistent pattern for data structures and I/O abstractions: define a struct, then attach methods to it. The receiver is accessed via . inside the method body, and nested fields via self.field (or .field for single-level).
// Data structure: stack (LIFO)
stack {
data []i64
n i64
}
stack.push = (val i64) {
.data[.n] = val
.n = .n + 1
}
stack.pop = () (val ?i64) {
.n == 0 -> {
val = nil
return
}
.n = .n - 1
val = .data[.n]
}
// Usage
buf [128]i64 = [0:128]
s = stack {
data: buf
n: 0
}
s.push(42)
val = s.pop()
The same pattern applies to heap, deque, path, regexp, file, io-reader, io-writer, sse-client. See Standard Library Overview for the full API.
The standard library includes comprehensive networking modules under std/net/:
std/net/http — HTTP/1.1 client (GET, POST, PUT, DELETE, PATCH), supports TLSstd/net/http2 — HTTP/2.0 client (RFC 7540, h2c prior knowledge mode)std/net/http3 — HTTP/3.0 client (RFC 9114, over QUIC)std/net/ws — WebSocket client and server (RFC 6455)std/net/quic — QUIC protocol (RFC 9000)std/net/tls — TLS 1.2/1.3 client connection (pure Nolang)std/net/sse — Server-Sent Events client (W3C EventSource), supports TLS and auto-reconnectstd/net/client — High-level TCP client with reconnect supportstd/net/server — HTTP serverstd/net/dns — DNS resolutionstd/net/url — URL parsingstd/net/cookie — HTTP Cookie handlingstd/net/multipart — Multipart form datastd/net/hpack — HPACK header compression (for HTTP/2)std/net/proxy — Proxy supportstd/net/pool — Connection poolstd/net/unix — Unix domain socketsstd/net/ip — IPv4 address parsing and classification// SSE client usage
client = sse.sse-connect('http://localhost:3000/events') // returns ?sse-client
client: {
nil -> print('connection failed')
-> {
{
ev = client.next-event() // returns ?sse-event
ev: {
nil -> * // EOF
err -> print(it) // error
-> print(ev.data) // event data
}
} ()
client.close()
}
}
Method calls on struct fields via self.field (abbreviated .field) are fully supported. The type checker resolves the field type from the struct definition, so return types are correctly inferred:
// .recv-buf is a str field → .recv-buf.slice() returns str
data = .recv-buf.slice(0, .recv-buf-len) // correctly inferred as str
// .tls-c is a tls-conn field → .tls-c.send() works directly
written = .tls-c.send(req, req.len)
// Define interface
json {
to-json()
}
// Interface default implementation
json.to-json = () {
}
// Interface implementation
user json {
name str
age i64
}
// Override + call parent implementation
user.to-json = () {
// Parent implementation
..to-json()
}
user.other = () {
// Current implementation
.to-json()
// Parent implementation
..to-json()
}
Types that implement the enter / leave interfaces are automatically called when entering and leaving a scope:
file enter, leave {
path str
}
file.enter = () {
.open()
}
file.leave = () {
.close()
}
read-file = () {
// Auto f.enter()
f = file{
path: 'data.txt',
}
// Use f
// Auto f.leave()
read(f)
}
arr_to_vec = (arr [n]t) (out []t) {
i <- [0..n): {
out[i] = arr[i]
}
}
// Returns the type name string
a = typeof(x)
// `as` is only allowed for FFI pointer type casts (e.g. *byte, **byte, *i64)
// Integers are internally i64, no explicit cast needed
y = x as *byte
The compiler type-checks integer assignments to prevent unsafe narrowing that could cause data loss.
A narrower integer type's value can be auto-assigned to a wider type, since the target range fully contains the source range:
b byte = 200
i i64 = b ; ✓ byte range [0,255] ⊆ i64 range
u u32 = b ; ✓ byte range ⊆ u32 range
Integer literals (default inferred as i64) can be assigned to any integer type whose range includes the literal value:
n u8 = 200 ; ✓ 200 ∈ [0,255]
m u8 = 300 ; ✗ 300 > 255, compile error
big u64 = 18446744073709551615 ; ✓ 2^64-1, u64 max
Assigning a wider-typed variable directly to a narrower type causes a compile error, as it may cause data loss. The error message includes an actionable fix hint suggesting how to narrow safely with bitwise operations:
d u64 = 42
h u32 = d ; ✗ cannot assign u64 value to u32 variable 'h'; hint: narrow safely with a bitwise mask (e.g. `& 4294967295`) or right shift (e.g. `>> 32`)
h u16 = d ; ✗ cannot assign u64 value to u16 variable 'h'; hint: narrow safely with a bitwise mask (e.g. `& 65535`) or right shift (e.g. `>> 48`)
h u8 = d ; ✗ cannot assign u64 value to u8 variable 'h'; hint: narrow safely with a bitwise mask (e.g. `& 255`) or right shift (e.g. `>> 56`)
x u32 = d + 1 ; ✗ addition result is still u64, unsafe
y u32 = foo() ; ✗ function call result type mismatch
Fix hint: The compiler auto-computes the exact mask value and shift amount for the target type. Apply the suggested mask or shift to narrow safely (see next section).
Signed target types: For
i8/i16/i32/i64, the hint explains that bitwise narrowing is not safe (sign-bit truncation is ambiguous) and suggests an explicit range check instead.
When the right-hand side of an assignment is a bitwise expression (&, |, ^, <<, >>) and the target type is an unsigned integer (u8/u16/u32/u64/byte), the compiler allows implicit narrowing — because high-bit truncation is the standard semantics of bitwise operations and does not cause unexpected data loss:
d u64 = 42
; ✓ mask operation: result ≤ mask value, safely fits u32
h u32 = d & 67108863 ; mask = 2^26-1 < 2^32
h u32 = d & 4294967295 ; mask = 2^32-1, exactly u32 range
; ✓ shift operation: high bits are 0 after right shift
hi u32 = d >> 32 ; u64 >> 32 leaves 32 bits
; ✓ XOR / OR combinations
c u32 = a ^ b ; bitwise operation result
b byte = v & 255 ; mask to byte range
; ✓ composite bitwise (common in crypto/codec)
s u32 = (key[0] & 255) | ((key[1] & 255) << 8) | ((key[2] & 255) << 16) | ((key[3] & 255) << 24)
Why allowed? Bitwise operations (mask, shift, XOR, OR) semantically construct a bit pattern. Assigning to a narrower unsigned type truncates the high bits intentionally — the developer has already ensured the result's range via mask or shift, or deliberately discards high bits. This is a standard pattern in cryptography (e.g. ChaCha20, Poly1305, Blake2) and codec code.
Unsigned target types only. For signed integer targets (
i8/i16/i32/i64), even with a bitwise RHS, an error is still reported because sign-bit truncation semantics are ambiguous:d u64 = 42 h i32 = d & 4294967295 ; ✗ still errors: signed target not eligible
Top-level must be a bitwise op. Only when the expression's top-level operator is
&/|/^/<</>>is it allowed. Addition, subtraction, function calls, direct variable references, etc. are not covered:d u64 = 42 h u32 = d ; ✗ top-level is Identifier, not bitwise h u32 = d + 1 ; ✗ top-level is +, not bitwise
New syntax:
# path(recommended). The olduse pathkeyword is deprecated but still supported. Always prefer#in new code.
// Std modules
# std/math.add
// Remote modules
# github.com/utils/math.add
// Local modules (must start with /)
# /utils/math.add
// Aliases
# std/math.add a
// ── Old syntax (deprecated, still works) ──
// use std/math.add
// use github.com/utils/math.add
// use /utils/math.add
// use std/math.add a
Nolang enforces a mandatory module namespace convention: when calling functions or constants defined in other modules (other .no files) from a .no file, you must use the ShortName. prefix. This avoids cross-module naming conflicts.
Standard library modules are automatically loaded by the compiler; no explicit import is needed (no # std/... annotation required), just use the ShortName. prefix to call them.
ShortName is the last segment of the module path, used as the prefix for cross-module calls.
| File path | FullPath | ShortName | Description |
|---|---|---|---|
std/math.no | math | math | Top-level file |
std/fs.no | fs | fs | Top-level file |
std/net/net.no | net/net | net | Last path segment |
std/net/client.no | net/client | client | Last path segment |
std/hash/sha256.no | hash/sha256 | sha256 | Last path segment |
std/archive/gzip.no | archive/gzip | gzip | Last path segment |
ShortName is the last segment of FullPath when split by slashes (e.g. hash/sha256 → sha256).
When calling module-level functions or constants defined in other modules, you must use the ShortName. prefix.
// Module-level functions
sha256.sha256(data)
sha256.sha256-hex(data)
fs.open(path, opts)
gzip.gzip-decompress(data)
math.degrees(rad)
// Module constants
net.NET-BUF-SIZE
math.PI
The following cases do not require a prefix:
1. printf / sprintf / print
These three functions are exempt from the prefix rule by convention. This is a special case for these three functions only, not because they are builtins — other builtin functions (such as open, close, read, write, etc.) still require the module prefix.
printf('hello %d', n) // ✅ no prefix
s = sprintf('x=%d', x) // ✅ no prefix
print('hello') // ✅ no prefix
fs.open(path, opts) // ✅ with prefix (builtins need it too)
2. Same-file definitions
Functions, constants, and methods defined in the same .no file are used directly without a prefix.
// In sha256.no:
sha256(data) // sha256 is defined in this file
HMAC-BLOCK-SIZE // constant defined in this file
3. Built-in type methods
Method calls on built-in types (str, i64, vec, arr, byte, char, bool, etc.) do not require a prefix. Methods are built into the type and resolved directly through the receiver type.
'hello'.starts-with('he') // str method
n.to-str() // int method
v.push(42) // vec method
a.contains(3) // arr method
c.is-digit() // char method
4. Struct instance methods
Calling methods on an already-created struct instance does not require a module prefix. Methods are resolved through the instance's type; the compiler automatically finds the corresponding struct.method definition.
f = fs.open(path, opts) // fs.open is a module-level function, needs prefix
f.read(buf, n) // file.read is a struct method, no prefix needed
f.close() // file.close is a struct method, no prefix needed
p = path{
p: '/tmp'
}
p.exists() // path.exists is a struct method, no prefix needed
Whether a method call requires a prefix depends on the method owner:
str.starts-with, i64.to-str, etc.) — no prefix neededf.read, p.exists, etc.) — no prefix neededfs.open, sha256.sha256, etc.) — prefix requiredIn fs.fil(), fs is the module's ShortName, and fil is the module-level function name. The fs. prefix cannot be omitted because fs here is not a variable name but a module path.
When referencing types (structs, interfaces, enums) defined in other modules, you must use the ShortName. prefix. This applies to:
1. Struct interface implementation — when a struct implements interfaces from another module, the interface name must be prefixed:
// ❌ Wrong: db, rows, stmt are interfaces defined in the sql module
db-mysql db {
fd i64
}
// ✅ Correct: use sql.db, sql.rows, sql.stmt
db-mysql sql.db {
fd i64
}
rows-mysql sql.rows {
fd i64
}
stmt-mysql sql.stmt {
fd i64
}
2. Function parameter and return types — cross-module types in function signatures need the prefix:
// ✅ Correct: return type uses sql.result
db-mysql.exec = (sql str) (r sql.result) {
...
}
3. Struct field types — cross-module types as field types need the prefix:
// ✅ Correct: field type uses sql.connection
conn-mysql sql.db {
handle sql.connection
}
No prefix needed for:
.no file)str, i64, bool, byte, etc.)enter, leave)// Same-file defined types, no prefix needed
result {
last-id i64
affected i64
}
// enter/leave are built-in interfaces, no prefix needed
// result is same-file struct, no prefix needed
db enter, leave {
close() (ok bool)
exec(sql str) (r result)
}
// Standard library modules are auto-loaded, no explicit import needed
// ─── No prefix needed ───
// Same-file functions
sha256(data)
// Built-in type methods
'hello'.starts-with('he')
n.to-str()
v.push(42)
// Struct instance methods
f = fs.open(path, opts)
f.read(buf, n)
f.close()
// printf/sprintf/print
printf('hello %d', n)
s = sprintf('x=%d', x)
// ─── Prefix required ───
// Module-level functions
sha256.sha256(data)
sha256.sha256-hex(data)
fs.open(path, opts)
gzip.gzip-decompress(data)
math.degrees(rad)
// Module constants
net.NET-BUF-SIZE
math.PI
// Cross-module type references (interface implementation, param types, return types, field types)
db-mysql sql.db {
fd i64
}
r sql.result = d.exec('CREATE TABLE ...')
Nolang uses the @ keyword to declare exports in the package root lib.no file. External packages can only access these exported symbols when importing via #.
@ path.func [alias]
path — Module path (relative to package root, starts with /, without .no extension)func — Name of the function/constant/enum to exportalias — Optional alias, the name used when importing externallylib.no file// lib.no - package root export file
@ /src/utils.greet a
@ /src/utils.hello b
@ /src/math.pi
// src/utils.no
// Define exported functions
greet = (name str) {
print('Hello, ' - name)
}
hello = () {
print('Hi')
}
External packages can only access exports declared in lib.no when importing via #:
// Import alias a (corresponds to package-name.utils.greet)
# package-name.utils.greet a
// Or use the function name directly
# package-name.utils.greet
lib.no to jump to its definition in the corresponding module file@ and paths# — import module@ — export module.. — parent (super). — self! — false (planned, currently still uses false)!! — true (planned, currently still uses true){ } () — infinite loop (new style; !! { } is deprecated){ } (cond) — conditional loop (new style; for cond { } is deprecated){ } * N — counted loop (body repeats N times; N ≤ 0 skips the body)** — continue (skip current iteration) (planned, currently still uses continue)* — break (exit loop) (planned, currently still uses break)... — return/terminate (planned, currently still uses return)<- — range iteration-> — match arm / if-else branch (cond -> body): — match expression (x: { ... })? — option type prefix (?i64, ?str) / ternary operatorrun — start async threadawy — await async thread completion+ // addition- // subtraction (also used for string concatenation)* // multiplication (also used for string repetition)/ // division== // equal to!= // not equal to< // less than> // greater than<= // less than or equal to>= // greater than or equal to&& // logical AND|| // logical OR (also used for match branch combination, e.g. nil || err -> body)! // logical NOT& // bitwise AND| // bitwise OR^ // bitwise XOR~ // bitwise NOT<< // left shift>> // right shift= // assignment+= // add-assign-= // subtract-assign*= // multiply-assign/= // divide-assign%= // modulo-assign&= // bitwise AND-assign|= // bitwise OR-assign^= // bitwise XOR-assign<<= // left shift-assign>>= // right shift-assign? // ternary operator (e.g. c = flag ? 1 : 2)as // FFI pointer type conversion (e.g. y = x as *byte).. // slice range (e.g. arr[1..3], arr[1..], arr[..3])#{c} annotation)Declare external C functions through the #{c} annotation to implement FFI (Foreign Function Interface). #{c} is on its own line, marking the next line as an FFI declaration. #{c} is the FFI language key of the annotation system; it also supports #{cpp}, #{rust}, and other languages. The old syntax #c is still backward compatible.
Private declarations: Names starting with _ are private (not exported); C ABI symbols automatically strip the leading _ and convert hyphens to underscores.
No separate file needed: FFI declarations and regular code can be written in the same .no file.
Pointer type syntax: FFI uses C-style *T, **T, ***T to represent pointers, which must have a concrete type T. Regular code cannot use this syntax.
| Syntax | Meaning | LLVM IR | Usage |
|---|---|---|---|
*byte | pointer to byte | i8* | opaque pointer (e.g. db handle) |
**byte | double pointer | i8** | output parameter (e.g. sqlite3**) |
***byte | triple pointer | i8*** | rare triple indirection |
// sqlite.no — FFI bindings and safe wrappers in the same file
// Compiler automatically converts hyphens (-) to underscores (_) to match C ABI symbols
// Names starting with _ are private; C ABI symbol automatically strips leading _
// Basic type parameters
#{c}
c-strlen = (s str) (n i64)
// Pointer parameter (*byte = opaque pointer), private declaration
#{c}
_sqlite3-close = (db *byte) (rc i32)
// Double pointer (**byte = output parameter, value auto-stored back to variable after call), private declaration
#{c}
_sqlite3-open = (filename str, db **byte) (rc i32)
// Multiple pointer parameters, private declaration
#{c}
_sqlite3-exec = (db *byte, sql str, callback *byte, arg *byte, errmsg *byte) (rc i32)
// Safe wrapper in the same file
open = (dsn str) (d db-sqlite) {
handle i64 = 0
rc i32 = _sqlite3-open(dsn, handle)
rc != SQLITE-OK -> {
return
}
d.handle = handle
}
Rules:
#{c} is on its own line, marking the next line as an FFI declaration (old syntax #c is still backward compatible)*byte); bare ptr is not allowed*T → i8*, **T → i8**, ***T → i8***i64 on the Nolang side (via ptrtoint)**T parameters are output params: C function writes pointer, Nolang auto-converts to i64 and stores backstr params are auto-converted to null-terminated i8*_ are private (not exported); C ABI symbol strips leading _.no file#{...} is the general annotation system — a comma-separated list of key-value pairs. It supersedes the #c directive: #{c} is the new FFI syntax (old #c still works).
Supported value types:
| Syntax | Type | Example |
|---|---|---|
| Bare key | bool | #{debug} |
| Integer | int | #{max=100} |
| String | string | #{name='hello'} |
| Identifier | ident | #{mode=fast} |
| Array | array | #{derive=[Serialize, Deserialize]} |
| Range | range | #{range=[0..256)} |
Multiple key-value pairs are separated by commas:
#{derive=[Serialize, Deserialize], range=[0..256), max=100, debug}
Range syntax supports four bracket combinations:
[a..b] — closed on both ends[a..b) — left-closed, right-open(a..b) — open on both ends(a..b] — left-open, right-closedThe FFI annotation #{c} is a special form of the annotation system. When an annotation contains an FFI language key (c, cpp, rust, etc.) and is followed by a function declaration, the compiler identifies it as an FFI binding:
// #{c} with additional annotations
#{c, debug}
_sqlite3-open = (filename str, db **byte) (rc i32)
Non-FFI annotations are automatically attached to the declaration that follows. This is useful for tagging numeric types (like num) with range constraints:
// Variable declaration with range annotation
#{range=[0..256)}
x num = 42
// Struct definition with annotation
#{derive=[Serialize, Deserialize]}
point {
x i64
y i64
}
// Struct field with range annotation (for num and other numeric types)
person {
#{range=[0..150]}
age num
#{range=[0..256)}
score i64
name str
}
Platform annotations are compile-time filters that include or exclude code based on the target platform. They use flattened keys that unambiguously specify both OS and architecture (e.g. #{mac-arm64}), and are attached to the declaration that follows. Non-matching code is excluded from the build entirely — no LLVM IR is generated, no type checking is performed.
Supported platform keys (6 flattened combinations):
| Key | Matches |
|---|---|
#{linux-amd64} | Linux on x86_64 |
#{linux-arm64} | Linux on ARM64 |
#{win-amd64} | Windows on x86_64 |
#{win-arm64} | Windows on ARM64 |
#{mac-amd64} | macOS on x86_64 (Intel) |
#{mac-arm64} | macOS on ARM64 (Apple Silicon) |
// Platform-specific print
#{mac-arm64}
print('running on macOS ARM64')
#{linux-amd64}
print('running on Linux x86_64')
#{win-amd64}
print('running on Windows x86_64')
// Platform-specific variable
#{mac-amd64}
#{mac-arm64}
sep = '/'
#{win-amd64}
#{win-arm64}
sep = '\\'
// Platform-specific function
#{mac-arm64}
#{mac-amd64}
greet = () {
print('hello from mac')
}
#{linux-amd64}
#{linux-arm64}
greet = () {
print('hello from linux')
}
greet()
Multiple keys on the same declaration are OR'd together — any match includes the code. No AND logic is needed because each key already specifies both OS and arch.
| Annotation | Meaning |
|---|---|
#{mac-arm64} | macOS ARM64 only |
#{mac-amd64, mac-arm64} | macOS on any arch |
#{linux-amd64, win-amd64} | Linux x86_64 or Windows x86_64 |
#{mac-arm64, linux-arm64} | macOS ARM64 or Linux ARM64 |
// Included on both macOS and Linux (all archs)
#{mac-amd64, mac-arm64, linux-amd64, linux-arm64}
shared = () {
print('unix-like')
}
// Only on Windows x86_64
#{win-amd64}
reg-key = () {
print('reading registry on win/x64')
}
// Only on macOS ARM64 (Apple Silicon)
#{mac-arm64}
neural = () {
print('Apple Neural Engine available')
}
Use os.get-arch() to get the current architecture at runtime, and platform annotations to include/exclude code at compile time.
The range annotation is particularly useful for num type (num = int | float) to mark valid value ranges. Range bounds can be integers or identifiers (e.g. constants):
#{range=[i8.MIN..i8.MAX]}
val i8 = 100
If an annotation is not followed by a declaration, it remains a standalone AnnotationStatement.
Nolang strings (str) are a union type (short ≤127 bytes stored on stack / long stored on heap), supporting multiple operators and methods.
Nolang supports three kinds of string/char literals:
Single-quoted strings ('...'): Standard string literal with escape processing (\n, \t, \\, \', \0, etc.). Type: str.
Double-quoted char ("x"): Single Unicode character (rune). Type: char (i32). Only one character allowed.
Raw strings (backtick-delimited): Multi-line, no escape processing. Type: str.
// Standard string
s = 'hello\nworld'
// Char literal (rune)
c = "中"
// Raw string — backtick-delimited, multi-line, no escapes
sql = `
SELECT id, name
FROM user
WHERE id > 100
`
Raw string format constraints (core design):
` must be immediately followed by a source newline;` must be on its own line (only whitespace allowed before it);\, \n, \t, \', \" are preserved literally;Concatenation (-)
// Literal concatenation
s = 'Hello' - ' ' - 'World'
// Concatenation with variable
greeting = 'Hello, ' - name
Repetition (*)
s = 'Hello' * 3
s = 'Hello World'
// Index to get char (character, not byte)
c = s[0] // c = 'H' code point
// Slice (view, shares underlying memory)
sub = s[6..] // 'World'
sub = s[6..11] // 'World'
sub = s[0..5) // 'Hello'
// Length
n = s.len // byte length
n = s.count() // code point count (Unicode character count)
For the complete list of string methods, see Standard Library Overview — str module.
When assigning s[i] = v, LLVM codegen automatically updates the len field to max(len, idx+1), no need to manually set .len:
s = ''
s[0] = 72 // len automatically becomes 1
s[1] = 105 // len automatically becomes 2
// Manually setting .len is only for truncation (shortening)
s.len = 5
The Nolang standard library (src/std/) contains 60+ modules, covering formatting, math, strings, data structures, encoding/decoding, encryption, compression, file operations, I/O abstractions, etc.
Usage: # std/xxx (core modules do not need to be imported).
The old-style
use std/xxxstill works but is deprecated; using the new-style# std/xxxsyntax is recommended.
Note: All code examples follow the "one statement per line" rule —
;and//are both comment markers; commas,must not join multiple statements on one line.
Nolang type to LLVM mapping:
| Nolang | LLVM |
|---|---|
bool | i1 |
byte | i8 |
char | i32 |
i8/i16/i32/i64 | i8/i16/i32/i64 |
u8/u16/u32/u64 | i8/i16/i32/i64 |
f32 | float |
f64 | double |
str | union (short: [127]byte / long: {*byte, i64}) |
Composite types:
[]t: underlying { t*, i64 } (data, len)[n]t: LLVM fixed-size arraystr: union type (short ≤127 bytes stored on stack / long stored on heap), supports s[i], s[i..j], s + toption tagged enum (ok t / nil / err str)for iter.next() {} (interface method next() (ok bool))option<t> tagged enum (tag=0=val, 1=nil, 2=err):
x ?t // Declare option<t>
x = 42 // Set to has-value
x = nil // Set to empty
x = err('msg') // Set to error
// match
x: {
val -> f(it)
nil ->
err -> g(it)
}
Style guide: When a function may fail or return an empty value, use ?t option instead of (val, ok bool). ?t has three states: ok (has value), nil (empty/normal absence), err (error). Normal values are implicitly bound. For example, pop() returns ?i64 (nil = empty), read-line() returns ?str (nil = EOF, err = error), lookup() returns ?str (nil = not found).
printf(fmt str, ...) // Formatted output, no trailing newline
print(...) // Print with newline
Constants: math.PI, math.E
Basic: math.abs, math.sqrt
Trigonometric: math.sin, math.cos, math.tan, math.asin, math.acos, math.atan, math.atan2, math.degrees, math.radians
Hyperbolic: math.sinh, math.cosh, math.tanh
Rounding: math.ceil, math.floor, math.round, math.trunc
Exponential/Logarithm: math.exp, math.log, math.log10, math.log2, math.pow, math.hypot, math.cbrt
Others: math.fmod, math.max, math.min
char is essentially i32 (Unicode code point), all operations are provided as methods:
c char = 'A'
c.is-digit() // Is digit (0-9) (method)
c.is-letter() // Is letter (a-z, A-Z) (method)
c.is-alpha() // Alias for is-letter (method)
c.is-alnum() // Is letter or digit (method)
c.is-space() // Is whitespace character (method)
c.is-upper() // Is uppercase letter (method)
c.is-lower() // Is lowercase letter (method)
c.to-upper() // Convert to uppercase (ASCII) (method)
c.to-lower() // Convert to lowercase (ASCII) (method)
c.to-bytes() // Unicode → UTF-8 bytes (method)
c.to-str() // Unicode → string (UTF-8, method)
ok = a.eq(b, n) // Equality comparison (method)
dst = s.copy() // String copy (method)
s.fill(val byte) // Fill with byte value (method)
pos = s.index(sub) // Substring position
ok = s.contains(sub) // Contains
ok = s.starts-with(sub) // Prefix check
ok = s.ends-with(sub) // Suffix check
s.to-upper() // Convert to uppercase
s.to-lower() // Convert to lowercase
out = s.trim() // Trim leading/trailing whitespace
out = s.repeat(n) // Repeat
out = s.slice(start, end) // Slice
b = s.to-bytes() // Convert to []byte
s = b.to-str() // []byte to str (method)
v = s.to-i64() // String to i64 (returns ?i64)
v = s.to-i8() // String to i8 (returns ?i8)
v = s.to-i16() // String to i16 (returns ?i16)
v = s.to-i32() // String to i32 (returns ?i32)
v = s.to-u8() // String to u8 (returns ?u8)
v = s.to-u16() // String to u16 (returns ?u16)
v = s.to-u32() // String to u32 (returns ?u32)
v = s.to-u64() // String to u64 (returns ?u64)
v = s.to-byte() // String to byte (returns ?byte)
v = s.to-f64() // String to f64 (returns ?f64)
v = s.to-bool() // String "true"/"false" to bool (returns ?bool)
s = v.to-str() // i64 to string (method)
out = s.reverse() // Reverse
c = s.compare(b) // Lexicographic comparison
n = s.count() // Total code point count
val = s.replace-char(old, new) // Replace character (returns result string)
out = s.trim-char(c) // Trim specified character
ok = s.empty() // Is empty
s.clear() // Clear (len=0, in-place)
out = s.with-cap(cap) // Create new string with specified capacity (len=0)
out = s.with-len(len) // Create new string with specified length (len=cap)
out = s.with-cap-len(cap, len) // Create new string with specified capacity and length
parts = s.split(sep) // Split by separator (returns []str, method)
out = ss.join(sep) // Join []str with separator (method)
number.max(a, b) // Maximum
number.min(a, b) // Minimum
r = num.clamp(lo, hi) // Clamp to range (method)
r = number.abs(a) // Absolute value (num generic)
r = num.sign() // Sign (-1/0/1, method)
number.even(v) // Even/odd check
number.odd(v)
number.gcd(a, b) // Greatest common divisor
number.lcm(a, b) // Least common multiple
r = number.pow(a, n) // Integer power
number.i64-to-f64(v) // Numeric conversion
number.f64-to-i64(v)
s = int.to-str() // i64 to string (method)
q = number.div(a, b) // Integer division quotient
r = number.mod(a, b) // Modulo
number.swap(a, b) // Swap
yes = float.is-nan() // NaN check (method)
yes = float.is-inf() // Inf check (method)
// Range constants
i8.MIN / MAX // -128 / 127
i16.MIN / MAX // -32768 / 32767
i32.MIN / MAX // -2147483648 / 2147483647
i64.MIN / MAX // -2^63 / 2^63-1
u8.MIN / MAX // 0 / 255
u16.MIN / MAX // 0 / 65535
u32.MIN / MAX // 0 / 4294967295
u64.MIN / MAX // 0 / 2^64-1
out = i64.to-bytes-be() // i64 → big-endian [8]byte
out = i64.to-bytes-le() // i64 → little-endian [8]byte
v = []byte.to-i64-be() // big-endian []byte → i64 (1~8 bytes)
v = []byte.to-i64-le() // little-endian []byte → i64 (1~8 bytes)
s = []byte.to-str() // []byte to str (method)
s = []byte.to-hex() // []byte → uppercase hex string
s = []byte.to-hex-lower() // []byte → lowercase hex string
s = byte.to-str() // byte to str (method)
v = vec.vec-create(n, val) // Create slice of length n, filled with val
ok = []t.eq(a, b, n) // Equality comparison
n = []t.len() // Length
[]t.push(val) // Append (auto-grow)
[]t.clear() // Clear (len=0, cap/data unchanged)
v = []t.with-cap(cap) // Create new slice with specified capacity (len=0)
v = []t.with-len(len) // Create new slice with specified length (len=cap)
v = []t.with-cap-len(cap, len) // Create new slice with specified capacity and length
val, new-n = []t.pop() // Pop
found = []t.contains(n, val) // Contains (n is length)
[]t.reverse(n) // Reverse first n elements
[]t.clone(dst) // Copy to dst
[]t.fill(n, val) // Fill first n elements
arr = []t.to-arr() // Convert to array
[]t.sort-asc() // Ascending sort (method)
[]t.sort-desc() // Descending sort (method)
out = [n]t.clone() // Copy
ok = [n]t.eq(b) // Equality comparison
[n]t.fill(val) // Fill
[n]t.reverse() // Reverse
ok = [n]t.contains(val) // Contains