Renderingen-US

Experimental through version 1. Version 0 was alpha. This is the first language release: the interface is relatively stable, not frozen. Nothing is promised stable until version 2.

Norma — the standard library

Norma is Faber's standard library. It provides English-named modules accessed through norma:* paths, with nested norma:parent/child submodule paths for shared types and facades. Stdlib declarations are Faber source in the compiler repository (lib/norma/src/) and are embedded in the faber binary. Norma is a platform default — apps use it without declaring it in faber.toml [dependencies].

Module names are English: norma:text, norma:fs, norma:console. A Latin spelling such as norma:textus is not a module name; it is rejected as PKG001 unknown_library_module. Since 1.16 the check runs for every target before any code is emitted, so an import of a module that does not exist never passes faber check.

Modules#

ModuleDomain
norma:consoleConsole I/O (stdin, stdout, stderr)
norma:cryptoCryptography (hash, HMAC, cipher, sign)
norma:csvCSV wire format
norma:dbSQLite: connections, transactions and prepared writes, with DbFault errors (runner and generated Rust; since 1.19)
norma:dequeDouble-ended queue
norma:encodingEncoding and decoding (base64, hex, URL)
norma:faultThe I/O fault union (IoFault)
norma:fsFilesystem operations
norma:fs/pathPure pathname operations
norma:httpHTTP client and server
norma:jsonJSON parsing and serialisation
norma:mathScalar math catalog
norma:netNetwork sockets (TCP)
norma:orderThe ordering contract (Orderable<T>)
norma:processProcess execution and environment
norma:randomEntropy and randomness
norma:sinkThe sinking contract (Sink<T>) and an in-memory Collector; checks but does not run yet (Sinks)
norma:sorted_mapKey-ordered map
norma:tensorTensor bridge helpers
norma:textText and cord operations, UTF-8 encode / decode
norma:timeTime and duration
norma:tomlTOML parsing and serialisation
norma:valueCodec-agnostic value-tree navigation
norma:vectorVector register intrinsics
norma:websocketWebSocket client and HTTP-upgrade accept

Nested submodules#

Shared types and facades live under a parent module — every .fab file in a subdirectory is a separately importable module:

ImportRole
norma:net/endpointTCP endpoint type (Endpoint)
norma:net/connectionConnected socket type (Socket)
norma:net/listenerTCP listener type (Listener)
norma:json/serializeJSON serialize implementation
norma:json/solveJSON parse implementation
norma:json/cursorParser cursor type (ScanResult)
norma:json/lexerShared lexical floor (internal)
norma:http/headersHTTP header map
norma:http/requestReceived HTTP request
norma:http/responseHTTP response
norma:http/clientHTTP client verbs
norma:http/serverHTTP/1.1 listener
norma:http/chunkedChunked transfer codec
norma:http/sseServer-sent events codec

Morphologia naming convention#

Norma follows the morphologia policy for all method names. Verb form carries execution mode; number carries flow. Two axes compose: time × flow (sync/async × finite/stream) and ownership (mutate vs copy-out).

Callable posture is a signature slot: bare means synchronous finite, async an asynchronous finite function, generator a synchronous stream, async_generator an asynchronous stream. @ future / @ cursor remain accepted compatibility spellings, but the posture words are the canonical surface.

StemSyncAsyncMeaning
read-read_fileread_file_asyncRead
write-write_filewrite_file_asyncWrite
query-—queryQuery (finite)
query-—query_streamQuery (stream)

Ownership pairs (mutate vs copy-out):

MutateCopy-outMeaning
addaddedAdd
reverseinvertReverse
sortsortedSort

Async finite verbs return promise<T>; async streams yield values through yield. The mechanical trio covers wire encode / decode: stringify / parse in json, toml, and csv (plus try_parse in json and toml), and encode / decode / try_decode in text.

Usage#

import from "norma:fs" fs
import from "norma:fault" fault

fn load_config() → string ⇥ fault.IoFault {
    return fs.read_file<string>("config.toml")
}

read_file is failable: its error channel is fault.IoFault, the union of I/O fault kinds, so the caller handles it or passes it on.

For files that must never be left half-written, norma:fs has write_file_durably and write_bytes_durably. They replace the file atomically: a failure or an interruption leaves the previous complete file, never a partial one.

import from "norma:fs" fs
import from "norma:fault" fault

fn save_config(string text) → void ⇥ fault.IoFault {
    fs.write_file_durably("config.toml", text)
}

Test code can live beside product source in colocated *.proba files — discovered only by faber test, never importable, and excluded from Cista package snapshots.