24. Project: an expense tracker
The last chapter teaches no new syntax. It puts the previous 23 chapters together into one complete little program: read a list of expenses, total them by category, and print the grand total. You will see why each part is written the way it is, plus two real compiler errors and one runtime error message.
In this chapter you will learn to:
- break a small requirement into a
variant, aclassand a set of functions; - why amounts are stored as whole cents instead of decimals;
- use
try/finallyso the program deletes only the file it created; - the whole flow: read a file, parse each line, total by category;
- read the two deliberate mistakes.
24.1 What to build
The input is text, one expense per line, three comma-separated fields: item, amount, category.
Coffee, 12.50, food
Taxi, 36.00, transport
Noodles, 18.00, food
Movie, 45.00, funThe program prints each category's total and the grand total. There are only three categories: food, transport and "other"; fun is neither food nor transport, so it lands in "other".
24.2 The complete program
The program is below. It creates and writes a temporary file first (so you can run it without preparing data), then deletes that file after reading it.
import "@std/files.spr" as files
import "@std/text.spr" as strings
# A category is one of a fixed set; a variant expresses that.
variant Category:
Food
Transport
Other
# One expense: item, amount (in cents), category.
class Expense:
let item: String
let cents: Int
let category: Category
# Write cents as "units.xx", for example 3050 -> "30.50".
func format_money(cents: Int) -> String:
let units = cents.divTrunc(100)
let rest = cents % 100
if rest < 10:
return units + ".0" + rest
return units + "." + rest
# Parse "12.50" into 1250 cents; a bad format throws.
func parse_amount(text: String) -> Int throws Error:
let parts = text.split(".")
let units = parts.get(0).toIntOrNull()
if units == null or parts.size() > 2:
throw Error("not an amount: " + text)
if parts.size() == 1:
return units * 100
let cents = parts.get(1).toIntOrNull()
if cents == null or parts.get(1).length() != 2:
throw Error("not an amount: " + text)
return units * 100 + cents
# A category name -> Category; anything unknown is Other.
func category_of(name: String) -> Category:
if name == "food":
return Category.Food
if name == "transport":
return Category.Transport
return Category.Other
# Category -> the name shown in the report.
func label(category: Category) -> String:
return match category:
case Category.Food:
"Food"
case Category.Transport:
"Transport"
case Category.Other:
"Other"
# One line "Coffee, 12.50, food" -> one expense.
func parse_line(line: String) -> Expense throws Error:
let fields = line.split(",")
if fields.size() != 3:
throw Error("expected item, amount, category: " + line)
let item = strings.trim(fields.get(0))
let cents = parse_amount(strings.trim(fields.get(1)))
let category = category_of(strings.trim(fields.get(2)))
return Expense(item=item, cents=cents, category=category)
# Read a file and parse every non-empty line into an expense.
func load_file(path: String) -> MutableList[Expense] throws Error:
let expenses: MutableList[Expense] = []
for line in strings.lines(files.read_utf8(path)):
if strings.trim(line) != "":
expenses.append(parse_line(line))
return expenses
# Total by category, then print the report.
func report(expenses: List[Expense]) -> Unit:
let totals: MutableMap[String, Int] = {}
var sum = 0
for expense in expenses:
let name = label(expense.category)
let previous = totals[name]
if previous == null:
totals[name] = expense.cents
else:
totals[name] = previous + expense.cents
sum += expense.cents
for name in ["Food", "Transport", "Other"]:
let amount = totals[name]
if amount != null:
print(name + ": " + format_money(amount))
print("Total: " + format_money(sum))
func main() -> Unit throws Error:
# Lines 1 and 2 create this temp file; the last line removes exactly that file.
let path = files.temp_file()
files.write_utf8(path, "Coffee, 12.50, food\nTaxi, 36.00, transport\nNoodles, 18.00, food\nMovie, 45.00, fun\n")
try:
report(load_file(path))
finally:
files.remove_file(path)
try:
main()
catch problem: Error:
print(problem.message)Food: 30.50
Transport: 36.00
Other: 45.00
Total: 111.50Look at the output first:
Food: 30.50:Coffee's 12.50 plusNoodles' 18.00 is 30.50.Transport: 36.00: just the oneTaxiline.Other: 45.00:funis not a known category, so it falls toOther.Total: 111.50: all four expenses added up.
The sections below follow the program in order.
24.3 Categories: variant and match
A category is "one of a fixed few, each carrying no data (Other is just a name)". That is exactly chapter 12's variant:
variant Category:
Food
Transport
Othercategory_of turns a text name into a Category, returning Category.Other for anything unknown. label goes the other way, turning a Category into the name shown in the report; it uses match, with all three branches present—match has no fallback, the compiler requires every case (chapter 12).
24.4 One expense: a class
class Expense:
let item: String
let cents: Int
let category: CategoryAll three fields are let: once created, an expense should not change (chapter 11). Construction always names the fields: Expense(item=item, cents=cents, category=category).
cents is an Int, not a Float. Chapter 3 already showed why: 0.1 + 0.2 prints 0.30000000000000004, and money in decimals drifts. So 12.50 yuan is stored as 1250 cents and converted back for printing.
24.5 The two money functions
parse_amount("12.50") turns text into 1250 cents:
let parts = text.split(".")split(".") splits on the decimal point into ["12", "50"], parts.get(0) is "12", and toIntOrNull() turns it into 12 or null if it cannot (chapters 4 and 13). The units part must exist and there can be at most one decimal point; the fraction must be exactly two digits, or the function throws:
if cents == null or parts.get(1).length() != 2:
throw Error("not an amount: " + text)throws Error is in the signature, so the caller must catch it or declare it too (chapter 14).
format_money goes the other way:
let units = cents.divTrunc(100)
let rest = cents % 100divTrunc is "integer division that drops the remainder" (chapter 17): 1250 divided by 100 is 12; % gives the remainder 50. When rest < 10 a zero must be added: 50 cents is ".50", 5 cents is ".05".
24.6 A line of text becomes one expense
parse_line takes "Coffee, 12.50, food" apart:
line.split(",")gives the three fields; not three means an error.strings.trim(...)strips spaces around each field (@std/text, chapter 20).parse_amountparses the amount;category_ofparses the category.- Finally an
Expenseis created and returned.
load_file reads the file into lines:
for line in strings.lines(files.read_utf8(path)):
if strings.trim(line) != "":
expenses.append(parse_line(line))strings.lines splits on line endings; a final line ending leaves one extra empty string, so trim filters empty lines out. Each parsed line is appended to a MutableList[Expense] (chapter 8).
24.7 Totalling: the map counting pattern
report uses a MutableMap[String, Int] to hold each category's total (chapter 9):
let previous = totals[name]
if previous == null:
totals[name] = expense.cents
else:
totals[name] = previous + expense.cents
sum += expense.centsReading a category that has not been recorded yet gives null, so the code reads first, checks, and then either creates or adds. You cannot write totals[name] += expense.cents here: with a missing key that is a runtime error.
Printing walks the fixed order ["Food", "Transport", "Other"]; a category with no expenses prints nothing.
24.8 main: read, clean up, delete only what you created
main has four steps, and the first one and the cleanup come as a pair:
let path = files.temp_file()
files.write_utf8(path, "Coffee, 12.50, food\n...")
try:
report(load_file(path))
finally:
files.remove_file(path)files.temp_file()creates a new file in the system temporary directory and returns its path (@std/files, chapter 20).files.write_utf8(path, ...)writes the sample data.\nis a newline (chapter 4).files.read_utf8(path)reads it back andload_fileparses it.- The
files.remove_file(path)in thefinallyblock deletes exactly the temp file created by line 1;finallyguarantees cleanup even when parsing fails (chapter 14).
The program ends with a try / catch around main, printing the message if it throws an Error (chapter 14).
To read your own expense file, replace main
Do not just change path: the program above would first write the sample data over your file, and the finally would delete it afterwards. The safe way is to make main read only, with no write and no delete:
func main() -> Unit throws Error:
report(load_file("my-expenses.txt"))That is, drop all three lines: temp_file(), write_utf8 and remove_file. Only a file the program created itself is the program's to delete.
24.9 Deliberate mistake: integers cannot be divided with /
Replace cents.divTrunc(100) in format_money with cents / 100:
let cents = 1250
print(cents / 100)SPR-NUM-DIVISION [TYPE] main.spr:2:7: Integer / would truncate; use a.divTrunc(b), or convert both operands explicitly (expected explicit division, actual Int / Int)
hint: Write cents.divTrunc(100) to drop the remainder on purpose, or cents.toFloatExact() / 100.toFloatExact() for a Float result. text.fixed(value, decimals) from @std/text.spr prints a Float with that many decimals.
1 error(s); run 'sprig explain <code>' for details on a diagnostic code.The error is at line 2, column 7, pointing at the /. The message lays out both choices: divTrunc when you mean to drop the remainder, or convert both sides to Float when you want a decimal. Sprig will not guess whether 7 / 2 should be 3 or 3.5.
24.10 Deliberate mistake: a missing match case
If label only had Food and Transport branches:
variant Category:
Food
Transport
Other
func label(category: Category) -> String:
return match category:
case Category.Food:
"Food"
case Category.Transport:
"Transport"
print(label(Category.Food))SPR-MATCH-NONEXHAUSTIVE [FLOW] main.spr:7:12: Missing case: Category.Other
hint: Add 'case Category.Other:' (there is no default case)
1 error(s); run 'sprig explain <code>' for details on a diagnostic code.The compiler says at line 7, column 12 (where match is) which case is missing, and the hint gives the exact line to add. When you add a new case to Category later, every match that forgot to handle it is found like this.
24.11 Runtime failure: a bad amount
Static checking catches type errors, not "the text is shaped wrong". Write the amount in the Movie line as 45.5 and the program throws while parsing that line, caught by the outermost catch:
# An amount must be "units.two digits"; "45.5" has one digit, so parsing fails.
func parse_amount(text: String) -> Int throws Error:
let parts = text.split(".")
let units = parts.get(0).toIntOrNull()
if units == null or parts.size() > 2:
throw Error("not an amount: " + text)
if parts.size() == 1:
return units * 100
let cents = parts.get(1).toIntOrNull()
if cents == null or parts.get(1).length() != 2:
throw Error("not an amount: " + text)
return units * 100 + cents
try:
print(parse_amount("45.5"))
catch problem: Error:
print(problem.message)not an amount: 45.5parse_amount insists on exactly two digits after the decimal point, 45.5 has one, so throw Error("not an amount: " + text) runs. The message carries the offending original text, which is far more useful than a silent default.
Summary
variantdescribes a fixed set of categories;matchforces every case to be handled.- One record is a
classwithletfields; amounts are whole cents. divTruncand%do the cents conversion;throws Errorputs failure in the signature.- The map totalling pattern is: read, check for
null, then add. - A program deletes only the files it created;
try/finallyguarantees cleanup. To read your own file, replace the wholemainwith a read-only version. - For a static error read the code, the position and the hint; runtime error messages are yours to design well.
Exercises
Exercise 1 (easy). What does format_money print for 5 cents and 0 cents? Write a small program to check. Hint: remember the zero padding when rest < 10.
Answer
# Check two edges: 5 cents prints 0.05, 0 cents prints 0.00.
func format_money(cents: Int) -> String:
let units = cents.divTrunc(100)
let rest = cents % 100
if rest < 10:
return units + ".0" + rest
return units + "." + rest
print(format_money(5))
print(format_money(0))0.05
0.005 cents is 0.05 yuan, 0 cents is 0.00. divTrunc(100) gives 0, % gives 5, padded to ".05".
Exercise 2 (easy). What do category_of("fun") and category_of("transport") print after passing through label?
Answer
variant Category:
Food
Transport
Other
func category_of(name: String) -> Category:
if name == "food":
return Category.Food
if name == "transport":
return Category.Transport
return Category.Other
func label(category: Category) -> String:
return match category:
case Category.Food:
"Food"
case Category.Transport:
"Transport"
case Category.Other:
"Other"
# An unknown category name falls to Other.
print(label(category_of("fun")))
print(label(category_of("transport")))Other
Transportcategory_of returns Category.Other for the unknown "fun".
Exercise 3 (medium). Add one line to report so the report prints Records: 4 (the number of records) before the total. Hint: expenses.size() is an Int; when concatenating with +, the other side must be a String.
Answer
import "@std/files.spr" as files
import "@std/text.spr" as strings
variant Category:
Food
Transport
Other
class Expense:
let item: String
let cents: Int
let category: Category
func format_money(cents: Int) -> String:
let units = cents.divTrunc(100)
let rest = cents % 100
if rest < 10:
return units + ".0" + rest
return units + "." + rest
func parse_amount(text: String) -> Int throws Error:
let parts = text.split(".")
let units = parts.get(0).toIntOrNull()
if units == null or parts.size() > 2:
throw Error("not an amount: " + text)
if parts.size() == 1:
return units * 100
let cents = parts.get(1).toIntOrNull()
if cents == null or parts.get(1).length() != 2:
throw Error("not an amount: " + text)
return units * 100 + cents
func category_of(name: String) -> Category:
if name == "food":
return Category.Food
if name == "transport":
return Category.Transport
return Category.Other
func label(category: Category) -> String:
return match category:
case Category.Food:
"Food"
case Category.Transport:
"Transport"
case Category.Other:
"Other"
func parse_line(line: String) -> Expense throws Error:
let fields = line.split(",")
if fields.size() != 3:
throw Error("expected item, amount, category: " + line)
let item = strings.trim(fields.get(0))
let cents = parse_amount(strings.trim(fields.get(1)))
let category = category_of(strings.trim(fields.get(2)))
return Expense(item=item, cents=cents, category=category)
func load_file(path: String) -> MutableList[Expense] throws Error:
let expenses: MutableList[Expense] = []
for line in strings.lines(files.read_utf8(path)):
if strings.trim(line) != "":
expenses.append(parse_line(line))
return expenses
func report(expenses: List[Expense]) -> Unit:
let totals: MutableMap[String, Int] = {}
var sum = 0
for expense in expenses:
let name = label(expense.category)
let previous = totals[name]
if previous == null:
totals[name] = expense.cents
else:
totals[name] = previous + expense.cents
sum += expense.cents
for name in ["Food", "Transport", "Other"]:
let amount = totals[name]
if amount != null:
print(name + ": " + format_money(amount))
# The added line: number of records.
print("Records: " + expenses.size())
print("Total: " + format_money(sum))
func main() -> Unit throws Error:
let path = files.temp_file()
files.write_utf8(path, "Coffee, 12.50, food\nTaxi, 36.00, transport\nNoodles, 18.00, food\nMovie, 45.00, fun\n")
try:
report(load_file(path))
finally:
files.remove_file(path)
try:
main()
catch problem: Error:
print(problem.message)Food: 30.50
Transport: 36.00
Other: 45.00
Records: 4
Total: 111.50The added line is print("Records: " + expenses.size()), placed after the category totals and before the grand total.
Exercise 4 (harder). Change the program to read your own my-expenses.txt; write the new main and explain why changing only path is not enough.
Answer
func main() -> Unit throws Error:
report(load_file("my-expenses.txt"))Changing only path is not enough: the original main would run write_utf8 first, overwrite your file with the sample data, and then the remove_file in finally would delete it. When reading your own data, leave out temp_file(), write_utf8 and remove_file; only a file the program created itself is the program's to delete.
Previous chapter: 23. Tools and AI assistants.
To go deeper into the Java boundary: Appendix F. Java interop in depth.
Coming from another language?
If you reach for BigDecimal or Java double for money: whole cents is what many payment systems really do—no floating-point rounding surprises, and you own every carry rule. try / finally works as in Java, except a Sprig try may have only finally and no catch, which is exactly the "clean up either way" shape used here.
