Skip to content

Sprig stage-0 — implemented feature status ​

This table reflects what the compiler in this directory actually does, as verified by python3 scripts/test.py (scripts/test.sh on Linux/macOS). The release validation record is on GitHub. The historical design kit in docs/history/design-kit/ describes target semantics rather than current capabilities.

FeatureFront endStatic semanticsCodegen + runtimeTests
Expression matchone expression per branchstrict contextual/inferred results, shared exhaustive/binder rulesJava switch expression/yield; no closures; scrutinee oncematch expression runtime/generic/null/effect tests
Expression if: if/elif/mandatory else, one expression per branchwherever an expression match is accepted; if at the start of a statement stays the statement; a missing else, one-line branches, multi-line branches, grouping and operand positions, a if c else b and c ? a : b get targeted SPR-SYNTAX-ERROR messagesBool conditions; expression-match result typing; the if statement's narrowingnested Java ?: with every branch converted to the result's Java type, so no numeric promotion or unboxing; conditions in order, only the chosen branch evaluatedruntime 39, tests/if_expression, semantics if_expression_*, syntax 14/20–24
Explicit export alias.Symbolyesoriginal symbols, collisions, cycles and package boundariesno wrapper/copyreexport runtime/API/package suite
Canonical sprig fmttrivia-preserving lexerparse structure invariantatomic file replacement, check/JSON modesformatter fixtures + valid corpus
sprig lsp language server (stdio)unsaved buffers parsed in place of files; signature help can complete the current call without its closing parenthesisdiagnostics, quick fixes from their suggested edits, hover, definition, references with a truncation warning, symbols, completion, declaration/Java signature candidates, resolved semantic tokens and verified local rename from the same resolver and checkernone; formatting reuses sprig fmttests/lsp JSON-RPC suite; VS Code client in editors/vscode unit and Extension Host tests
Function references: a named function, a module function or a method used as a value (items.map(shout), lists.sum, counter.bump), print where a fn(T) -> Unit is expected, generic functions with written type arguments (identity[Int])a name, alias.name, receiver.method or name[Type] in value positionthe forwarding lambda's type, throws clause included; receiver of a method reference evaluated once; print only with an expected fn(T) -> Unit (SPR-TYPE-NOT-CALLABLE); generic needs written arguments (SPR-TYPE-GENERIC-ARGS-REQUIRED); at most three parameters; Java and built-in methods stay calls; ==/!= on function values rejected (SPR-TYPE-OPERAND)the same FnN object a lambda produces; a bound receiver through SprigRuntime.bindruntime 45, semantics fnref_*, function_values_not_comparable
Contract classes: a class whose methods have no body is a contract; conform C to Contract (or alias.Contract) with every method matched exactly; a conforming object goes where the contract type is expectedbodiless method header inside a class; a bodiless function elsewhere is SPR-SYNTAX-ERRORno fields, no mixed bodies, not constructible (SPR-CLASS-ABSTRACT); exact parameter/result types (SPR-CONFORM-MEMBER), throws no more than the contract (SPR-CONFORM-EFFECTS); no conversion back, no type test (SPR-MATCH-SCRUTINEE/SPR-MATCH-UNKNOWN-CASE hints); deliberate 0.8 rules, each with a targeted hint: never generic (SPR-CLASS-ABSTRACT, generic conforming class SPR-CONFORM-SOURCE), a type and never a requires bound (SPR-GENERIC-CONSTRAINT), no default methods (SPR-CLASS-ABSTRACT); no retroactive or structural conformancepublic interface with one abstract method per Sprig method; the class implements itruntime 44, syntax 16/24, semantics contract_*, class_as_bound, conform_to_plain_class; newcomer hints contract-*, retroactive-conform-*
Foreign JVM conformance conform C to J, and conform C to J(field, ...) as NAME to extend a Java classdeclaration form, one per relation; parentheses name the superclass constructor fields, as the parent viewexact JVM witness matching, overrides matched by shape, final/static/abstract rules, NAME.m(...) as the inherited call, v1 restrictions, foreign conformance conversionemitted implements/extends, super(...), @Override, C.super.m(...); non-null entry guards (SPR-CONFORM-*)tests/conform runtime and negative suite
Functions, typed parameters/returns, recursionyesyesJava static methodsruntime 01/02, visitor
Indentation, blocks, if/elif/else, while, for, break/continueyesyesJava control flow; for x in range(...) is a counted loop that builds no list, with bounds evaluated once and a fresh binding per iterationruntime 03/13/32
let/var, local inference, assignment rulesyesyes (SPR-NAME-LET-ASSIGN)locals/static fieldsruntime 16
Classes: named auto-ctor, per-instance defaults, implicit fields/methods; one-line form class Pair(first: Int, second: Int) (let fields only, no defaults or methods)yes; the one-line form's :, var, = or empty parentheses get a targeted SPR-SYNTAX-ERRORyes; == on two class objects compares identityfinal Java classes without generated equals; both forms generate the same classruntime 04/12/34/42, syntax 15/23
compareTo on Int, Int32, Float, Float32, Decimal, BigInt (and String): argument of the receiver's type (an Int32 widens to an Int receiver and a Float32 to a Float, as for any parameter), Int32 resultyesyes; an argument that would narrow or change family is SPR-NUM-CONVERSION/SPR-NUM-MIXEDLong.compare/Integer.compare/Double.compare/Float.compare, signum(compareTo) for Decimal/BigIntruntime 43
enum + exhaustive matchyesyesJava enum + if-chainruntime 06
variant + typed case binders + exhaustive matchyesyes; == compares case and payload by value, and two different cases of one variant compare at the variant's type (never equal)sealed interface + nested classes with value equals/hashCoderuntime 05/14/34/55, visitor, semantics equality_cases_*
Missing/duplicate/wrong-type cases, enum binder rejection—yes (SPR-MATCH-*)—semantics 11 cases
Nullability T?, null checks, narrowingyesyes (SPR-TYPE-NULL/NULLABLE); a T? cannot be joined into a String; immutable names narrow in the guarded block, the right side of and/or, after an early exit, and in each elif and the else by every earlier condition; a name declared T? may be compared with null while narrowedboxed nullable localsruntime 07/24/31/38, semantics nullable_join*, elif_*
List/MutableList/Map/MutableMap, snapshots, indexing, inyesyes, distinct mutability; a mutable collection is accepted where the read-only type is expected, as the same collection seen read-only (never the reverse; element types invariant); a list or map literal compared with ==/!= takes the other operand's type (xs == [])runtime wrappers; SprigMutableList extends SprigList carries the view; in, contains, indexOf and remove find an element with == (a Float/Float32 NaN nowhere, -0.0 at 0.0)runtime 09/16/41/54/55, numeric acceptance suite, semantics list_to_mutable_rejected, nested_list_mutability_invariant, equality_literal_*
String positions: length, indexing, charAt, codeAt, substring, indexOf, lastIndexOf, iterationyesUnicode code-point indices; one-code-point String elements; no Char typesprig.runtime.StringOps helpers: text without a surrogate pair is indexed by char offset, and the code-point count of the last text of 32 UTF-16 units or more is kept in one volatile entry keyed by identity, so a loop over the same text counts it once (text with a supplementary code point still counts to the index); iteration walks the string once, sharing the one-character ASCII elementsruntime 20/46/48 + String semantics suite with a concurrent StringOpsProbe
String + joins, ==/!= and compareToyesa String on either side joins any non-null value of a concrete type, except Unit; ==/!= compare contents, and a String? side may be null; a.compareTo(b) is an Int32 in the order of <Java concatenation for String, Int, Int32, Float, Float32 and Bool, SprigRuntime.str for other values; left.equals(right) for two Strings and java.util.Objects.equals when either side is String?, the left operand evaluated first and each once; Integer.signum(a.compareTo(b))runtime 33/35/47, correctness string-join checks
text += part in a loop (string building)yesno source rule: a function's local var of type String that a loop appends to (text += part, text = text + a + b) builds in time proportional to the text; a module-level var and a field copy the text on each appendsprig.runtime.TextAccumulator for the local: appends go to a builder, a read takes the text out once, length(), isEmpty() and a comparison with "" are answered from the builderruntime 61, check_strings.py accumulator and growth checks
Immutable collection mutation rejected—yes (SPR-COLLECTION-IMMUTABLE)—semantics
User generics: generic K, V: blocks (one or more parameters) for class/variant/function, applied as Entry[String, Int] or inferred, erased and boxed in generated Javayesyes (SPR-TYPE-GENERIC-*); each use's type arguments are checked against what the declaration writes and what its body infers (map literal keys, nested generic calls), reported at the useraw Java classes + compiler-controlled boxing/unboxingruntime 19, visitor generic_stack, semantics 8 cases and generic_map_key_*, numeric suite, syntax 08
Type arguments inferred from call arguments: generic Sprig function calls (local and imported), generic class constructors, generic variant cases with a payloadno new syntax; written [Type] arguments still win, all or nonestructural matching over Sprig types; weak numeric literals; null/[]/{} say nothing; lambdas typed without an expected type; never from the expected type; arguments then checked as with written arguments; conflicts and undetermined parameters report SPR-TYPE-GENERIC-ARGS-REQUIRED; requires X: Comparable checked on the inferred argumentsame generated Java as the written formruntime 37, semantics generic_inference*, adversarial v08
Generic variant expanded payloads + exhaustive match on instantiationsyesyesraw nested case classesruntime 19
requires X: Equatable equality capabilityyesequality on the parameter allowed only with the clause; value equality in codegenboxed Objects-style equalityvisitor generic_stack, runtime 19
requires X: Comparable ordering capabilityyes< <= > >= and sort() on the parameter only with the clause; type arguments checked at every call (SPR-GENERIC-CONSTRAINT)SprigRuntime ordering helpers that keep each concrete type's semanticsruntime 26, capabilities suite
Project model: sprig.toml discovery, defaults, init, project --json, deps --json, explicit-file priority, check/build/run --bin, check of every binyesvalidated (SPR-PROJECT-*)default entry compiled with the normal pipelineproject model suite
Local and Git Sprig dependencies: recursive resolution, @alias/module.spr imports, exports enforcement, cycle detection, sprig.lock, stale/missing lock refusalyesyes (SPR-DEP-*, SPR-PROJECT-*)dependency source modules compile through the normal pipelinedependency resolver suite
Offline mode for local/Git dependencies (--offline, warm cache required)yesSPR-DEP-OFFLINE when the cache is incomplete~/.sprig/git verified detached checkoutsdependency resolver
Maven/JVM dependency resolutionexact direct release coordinatesApache Resolver effective POM + transitive mediation, schema-5 hashes/graph/locators and compiler identityshared locked check/build/run/api/doctor classpathMaven fixtures + real commons-text showcase
Package registries: sprig search, sprig add NAME [--version V] [--registry R], sprig publish --tag T / --yank V --reason TEXT, [[registry]] path or Git indexespackages/NAME.toml entriesthe newest release by SemVer order, yanked releases skipped, a moved tag refused (SPR-DEP-REGISTRY); the default registry/ is strictadd writes an ordinary Git dependency, so builds never read the registrytests/registry/check_registry.py, scripts/internal/check-registry-index.py
Source callable types fn(A) -> R, nullable (fn(A) -> R)?, invariant, arities 0–3yessignatures/fields/locals/collections/generics; the only effect a callable type carries is throws Error (see the throwing-callables row)existing Fn0..Fn3 representation; a callable whose type mentions a type parameter is erased, and each call restores its concrete result typetests/callables, runtime 27
Bundled helpers: @std/lists.spr search, totals, sorted, max/min/max_by/min_by, slicing, distinct, enumerate/zip; @std/nulls.spr; @std/text.spr padding, ASCII checks, strip_prefix/strip_suffix, escape_html, fixed; @std/test.spr value checks and the check/check_error/finish runner, process.run; @std/math.spr exact Int helpers; @std/sets.spr, @std/random.spr, @std/regex.spr with capture groups, @std/dates.spr; files.read_lines/walk, time.sleep/monotonic_nanosordinary Sprig modules, no new syntaxtype arguments inferred from the arguments or written; sorted, max and min require Comparable items, max_by and min_by a Comparable key; a nullable type argument for nulls is rejectedplain Sprig, no host codescripts/test-stdlib.py, seven std_* semantics cases
Structured concurrency (@std/concurrent.spr): scope/spawn/run over JDK 21 virtual threads, pool/spawn_on/parallel_map, channel, counter, lock, latchordinary Sprig module, no async/await syntaxa task body has no throws clause; await() reports a failure as Error; leaving a scope waits for its tasks, and the first failure cancels the rest and is rethrown by scopesprig.runtime.concurrent (HostScope, HostTask, HostPool, HostChannel, HostLock, HostLatch)tests/concurrent/check_concurrent.py, examples/parallel_words
JVM callable ABI with concrete sprig.runtime.Fn0..Fn3 signaturesyesboxed invariant parameters/results, non-null argumentsdirect calls, nullable returned callable and runtime contract guardstests/callables
Lambdas fn(...) => expr, arities 0–3, map/filter/forEachyesyesFn0..Fn3 anonymous classesruntime 10, 18
throw/throws/try/catch/finally (typed errors); error classes class E: with message: String + conform E to Error(message)yesyes (SPR-FLOW-THROWS); an error class is thrown, declared, caught by name or as Error, a catch after one of Error is unreachable; a lambda throwing one has throws ErrorJava exceptions; an error class extends sprig.runtime.SprigErrorruntime 08/40, interop 15, semantics error_class_*, throw_plain_class
Throwing callables: fn(A) -> R throws Error types, lambdas that call functions throwing Error, rethrows functions that throw what their callable arguments throwthrows Error after a function type's result (parenthesized in a declaration's return position); rethrows in place of throwsthe clause is part of the type: no-throws values are accepted where throws Error is expected, never the reverse (SPR-TYPE-CALLABLE-THROWS); rethrows needs a throwing callable parameter (SPR-FLOW-RETHROWS); only Error crosses a callableno generated change: Error is unchecked on the JVMruntime 28, semantics callable_*/rethrows_*, tests/stdlib/lists.spr
Flow: definite return, unreachable code; while true without break completes only through return/throw—yes (SPR-FLOW-*)—semantics, runtime 25
Modules: file imports, alias access, init once, cycle detectionyesyesstatic $init() per module, started by the generated main; Java code that calls a function or makes an object with methods before that starts it too (see Gradle integration)runtime 12, semantics, tests/java_callers/check_java_callers.py
Initialization order: top-level statements run once, in source order—top-level code cannot use a binding declared below it (SPR-NAME-FORWARD-REFERENCE)a function, method, lambda or field default that runs before a later binding's initializer fails with SPR-RUNTIME-EXCEPTION (data.origin="init-order") instead of observing 0, false or null; constant prologues are unguardedsemantics, runtime diagnostics
JDK interop: imports, ctors, static/instance methods/fields, overloadsyesreflection-based; reference results nullable and require narrowing unless a nullability annotation (kept at run time or only in the class file) declares them non-null (a parameter annotated nullable accepts T?); an Int narrows to int/Integer with a run-time range check, exact long overloads preferreddirect Java callsruntime 15, correctness regressions, JVM interop suite
Checked Int/Int32, explicit integer quotient, numeric literal rangesyesSPR-NUM-* checksNumericOps checked JVM operationsnumeric acceptance suite
IEEE Float/Float32, explicit exact/lossy conversionyesmixed-type and narrowing checksJava double/floatnumeric acceptance suite
BigInt and Decimalyesdistinct native typesBigInteger/BigDecimal wrappersnumeric acceptance suite
Java checked exceptions + typed catch + error.messageyesyes; an Error's message is a String, a Java exception's a String?, and toString() on either is the text print shows; a catch of a checked Java exception its try block cannot throw is SPR-FLOW-CATCH-NEVER-THROWN, a declared checked Java exception the body cannot throw is SPR-FLOW-THROWS-UNUSED (not Exception, Throwable or Error, as in Java)Java try/catch; toString() on an exception is SprigRuntime.strruntime 15, 30 and 36, semantics catch_never_thrown*/throws_unused*/java_exception_message_join
sprig check/run/build/explain/codes/help/capabilities/api/doctor, --json, --syntax-only———scripts/test.sh, agent tooling suite
Java callables and varargs: a functional-interface parameter (Runnable, Comparator<T>, Consumer<? super T>, ...) accepts a Sprig fn(...) -> R value; a varargs parameter takes the trailing arguments or one opaque arraythe compiler emits a typed Java lambda that calls the Sprig Fn; trailing arguments are packed into new Element[] {...}exact parameter types after the Java mapping, void accepts any result, an int result takes an Int-returning lambda with a run-time range check, wildcards read as their bound only inside the interface's type arguments, the method's own type variables come from the receiver, written method[Type] arguments or the plain arguments (never from the lambda), a throwing callable is rejected (SPR-TYPE-CALLABLE-THROWS); fixed-arity overloads win over expansionjava-callable level and java-callable-adapter/varargs-expansion reason codes in sprig apiruntime 29, tests/jvm_interop, tests/callables
sprig build --bundle [--archive]: a directory with launchers, lib/ (program, runtime and locked JARs) and a jlink runtime image of the modules jdeps finds, for a machine without a JDK--bundle, --archive, --bin, -d as for buildthe program is checked and compiled first; never executed while bundlingjdeps + jlink of the running JDK (--strip-debug --no-header-files --no-man-pages --compress zip-6 --generate-cds-archive), legal notices kept, launchers with -XX:+AutoCreateSharedArchive; SPR-BUNDLE-TOOLS/-JDEPS/-LAYOUT; runs only on the building platformtests/bundle/check_bundle.py (five programs run without java on PATH)
Explicit local --classpath on check/build/run/api—shared class loader + javac/JVM pathlocked JVM JARs precede explicit entries; compiler libraries isolatedagent tooling suite
Bounded JVM interop: opaque arrays, concrete generics, explicit collection adaptersexplicit Type[Arg] application; @std/jvm.spr; sprig.runtime.jvm.HostBytesstructured interopLevel/interopReasonCodes; a method's own type parameters inferred from plain arguments and a single recursive bound (generic-bound-recursive) checked at the call; intersection bounds, generic arrays and type-variable varargs rejected before javac; wildcards keep their bounds (wildcard-bounds: reads at the upper bound, writes through ? extends rejected)arrays keep exact JVM classes; snapshots/copies are independent; no implicit conversionJVM interop suite
javac error and runtime frame → Sprig span translation——1-based line map shared by javac diagnostics and runtime failures; a runtime failure reports the innermost frame in the program's own modules, so one inside an @std function points at the calling lineruntime diagnostics
Java-reserved spellings as Sprig identifiers (Java keywords and restricted identifiers, java.lang.Object member names, package roots such as java or an imported org)——renamed JVM names; enum and variant values still print their Sprig spellingcheck_java_identifiers
JVM class-file limits——string literals beyond the constant-pool limit are split; a method over 64 KB of bytecode fails with SPR-JVM-COMPILE and an actionable hintcheck_jvm_limits
Checked effects from omitted class defaults—checked at each constructor call; explicit field values skip unused defaultsdefaults still evaluate per instance, in declaration ordercorrectness regressions
Unit value positions and unsupported type argumentsrejected before codegenSPR-TYPE-UNIT / SPR-TYPE-MISMATCHno invalid Java emittedcorrectness regressions
Match on statically inferred variant caseyessingleton exhaustiveness; impossible other branches rejectedconcrete case instanceof dispatchcorrectness regressions
JSON CLI results—includes command/status and structured diagnosticsrun output carried as programOutput, and what the program wrote to standard error as programErrorOutputcorrectness regressions, scripts/test-stdlib.py
Command-line I/O in @std/process.spr: exit, print_error, read_line, read_lines, read_allordinary Sprig module, no new syntaxexit returns Unit (the checker does not model it as terminating); the readers declare throws ErrorHostSystem: UTF-8 for piped input with malformed bytes rejected, the terminal's encoding for typed input; sprig run forwards standard input and the exit statusscripts/test-stdlib.py through real pipes
sprig test project runnerordinary .spr files under tests/compile-fail .expect.toml matches stable error codes using normal project/dependency checkingisolated child JVM per runtime test, 30-second timeout, per-test temp directory, deterministic JSON rows and @std/test.spr process helpertest runner integration suite + five-case dogfood project
Managed Linux/macOS SDK install and upgraderelease ZIP + checksum workflowmanaged-install metadata and layout validationstaged installation and atomic current pointer switch; older versions retainedinstaller, upgrade and installed-SDK dogfood suites
SQLite migrations (@sqlite/migrations.spr)Sprig package modulevalidated NNN_description.sql names, sorted ledger and idempotent apply; names, sequence numbers and order are checked against the ledger before any file runstrusted multi-statement SQL and ledger row share a SQLite batch transactionmigration apply/restart/failure-retry suite
Typed JSON fields (@std/json_codec.spr; @json-codec/codec.spr reexports it)bundled Sprig moduleexact JSON kinds, no coercion, missing and null kept apartpath-prefixed Error messages; root/root_array, required_*, optional_*, buildersJSON codec suite, task tracker example
CLI parsing (@cli/cli.spr)Sprig package moduletyped option specs, duplicate/unknown/missing checksdeterministic usage, flags/values/aliases/positionalsCLI library and installed json-select dogfood
Sprig module API (sprig api module.spr|@pkg/module.spr)resolved checked ASTdeclaration/field/method/throws/generic metadata and the comment above each declaration or member (doc); --member Type.membercompiler-owned JSON; never executes codeSprig API suite
Java-to-Sprig wrapper generator (sprig wrap)shared JvmMetadata.Support classification; canonical formatting; generated source is checked before writingplain editable .spr, deterministic, --force overwrite, structured skip reportno runtime reflection or generator dependency; Optional/adapters/throws mappings; unsupported members keep their reason codeswrap suite
Project API inventory (sprig api .)project + lockfile validationsource modules plus each dependency's exported modulesno application execution; stale/unexported targets refusedSprig API suite and installed SDK dogfood
Structured diagnostic metadataoptional relatedHelp and repair fieldsmachineApplicable false unless semantics-preserving and unambiguousstable fields unchangedagent tooling suite
Capability feature guidancefeatureGuidance per unsupported featurealternatives and help topic reflect current compiler onlyadditive to features booleansagent tooling and Sprig API suites
Operational explainwhyMatters, confusedWith, causes/fixes/examples, repair, relatedHelpconservative, compactsame data in text and --jsonagent tooling suite
Sprig-written agent toolsexamples/agent_tools (api-report, diag-summary, api-diff)plain Sprig JSON/file/CLI policyconsume saved compiler JSONagent tools suite
Agent task packdeterministic fixtures and runner under tests/agent_evalacceptance is mechanical; no model run claimedinitial states fail, known solutions passtask-pack gate

Not implemented (honest status): inference of type arguments from the expected type, variance, user-defined capabilities, inheritance between Sprig classes, an interface keyword (a contract class is the one form of open polymorphism; see below), nested/positional patterns, %=, tuples/destructuring (a one-line class replaces a tuple), source array syntax/annotations in interop, wildcard syntax in Sprig declarations, inference of Java method type parameters through a lambda, null, a Sprig collection or the result, a hosted package registry with authentication (the repository registry takes publications by pull request), incremental checking, self-hosting. See known limitations for boundaries.

Sprig is licensed under Apache-2.0 · v0.7.1-beta.1 published as a prerelease