Built-in Prelude & Runtime Helpers
Relevant source files
The following files were used as context for generating this wiki page:
- README.md
- jazz-next/README.md
- docs/spec/runtime/primitive-semantics.md (referenced in scripts/check-clarification-specs.sh)
- jazz-next/src/JazzNext/Compiler/Semantics/BuiltinCatalog.hs (referenced in jazz-next/scripts/test-warning-config.sh)
- jazz-next/src/JazzNext/Compiler/Modules/Prelude.hs (referenced in jazz-next/README.md)
The Built-in Prelude and Runtime Helpers constitute the standard library environment automatically available to Jazz programs. In the active compiler implementation (jazz-next), the prelude is loaded by default in CLI mode, providing essential functional primitives and impure side-effecting helpers. This environment allows developers to use core operations like list manipulation and console output without explicit imports, bridging the gap between high-level functional syntax and the underlying runtime behavior.
Sources: README.md:12-16, README.md:38-40
Prelude Architecture
The prelude is not a hard-coded set of compiler keywords but a bundled set of functions defined within the language or as runtime primitives. The compiler's PreludeLoading and BuiltinCatalog modules manage the registration and availability of these symbols.
The diagram shows how the bundled prelude is injected into the compilation flow specifically during CLI/active run paths.
Sources: README.md:38-40, jazz-next/README.md:46-48, jazz-next/scripts/test-warning-config.sh:30-31
Core Built-in Functions
The following functions are verified as part of the bundled prelude and active runtime path. These functions support standard functional programming patterns like mapping, filtering, and list traversal.
| Function | Type (Implicit) | Description |
|---|---|---|
map | (a -> b) -> [a] -> [b] | Applies a function to each element of a list. |
filter | (a -> Bool) -> [a] -> [b] | Filters a list based on a predicate. |
hd | [a] -> a | Returns the head (first element) of a list. |
tl | [a] -> [a] | Returns the tail (remaining elements) of a list. |
print! | String -> () | Impure helper for printing strings to standard output. |
Sources: README.md:16, README.md:38-40, README.md:52-54
List Manipulation Logic
Functions like map and filter leverage the language's support for first-class functions and partial application. For example, map can be partially applied to a function to create a new specialized list transformer.
add10List :: [Int] -> [Int].
add10List = map (+10).
Sources: README.md:57-59
Side-Effect Denotation
Jazz distinguishes between pure functions and impure "helpers." Impure functions in the prelude, such as print! and getLine!, are denoted with a ! suffix. The runtime enforces that these cannot be called from within pure binding bodies through "stub-v1" direct-callee enforcement.
Sources: README.md:17, README.md:92-95
Runtime Primitive Semantics
The underlying runtime defines the contract for primitive operations, including equality and arithmetic. These are managed via the Primitive Contract Table and Builtin Catalog.
Built-in Operators
Operators such as +, -, and == are integrated into the prelude's semantic layer. The operator $ is specifically defined as a right-associative, zero-precedence function application operator to minimize the need for parentheses.
| Operator | Associativity | Precedence | Description |
|---|---|---|---|
$ | Right | 0 | Function application operator. |
+ | Left | (Standard) | Numerical addition. |
== | Non-assoc | (Standard) | Equality comparison. |
Sources: README.md:65-68, docs/spec/syntax/operators.md (via scripts/check-clarification-specs.sh:34-36)
Sequence of Runtime Execution
When a user-facing helper like print! is called, the runtime follows a specific resolution path through the BuiltinCatalog.
The sequence illustrates the lookup and execution flow for built-in helpers during runtime evaluation.
Sources: jazz-next/README.md:21-22, jazz-next/scripts/test-warning-config.sh:30-31
Implementation Status
The prelude and its helpers are categorized by their implementation readiness within the jazz-next compiler path.
- Verified Today:
map,filter,hd,tl,print!. - Planned/Aspirational:
Num.pow,mod,println!, and advanced ADT/Pattern matching behaviors.
Sources: README.md:16, README.md:82-84, docs/feature-status.md (via scripts/check-docs.sh:30-35)
Summary
The Built-in Prelude & Runtime Helpers provide the foundational toolset for Jazz developers, offering standard list processing and IO capabilities. By distinguishing between pure functions and impure helpers (marked with !), the prelude supports the language's safety goals while maintaining a familiar functional programming interface. These helpers are automatically integrated into the CLI environment, ensuring that "Hello World" and other basic functional patterns are available out-of-the-box.