3 The surface — full stops, blocks and clause order

3.1 The name first, then the arguments#

Lowent expressions use prefix notation. The name of the operation comes first and its arguments follow. add a b adds a and b, and a form inside a form is wrapped in parentheses.

let total u64 be add 1 2 .
let mixed u64 be add 1 (mul 2 3) .

Prefix notation has no precedence. Someone reading 1 + 2 * 3 knows that multiplication comes first because they memorised it, but in add 1 (mul 2 3) the parentheses already say so. The principle is the same for ops you write yourself. write_out out 1 "hi", field p x and mean xs all put the name first.

3.2 A free-standing full stop closes#

The end of a statement or clause is closed by a free-standing full stop ., called a closer. A newline is not a closer — it is whitespace, exactly like a space. So wherever you break a line, the meaning stays the same.

module newline .
rem run: poly 5 4
rem run: poly_expr 5 4

note WHY
  개행은 공백이다. 폼은 자기 닫개인 떨어진 마침표에서 끝난다.
  그래서 줄을 어디서 나누어도 뜻이 같다.
WHY

fn poly input a u64 . input b u64 . output u64 .
do
  return add (mul a 2)
             (mul b 3) .
end

fn poly_expr input a u64 . input b u64 . output u64 .
do
  return expr a * 2 + b * 3 .
end

$ lowentc --run poly poly.low 5 4
poly(5, 4) = 22
$ lowentc --run poly_expr poly.low 5 4
poly_expr(5, 4) = 22

The return in poly spans two lines but is one form; it ends at the full stop at the end of the second line. That is why there is no line-continuation marker (C’s trailing backslash, a trailing comma, indentation rules). poly_expr in the same file writes the same computation as an expr island, and the two ops give the same answer.

note WHY … WHY is a multi-line comment; it ends at a line where the word written after note stands alone. rem is a line comment. The language has no symbolic comments like // or /* */ — comments too are opened with words.

The number of full stops works as a kind of checksum. If opened forms and closers do not match, the compiler says so. Forgetting one parenthesis looks like this.

module dots .
rem expect: E-GROUP-UNCLOSED

fn poly input a u64 . input b u64 . output u64 .
do
  return add (mul a 2 (mul b 3) . .
end

$ lowentc --check dots.low
7:1 E-PAREN-ESCAPE: a `(` opened inside this block was never closed — it would have ESCAPED past the `end`. It used to: the newline-continuation stayed on for the REST OF THE FILE and every op after it was swallowed into the group. A bracket may not cross a block boundary; it is closed here
6:14 E-GROUP-UNCLOSED: missing ')'

The first diagnostic means a parenthesis tried to leak past the block’s end. Parentheses cannot cross a block boundary. So a single wrongly closed parenthesis stops inside that block instead of silently swallowing the rest of the file.

module semi .
rem expect: E-VOCAB-REMOVED

fn twice input a u64 . output u64 . do return mul a 2 . ; end

$ lowentc --check semi.low
4:57 E-VOCAB-REMOVED: `;` was a THIRD spelling of the closer `.` (the lexer literally emitted a DOT for it) — one meaning, three spellings, and SPEC-002 §2.5 forbids synonyms. It only survived inside the old interpreter's second language. Write `.`

3.3 A block is always do … end#

Every place that groups statements opens with do and closes with end: an op body, the body of if, while and for, the arms of match, and the bodies of declarations such as struct, enum, trait and actor.

struct point do
  x u64 .
  y u64 .
end

fn sum_to input n u64 . output u64 .
do
  var total u64 be 0 .
  var i u64 be 1 .
  while le i n . do
    set total (add total i) .
    set i (add i 1) .
  end
  return total .
end

do … end works like a pair of braces. end closes only its own do and leaves everything outside alone. So there are just two rules to know.

• A construct that owns a block as its body ends at end: op declarations, struct·enum, if·while·for·match. As in the example above, no full stop follows the end — one there closes nothing and is rejected with E-DOT-STRAY.
• A statement that uses a block as a value ends with its own full stop, like any statement. Building a struct value with make and binding it with let is the usual case: let p point be make point do x 1 . y 2 . end . — the last stop belongs to the let. Leaving it out is E-DOT-MISSING.

In C terms: no ; after if (c) { … }, but one after p = (struct point){ 1, 2 };.

while le i n . do  …  end                  block as body: the while statement ends at end
└─── while statement ───┘

let p point be make point do x 1 . end .   block as value: the block is make's, the statement ends with its own .
               └──── make value ─────┘ │
└─────────── let statement ────────────┘

Each statement inside a block must end with its own full stop too; end does not close an open statement for you. A bare do … end with nothing opening it is not allowed either (E-BLOCK-NOHEAD) — a block always has a head. Opening a declaration block with only a line break instead of do is rejected with E-STMT-NODO, and --fmt inserts the do. The clauses of an op header work the same way. Each ends with its own stop — input n u64 . · output u64 . — and the next clause word does not close the one before it; leaving the stop out is E-DOT-MISSING.

3.4 Comments and literals#

An integer literal has no type of its own; the place where it is used gives it one. A leading 0 is not octal (0755 is 755). A literal that does not fit the type of its place is rejected rather than silently truncated.

module lit300 .
rem expect: E-TYPE-WIDTH

fn f output u8 .
do
  let x u8 be 300 .
  return x .
end

$ lowentc --check lit300.low
lit300.low:6:0 E-TYPE-WIDTH: value does not fit the declared type (a literal out of range, or a narrowing — use narrow / narrow_wrap / narrow_sat / round_to)

C truncates 300 to 44 when it is put in a u8. Then the value written in the source and the actual value differ. Lowent stops it at translation time. Shrinking is done by writing one of the named narrow operations (chapter 4).

The set of string escapes is closed. There are the familiar \n, \t, \\ and \", plus \xNN (exactly two digits), \uXXXX (four) and \UXXXXXXXX (eight); any other escape is rejected with E-STR-ESCAPE. C’s \x eats hex digits without end, so the meaning of "\x41e" depends on the character next to it; in Lowent \x41e is always A followed by e. A string is not a separate type but a byte slice (slice u8).

\uXXXX and \UXXXXXXXX write a code point, and the prefix decides how many units carry it — "\U0001F600" is 4 bytes, u"…" is 2 UTF-16 code units (a surrogate pair) and U"…" is 1 code point. Surrogate values (D800 … DFFF) and values above 10FFFF are rejected. There are no octal escapes — the language has no octal notation at all, so reviving it only in literals would make that the one exception.

Using every shape in the table in one file looks like this.

module literals .
rem run: ints
rem run: floats
rem run: chars
rem run: texts

note END
note 와 같은 태그 사이의 줄은 모두 주석이다.
Lines between note and the same tag are all a comment.
END

rem integers: binary, digit separator _, hexadecimal; a leading 0 is not octal
fn ints output u64 . do
  let a u64 be 0b1010 .
  let b u64 be 1_000_000 .
  let c u64 be 0xFF_FF .
  let d u64 be 0755 .
  return add (add a b) (add c d) .
end

rem floating point: exponent e, hexadecimal float p (0x1.8 is 1.5, p1 multiplies by 2)
fn floats output f64 . do
  let e f64 be 1.5e3 .
  let h f64 be 0x1.8p1 .
  return add e h .
end

rem characters: 'A' is one byte, u'가' one UTF-16 code unit, U'😀' one code point
fn chars output u64 . do
  let a u8 be 'A' .
  let k u16 be u'가' .
  let s u32 be U'😀' .
  return add (widen u64 a) (add (widen u64 k) (widen u64 s)) .
end

rem strings: \x41 takes exactly two digits so "\x41e" is two bytes; u"가나" is two code units
fn texts output u64 . do
  let x u64 be len "\x41e" .
  let w u64 be len u"가나" .
  rem text TAG … TAG holds several lines as written; a \n in the body is not unescaped
  let h u64 be len text DOC
line one
a\nb
DOC .
  return add (mul x 100) (add (mul w 10) h) .
end

$ lowentc --run ints literals.low
ints() = 1066300
$ lowentc --run floats literals.low
floats() = 1503.0
$ lowentc --run chars literals.low
chars() = 172609
$ lowentc --run texts literals.low
texts() = 233

• ints is 10 (0b1010) + 1000000 (1_000_000) + 65535 (0xFF_FF) + 755 (0755). An underscore goes only between digits and does not change the value; it makes long numbers easier to read. 0755 is 755, not 493, a choice that removes a C trap.
• floats is 1500 (1.5e3) + 3 (0x1.8p1 — 1.5 × 2¹). Hexadecimal floats are for when the bits must be written exactly. Decimal 0.1 cannot be written exactly in binary, but 0x1.8p1 is exactly 3.
• chars is 65 ('A') + 44032 (u'가') + 128512 (U'😀'). The prefix decides the width of the element. Writing a character that does not fit in one byte, such as '가', without a prefix is refused with E-CHAR-WIDTH.
• In texts, "\x41e" is 2 bytes, u"가나" is 2 code units and text DOC … DOC is 13 bytes. A multi-line string (heredoc) holds, exactly as written, everything from the tag after text to the line where the same tag stands alone. The \n in the body is two characters, not a newline, and no newline is added after the last line. It is there to paste long descriptions or test input without escapes.
• The note END … END at the top is a multi-line comment. It turns a whole block into a comment without rem on every line.

3.5 Names#

A name starts with an ASCII letter or underscore and continues with letters, digits and underscores. Two things differ from other languages.

First, declared names contain no dots. A place with a dot attached is a path referring to a name, and it has only three meanings — a module’s name (allocs.byte_allocator), a variant’s name (node.lit), and the name of a declaration attached to a type (rect.area). Looking inside a value (reading a field, calling a method) is not a glued dot but a form: field p x · method s area.

Second, there is no shadowing. An inner name that reuses the spelling of an outer name is rejected.

module shadow .
rem expect: E-NAME-SHADOW

fn f input n u64 . output u64 .
do
  let n u64 be add n 1 .
  return n .
end

$ lowentc --check shadow.low
shadow.low:6:0 E-NAME-SHADOW: a local binding takes the name of a PARAMETER of the same op. The namespace is FLAT (SPEC-002 2.10: no shadowing) — from here on the same letters mean the new binding, and a reader who saw the signature will read the wrong value. Rename the local

A shadowed name makes someone who read the head think of a different value. If you had to work out on every line whether n is the parameter or the new local, that is exactly semantic entropy. No parameter, module name, builtin op name or name still alive in an outer block can be shadowed. Choose a new name instead.

3.6 Words are a budget#

The words the language gives meaning to (keywords) form a closed list. Adding a new word grows the language, so nothing that existing words can express gets a new one. Roughly, they fall into these groups.

add, len, neg and the like are not words but builtin ops. They cannot be used as parameter names either, but they occupy the space of names rather than grammar. Removed words (in, loop, as, to and so on) are not quietly accepted; E-VOCAB-REMOVED tells you what to use instead.

3.7 The boundaries of the expr island#

What the island allows fits in one table. * and / bind tighter than + and -, comparisons (eq, lt and so on) come below them, and and binds tighter than or. Bitwise operations, remainder, minimum and the like are written in prefix form even inside the island. The precedence of bitwise operations differs between languages, so putting them in the island would not make them easier to read — it would add something to look up.

Comparisons cannot be chained.

module chain .
rem expect: E-EXPR-CHAIN

fn between input a u32 . input b u32 . input c u32 . output bool .
do
  return expr a lt b lt c .
end

$ lowentc --check chain.low
chain.low:6:0 E-EXPR-CHAIN: comparisons do not chain in an `expr` island — `a lt b lt c` reads like mathematics but means `(a lt b) lt c`, which compares a bool with a number. Say what you mean: `expr (a lt b) and (b lt c)`

Mathematical a < b < c means “a is less than b and b is less than c”, but in many languages that spelling reads as (a < b) < c. A spelling that means one thing to people and another to the machine is a place where code is silently wrong. As the diagnostic suggests, write expr (a lt b) and (b lt c).

3.8 Clause order in an op head#

An op head is a name followed by clauses. Each clause is closed by a full stop, and clauses have one fixed order.

You need not memorise every clause; most ops use four or five of them. What to remember is the principle — clauses are placed so that earlier ones are used by later ones. Type parameters before inputs, capabilities before data, inputs before the output, capabilities before effects, effects before contracts.

proc copy_upper
  input out cap io .            rem capability input
  input src slice u8 .          rem data input
  output u64 .
  effects io .
  requires gt (len src) 0 .
do
  return write_out out 1 src .
end

Written on one line or one clause per line, the meaning is the same (newlines are whitespace). This book writes short heads on one line and heads with contracts one clause per line.

3.9 Common mistakes#

Surface mistakes mostly come from habits carried over from other languages. Some diagnostics point somewhere unexpected, so it helps to remember the shapes too.

module mistake_slash .
rem expect: E-RETURN-PARTIAL

fn twice input a u64 . output u64 .
do
  rem ✘ `//` is not a comment marker --- this line and the next become one form ending at a single stop
  // double it
  return mul a 2 .
end

$ lowentc --check mistake_slash.low
mistake_slash.low:4:0 E-RETURN-PARTIAL: this op says it OUTPUTS a value, but some path through its body reaches the end without a `return`. Until now the tool quietly returned 0 there — a value that appears NOWHERE in your source (RFC-0019 G-TOTAL). Give every path a `return`, or say `output void` if it really produces nothing. An exhaustive `match` whose every arm returns counts as returning
mistake_slash.low:7:0 E-VOCAB-REMOVED: `//` is not a comment here — this language has never had it. A comment starts with `rem` (to the end of the line) or `note <tag>` … `<tag>` (several lines). Until today `//` slipped through to lowering and was reported as an unsupported FEATURE, which sent the reader looking for a missing capability instead of a wrong spelling

module mistake_glued .
rem expect: E-FIELD-GLUED

struct point do
  x u64 .
  y u64 .
end

fn getx input p point . output u64 .
do
  rem ✘ reads a field with a glued dot --- fields are read with `field p x`
  return p.x .
end

$ lowentc --check mistake_glued.low
mistake_glued.low:12:10 E-FIELD-GLUED: glued-dot field access is gone — write `(field <value> <name>…)` instead. One meaning gets one spelling: the dot still means module qualification (`mod.name`), a variant name (`err.too_short`) and a type-associated declaration (`fn pt.twice`), so a fourth meaning made the same letters mean four things. `field` chains: `(field o i z)`

module mistake_order .
rem expect: E-CLAUSE-ORDER

rem ✘ `output` comes before the input --- clauses have one order
fn twice output u64 . input a u64 .
do
  return mul a 2 .
end

$ lowentc --check mistake_order.low
mistake_order.low:5:23 E-CLAUSE-ORDER: a data input comes after `output`. An op header has ONE order: `satisfies`/`lowdoc` · `vector`/`priority` · `comptime` inputs · capability/region inputs · `using` · data inputs · `output` · `effects` · `link`/`variadic` · `asm` · `access`/`inplace`/`invalidates`/`parallel`/`reduce` · `requires` · `ensures` · `errors` · `tests` (`--fmt` moves the non-input clauses for you; inputs are call positions, so reorder those and their call sites yourself)

module mistake_ifdo .
rem expect: E-TOPLEVEL

fn pick input a u64 . output u64 .
do
  rem ✘ the body of `if` was not opened with `do`
  if gt a 3 .
    return 1 .
  end
  return 0 .
end

$ lowentc --check mistake_ifdo.low
mistake_ifdo.low:10:0 E-TOPLEVEL: this is a STATEMENT, and it sits outside every op body — an `end` above it closed the op earlier than you meant. The usual cause is a control head written without `do`: `if <cond> .` alone takes the ONE statement that follows as its body, so the `end` written for the `if` ends the OP instead. Write the body as `if <cond> . do … end` whenever it holds more than one statement
mistake_ifdo.low:4:0 E-RETURN-PARTIAL: this op says it OUTPUTS a value, but some path through its body reaches the end without a `return`. Until now the tool quietly returned 0 there — a value that appears NOWHERE in your source (RFC-0019 G-TOTAL). Give every path a `return`, or say `output void` if it really produces nothing. An exhaustive `match` whose every arm returns counts as returning

module mistake_quote .
rem expect: E-CHAR-WIDTH

fn size output u64 .
do
  rem ✘ single quotes hold one character --- strings use double quotes, "hi"
  return len 'hi' .
end

$ lowentc --check mistake_quote.low
mistake_quote.low:7:0 E-CHAR-WIDTH: this character does not fit ONE unit of the prefix you chose. `u8'…'` holds one BYTE (a Hangul syllable is three in UTF-8), `u'…'` one UTF-16 code unit (a non-BMP character is a surrogate PAIR), `U'…'` one code point. Widen the prefix, or use a string — the tool will not silently keep the first unit and call it the character

module octal .
rem run: perm

fn perm output u64 .
do
  rem a leading 0 means nothing --- this is seven hundred fifty-five
  return 0755 .
end

$ lowentc --run perm octal.low
perm() = 755

3.10 This chapter’s syntax at a glance#