The LIA Programming Language v1.0.0 Specification [DRAFT]

Revision: 4
Release Date: 30/8/2025
Author: Lawton "Lawtro" Kelly

This document describes the core language specifications and not particularly the current state of LIA-lang. This is simply the target of what LIA-lang should be.

Introduction

This specification defines the normative syntax, semantics, and external interface of the LIA programming language. Its goal is to provide a precise, implementation‑agnostic contract for:

• Lexical elements (tokens, literals, keywords)
• Grammar and syntactic forms
• Type system and coercion model
• Runtime constructs (functions, objects, arrays)
• Memory and lifetime directives (free)
• Module and external library importing
• Native interoperability surface

Scope: Only the core language and its required runtime behaviors.
Non‑scope: Tooling, build systems, optimization strategies, debugging facilities, editor integration, and prospective future extensions.

Conformance: An implementation is conforming if it:

1. Accepts all grammatically valid programs defined herein.
2. Rejects (with a diagnostic) any lexically or syntactically invalid input.
3. Preserves the specified evaluation order and side‑effects.
4. Implements the defined type and value categories (including null and void semantics).

Undefined Behavior: Any construct not explicitly covered (e.g. accessing non‑existent object fields) is undefined and may terminate execution or produce implementation‑specific results.

Versioning: This draft targets v1.0.0. Backward incompatible changes after ratification require a major version increment.

"Must" / "Shall"

mandatory.

"Should"

recommended.

"May"

optional.

"Undefined"

intentionally unspecified—implementations are not required to diagnose.

"LIA-lang"

the LIA Programming language

All examples are illustrative; if an example conflicts with a formal rule, the rule governs.

1. Lexical Structure

Character set: ASCII (string contents treated as raw bytes)
Whitespace: space, tab, CR, LF (insignificant outside string literals)
Comments:

• // to end of line
• /* to next */ comment closure

1.1 Identifiers

Pattern: [A-Za-z_][A-Za-z0-9_]*
Case-sensitive. Reserved keywords excluded.

1.2 Keywords

Note that keywords and their aliases aren't particularly reserved when defining variables

Aliases

• function: fn, fun, func, def
• var: let, local
• const: final
• break: stop
• skip: continue, next
• free: delete, pop
• null: nul
• bool: boolean

1.3 Literals

• Integer: decimal digits (123).
• Float: digits with a decimal point (1.0, 0.5).
• String: " until next " (new lines do not close strings).
• Boolean: true / false.
• Null: null.
• Object literal: { <type>? <identifier>: <value> (, <type>? <identifier>: <value>)*, }.
• Array literal: <type>? [element (, element)*] (optional leading inline type token).

1.4 Operators

• Arithmetic: + - * /
• Comparison: ==
• Assignment: =
• Unary: prefix + -
• Index: ident[expression]
• Member access: grammar placeholder exists but is not part of the active syntax; accessing object fields directly is not defined outside literal construction.

1.5 Delimiters

2. Types

Primitive core:

• int<S> / uint<S> (signed / unsigned integers by size)
• float<S>
• string
• bool
• void (function return type only)
• null
• any (internal fallback / inference default)

S = storage size in bytes; default size when omitted is 32 bits.

Sub‑type Aliases

Default integer width: 32 bits (alias int = int32).

Integers (signed / unsigned):

• 8: int8, i8, byte / uint8, u8, ubyte
• 16: int16, i16, short / uint16, u16, ushort
• 32: int32, i32 / uint32, u32 (alias int = int32)
• 64: int64, i64 / uint64, u64

Floats:

• 32: float, float32, f32, number, num
• 64: float64, f64, double, real

Strings: string, str, text

Composite:

• Arrays: dynamic length; literal syntax [...].
• Objects: anonymous record literal { type name: value, ... }.
• Functions: first‑class by identifier (no closures).

3. Variables

Syntax:

• var <type>? <name> (= expression)?
• var <type>? <name>[index]? (array element assignment after declaration uses assignment)
• const <type>? <name> (= expression)? (var can be inferred)
• global var <type>? <name> (= expression)?

const modifier is parsed; enforcement of immutability is nominal.

Variables with no declared type default to any
Uninitialized variables get null.

4. Statements

• Expression statement
• if (expr) { block } (else { block })?
• while (expr) { block }
• loop (num) { block }
• for (init; condition; increment) { block }
• return expression
• free(identifier (, identifier)*)
• import "path.lia" | "lib.llb"
• break (breaks out of loops)
• skip (skips current loop)

5. Functions

Syntax:
function <return_type> <identifier>( <param_list>? ) { block }

Parameters:
<type> <identifier> separated by commas.

Return:
return <expression> (void functions may return without an expression producing null).

No overloading or default parameters.

6. Objects

Literal:
{ <type> <fieldName>: <expression>, ... }

Element type is either explicitly defined or inferred as Any.

7. Arrays

Two forms:

• Indexed identifiers: arr[i]
• Literals: <optionalLeadingType> [ elem1, elem2, ... ]

Element type is either explicitly defined or inferred as Any.

8. Classes

class <classname> (args?*) { block }

The main code block acts as the constructor for classes in LIA-lang.
Anything defined in the scope of a class becomes accessible from the class object.
Classes can be instantiated as so new <classname> (args?*).

9. Casting

Prefix type token followed by a parenthesized expression: <type> (expr)

10. Import System

import "<.lia/.llb/.dll path>" (as <identifier>)?

• import "relative/or/absolute/path.lia"
  Loads and tokenizes file; AST is inlined (recursive parse).
• import "library.llb"
  loads a LIA-lang library.
• import "library.dll"
  loads a dynamic link library
• import "library.lia" as lib
  import content is placed in an object instead of global scope

Search path: relative to current working directory. No cycle detection.

11. Memory Management

Once a scope is exited the scope and its contents are removed and freed from memory.
The free() function removes the inputted variable from the scope and frees the memory.

10.1 Memory Allocation Model

Stack Allocation

• Primitive types (int, float, bool)
• Function parameters and local variables
• Automatically freed on scope exit

Heap Allocation

• Dynamic arrays and strings
• Objects and complex data structures
• Subject to implementation-defined size limits

Allocation Behavior

12. Runtime / Execution Model

LIA-lang is an interpreted programming language meaning execution is handled by a program that reads in the code and executes it based on its operation. LIA uses a Tree‑walk interpreter that executes assembled LIA code. LIA code is assembled into an abstract syntax tree and/or serialised into .ast file before execution or being bundled with an interpreter. Runtime interpreters are either embedded into a compiled binary with assembled LIA bytecode or are separate and read in .ast or .lia files for execution. In the case of a separate interpreter .lia files are parsed into unserialised .ast LIA bytecode before being executed A separate interpreter will deserialise .ast files before executing them. An embedded interpreter will deserialise the LIA bytecode appended to the end of its file after the "LIA\xFF" header before executing it.

Execution Model

13. Error Handling

Categories:

Standard diagnostic format (illustrative):

<KIND>: <MESSAGE>
at <FILEPATH>:<LINE>
<OPTIONAL EXTRA CONTEXT>

Fatal runtime errors terminate the process with an implementation‑defined exit code. Non‑fatal runtime issues may be logged to stderr or console depending on runtime flags.

14. Grammar (EBNF Approximation)

program          ::= statement*
statement        ::= function_decl
                   | var_decl
                   | if_stmt
                   | while_stmt
                   | return_stmt
                   | free_stmt
                   | import_stmt
                   | expression
function_decl    ::= "function" type identifier "(" param_list? ")" block
param_list       ::= param ("," param)*
param            ::= type identifier
var_decl         ::= "var" ("const")? type identifier ("=" expression)?
if_stmt          ::= "if" "(" expression ")" block ("else" block)?
while_stmt       ::= "while" "(" expression ")" block
return_stmt      ::= "return" expression
free_stmt        ::= "free" "(" ident_or_index ("," ident_or_index)* ")"
import_stmt      ::= "import" string_literal
block            ::= "{" statement* "}"
expression       ::= assignment
assignment       ::= binary ("=" assignment)?
binary           ::= unary (op unary)*        # op in precedence order (* /, + -, ==)
unary            ::= ("+" | "-" | cast_prefix) unary | primary
cast_prefix      ::= type "("
primary          ::= number
                   | string_literal
                   | "true" | "false" | "null"
                   | identifier call_or_index?
                   | array_literal
                   | object_literal
                   | "(" expression ")"
call_or_index    ::= "(" arg_list? ")" | "[" expression "]"
arg_list         ::= expression ("," expression)*
array_literal    ::= "[" type? (expression ("," expression)*)? "]"
object_literal   ::= "{" object_field ("," object_field)* "}"
object_field     ::= type identifier ":" expression
ident_or_index   ::= identifier ("[" expression "]")?
type             ::= "int" size? | "uint" size? | "float" size? | "char" size? | "string" | "bool" | "void" | "any"
size             ::= integer_literal

15. Operator Precedence (High → Low)

1. Unary (++ --)
2. Multiplicative (* /)
3. Additive (+ -)
4. Equality (==)
5. Assignment (= right-associative)

16. Native Interop

.dll files:

.dll files can be loaded via import or the loadLibrary() native function
.dll public functions will be converted to work with LIA-lang placed in the global scope

.llb files:

.llb files can be loaded via import or the loadLibrary() native function and are essentially libraries specifically made for LIA-lang.
.llb files are technically just .dll files under the hood just with special functionality to interface with LIA-lang

18. Native Functions (Built‑ins)

The following native (built‑in) global functions are provided by the reference interpreter. Availability or exact behavior may vary in other runtimes.

19. .AST Bytecode Format

18.1 Headers

18.2 Instructions

18.3 Types

18.4 Literal Values

20. Implementation Recommendations

• Implementations of LIA-lang should be memory safe.