Repository navigation
Sprig v0.9.0-beta.1
Pre-releaseSprig v0.9.0-beta.1
The release body is this file as of the tag. The latest published SDK is
v0.8.0-beta.1; the version number follows the
release and versioning policy: a new MINOR, because
Java code that names a generated Sprig class has to change.
Sprig v0.9.0-beta.1 lets two Sprig mods live in one Minecraft game: each
project's generated classes, and in Gradle builds its runtime, are in a package
of the project's own. A loop that builds a String with text += part now takes
time in proportion to the text. sprig-sqlite gains scoped transactions, a CSV
library joins the first-party packages, and using a deprecated Java API is a
warning at the Sprig line. The compiler is 0.9.0-beta.1; the language
version remains 0.8-dev, and no Sprig source has to change. JDK 21+ is
required. Linux and macOS are release-supported; Windows remains an
experimental, non-blocking preview. It is an experimental Beta, not a promise
of production stability or a frozen API.
A package for each project
Every Sprig program used to compile into the one package sprig.user, and
every Gradle-built jar carried the runtime as sprig.runtime. Fabric loads all
mods in one class loader, so with two Sprig mods installed one copy of each
class shadowed the other: the Fabric starter and the waypoint example together
crashed the game with a NoSuchMethodError on sprig.user.$M_main.
A project's jar now holds:
| Package | Contents |
|---|---|
sprig.user.<project> |
The classes generated from the project's modules, its dependencies' modules included |
sprig.user.<project>.runtime |
The project's own copy of the runtime, in Gradle builds |
<project> is the name in sprig.toml, with every character a Java package
name cannot hold replaced by _: sprig-fabric-counter gives
sprig.user.sprig_fabric_counter. A file compiled outside a project has no
name to take and stays in sprig.user. sprig project and
./gradlew sprigInfo print the package.
Two jars built this way share no class name, so one class loader can hold both:
two Fabric mods in one game, or two Sprig-built libraries on one classpath.
Each has its own runtime classes, so values cross between them as Java types
(String, numbers, an interface both know).
sprig run,sprig testand a plainsprig buildgenerate into the
project's package and keep using the runtime the SDK ships precompiled.sprig build --emit-java-only --with-runtimealso writes the runtime's Java
sources, assprig.user.<project>.runtime, and the generated code uses that
copy: one source tree for a build tool to compile.--jsonlists
runtimeSourcesand reportsgeneratedPackageandruntimePackage. The
dev.sprigGradle plugin builds with it.
See the upgrade section for the one change this asks of a Gradle project.
Language and compiler
text += part in a loop is linear
A String is immutable, so a loop that appends n parts with text += part
copied the accumulated text n times. The generated code now keeps a function's
local var of type String that a loop appends to in a builder; nothing
changes in the source, and every read gives the same text as before. On one
machine, joining 100,000 JSON rows went from 32 seconds to 26 milliseconds.
A module-level var and a field are shared state and stay plain Strings; see
string building.
Deprecated Java APIs
Calling, reading or overriding a Java member annotated @Deprecated, or
importing a deprecated class, gives the warning SPR-JVM-DEPRECATED at the
Sprig location. The message names the overload, as in
java.net.URLDecoder.decode(String), because another overload may be current.
sprig api reports deprecated and forRemoval for each member.
A warning says it is one: its line has warning: after the location, and the
closing line counts warnings apart from errors. A program that only has
warnings still compiles and exits 0.
Diagnostics that point at a worked example
A diagnostic about a Java call can carry example, the URL of a page with a
worked example: its own example: line in text output, "example" in JSON,
and codeDescription.href for editors. They point into the new
Java interop cookbook
(中文): a
result that may be null, a checked exception, a collection, a callback and an
overloaded call, each with the rejected program, the compiler's message and
the working program. SPR-JVM-MEMBER and SPR-JVM-AMBIGUOUS for a Java call
also name the sprig api command that lists the signatures the call can match.
Libraries
sprig-sqlite: scoped transactions
sqlite.transaction(database, body) runs body with a Transaction whose
query and execute share one connection. It commits when the body returns
and rolls back when the body throws or an SQL operation fails;
sqlite.transaction_run is the same for a body that returns nothing. A call on
the database itself inside the body is refused at once with an Error that
says to use the Transaction: it would run on a second connection that does
not see the transaction's writes.
sprig-csv
A new first-party package for CSV tables, on Apache Commons CSV 1.14.1:
parse, encode, read and write, a Format(delimiter=",", header=true),
and table.cell(row, column) and table.column_index(column) to read by
header. Cells stay text. It is strict where CSV is ambiguous: a missing, blank
or duplicate header and a record of the wrong width are errors, and every
failure is a CsvError whose message says what went wrong in words. The
package ships in the SDK and is used by path; it is not in the registry yet.
Upgrade from v0.8.0-beta.1
Run sprig upgrade, then sprig resolve once in each project: a lock records
the compiler that wrote it.
Incompatible: Java names a generated class with the project's package
This affects Gradle projects, Fabric mods among them, whose Java code calls
generated Sprig classes. Add the project's package:
// v0.8.0-beta.1
CounterActions counter = sprig.user.$M_main.fn$new_counter();
// v0.9.0-beta.1, for a project named sprig-fabric-counter
CounterActions counter = sprig.user.sprig_fabric_counter.$M_main.fn$new_counter();javac reports every reference that still uses the old package, and
./gradlew sprigInfo prints the new one. The package follows the project's
name: after a rename, the same edit is due again.
Java code that names a runtime class of its own project uses
sprig.user.<project>.runtime in place of sprig.runtime. Sprig source is
not affected: import sprig.runtime.host.HostFiles as HostFiles keeps its
spelling.
The Gradle plugin and the compiler come from one SDK
The plugin asks the compiler for build --emit-java-only --with-runtime.
Pointed at an older compiler, it stops while the build is configured and says
what the compiler must provide. Projects that include the plugin from
SPRIG_HOME/libraries/sprig-gradle, as the starter does, get the matching pair.
Output a tool may read
- The
mainClassof a project issprig.user.<project>.$M_<module>. A single
file's is unchanged. - Text output labels warnings with
warning:, and prints the closing count
line for warnings alone. - Diagnostic JSON gains the optional
example;build --emit-java-only --json
gainsgeneratedPackageandruntimePackage;project --jsongains
generatedPackage.
Known limits
A project's package follows its name, so two projects with the same name
still collide, and my-mod and my_mod give the same package. Java that calls
a generated function directly does not run the module's top-level statements
first, so a top-level binding the function reads is not initialized yet; call
$init() on the module's class before it, or keep such state in a class. The Loom
tests, including the one that starts a client with two Sprig mods, need
Minecraft and run outside CI. See
known-limitations.md.