Lowent Manual
Systems Programming with Contracts and Effects
draft
rubidus@gmail.comgithub.com/rubidus-api/lowent_lang
An introduction to the Lowent language, and its user manual.
Written for readers who have programmed a little,
up to those who already use a systems language such as C or Rust.
This edition is a draft. For the paginated index and exact typesetting, see the PDF.
If anything in the book leaves you wondering, please ask on the Q&A board. I answer as time allows and as far as I know the answer. Korean or English, either is fine. For typos and mistakes, an issue is the better place.
Contents
Part I — Getting started
1 What Lowent sets out to do2 A first program — build, run, get rejected3 The surface — full stops, blocks and clause order
Part II — Values and flow
4 Numbers — fixed-width integers and floating point5 Ops — fn and proc6 Locals — let and var7 Flow — branches, loops and leaving early8 Expressions — prefix notation and the expr island
Part III — Data
9 Sequences — arrays and slices10 Aggregates — struct and enum11 Types that hold answers — option and result12 Borrowing — ref and mut_ref13 Named types — type, newtype, range, cast
Part IV — Contracts and effects
14 Contracts — write them, have them checked, lose the checks15 Effects — the marks an op leaves on the world16 Capabilities — power that is handed over17 Designing failure
Part V — Memory
18 Regions — where values live, and memory reclaimed all at once19 Ownership — one party responsible for disposal20 Allocators and fixed memory
Part VI — Abstraction
21 Modules — hidden by default22 Generics — parameters fixed at translation time23 Traits — one promise kept by many types24 pipe — one line for each thing you mean to do
Part VII — Concurrency
25 Actors — living with state, by messages26 Tasks and channels — exchange between bound flows27 Parallel loops and atomic operations
Part VIII — The outside world
28 Input, output and files29 Meeting C30 Hardware — registers, interrupts, machine instructions31 Building and testing — packages, configuration, tests, cross-checks
Part IX — The standard library
32 A map of the standard library33 Text and encodings — strings, fmt, utf8, codec, hash34 Containers and sorting — sortlib, sortgen, hashmap, vecgen, spsc35 Storage and handles — pool, shard, budget, wire36 Input/output, networking, time, randomness, cryptography37 The terminal — term and tty
Part X — Grounds: what has been proven
38 Why prove39 The mathematical toolkit40 Proofs about numbers — widening, narrowing, division41 Proofs about bounds — intervals, relations, row-major addresses42 Proofs about ownership and borrowing43 Loops and fixed points — proving “however many times”44 Proofs about effects — writing “what it can do” into the type45 Proofs about races and parallelism — discipline instead of a memory model46 Proofs about weak memory — with the default, you may think sequentially47 Proofs about locks — where heavy tools are really needed48 Proofs about syntax — whichever closer closes it, the same tree49 Proofs about hashes — calling things by content, not name50 What is not proven
Front and back matter
Appendix A — Words and builtinsAppendix B — Diagnostics indexAppendix C — Common mistakes and how to fix themAppendix D — Grammar summaryAppendix E — Standard library modulesstrings — string view operationsstrbuf — owned string buffer and null-terminated cstrfmt — formatting assembled into the caller’s bufferutf8 — UTF-8 code point iteration and validationutf16 — UTF-16 surrogate arithmeticunicode — Unicode property tablescodec — hex and base64regex — Pike VM regular expressions without backtrackingterm — terminal renderer (the pure half)sortlib — in-place quicksortsortgen — generic sorting (the type brings the comparison)searchlib — binary search on sorted sliceshashmap — u64 → u64 hash mapstrmap — string-keyed hash mapvecs — growable byte vectors with caller-held buffersspsc — lock-free SPSC ring bufferhash — hashing (hash map slots · corruption detection · SHA-256)math — floating-point mathsrandom — random numbers (reproducible sequences · OS entropy)hmac — HMAC-SHA256 and HKDFchacha — ChaCha20 stream cipherpoly — Poly1305 one-time authenticatoraead — ChaCha20-Poly1305 seal and openx25519 — key agreement on a curveaes — the AES-128 block ciphergcm — AES-128-GCM authenticated encryptioncrypto_hw — arithmetic the machine helps withbigint — big-number modular arithmeticrsa — RSASSA-PSS verificationp256 — the NIST P-256 curve and ECDSA verificationp384 — the NIST P-384 curve and ECDSA verificationecdsa — ECDSA P-256 signinged25519 — Ed25519 signature verificationder — minimal DER parserpem — unwrapping PEM envelopesx509 — reading X.509 certificatesverify — certificate signatures and one link of a chaintls13 — the computational parts of TLS 1.3tlssrv — the TLS 1.3 server handshaketlscli — the TLS 1.3 client handshakehttp — HTTP/1.1 request parsersoa — an SoA layout trial: one array per fieldallocs — allocator traits, bumps and default allocatorspool — generational-handle block poolshard — access units that split a storebudget — handle bit budgets and generation wraparoundwire — dividing one word into fieldsflags — named on/off settings in one wordsegarena — fixed-size segment arenapagecache — page ids and pinning cursorsgrowvec — self-growing byte vectorvecgen — generic self-growing vector vec t amapgen — generic hash map table k vnodelist — fixed intrusive listssegview — cursors, total length and coalescing for segment viewslifemode · lifeatom — when a value endsio — stream reading over slicesoutbuf — buffered output where forgetting to flush is a compile errorfiles — file and directory streams where forgetting to close is a compile errortty — terminal inputnet — sockets (TCP loopback · in-process pairs)clock — time and deadlinestrust — finding a trusted root in the trust storeIndex
Copyright and contact
The text — Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International (CC BY-NC-SA 4.0). You may share and adapt it freely with attribution; commercial use is not permitted, and adaptations must carry the same licence.
creativecommons.org/licenses/by-nc-sa/4.0/
The example code — MIT licence. Take it and use it. The Lowent compiler and standard library used by the examples follow the repository's MIT licence.
Every code demonstration in this book is output actually obtained by checking and running it with lowentc. The typesetting is done with Typst.
This book keeps being revised. What you are reading is the edition numbered above; corrections and additions follow it. Reports and suggestions are taken at the repository.