Sprig generics (implemented contract)
Sole current generics reference. The website and SDK use this source.
This document describes the generic type system the stage-0 compiler implements. It is narrower than a general generics design and deliberately so.
Declaration
generic T:
class Box:
let value: Tgeneric T:wraps one declaration: a class, variant or function.- Blocks may declare any number of parameters:
generic K, V:. There is no arbitrary limit, and there is no separate single-parameter type system. - Duplicate names in one list (
generic T, T:) reportSPR-NAME-DUPLICATE. - Parameters are visible only inside the block; they never leak, and a name or type outside the block cannot refer to them (
SPR-NAME-UNRESOLVED).
Application: written or inferred from the arguments
let box = Box[Int](https://github.com/ColinHouse/Sprig/blob/main/docs/language/value=42) # written type arguments
let value = identity[Int](https://github.com/ColinHouse/Sprig/blob/main/docs/language/42)
let some: Option[Int] = Option[Int].Some(value=1)
let none: Option[Int] = Option[Int].None
let inferred = Box(value=42) # Box[Int], inferred from the arguments
let same = identity(42) # identity[Int]
let kiwi = Option.Some(value="kiwi") # Option[String].Some- A call of a generic Sprig function (local or from an imported module, such as
lists.sort_by), a constructor of a generic class (named arguments) and a constructor of a generic variant case that has payload fields may leave out the[Type]arguments. They are then inferred from the argument expressions of that call only: never from the expected type, the assignment target, the enclosing call or the result. There is no bidirectional inference. - Written arguments still work and are used as written. They are all or nothing:
Entry[String]for a two-parameter declaration reportsSPR-TYPE-GENERIC-ARITY, as does a bareBoxin a type position or arguments on a non-generic type. Partial arguments are never inferred. - Type positions (
let box: Box[Int]), payloadless cases (Option[Int].None) and Java generic types (ArrayList[String]) always write their arguments. A Java method's own type parameters follow the same rule as Sprig calls: inferred when the arguments fix every one exactly (Collections.sort(names),List.of(1, 2, 3)), written otherwise (Collectors.toList[Int]()); see JVM interop. - Nested applications are ordinary:
List[Option[Int]],Map[String, Box[Int]],Box[List[String?]]. - Generic types are invariant. No
out/in, wildcards or subtyping.
How arguments determine type parameters
Each argument is matched against its declared parameter or field type, structurally: a type parameter, T?, List/MutableList, Map/MutableMap, function types and generic class and variant applications. A Java generic type is never looked into.
- Positions. An argument passed directly for
T, an element of a list or map literal, and the result of a lambda are flexible: the value only has to be assignable there. A position inside another type (List[T]againstList[Int], a lambda's written parameter type againstfn(T) -> R) is exact, because generic types are invariant. - Several arguments. All exact positions must agree, and every flexible argument must be assignable to that type. Without an exact position, the narrowest type every flexible argument is assignable to wins, in any argument order:
Int32andIntgiveInt,String?andStringgiveString?andInt32?andIntgiveInt?(where a nullable argument is accepted), and a variant case value gives its variant (Option.Some(value=1)makesTOption[Int]), so two cases of one variant meet at the variant. - Weak literals. An unannotated numeric literal binds a parameter only if no other argument binds it. For
generic T: func pair(a: T, b: T) -> List[T]andsmall: Int32,pair(small, 8)infersInt32;pair(1, 2)infersIntandpair(1.5, 2.5)Float. Literals of different kinds (pair(1, 2.5)) disagree, as they do in a list literal. A list or map literal passed for a bareTis typed as a whole and is weak in the same way: on its own,pair([1], [2])infersMutableList[Int], aslet xs = [1]does, but next to aList[Int]value the literal becomes aList[Int]too, sonulls.or_else(config["tags"], ["default"])works for aMap[String, List[String]]. - No information.
null,[],{}, a literal that holds only those, and aUnitresult say nothing. A non-empty list or map literal passed forList[T]orMap[K, V]infers from its elements, each on its own. - Lambdas. Lambda parameters are always annotated. A lambda is typed without an expected type; its parameter types bind exactly and its body binds the function type's result flexibly.
- Nullability. A parameter written
T?matched againstXorX?bindsT = X. A bareTmatched againstX?bindsT = X?only if an explicit[X?]would be accepted (see the nullability rule below); otherwiseT = X, and the nullable argument is reported by the argument check. Inside another type the nullable type is kept, becauseList[T]againstList[String?]can only meanT = String?; where[String?]is not accepted, the call reportsSPR-TYPE-GENERIC-NULLABLEas the written form does.
After inference every argument is checked against the substituted parameter types exactly as with written arguments, so a literal adapts (the 8 above is an Int32) and a wrong argument gets the usual SPR-TYPE-MISMATCH or SPR-TYPE-NULLABLE. The inferred arguments are validated like written ones (nullability rule, substituted annotations), stored where written ones are, and every requires X: Comparable is checked against them at the call. Generated Java is the same as for the written form.
A mismatch on an argument whose expected type was inferred from another argument says so in its hint (T is String, from argument 2).
A parameter that no argument determines, or that two arguments give incompatible types, reports SPR-TYPE-GENERIC-ARGS-REQUIRED. The message names each parameter and why (argument 1 is an empty list, which says nothing about T; T is String from argument 1 but Bool from argument 2), and the hint writes the call with the inferred arguments filled in where known, spelled as the calling module writes them (lists.Pair[Int, String] through an import alias, a Java class by its import alias, a variant case as its variant), for example Write lists.first[Type](https://github.com/ColinHouse/Sprig/blob/main/docs/language/...) or Write Result[Int, Type].Ok(...). When a parameter is unknown only because an argument has another shape than its parameter (lists.sort_by(orders, 5)) or is a Unit result, that argument is reported instead, as the SPR-TYPE-MISMATCH or SPR-TYPE-UNIT it is, because writing the type arguments would not help. An argument that already has an error of its own is no evidence, and its error is reported instead of a second one.
Inference first types each lambda and literal argument on its own; a generic call nested inside it stops there once it knows its own type arguments. The argument is then checked once more against the inferred types, so checking stays polynomial in the nesting depth of generic calls instead of doubling with every level.
Type parameters have almost no abilities
Inside a generic declaration, T supports assignment, passing, returning and being placed in compatible generic containers. It has no operators or methods, and equality or ordering only when the enclosing function declares them: value + value is SPR-TYPE-OPERAND; a == b is rejected unless the function starts with requires K: Equatable, in which case equality is checked with value equality on the boxed representation; a < b is rejected unless it starts with requires K: Comparable.
Capabilities are deliberately minimal:
| Capability | Status |
|---|---|
Equatable | implemented for <T> equality under requires X: Equatable |
Comparable | implemented for < <= > >= and sort() under requires X: Comparable |
The set of capabilities is closed; any other name reports SPR-GENERIC-CONSTRAINT. Capabilities are independent: Comparable does not grant ==, so a function that needs both writes both clauses.
Comparable
requires T: Comparable grants the ordering operators <, <=, > and >= between two values of type T, and sort() on a MutableList[T].
- Type arguments. Comparable types are exactly the types that already have ordering operators:
Int,Int32,Float,Float32,Decimal,BigIntandString, plus a type parameter of the calling function that itself declaresrequires X: Comparable. Nullable types,Bool, classes, enums, variants, collections and Java types are not Comparable. Every call that instantiates the requirement is checked: a generic function call, a method call on a generic class instance, or an unqualified method call inside the class. A violation reportsSPR-GENERIC-CONSTRAINTat that call. - Meaning. A generic comparison means exactly what the same operator means on the concrete type: numeric order for
Int,Int32,DecimalandBigInt; IEEE comparison forFloatandFloat32(every comparison with NaN is false, and-0.0and0.0compare equal); UTF-16 code unit order forString. - Sorting.
sort()on aMutableList[T]uses the same ascending, stable order assort()on a concrete list, which forFloatplaces-0.0before0.0and NaN last.sort()acceptsBooland every Comparable element type. - Lowering. Generated Java calls
SprigRuntime.lessThan,lessOrEqual,greaterThanorgreaterOrEqualon the erased values; those helpers dispatch on the boxed type to keep the concrete semantics above.
Clauses must form a leading prefix of the function body. A late or nested clause reports SPR-GENERIC-CONSTRAINT and grants no capability.
Any requires clause naming a parameter that is not in scope reports SPR-NAME-UNRESOLVED.
Nullability rule (Practical Strict)
List[String?],Box[String?]andOption[String?]are legal.If the declaration itself applies
?to the parameter:spriggeneric T: class Box: let value: T?then
Box[String]is legal butBox[String?]is rejected withSPR-TYPE-GENERIC-NULLABLE. The compiler does not flattenT?or inventString??; the declaration already owns the nullable position. This applies recursively to written annotations, local/lambda types and nested generic uses, written or inferred (see below), and is independent of declaration order.
Checked again with the type arguments
A generic declaration is checked once, with its parameters standing for any type. The rules that depend on the actual type are checked again at every use with type arguments, written or inferred: the call, the construction or the type annotation that gives them. Two things are checked with the arguments substituted:
- What the declaration writes: its annotations, locals, lambda parameter types and generic applications.
- What its body infers: the key type of a map literal (
{value: true}keyed byT), and the type arguments of the generic calls and constructions it makes (sets.of(values)withvalues: List[T]), which are checked the same way with their own arguments, all the way down.
Among these rules are the Map key rule (Float and Float32 are not map keys, SPR-NUM-CONVERSION; see numeric semantics) and the nullability rule above. A failure is reported at the use that gives the type argument, with the code and message it has where it arises; the hint names the declaration, the arguments and that place, also inside a library:
SPR-NUM-CONVERSION [TYPE] main.spr:3:9: Float and Float32 cannot be Map keys: NaN and signed zero have no stable key equality
hint: Rejected inside 'of' with T = Float, at @std/sets.spr:7:33. Use an explicit quantized Int key, or a Decimal key when decimal identity is intended.An error the generic code has whatever its arguments, such as a map literal keyed by a Float value inside it, is reported once, where it is written, and not again at each use.
Generic variants
Generic variants use the expanded payload form:
generic T:
variant Option:
Some:
value: T
None:Option[Int].Some(value=42) builds a value, and so does Option.Some(value=42), which infers T from the payload; Option[Int].None is a value, not a call, and has no payload to infer from. A match writes the unapplied case owner; do not put [Int] in a case:
func read(option: Option[Int]) -> Int:
match option:
case Option.Some as some:
return some.value
case Option.None:
return 0Exhaustive match works on instantiations and a new case still reports SPR-MATCH-NONEXHAUSTIVE for every match that misses it.
Relationship to indexing
values[index] remains ordinary indexing. The parser records a bracket payload that parses as type references as a candidate; the checker decides:
- if the base names a generic declaration, the bracket is a type application;
- otherwise a single plain name is indexing, as in the design kit.
handlers[index](https://github.com/ColinHouse/Sprig/blob/main/docs/language/arg), indexing a list of function values and calling the result, is an ordinary call on an indexed value.
JVM lowering
Generics are erased and boxed in generated Java:
- a type parameter becomes
java.lang.Object; - generic classes and variants are emitted as raw classes;
- the compiler inserts boxing at generic argument positions and casts plus unboxing at generic result positions;
instanceofstays raw, so match exhaustiveness is unaffected.
Sprig types are preserved at the source level: Box[Int] is Int to Sprig even though the JVM sees a boxed value.
Imported Java generics
Explicit type arguments also apply to imported Java classes and methods (ArrayList[String], Host.method[String](https://github.com/ColinHouse/Sprig/blob/main/docs/language/value)). Concrete arguments are preserved in Sprig types and in sprig api metadata; class type variables resolve through the receiver and its inherited hierarchy. The profile is deliberately bounded: no wildcard syntax in Sprig (an imported wildcard keeps its bound and cannot be written through) and no capture conversion; a method's own type parameters are inferred when the plain arguments fix every one of them exactly and are written otherwise (see JVM interop), and intersection bounds or generic arrays are rejected before codegen (a single recursive bound is accepted and checked at each call). Java reference results remain conservatively nullable. See JVM interop for arrays and collection adapters.
Not implemented
Inference of type arguments from the expected type, inference of Java method type variables through a lambda, null, a Sprig collection or the result, variance, any user-defined capability, and generic constraints on JVM types. The manifest and entry-discovery model (sprig.toml, init, project, deps, run --bin), schema-5 lockfiles, local/Git and Apache Maven resolution are implemented; see the current project/dependency documentation.
