Documentation
Learn Calx from the guide, look up what each feature does in the reference and the standard library, and see what is designed but not built yet.
Guide
Installing Calx, then learning it by building one small program, stash, which keeps count of items from commands it reads.
- Install CalxBuilding the compiler from source on Windows or Linux, and checking that it runs a program
- Getting startedThe program, the
calxcommand, values and variables, functions, loops, and the checker's errors - Reading the commandsStandard input a line at a time, optionals and
while let, and splitting a line into words - What the commands meanCommands as an enum, parsing numbers, functions that fail, matching on text, and copying out of a list
- The stashA sorted map, parameters that own or change what they're given,
try, the whole program, and modules
Reference
What's built, one page per feature.
- The calx commandCheck, build, run, emit-c, how builds stay fast, and errors for editors
- Editor supportThe VS Code extension, and the grammar and error format other editors can use
- SyntaxFiles, comments, names, keywords, literals, raw strings and operators
- TypesThe primitive types, arrays,
Copy, and where the other types are - VariablesLet, var, constants, assignment, unused names, no shadowing
- IntegersWrapping, division, shifts and constant expressions, as in Java
- FloatsIEEE 754 arithmetic and printing, as in Java
- ConversionsExact
T(x), the named lossy conversions, andtry_from - Control flowIf, while, while let, for,
for x in mut xs, loop, break and continue - FunctionsParameter modes, named arguments, returns, evaluation order
- StructsFields, defaults, literals and methods
- EnumsVariants with and without data, representations, conversions
- TuplesValues grouped by position, and destructuring
- Optionals
T?instead of null,??,!,?. - ErrorsFunctions that can fail,
fail,try, matchingokanderr,!, a failingmain, and their C - Patterns and matchMatch, exhaustiveness,
if let,let ... else - Strings
strandString, free literals, building, methods, slicing, Java's case mapping and matching - Lists
List<T>, its methods, indexing, loops and printing - Deques
Deque<T>, added to and taken from at both ends, its methods, indexing, Java's and Rust's names for them, and its C - Priority queues
PriorityQueue<T>, least first, its elements in Java's places, its methods, taking out marked elements, Java's names for them, and its C - Boxes
Box<T>, one value on the heap so a type can hold itself, its value as the placeb.value, and its C - Maps and sets
Map<K, V>andSet<T>, their methods, indexing, loops, deterministic order,Hash, and their C - Linked maps and sets
LinkedMap<K, V>andLinkedSet<T>, in the order keys went in, their ends, Java's and fastutil's methods written in Calx, and their C - Sorted maps and sets
SortedMap<K, V>andSortedSet<T>, in key order, their ends, the nearest keys, ranges, Java's and fastutil's methods written in Calx, and their C - Ownership
Copy, moves, views, partial moves, when values are freed, and their C - Arenas
ArenaandArenaList<T>, lists freed all at once, the rules that keep them safe without lifetimes, parallel loops, and their C - GenericsGeneric functions and types, inference, bounds,
Copy,Equal,Display,HashandJavaHash, and their C - InterfacesMethods, constants and defaults, impls, and naming the interface
- Comparing and printingThe derived
EqualandDisplay,==and{x}on every type, and their bounds - ModulesFiles as modules, imports,
pub, and one C file per module - Printing and panicsPrint, println, eprint, eprintln, assert and panic, and
@track_caller - Unsafe code and C functions
unsafeblocks and functions, raw pointers, and calling C - Libraries
calx build --lib,@export, opening a library while a program runs, types checked down to the fields, and the one runtime they share - AttributesAttributes a library defines as Calx functions the compiler runs, their arguments, attributes on fields, the code they generate, the cache, and
calx expand - Parallel loops
parallel forover a range or a list's elements, the capture check, and the same result with any number of threads - StrictnessThe rules that make the checker stricter than Rust's
Standard library
The std modules, one page each (modules).
- std.ioStandard input and output as bytes, and standard input a line at a time
- std.mathFast math functions, accurate to about half an ULP and the same on every platform
- std.java.mathMath functions with
StrictMath's results bit for bit - std.timeA monotonic clock, and the wall clock with its dates and local time zone, which only
unsafecode can read - std.envThe command-line arguments
- std.poolThe threads
parallel forruns on - std.netTCP connections driven by events, on IOCP and epoll
- std.hint
black_box, which hides a value from the optimizer, for benchmarks - std.text.mutf8Java's Modified UTF-8, as
DataOutputStream.writeUTFwrites it - std.mailMessages between actors, delivered at the barrier in order of sender, then of sending
- std.hashMD5, SHA-1, SHA-256 and HMAC-SHA256, as Java's
MessageDigestandMacgive them - std.cryptoRandom bytes from the system, AES-CFB8 and RSA
- std.zlibZlib, gzip and raw deflate, as Java's
Deflater,Inflaterand GZIP streams write and read them - std.httpHTTP and HTTPS requests on the system's own client, each on a thread of its own
- std.lz4LZ4 block streams, as lz4-java's
LZ4BlockOutputStreamandLZ4BlockInputStreamwrite and read them - std.threadThreads for services, which only
unsafecode starts, the typed queues they talk through, and sleeping - std.metaDeclarations as data, and the code an attribute gives back
- std.fsFiles and directories, read and written whole or in parts in place, with atomic renames, locks, real paths and temporary directories
- std.buildThe program's build ID, which changes exactly when its code does, for keying caches
- std.termThe terminal's size, raw input a key at a time, and the text that puts it back however the program ends
- std.processThis process's memory, the memory it may use, its CPU time and its processors, and
exit - std.text.utf8Bytes that may not be UTF-8 as text, with U+FFFD in their place, as Java reads them
- std.paletteMinecraft's paletted containers, a chunk section's block states and biomes, grown, sent, saved and loaded as Java Edition 26.3 does them
Java compatibility
Hash tables that iterate in exactly the order Java's or fastutil's do, for code ported from Java whose results depend on it. They're in the reference too, but most programs want Map and Set.