Lightning Script Documentation

This manual follows the broad organization of the Lua 5.4 Reference Manual: language and execution model first, standard libraries second, and the host embedding interface last. The chapters are intended to be read in order, while each library chapter also serves as a reference.

Part I — The Language

1. Getting Started

Installing or building Lightning, running the li command, the source-file model, the REPL, the first program, imports, and the conventions used throughout this manual.

2. Basic Concepts

Values and types, truthiness, variables, lexical scope, deterministic reference counting, equality, indexing, iteration, errors, and the execution model shared by the interpreter and JIT.

3. Language Syntax

Lexical rules, comments, numeric and string literals, template and raw strings, operators, precedence, table and array construction, declarations, annotations, and statement termination.

4. Control Flow

Conditional execution, while and for, ranges and collection iteration, break, leave, return, exceptions, try/catch, throw, and deterministic defer cleanup.

5. Functions and Closures

Named and anonymous functions, parameters and defaults, optional and variadic calls, return values, self, UFCS calls, capture-by-value closures, recursion, and callable values.

6. Structs and Classes

Struct and class declarations, fields, construction and destruction hooks, methods, properties, inheritance, dynamic hooks, operators, object lifetime, and native-layout fields.

7. The Strict Tier

Attributes and [[strict]], sized and typed values, forward type inference, compile-time diagnostics, the checked boundary with dynamic code, struct copy rules and unions, generics with per-type instantiation, static evaluation, and guard-free compiled numeric loops.

Part II — Standard Libraries

8. Built-in Functions

Core operations available through builtin, including printing, assertions, type inspection, explicit conversions, dynamic loading and evaluation, and other universally available services.

9. Collections

Tables, arrays, ranges, map/filter/reduce operations, iterators, mutation rules, presence and deletion, copying, sorting, and collection-oriented programming patterns.

10. Mathematics and Typed Values

The math module, IEEE 754 behavior, random numbers, numeric utilities, fixed-width integer and floating types, typed arrays, and native numeric storage.

11. System, Concurrency, and Runtime Libraries

File-system access, high-resolution time, stackful coroutines, process-wide shared values, locks and atomic updates, weak references, native vectors, reflection, debugging, and JIT controls.

Part III — The Host Interface

12. Embedding API

Embedding architecture, the <lightning.h> C ABI, the <lightning.hpp> C++20 RAII wrapper, value ownership and NaN-boxing, native registration, callback signatures, cross-VM transfer, hooks, exception conversion, userdata, threading, stack safety, and the trusted-script security boundary.

Runnable examples

Every example below is a complete Lightning source file. From the repository root, run one with:

./build/li docs/examples/01_hello.li