Welcome to Pop Lang

Relevant source files

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

• README.md
• architecture/01-vision-and-principles.md
• architecture/README.md
• architecture/21-cli-tooling-and-code-units.md
• architecture/09-relationship-to-luau.md
• AGENTS.md
• CONTRIBUTING.md

Pop Lang is a native, strongly and statically typed programming language heavily inspired by Luau. It preserves the readable, lightweight syntax of Luau—such as end-based blocks and local type inference—while establishing a foundation designed for general-purpose software, predictable native runtimes, and explicit static guarantees. Unlike Lua-based languages, Pop does not treat tables as the underlying implementation for every feature; instead, it provides distinct semantics for records, classes, interfaces, and namespaces.

The project follows an architecture-first philosophy, where the documents under the architecture/ directory serve as the binding contract for the project. The language aims to provide a high-performance, portable environment where every operation is checked before execution, rejecting dynamic fallbacks like any or dynamic types.

Sources: README.md:14-25, architecture/01-vision-and-principles.md:3-10, CONTRIBUTING.md:3-5

Core Principles and Identity

Pop Lang focuses on a "Luau-first" feel but enforces strong static typing. It is not intended to be 100% source-compatible with Luau or Lua, especially where compatibility would weaken the type system or safety model.

Key Language Invariants

• Static Typing: Every runtime value and operation has a compiler-proven type. No Any or Dynamic escape hatches are permitted.
• Backend Neutrality: The High-Level Intermediate Representation (HIR) and Mid-Level Intermediate Representation (MIR) are backend-neutral and do not contain LLVM-specific objects.
• Explicit Semantics: Distinct semantic concepts (Item, Module, Bubble, Package, Workspace) remain separate at runtime and compile time.
• Deterministic Compile-time: Compile-time execution is budgeted, capability-limited, and deterministic.

Sources: AGENTS.md:13-35, architecture/README.md:41-60, README.md:95-103

Comparison with Luau

Feature	Luau Approach	Pop Lang Direction
Type System	Gradual typing with any	Strong static typing; reject any
Identity	Table-centered foundations	Distinct Records, Classes, Interfaces
Numbers	Universal IEEE-754 number	Explicit Int and Float types
Modules	require-style values	Static file-scoped namespaces
Globals	Implicit globals allowed	Rejected; must be explicitly typed

Sources: README.md:258-274, architecture/09-relationship-to-luau.md:17-38

System Architecture

The Pop Lang compiler utilizes a structured pipeline that transforms source code into backend-specific machine code while maintaining semantic integrity at each stage.

The diagram shows the semantic pipeline from source code to final backend execution, highlighting the backend-neutrality of the HIR and MIR stages.
Sources: AGENTS.md:280-290, architecture/README.md:16-20

Code Organization Hierarchy

Pop Lang defines a strict hierarchy for code units, governing ownership and visibility:

1. Item: The smallest unit (function, type, constant).
2. Module: A single .pop source file; defines the private boundary.
3. Bubble: The unit of independent compilation and internal visibility.
4. Package: A publishable directory containing a bubble.toml manifest.
5. Workspace: A group of Packages sharing a bubble.lock and target/ root.

Sources: architecture/21-cli-tooling-and-code-units.md:3-15, AGENTS.md:237-250

Tooling and Commands

The unified pop command provides a single entry point for development tasks.

Command	Description
pop check	Performs type-checking through HIR/MIR verification.
pop build	Compiles selected Bubbles and dependencies.
pop run	Builds and executes a binary Bubble.
pop test	Runs unit, integration, and documentation tests.
pop format	Applies the canonical formatter (4-space indentation).
pop add	Transactionally adds a dependency to bubble.toml.

Sources: architecture/21-cli-tooling-and-code-units.md:136-160, README.md:245-256

Development Workflow

Contributors must follow an architecture-first workflow. Before implementation, gaps must be closed in the architecture documents, followed by the creation of deterministic tests.

The sequence diagram illustrates the mandatory "Architecture -> Tests -> Implementation" workflow.
Sources: CONTRIBUTING.md:12-23, AGENTS.md:133-145

Technical Requirements

• Rust Toolchain: The compiler and tools are implemented in Rust (pinned to version 1.96).
• Scripts: Python is forbidden for repository scripts; Ruby is the preferred scripting language.
• Casing: PascalCase for types/namespaces; camelCase for functions/locals; UPPER_SNAKE_CASE for constants only.

Sources: CONTRIBUTING.md:46-51, AGENTS.md:214-235, CONTRIBUTING.md:73-80

Documentation and Metadata

Pop Lang uses structured XML documentation comments (---) inspired by C#. These are not mere comments but are checked by the compiler for accuracy regarding parameters, return types, errors, and effects.

--- <summary>
--- Awards points to a player and returns a new player record.
--- </summary>
--- <param name="player">The player receiving points.</param>
--- <param name="points">Number of points to award.</param>
public function award(player: Player, points: Int): Player
    return player with {
        score = player.score + points,
    }
end

Sources: README.md:34-42, architecture/README.md:83-88