SLeeLa # SLeeLa International — Language and Feature Reference **Edition:** International Version 3.0 **Language syntax:** SLeeLa 3.0 **Source extension:** `.sleela` (Wrapper™) **Normative grammar:** [`SLEELA.syntax`](../../SLEELA.syntax) **Compiler/runtime implementation:** see [`VERSION.md`](../../VERSION.md) and [`markdown/COMPILER.md`](../../markdown/COMPILER.md) > This document is an organized, reader-facing overview of the SLeeLa language and its feature surface. The normative grammar and implementation-specific references linked below remain authoritative where a detail differs. A feature's presence in the 3.0 reference does not mean every possible width, platform bridge, library adapter, or optional subsystem has identical end-to-end validation. --- ## 1. What SLeeLa is SLeeLa is a Java-like, class-oriented programming language built around a native compiler, a C/C++ execution core, a virtual-machine instruction set, and a large SLeeLa-authored standard library. Its central idea is that a programming language is not only its grammar. It is the connected system of: - a source language and versioned file format; - a compiler front end and semantic pipeline; - a stable native execution core and VM bytecode; - a growing, recursively discovered standard library; - explicit operating-system and native-service bridges; - development, documentation, packaging, and verification tools. SLeeLa source is compiled to Core bytecode and executed by the native core. The compiler front end is implemented in C++ and drives the C core through its exchange interface; it is not a separate interpreter that independently executes the language. The project describes its work through four complementary areas: **Math**, **Object**, **Science**, and **Reach**. These describe calculation, the organization of things, disciplined inquiry, and the ability to connect software to other systems and people. The project's national-interest and provenance vocabulary is retained as descriptive metadata where relevant; it does not replace ordinary programming semantics. ## 2. Versioning and compatibility SLeeLa keeps the language edition separate from the compiler/runtime product release. | Version track | Meaning | |---|---| | **International Version 3.0** | The edition designation used by this overview. | | **Syntax 3.0** | The current normative source-language grammar. | | **Compiler/runtime release** | The independently versioned implementation; query `sleela version` and consult `VERSION.md`. | | **Library/API edition** | The versioned API documentation and snapshots generated from the current `/lib` source tree. | A source file may declare its grammar edition with a first-line version pragma: ```sleela #sleela 3.0 ``` The current compiler gate accepts declared syntax versions **1.0 through 3.1**. If the pragma is omitted, the compiler defaults to 3.1 with a warning. A version outside the accepted range, or a malformed declaration, is rejected. Syntax 3.0 consolidates the established 1.x and 2.x language surface. It does **not** erase historical feature gates: a construct introduced in 2.9 remains gated at 2.9 even when compiled by a 3.0-capable compiler. See [the syntax-version matrix](../../api/sleela/2.1/language/SYNTAX-VERSION-MATRIX.md). ## 3. Source files and program structure The human-authored program file is a **Wrapper™**, with the `.sleela` extension. It is UTF-8 text. A program consists of one or more class declarations and may include struct declarations. A program has exactly one entry method: ```sleela void main() { print("Hello, SLeeLa"); } ``` The entry signature is `void main()`. The source format, version pragma, and lifecycle are described in [`markdown/SOURCE.md`](../../markdown/SOURCE.md). ### 3.1 Lexical conventions - Identifiers are case-sensitive and begin with a letter or underscore. - Whitespace separates tokens and is otherwise insignificant. - Decimal, hexadecimal (`0x`), binary (`0b`), and octal (`0o`) integer literals are supported; underscores may separate digits. - Floating-point literals use a decimal point and may include an exponent. - Boolean literals are `true` and `false`; `null` is the null literal. - String literals use double quotes and support the documented escapes: newline, tab, carriage return, backslash, and quote. Both conventional comments (`//`, `/* ... */`) and the preferred angle-bracket comment forms are recognized. The go-forward house style is: ```sleela < A line comment > << A block comment spanning multiple lines >> ``` The angle-bracket opener must begin as the first non-whitespace text on its line. See [`SLEELA.syntax` §1](../../SLEELA.syntax). ## 4. Types and data model ### 4.1 Core source types The core source vocabulary includes: - `int` — signed 64-bit integer; - `double` — floating-point number; - `boolean` — logical value; - `String` — first-class string value; - `void` — method return type; - declared `struct` types; - supported generic reference-type signatures; - additional named integer and character-catalogue signature families described below. The core runtime has a dynamic value representation underneath the language surface. The syntax specification distinguishes source-level declarations from the runtime's actual enforcement and representation. Do not assume that every declared width or signature automatically has every arithmetic operation implemented end-to-end. ### 4.2 Structs and object handles A `struct` declares a named aggregate of fields: ```sleela struct Point { int x; int y; } class Example { void main() { Point p = new Point(); p.x = 10; p.y = 20; print(p.x + p.y); } } ``` Struct values are VM-managed instance handles, not exposed raw pointers. Assignment and parameter passing share the same instance; equality is identity-based. Struct fields are initially null/zero according to the runtime's documented initialization rules. The specification sets limits on struct types, fields, and live instances per VM. Struct values can be converted to a portable JSON representation using `structPack(instance)` and reconstructed with `structUnpack(TypeName, json)`. This is the supported shape for moving struct data through text-based transports or thread mailboxes; a VM-local handle itself is not a portable wire value. ### 4.3 Classes, fields, and methods A class contains fields and methods. Fields are class-level shared state in the current execution model; method locals are per-thread. Field initializers are initialized in declaration order as part of program startup. Methods use declared parameter and return types. The `static` modifier is accepted; the current model treats methods as class-bound. Methods can call other methods and recurse. ### 4.4 Inheritance and nested classes Syntax 1.10 introduced resolved, single-base class inheritance: ```sleela class Animal { String name; String describe() { return "animal " + name; } } class Dog extends Animal { String describe() { return "dog " + name; } } ``` Derived classes inherit base fields and methods; a same-name derived method overrides the inherited method. Unknown bases and inheritance cycles are semantic errors. The same keyword also has a distinct top-level document relationship form, `extends to ...`, which organizes document targets as `linear`, `group`, or `services`. This is not class inheritance; see [`markdown/EXTENDS.md`](../../markdown/EXTENDS.md). Syntax 1.11 adds one level of nested class declarations. The enclosing class plus its nested class form the maximum lexical nesting depth; deeper types should be declared at top level and referenced by field. ### 4.5 Generics Syntax 2.2 adds class-level generic type parameters, parameterized reference types, and wildcards, including `?`, `? extends T`, and `? super T`. The specification restricts the accepted generic forms: primitive and keyword `String` type arguments are not interchangeable with reference-type arguments, and method-level type parameters are not part of the accepted grammar. ### 4.6 Numeric families In addition to the 64-bit `int`: - `long` and `int64` are documented as 64-bit signed aliases; - `int128` is accepted as an integer type but is documented as 64-bit-backed for now; - syntax 2.7 defines signed power-of-two names from `int32` through `int16777216`; - syntax 2.8 defines the corresponding unsigned family from `uint32` through `uint16777216`; - the earlier `U` family describes unsigned values with a declared width from 1 to 1,048,576 bits; - `C` describes character-catalogue capacity from 1 to 1,048,576 entries. It is a capacity signature, not an integer type or a guarantee that all entries are populated. The arbitrary-width unsigned value foundation and type recognition are documented separately from complete VM operator coverage. Likewise, character-catalogue declarations must not be mistaken for a claim that every catalogue is Unicode or that every declared entry is populated. See [`markdown/SOURCE.md`](../../markdown/SOURCE.md) and [`SLEELA.syntax`](../../SLEELA.syntax). ## 5. Expressions, operators, and statements ### 5.1 Operators The expression grammar defines: | Category | Operators | |---|---| | Arithmetic | `+`, `-`, `*`, `/`, `%` | | Comparison | `==`, `!=`, `<`, `<=`, `>`, `>=` | | Logical | `&&`, `||`, `!` | | Assignment | `=` | | Grouping | `()` | The `+` operator performs numeric addition or String concatenation when a String operand is involved. Equality on struct handles compares identity. The language's precedence is conventional: logical OR, logical AND, equality, comparison, additive, multiplicative, unary, then primary expressions. ### 5.2 Control flow The language provides: - blocks with braces; - local declarations and assignments; - `if` / `else`; - `while`; - `for`; - `return`; - `print(...);`; - expression statements, commonly method or built-in calls. The `for` form supports the ordinary initializer, condition, and update. The extended form can include a Boolean thread-stability guard and a Boolean VM/heap-health guard. Guards are checked at the start of each iteration before the body. A heap-health guard only reflects real VM health if the host/runtime connects it to a genuine health signal. ### 5.3 Garbage-collection hints Syntax 1.9 adds the contextual forms: ```sleela target = gc 50; target = mem 25; ``` These request short-term garbage-collection cleanup with an optional 0–100 aggressiveness value. They are not ordinary assignments and do not guarantee immediate reclamation; reachable objects remain valid. The target retains its value. ## 6. Conducted methods and the system object catalogue A distinctive SLeeLa facility is the conducted-method vocabulary, which addresses named objects in `SHEET.sheet`. The contextual built-ins are: | Built-in | Purpose | |---|---| | `conduct(name)` | Test whether a named object is catalogued. | | `role(name)` | Return the object's role. | | `insight(name)` | Return its descriptive insight. | | `congruent(a, b)` | Test the documented congruence relationship. | | `route(a, b)` | Return a route description when the objects are congruent. | | `sysdepth()` | Read the system-depth limit. | | `degreemax()` | Read the maximum complexity degree. | The catalogue describes sixteen role categories, including root, start, idiom, highlight, call, method, attention, gain, conversation, piping, transitive, completitive, inheritance, smart-move, congruence, and limit. The documented system invariants are a maximum system depth of **3024** and a maximum complexity degree of **4**. These values describe the project's catalogued connection model; they are not a substitute for application-level validation. ## 7. Concurrency and communication SLeeLa exposes a bounded thread-friendly model through contextual built-ins: | Built-in | Purpose | |---|---| | `spawn(method)` | Start a no-argument method on a new thread and obtain its thread identifier. | | `join()` | Wait for spawned threads to finish. | | `lock(n)` / `unlock(n)` | Acquire or release a lock-table slot. | | `send(slot, value)` | Place a value on a mailbox slot. | | `recv(slot)` | Wait for a value on a mailbox slot. | The documented core limit is 128 threads and the lock-table slot range is 0–31. Shared fields should be protected with locks; mailboxes are the intended way to exchange values between threads. Printed lines are atomic across threads. ### 7.1 Structural send The `:::` operator expresses a String transfer to a receiver handle: ```sleela source ::: receiver; ``` The VM performs the element-by-element stream framing and transport. The left operand is a String and the receiver must evaluate to a suitable reach handle. The expression evaluates to the original source String, allowing a chain of receivers. This is a VM transport operation, not ordinary punctuation or a replacement for general networking APIs. ## 8. Reach, measurement, and selection built-ins The language includes contextual built-in families beyond the core control-flow vocabulary: - **Munction** — `Munction.start(name)` and its fluent reach verbs, including connection, enablement, send, consume, observe, propagation, latch, and receipt-oriented closure operations. The chain is a structured reach sentence; consult [`MUNCTION.md`](../../MUNCTION.md) for the full contract. - **Synchro** — `synchroOpen`, `synchroDispatch`, `synchroReport`, `synchroClose`, and measurement operations for sent/received counts, mean, minimum, maximum, P95, and loss. These are measurement surfaces; see [`SYNCHRO.md`](../../SYNCHRO.md). - **Best-of** — the `bestOf...` family models candidate, architecture, cost-budget, version, score, choice, report, mean, loss, jitter, and certainty data. See [`TIMINGS.md`](../../TIMINGS.md) and [`NETWORK.md`](../../NETWORK.md). - **System namespace** — `ran::` qualifies system references such as `ran::mem` and `ran::gc`. These names are contextual built-ins, not all reserved words. They are recognized in their documented call or namespace positions and should be used according to their subsystem references. ## 9. Syntax 3.0 behavioral additions Syntax 3.0 includes several additions that go beyond declarative source annotations. ### 9.1 Loop timing - `@loopDelay` inserts a fixed pause per loop iteration. - `@loopBudget` distributes a known iteration count over a requested wall-clock budget. - `@spill` marks a loop timer-start behavior as defined by the normative syntax specification. - `sleep(ms)` blocks the current thread for a millisecond count. The loop annotations lower to the VM sleep operation (`OP_SLEEP`, ISA index 157). See [the loop-timing API reference](../../api/sleela/3.0/LOOP_TIMING_API.md) and [the runnable example](../../examples/loop-timing-annotation-demo.sleela). ### 9.2 Big-integer operations Syntax 3.0 defines native built-ins: - `bigmul(a, b)`; - `bigadd(a, b)`; - `bigdivmod(a, b)`. They operate on base-1,000,000,000 limb arrays and lower to dedicated VM arithmetic operations. The documented array ceiling is 2^24 elements. This interface is a limb-array arithmetic facility; it should not be confused with the ordinary 64-bit `int` type or a claim that every integer width in the language has arbitrary-precision semantics. ### 9.3 Explicit floating-point narrowing The syntax 3.0 specification records explicit casts from `double` to integer types. Narrowing is explicit rather than an implicit conversion. ## 10. Preonems and document markers SLeeLa includes a contextual family of declarative document markers, collectively called the **Preonems**. They describe the standing or nature of a source document. Except where specifically noted, they do not change parsing, type checking, code generation, or runtime behavior. The documented marker vocabulary includes: - `author` / `authorial` — the compiler-active marker associated with professional-council handling, duplicate member declarations, declaration-order identity, SHA-256 branding, and an originated source twin; - `material` — marks a document as a settled source/material document; - `memory` — marks a document as a memory document; - `determine` — marks a document as open to further processing or completion; - `object` — marks object standing in the document catalogue, with its reified standing specified from syntax 2.8; - `field` — marks the ground of relation in which objects stand; - `pure` and `gasoline` — syntax 3.0 declarative markers concerning the document's stated standing by its own honesty. - `spark` — syntax 3.0 marker that indicates Java style declarative: the document declares itself SLeeLa constructs written in Java style, supported at the interpreter/VM level (see `SLEELA.syntax` section 43). These words are contextual: outside their defined document-marker position they remain ordinary identifiers. Do not treat a marker as authorization to execute a program or as proof of external legal status. The `prestige` marker described in the syntax document is a **future proposal**, not an implemented 3.0 feature. ## 11. Metadata, annotations, and supporter records The Metadata Class standard gives class-bearing source units a descriptive metadata record for provenance, legality, and jurisdictional scope. Metadata describes a unit; it does not grant execution authority. The compiler also carries source annotations through its annotation pipeline. Syntax 2.6 adds keyword supporter records for selected control-flow keywords (`try`, `catch`, `throw`, `synchronized`, and `super`), linking each occurrence to a stable hash and a corresponding support-document location. This documentation mechanism does not change the underlying keyword's control-flow semantics. Syntax 3.0 also documents `@modium` and `@registry` subsystem-role annotations. These are labels for the Modium/Registry responsibility split, not new grammar or execution privileges. ## 12. Standard library and package model The `/lib` tree is the unified SLeeLa source layer for the language-facing SDK and VM/OS object model. Packages are recursively discovered by the compiler and Nordshrift loader; adding a package does not require a separate hard-coded compiler allow-list. The library spans foundational and application-facing areas, including: - core runtime, collections, text, math, and data structures; - file systems, streams, process, memory, and operating-system services; - networking, HTTP, Wi-Fi, telephony, and server components; - cryptography, security, codecs, XML, regular expressions, and databases; - user interfaces, GUI, terminal, graphics, and CAD-related models; - CPU, VM, opcode, compiler, decompiler, reflection, and debugging tools; - AI-facing packages for large language models, neural networks, and related interfaces; - documentation, source-sheet, registry, and structured-document facilities. The package catalogue is extensive and changes as the library develops. The canonical class vocabulary is [`lib/LIBRARY.SYMBOLS.md`](../../lib/LIBRARY.SYMBOLS.md); the package overview is [`lib/README.md`](../../lib/README.md); generated class/member documentation is available at [`sleeladoc-api/index.html`](../../sleeladoc-api/index.html). ### 12.1 Cross-platform model The project targets **Linux, macOS, and Windows 10+**. Pure SLeeLa library code is portable by construction. Facilities requiring host services cross an explicit VM/OS bridge, whose native backend resolves to the host platform. Platform-specific differences are exposed through OS-specific classes rather than silently treated as identical. A platform-support statement is not a claim that every optional device, driver, or external dependency is present on every machine. Consult [`docs/PLATFORM-SUPPORT.md`](../PLATFORM-SUPPORT.md) and the relevant package README for requirements. ### 12.2 Explicit native boundary C and C++ remain below explicit VM/OS bridge boundaries for operations requiring kernel, device, memory, networking, cryptography, or process primitives. The source library expresses the SLeeLa-facing contracts; native implementations provide the host-specific service where required. ## 13. Compiler, runtime, and virtual machines The documented compilation path is: ```text .sleela Wrapper™ | v syntax-version resolution | v lexer -> parser -> AST / annotations | v semantic analysis and code generation | v SLeeLa Core bytecode | v native C SLVM / runtime ``` The compiler's principal stages are version resolution, lexing, parsing, semantic analysis, and code generation. The C core provides the value model, operand stack, call frames, and opcode dispatch. The front end builds and runs through the core's exchange interface. SLeeLa also documents a family of VM and runtime services, including memory management, garbage collection, instruction dispatch, system bridges, and VM selection/inspection tooling. The Native VM is the recommended starting point in the user guide. VM generations and premium profiles must be evaluated against their own implementation and validation records; a specification or profile name alone is not proof of complete runtime support. See [`markdown/COMPILER.md`](../../markdown/COMPILER.md), [`virtual-machine/USER-GUIDE.md`](../../virtual-machine/USER-GUIDE.md), and [`docs/ARCHITECTURE.md`](../ARCHITECTURE.md). ## 14. Documentation and developer tools SLeeLa includes a documentation system designed to document intent as well as signatures. **SleelaDoc** uses structured angle-bracket doc comments with `@doc` / `@page` sentinels and tags such as `@intent`, `@thesis`, `@axiom`, `@param`, `@see`, and `@mastery`. The extractor renders Markdown or HTML API pages. The generated site organizes the library by package, class, and member. The command-line documentation interface supports topic and class lookup, case-insensitive resolution, suggestions for near misses, offline generated corpora, and facade-topic filesystem discovery within documented limits. Other developer-facing facilities include: - `sleela check` for source validation without execution; - `sleela run` for compile-and-run; - `sleela version` for toolchain and supported syntax information; - `sleela docs` for documentation lookup; - Nordshrift for declarative `.sst` build sheets and recursive source discovery; - generated API sites and immutable versioned API snapshots; - local project generation and standalone utility programs. See [`lib/sleeladoc/README.md`](../../lib/sleeladoc/README.md), [`manifesto/SLEELADOC.md`](../../manifesto/SLEELADOC.md), and [`api/sleela/3.0/SESSION-ADDITIONS-API.md`](../../api/sleela/3.0/SESSION-ADDITIONS-API.md). ## 15. Build and try SLeeLa A typical source file: ```sleela #sleela 3.0 class Hello { void main() { String greeting = "Hello"; int answer = 40 + 2; print(greeting + ", International SLeeLa " + answer); } } ``` Build and run from a configured checkout: ```sh make ./build/sleela version ./build/sleela check path/to/Hello.sleela ./build/sleela run path/to/Hello.sleela ``` For the native core alone, see the instructions in [`impl/README.md`](../../impl/README.md). The repository root build may build additional products beyond the compiler/runtime. Use [`markdown/TESTING.md`](../../markdown/TESTING.md), the test-suite guide, and the live GitHub Actions results to assess the exact checkout. ## 16. Implementation and conformance boundaries SLeeLa is a broad language-and-runtime project. Its documentation should distinguish: 1. **Normative syntax** — what the language specification defines. 2. **Compiler acceptance** — what the current front end parses and validates. 3. **Runtime behavior** — what the Core/VM actually executes. 4. **Library availability** — what source classes and native bridges are present. 5. **Verified conformance** — what the current tests and CI have demonstrated. Important qualifications in the current references include: - Syntax 3.1 is the current accepted grammar ceiling (this reference describes the 3.0 surface), not an automatic enablement of every historical or proposed feature. - Constructor overload resolution and `this(...)` / base-constructor delegation are not verified and are rejected explicitly. - `prestige` remains a proposal. - `U`, `C`, and the named wide-integer families have distinct documented meanings and implementation boundaries; do not infer universal end-to-end support from their grammar or type recognition. - Optional native bridges, devices, network services, and platform integrations require their own build and runtime tests. - A passing historical CI run does not establish the status of the current commit. Use the live Actions page and current test logs. This separation is intentional: SLeeLa aims to be ambitious in its language and system model while keeping implementation claims traceable to code and tests. ## 17. Primary references - [Normative language syntax — `SLEELA.syntax`](../../SLEELA.syntax) - [Compiler pipeline and versioning](../../markdown/COMPILER.md) - [Wrapper™ source-file contract](../../markdown/SOURCE.md) - [Syntax version matrix](../../api/sleela/2.1/language/SYNTAX-VERSION-MATRIX.md) - [Class inheritance and document grouping](../../markdown/EXTENDS.md) - [Standard library overview](../../lib/README.md) - [Canonical library symbols](../../lib/LIBRARY.SYMBOLS.md) - [Generated SleelaDoc API](../../sleeladoc-api/index.html) - [Platform support](../PLATFORM-SUPPORT.md) - [Virtual-machine user guide](../../virtual-machine/USER-GUIDE.md) - [Testing policy](../../markdown/TESTING.md) - [GitHub Actions](https://github.com/mearvk/SLeeLa/actions) --- **SLeeLa International 3.0** *The Now. The Ingredient.*