The Sprig Programming Language
Welcome. This book teaches Sprig from scratch: a small language that runs on the JVM, looks like Python, and — when you get something wrong — tells you which line is wrong, why, and how to fix it.
Every program in the book has really run, and the output under a program is what it printed. Every "Deliberate mistake" has really been rejected by the compiler, with the error text copied as it is. You do not need to have programmed before, and you do not need to know Java.
What kind of language Sprig is
Start with one complete program:
func parse_amount(text: String) -> Int throws Error:
let value = text.toIntOrNull()
if value == null:
throw Error("not a number: " + text)
return value
func total(lines: List[String]) -> Int throws Error:
var sum = 0
for line in lines:
sum += parse_amount(line)
return sum
try:
print(total(["12", "30"]))
print(total(["12", "abc"]))
catch problem: Error:
print("failed: " + problem.message)
finally:
print("done")42
failed: not a number: abc
doneThose dozen lines already show several of Sprig's core ideas:
- Indentation is structure. No braces, no semicolons, one thing per line.
- Types on signatures, inference in locals. Function parameters and results always name a type;
let value = ...inside a function body does not. - Failure goes into the type.
throws Erroris part of the signature, and a caller either handles the error or declares it as well. Nothing escapes silently. - So does absence. A value that may be missing says so in its type, and you need a
== nullcheck before you can use it as an ordinary value. - No implicit conversions, no "nonzero is true", no fallback branch, and no inheritance. You will meet each of these in the chapters.
This program uses functions, Error, and try/catch/finally. It is fine if none of that makes sense yet: Chapter 7 covers functions and Chapter 14 covers handling errors.
Who this book is for
It is written for people who have never programmed, and for people coming from another language.
- If this is your first language: read in order. In each chapter, first look at the examples, then at the output, then do the exercises. The answers are folded away, so try before you peek.
- If you know Python, JavaScript or Java: the first chapters can go quickly, but Chapter 3 (numbers) and Chapter 13 (values that may be missing) cover where Sprig differs from other languages, so do not skip them. Appendix D maps your old habits onto Sprig one by one, to consult as you read.
How to read this book
There are 24 chapters in three parts, with appendices after them.
Each chapter starts with what you will learn and ends with a summary and exercises. The book's conventions:
- A
textblock directly under a code block is the result of running it. - In a "Deliberate mistake" section the code does not compile, and the
textblock under it is the compiler's real error. TheSPR-...at the start is the error code;sprig explainfollowed by that code gives the full explanation. - Every complete program in the book is a real
.sprfile in the repository, and you can run it withsprig run <file>. - The errors come from the compiler, not from a human. Another version may word them differently, but the codes do not change.
Which compiler version you need
This book uses the 0.8 language, reported as language 0.8-dev by sprig capabilities. The SDK release version and the language version describe different things.
The published v0.9.0-beta.1 SDK includes the syntax and standard modules used in this book and requires JDK 21+. Install the SDK directly; you do not need to build the compiler first. Chapter 1 explains installation and version checks. This site follows main; see release status for later differences and sprig capabilities --json for your installed compiler's capabilities.
Chapter map
Part 1: Writing programs from scratch
| Chapter | What you will learn |
|---|---|
| 1. Getting set up | the terminal, the JDK, the compiler, an editor, and how to check the version |
| 2. Your first program, and reading errors | print, comments, the four parts of an error, sprig explain |
| 3. Values, variables and arithmetic | let/var, types, the rules for integers and floating-point values, Bool |
| 4. Text | escapes, common string methods, code points, @std/text |
| 5. Making decisions: if | conditions, elif, if expressions |
| 6. Repeating: loops | while, for, range, break/continue |
| 7. Functions | parameters, results, scope, recursion, naming |
| 8. Lists | List and MutableList, common methods, sorting |
| 9. Maps and sets | Map, counting patterns, @std/sets |
| 10. Project: guess the number | reading input, command-line arguments, random numbers |
Part 2: Describing the world with types
| Chapter | What you will learn |
|---|---|
| 11. Classes and objects | fields, methods, one-line classes, identity |
| 12. Enums, variants and match | closed sets of types, exhaustive matching, recursive variants |
| 13. Values that may be missing | T?, narrowing, or_else |
| 14. Handling errors | throws, error classes, rethrowing, finally |
| 15. Functions as values | lambdas, function references, capture, function types that throw |
| 16. Generics and contract classes | generic, requires, contract classes and conform |
| 17. More about numbers | Int32/Float32, the conversion table, Decimal/BigInt, @std/math |
Part 3: Building real programs
| Chapter | What you will learn |
|---|---|
| 18. Modules, projects and dependencies | import, sprig.toml, lockfiles, dependencies |
| 19. Testing | @std/test, sprig test, compile-fail tests |
| 20. The standard library at work | files, JSON, date and time, regular expressions |
| 21. Calling Java | importing Java classes, nullable results, collection adapters |
| 22. Concurrency | virtual threads, tasks, channels, locks |
| 23. Tools and AI assistants | the language server, fmt, structured queries, writing with an assistant |
| 24. Project: an expense tracker | the whole book in one complete program |
Appendices
| Appendix | What is in it |
|---|---|
| A. Operators and precedence | every operator, the precedence table, associativity |
| B. Error codes and where to read about them | the stable SPR- codes, grouped |
| C. Keywords and built-in functions | keywords, built-in functions, built-in methods |
| D. Coming from Python, JavaScript or Java | old habits mapped onto Sprig |
| E. What Sprig leaves out | deliberate omissions and what to write instead |
| F. Java interop in depth | wildcards, annotations, parent classes, wrap |
What this book does not cover
It is not the language specification, and not a complete API list. For the syntax line by line there is the language quick reference; for the precise contracts of numbers, nullability and generics there is the reference. Fabric mods, Gradle integration, web and SQLite each have their own guide.
Ready? Start with Chapter 1: Getting set up. Then go in order and do not skip chapters: each one only uses what earlier chapters taught.
