Language Syntax Tour

Relevant source files

The following files were used as context for generating this wiki page:

• architecture/13-syntax-and-nomenclature.md
• README.md
• architecture/01-vision-and-principles.md
• architecture/09-relationship-to-luau.md
• architecture/20-xml-documentation-comments.md
• AGENTS.md

Pop Lang is a native, strongly and statically typed programming language inspired by the lightweight syntax and ergonomics of Luau. It is designed to preserve Luau's visually calm aesthetic—utilizing end-based blocks, local inference, and low ceremony—while providing a foundation built for general-purpose software with strict static guarantees and no dynamic fallback. Sources: README.md:1-12, architecture/01-vision-and-principles.md:5-13

The language explicitly rejects Lua's table-centered semantics as a hidden implementation for all features. Instead, it introduces distinct semantic concepts for records, classes, interfaces, and namespaces, ensuring that every operation has a statically known meaning. Sources: README.md:15-18, AGENTS.md:183-188

Core Naming and Nomenclature

Pop Lang enforces strict casing rules to maintain a consistent visual dialect. It avoids lowercase snake_case entirely, reserving underscores for constants or ignored bindings. Sources: architecture/13-syntax-and-nomenclature.md:15-20

Entity	Convention	Examples
Namespace / Package	PascalCase	Game.Players, Pop.Standard
Type (Class, Record, Interface)	PascalCase	Player, LoadResult
Function / Method	camelCase	calculateScore, award
Local / Parameter	camelCase	playerCount, deltaTime
Constant	UPPER_SNAKE_CASE	MAX_RETRIES, DEFAULT_PORT
Attributes	PascalCase	@Serializable, @CompileTime

Sources: architecture/13-syntax-and-nomenclature.md:32-46, AGENTS.md:237-251

Type System and Numeric Types

Pop Lang is strictly typed with no source-visible any or dynamic escape hatches. While it utilizes local type inference to reduce repetition, every expression has a compiler-proven type before execution. Sources: README.md:65-71, AGENTS.md:195-207

Numeric Hierarchy

Unlike Luau's universal number type, Pop Lang uses explicit fixed-width numeric types to ensure predictable arithmetic and overflow behavior. Sources: README.md:144-150

• Integers: Int64 (aliased as Int), UInt64, Int32, UInt8 (Byte), etc.
• Floats: Float64 (aliased as Float) and Float32.

Sources: architecture/13-syntax-and-nomenclature.md:64-70, README.md:152-157

Data Structures and Abstractions

Pop Lang prioritizes data and functions over deep object-oriented hierarchies. It separates structural data from nominal classes. Sources: architecture/01-vision-and-principles.md:46-55

Records and Tagged Unions

Records are used for typed structural data. They support the with expression for functional updates. Tagged unions (sum types) represent states that must be handled explicitly via match statements. Sources: README.md:95-103, architecture/13-syntax-and-nomenclature.md:146-150

public record Request
    path: String
    retryCount: Int = 0
end

local nextRequest = request with { retryCount = request.retryCount + 1 }

Sources: README.md:97-106

Native Classes and Interfaces

Classes provide identity, mutable state, and lifecycle management. Interfaces define nominal contracts for polymorphism. Neither is implemented via tables or metatables. Sources: README.md:120-128, architecture/13-syntax-and-nomenclature.md:173-182

This diagram illustrates the nominal relationship between interfaces and classes in Pop Lang. Sources: architecture/13-syntax-and-nomenclature.md:184-192

Control Flow and Loops

Pop Lang adopts Luau's loop structures but strengthens the underlying semantics, such as requiring Boolean conditions and enforcing immutable loop bindings. Sources: architecture/13-syntax-and-nomenclature.md:235-245

• Conditional Expressions: Uses the if ... then ... else keyword form as an expression. Sources: architecture/13-syntax-and-nomenclature.md:226-233
• Numeric For Loops: Uses a comma-separated range for index = start, stop, step do. Sources: architecture/13-syntax-and-nomenclature.md:246-250
• Generalized Iteration: Uses for value in collection do, resolving through nominal protocols. Sources: architecture/13-syntax-and-nomenclature.md:255-263
• Error Handling: Uses Result<T, E> for expected failures and try for propagation. panic is reserved for unrecoverable invariant failures. Sources: README.md:160-166, architecture/13-syntax-and-nomenclature.md:104-118

Module and Ownership Hierarchy

Code organization follows a strict ownership hierarchy that governs visibility and compilation boundaries. Sources: AGENTS.md:264-272

The hierarchy defines the scoping and visibility of code within a project. Sources: AGENTS.md:264-276, README.md:183-187

Visibility Modifiers

Pop Lang does not use export. Instead, declarations are marked with visibility keywords:

• public: Visible to dependent Bubbles.
• internal: Visible across Modules in the same Bubble (default).
• private: Visible only within the declaring Module.

Sources: AGENTS.md:222-228, architecture/13-syntax-and-nomenclature.md:158-166

XML Documentation Comments

Pop Lang supports structured documentation using --- triple-hyphen comments, which contain validated XML fragments. Sources: architecture/20-xml-documentation-comments.md:13-20

--- <summary>
--- Loads a player from the given path.
--- </summary>
--- <param name="path">The save file to read.</param>
--- <returns>The decoded player.</returns>
public function loadPlayer(path: Io.Path): Result<Player, Io.Error>
end

Sources: architecture/20-xml-documentation-comments.md:22-38

The compiler validates tags like <param>, <returns>, and <error> against the actual function signature during compilation. Sources: architecture/20-xml-documentation-comments.md:195-204

Summary of Architectural Constraints

Pop Lang is architected to prevent "Lua regressions"—the accidental reintroduction of dynamic, table-centered behavior. Sources: architecture/19-architecture-conformance-and-regression-policy.md:76-80

Feature	Pop Lang Implementation	Forbidden Regression
Objects	Classes with native layout	Tables with metatables
Namespaces	Static name scopes	Runtime tables
Failure	Typed Result values	Dynamic exceptions / Nil-only
Types	Statically proven	Any / Dynamic / Gradual fallback

Sources: architecture/19-architecture-conformance-and-regression-policy.md:82-100, README.md:214-230