Documentation

Saule is a statically typed, class-oriented scripting language. It reads like Lua and checks like a typed language: every parameter and field states its type, nil is a thing a type opts into rather than a value any slot can hold, and the compiler reports what it found before anything runs.

This page is the index. If you are starting from nothing, read Introduction and then Your First Program — about fifteen minutes together. If you are here to look one thing up, the Quick Reference and the Grammar are the two pages that answer most questions without reading prose.

Start here

IntroductionWhat the language is for, what it borrows from Lua, and what it does differently.

InstallationInstall the toolchain on Linux, macOS or Windows, and check it works.

Your First ProgramFrom an empty file to a running program, with the type checker explained as it speaks.

PlaygroundWrite and run Saule in the browser. Nothing to install.

The language

Fifteen pages covering the whole language, in the order they build on each other. Each one is worth reading end to end once; afterwards they work as reference.

Typesinteger, float, string, bytes, byte, boolean, any — and why integer and float never mix implicitly.

Variableslocal bindings, module variables, inference, and the rule that a non-nullable slot can never start empty.

TablesOne structure, two jobs: 1-based arrays and typed maps, with element types that are invariant.

FunctionsDefaults, named arguments, multiple returns, variadics, generics and the when(...) pipeline.

Lambdas and ClosuresArrow lambdas, inferred parameter types, captured state, and trailing blocks.

ClassesFields, methods, visibility, static members, inheritance and overriding.

InterfacesContracts a class fulfils, including the Op* family behind operator overloading.

EnumsPlain variants, valued variants, payloads, methods and generic enums.

Pattern Matchingmatch as a statement and an expression, with guards and exhaustiveness checking.

Null SafetyT?, ?., ?[ ], ?? and ! — how absence is expressed and how the checker makes you handle it.

Error Handlingthrow, try, several catch clauses, finally — and when a nullable return is the better answer.

LoopsNumeric for, for-in over tables and iterables, while, repeat-until, break and continue.

CoroutinesFunctions that pause with yield and resume where they stopped — typed as Coroutine, stackful, and iterable.

Imports and File Structureexport, import, folder modules, visibility across files, and why circular imports are refused.

Project Configurationsaule.config: entry points, source roots, dependencies and the minimum toolchain version.

Standard library

Everything Saule ships with. All of it is in scope with no import — the modules are static classes, not packages.

Preludeprint, println, printf, tostring, type, assert, error — and the interfaces the language itself looks for.

StringUTF-8 aware text: slicing, searching, splitting, joining, padding and formatting.

BytesBuffers that are not text, kept apart from string so a byte can never be mistaken for a character.

MathRounding, arithmetic, trigonometry and randomness, generic over integer and float.

TableThe mutating half of the sequence API: insert, remove, sort, and questions about a table.

IterThe deriving half: map, filter, reduce and friends, eager and fully typed.

CoroutineCoroutine.create, resume, status and error, and the Yielder a body yields through.

Io / FileStandard streams and file handles, with modes and seek positions as real enums.

OsTime, environment, filesystem, and child processes you can talk to while they run.

SauleThe version of the toolchain running your code, and how to degrade gracefully on an older one.

ProjectThe saule.config of the code being run: name, version, root and source directories.

ConventionsThe patterns that repeat across the whole library, and why each one is the way it is.

Reference

Quick ReferenceKeywords, literals, operators and coroutines in four tables, for looking something up at a glance.

GrammarThe complete syntax, transcribed from the parser, so it describes what the compiler accepts.

CLIsaule run, check, fmt, build and the rest, with the flags each one takes.

Editor SupportSyntax highlighting, the language server, and what it gives you in each editor.

Worked examples

Complete programs rather than fragments — each one is a project you can read end to end, grouped simple to advanced on the index.

All examplesThe index, with what each program demonstrates.

Operator OverloadingA Vec2 that adds, subtracts and scales through the Op* interfaces.

Bitwise OperatorsA permission flag set and a packed RGBA colour, with Lua 5.3's spellings.

CoroutinesLazy stream combinators, a stackful tokenizer, and a cooperative scheduler.

Todo AppA multi-module program with imports, file IO and a real project layout.