Skip to content

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:

spr
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")
text
42
failed: not a number: abc
done

Those 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 Error is 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 == null check 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 text block directly under a code block is the result of running it.
  • In a "Deliberate mistake" section the code does not compile, and the text block under it is the compiler's real error. The SPR-... at the start is the error code; sprig explain followed by that code gives the full explanation.
  • Every complete program in the book is a real .spr file in the repository, and you can run it with sprig 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 ​

ChapterWhat you will learn
1. Getting set upthe terminal, the JDK, the compiler, an editor, and how to check the version
2. Your first program, and reading errorsprint, comments, the four parts of an error, sprig explain
3. Values, variables and arithmeticlet/var, types, the rules for integers and floating-point values, Bool
4. Textescapes, common string methods, code points, @std/text
5. Making decisions: ifconditions, elif, if expressions
6. Repeating: loopswhile, for, range, break/continue
7. Functionsparameters, results, scope, recursion, naming
8. ListsList and MutableList, common methods, sorting
9. Maps and setsMap, counting patterns, @std/sets
10. Project: guess the numberreading input, command-line arguments, random numbers

Part 2: Describing the world with types ​

ChapterWhat you will learn
11. Classes and objectsfields, methods, one-line classes, identity
12. Enums, variants and matchclosed sets of types, exhaustive matching, recursive variants
13. Values that may be missingT?, narrowing, or_else
14. Handling errorsthrows, error classes, rethrowing, finally
15. Functions as valueslambdas, function references, capture, function types that throw
16. Generics and contract classesgeneric, requires, contract classes and conform
17. More about numbersInt32/Float32, the conversion table, Decimal/BigInt, @std/math

Part 3: Building real programs ​

ChapterWhat you will learn
18. Modules, projects and dependenciesimport, sprig.toml, lockfiles, dependencies
19. Testing@std/test, sprig test, compile-fail tests
20. The standard library at workfiles, JSON, date and time, regular expressions
21. Calling Javaimporting Java classes, nullable results, collection adapters
22. Concurrencyvirtual threads, tasks, channels, locks
23. Tools and AI assistantsthe language server, fmt, structured queries, writing with an assistant
24. Project: an expense trackerthe whole book in one complete program

Appendices ​

AppendixWhat is in it
A. Operators and precedenceevery operator, the precedence table, associativity
B. Error codes and where to read about themthe stable SPR- codes, grouped
C. Keywords and built-in functionskeywords, built-in functions, built-in methods
D. Coming from Python, JavaScript or Javaold habits mapped onto Sprig
E. What Sprig leaves outdeliberate omissions and what to write instead
F. Java interop in depthwildcards, 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.

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