20. 标准库实用篇
程序不能只会算数和操作自己的数据,它还得和外面的世界打交道:读配置、存结果、解析别人发来的 JSON、算两个日期的间隔、在文本里找符合模式的部分。这些活不用自己写——随编译器一起发货的标准库里都有。
标准库是以 @std/ 开头的模块,和平常一样导入:import "@std/files.spr" as files。前面的章节里你已经用过其中一些:@std/text(第 4 章)、@std/lists(第 8 章)、@std/sets(第 9 章)、@std/process 和 @std/random(第 10 章)、@std/nulls(第 13 章)、@std/math(第 17 章)、@std/test(第 19 章)。
这一章补齐四组做真实程序离不开的模块:文件、JSON、日期和时间、正则。
这一章你会学到:
@std/files:读、写、原子替换、列目录、临时文件;每个失败都抛Error;@std/json和@std/json_codec:解析与生成 JSON,按名字和类型取字段,错误消息带着路径;@std/dates和@std/time:日期就是 ISO 文本,时间戳就是毫秒数;@std/regex:查找、替换、整体匹配、分组、切分。
20.1 文件:@std/files
为什么需要它:变量和列表活在内存里,程序一结束就没了。要留住结果、读别人的数据,就得写文件、读文件。
最小的例子在一个临时文件上走完整个来回:
# 临时文件里的读写:先随便写一版,再原子替换,最后读回来删掉。
import "@std/files.spr" as files
let path = files.temp_file()
files.write_utf8(path, "first draft\n")
files.atomic_write_utf8(path, "first\nsecond\n")
print(files.exists(path))
print(files.read_lines(path).size())
print(files.read_utf8(path).trim())
files.remove_file(path)
print(files.exists(path))true
3
first
second
false逐行读:
files.temp_file()在操作系统的临时目录里新建一个空文件,返回它的绝对路径。它不会被自动删除,用完了要自己remove_file。files.write_utf8(path, "first draft\n")把文本按 UTF-8 写进文件。文件已存在就原地覆盖——写到一半时,别的程序可能读到一个不完整的文件。files.atomic_write_utf8(path, "first\nsecond\n")也是写,但先写一个临时邻居,成功后再整体改名替换。读者要么看到旧内容,要么看到新内容,不会看到一半。要保证"别人随时来读都读到完整内容",就改用它。files.exists(path)打印true:文件在。files.read_lines(path)按行读回来,返回List[String],行尾的换行符被去掉。"first\nsecond\n"分成["first", "second", ""]:最后的换行符留下一个空行,所以.size()是3。files.read_utf8(path).trim()把整个文件读成一个字符串,trim()去掉末尾换行,打印first和second。files.remove_file(path)删除文件;删完再exists,得到false。
文件操作的失败是常态——路径不存在、权限不够、磁盘满了。@std/files 里会失败的操作(读、写、删、建目录、列目录……)签名里都写着 throws Error,失败时抛一个消息为 cannot 操作 文件: 原因 的 Error:
# 读一个不存在的文件:Error 的消息说清了是什么操作、哪个文件、为什么。
import "@std/files.spr" as files
try:
print(files.read_utf8("no-such-file.txt"))
catch problem: Error:
print(problem.message)cannot read no-such-file.txt: no such file用第 14 章的 try/catch 接住,problem.message 就是这行消息。读一个不存在的文件不会给你空字符串或者 null;"读不到"必须显式处理。
其他常用函数:is_file / is_directory 看路径是什么;make_directory 建目录(连同缺失的上级);copy_file 和 move 复制、移动(都不覆盖已有文件);file_name / parent / join / normalize / absolute 摆弄路径文本;list 和 walk 列目录;temp_file 拿临时文件。注意 files.parent(...) 可能没有父目录,它返回 String?。
列目录
想知道一个目录里有什么,用 list;要递归整个目录树,用 walk:
# 列目录:在系统临时目录里建一个自己的目录,list 排序列出,walk 递归列出,最后清掉文件。
import "@std/files.spr" as files
let anchor = files.temp_file()
let parent = files.parent(anchor)
if parent == null:
throw Error("no parent directory")
let dir = files.join(parent, "sprig-book-" + files.file_name(anchor))
files.remove_file(anchor)
files.make_directory(dir)
files.write_utf8(files.join(dir, "a.txt"), "one\n")
files.write_utf8(files.join(dir, "notes.txt"), "two\n")
print(files.list(dir).size())
for entry in files.walk(dir):
print(files.file_name(entry))
files.remove_file(files.join(dir, "a.txt"))
files.remove_file(files.join(dir, "notes.txt"))
print(files.list(dir).size())2
a.txt
notes.txt
0逐行读:
files.temp_file()先给一个临时文件;files.parent(anchor)取它所在的目录。parent的类型是String?,所以先if parent == null: throw,让后面的parent收窄成String(第 13 章)。files.join(parent, "sprig-book-" + files.file_name(anchor))用路径规则把目录和名字拼起来。目录名里带上临时文件的名字,每次运行都不重样。files.remove_file(anchor)把只用来取名字的小文件删掉。files.make_directory(dir)建出目录,然后往里写a.txt和notes.txt。files.list(dir)返回排好序的目录快照,元素是绝对路径。打印绝对路径会带上你机器上的目录名,不可移植,所以用file_name取出最后一段:a.txt、notes.txt。files.walk(dir)递归列出目录下所有文件的绝对路径。这个目录里只有两个文件,所以又是这两行;walk不列目录本身。- 最后删掉两个文件再数一次
list,得到0。
目录本身没有删——@std/files 只删文件,不删目录;它在操作系统的临时目录里,由系统清理。
故意写错:忘了写 throws
read_lines 会抛 Error,调用它的函数必须在签名上承认这一点,否则编译器拒绝:
# 函数里调用会抛错的文件操作,却忘了在签名上声明。
import "@std/files.spr" as files
func first_line(path: String) -> String:
return files.read_lines(path)[0]
print(first_line("no-such-file.txt"))SPR-FLOW-THROWS [FLOW] main.spr:5:12: Call may throw Error; declare 'throws Error' or handle it with try/catchSPR-FLOW-THROWS:第 5 行第 12 列调用了一个可能抛错的东西,而 first_line 既没声明 throws Error,也没用 try 包住调用。修法有两个:给 first_line 的签名加上 throws Error(它的调用者接着也要处理或声明),或者在调用处 try / catch。
学过其他语言?
- 没有文件句柄要开和关:这些函数一次读写整份文件,路径就是个
String。 - 失败既不是返回值(C 的
-1、Go 的err),也不是悄悄往外传播的异常:它抛Error,你必须处理或声明。 - 路径函数是纯文本运算:
join、normalize不碰磁盘,也不解析软链接。
20.2 JSON:@std/json 和 @std/json_codec
程序之间交换数据最常用的文本格式是 JSON。标准库把它拆成两层:@std/json 管"JSON 文本 ↔ JSON 值",@std/json_codec 管"从 JSON 值里按名字和类型取字段"。
# 解析一段 JSON,读类型化字段,再打印回紧凑 JSON。
import "@std/json.spr" as json
import "@std/json_codec.spr" as codec
let doc = "{\"name\": \"sprig\", \"stars\": 12, \"tags\": [\"small\", \"typed\"]}"
let root = codec.root(json.parse(doc))
print(codec.required_string(root, "name"))
print(codec.required_int(root, "stars"))
print(codec.required_string_array(root, "tags"))
print(codec.optional_string(root, "license"))
print(json.stringify(json.parse(doc)))sprig
12
[small, typed]
null
{"name":"sprig","stars":12,"tags":["small","typed"]}逐行读:
json.parse(doc)把文本解析成一个json.Value。JSON 的每种东西对应一个 case:Null、Boolean、Number、Text、Array、Object。数字保存的是原始文本(Number(text: String)),不会先转成Float丢精度;对象里重复的键会被拒绝,不是"最后一个赢"。codec.root(...)要求文档本身就是个对象,返回一个带着路径的 reader,根路径是$。文档是数组时用codec.root_array,元素路径是$[0]、$[1]……codec.required_string(root, "name")取name字段,要求它是字符串,打印sprig;required_int(root, "stars")取整数,打印12。codec.required_string_array(root, "tags")取字符串数组;列表打印成[small, typed]。codec.optional_string(root, "license")取可有可无的字段:缺失或为 JSONnull时返回String?的null,这里打印null。json.stringify(json.parse(doc))把值写回紧凑 JSON,没有任何多余空格;stringify也会检查手工拼出来的对象有没有重复的键。
字段缺失、是 null、或者类型不对,required_* 都抛 Error,消息里带着字段在文档里的路径:
# 字段不是期望的类型:Error 的消息带着它在文档里的路径。
import "@std/json.spr" as json
import "@std/json_codec.spr" as codec
let root = codec.root(json.parse("{\"stars\": \"12\"}"))
try:
print(codec.required_int(root, "stars"))
catch problem: Error:
print(problem.message)$.stars: expected integer, found string$.stars 是路径,expected integer, found string 说清两边。注意 "integer" 比"数字"严格:JSON 的 12.0 和 1e3 都是数字,但不是整数,required_int 会拒绝;这种情况用 required_number_text(原文)或 required_decimal(精确小数)。
json_codec 的取字段函数是成对的:required_* 要求字段在且类型对,optional_* 允许缺失(结果是 T?),as_* 给数组元素这类"已经拿到值"的场景。要拒绝不认识的字段(读配置时很有用),用 reject_unknown_fields(root, ["name", "stars"])。
故意写错:optional 的结果不能当普通值用
optional_int 找不到字段时返回 null,类型是 Int?,不能直接赋给 Int:
# optional_int 的结果是 Int?,不能直接当 Int 用。
import "@std/json.spr" as json
import "@std/json_codec.spr" as codec
let root = codec.root(json.parse("{}"))
let stars: Int = codec.optional_int(root, "stars")
print(stars)SPR-TYPE-NULLABLE [TYPE] main.spr:6:18: Nullable value is not assignable to Int (initializer); check for null first (expected Int, actual Int?)修法还是第 13 章那套:先判 null,或者用 nulls.or_else / nulls.require。别为了过编译随手改成 required_int——"可以没有"和"必须有"是不同的意思,读代码的人靠这个区分。
学过其他语言?
- 数字不经过
Double:Value.Number保存原文,required_decimal给你精确的Decimal。这是给金额准备的。 - 取值不是"先拿
Any再强转":required_int在类型层面保证结果就是Int,失败抛错。 - 想处理任意形状的 JSON,可以
matchjson.Value的 case(第 12 章);形状固定就用 codec。 - 构造 JSON 用
codec.text/int/number/bool/member/object/array拼,再json.stringify;不要手拼字符串。
20.3 日期和时间:@std/dates 和 @std/time
记录什么时候创建的、算还有几天到期、比较先后——都要日期。Sprig 不发明新的日期类型:日期就是一个 ISO 文本,例如 2026-10-05;时间戳是一个 Int,表示 1970-01-01T00:00:00Z 以来经过的毫秒数,也可以转成带时区的 ISO-8601 文本。
# 日期用 ISO 文本表示;时间用 1970 年以来的毫秒数或 ISO UTC 文本。
import "@std/dates.spr" as dates
import "@std/time.spr" as time
let start = dates.parse("2026-10-05")
print(start)
print(dates.plus_days(start, 10))
print(dates.days_between(start, "2026-10-19"))
print(dates.day_of_week(start))
print(dates.is_valid("2026-02-30"))
print(time.format_utc(0))
print(time.format_utc(1500))
print(time.parse_utc("2026-10-08T17:15:30+08:00"))2026-10-05
2026-10-15
14
1
false
1970-01-01T00:00:00Z
1970-01-01T00:00:01.500Z
1791450930000逐行读:
dates.parse("2026-10-05")检查文本是不是真实存在的日历日期(ISO 形式),返回它,打印2026-10-05。dates.plus_days(start, 10):10 天以后,2026-10-15;第二个参数给负数就往回走。dates.days_between(start, "2026-10-19"):从第一个日期到第二个相差14天;第二个更早会得到负数。dates.day_of_week(start):1是星期一,7是星期日。2026-10-05 是星期一。dates.is_valid("2026-02-30"):二月没有 30 日,返回false。is_valid只回答"是不是合法日期",不抛错。time.format_utc(0):毫秒0就是1970-01-01T00:00:00Z;1500是同一时刻 1.5 秒后,打印1970-01-01T00:00:01.500Z。time.parse_utc("2026-10-08T17:15:30+08:00"):带时区的文本换成毫秒数1791450930000。+08:00是东八区,同一瞬间在 UTC 是 09:15:30。
@std/dates 还有 today_utc()(今天)、year / month / day。@std/time 还有 utc_now()(现在)、epoch_millis()(现在的毫秒数)、sleep(毫秒)(暂停)、monotonic_nanos()(只用来量经过的时间,不受系统时钟调整影响)。
parse 不做猜测:不合法的日期在运行时抛错,而不是悄悄给你一个别的日期。
# 2 月 30 日不是真实日期:parse 在运行时拒绝它。
import "@std/dates.spr" as dates
try:
print(dates.parse("2026-02-30"))
catch problem: Error:
print(problem.message)not a date: 2026-02-30故意写错:天数不是文本
plus_days 的第二个参数是 Int。用 "3" 表示三天,编译器直接拒绝:
# plus_days 的第二个参数是天数(Int),不是文本。
import "@std/dates.spr" as dates
print(dates.plus_days("2026-01-01", "3"))SPR-TYPE-MISMATCH [TYPE] main.spr:4:37: Type mismatch in argument 2 of plus_days (expected Int, actual String)SPR-TYPE-MISMATCH 说清是第几个参数、期望什么、给了什么。Sprig 不会把文本自动变成数字;真要解析用户输入,用第 4 章的 "3".toIntOrNull()。
学过其他语言?
- 没有日期对象:日期就是
String,dates的函数就是纯函数。ISO 文本按字典序比较就等于按时间先后比较,"2026-10-05" < "2026-10-06"是true。 dates是"日历日",time是"时刻"。没有时区数据库、没有时长类型、没有格式化模式串。- 要更复杂的日期运算(时区、周期、格式化),第 21 章起直接调用 Java 的
java.time。
20.4 正则:@std/regex
文本里常常要"找像电话号码的一段""把所有数字换成 #""检查整个字符串符不符合格式"。正则表达式就是描述这种模式的迷你语言。
# 正则:找、替换、整体匹配、分组、切分。
import "@std/regex.spr" as regex
let text = "a1 b22 c333"
print(regex.find_all("[a-z][0-9]+", text))
print(regex.replace_all("[0-9]+", text, "#"))
print(regex.matches("[a-z][0-9]+( [a-z][0-9]+)*", text))
print(regex.find_groups("([a-z])([0-9]+)", text))
print(regex.split("\\s+", text))
print(regex.find("z+", text) == null)[a1, b22, c333]
a# b# c#
true
[a, 1]
[a1, b22, c333]
true逐行读:
regex.find_all("[a-z][0-9]+", text):找"一个小写字母后跟一串数字"的片段,按出现顺序返回所有匹配,打印[a1, b22, c333]。regex.replace_all("[0-9]+", text, "#"):每一段数字整体换成#,得到a# b# c#。regex.matches(...):问"整段文本是不是恰好符合模式",是就true。和find_all的区别是它要求从头到尾匹配。regex.find_groups("([a-z])([0-9]+)", text):括号是捕获组;返回第一个匹配里的各组[a, 1]。没匹配时返回null,组没参与匹配的位置是null。所有匹配的所有组用find_all_groups。regex.split("\\s+", text):按空白切开,得到[a1, b22, c333]。模式里的\\s:\\是字符串转义(第 4 章),正则引擎收到的是\s。regex.find("z+", text):找"一个或多个 z";文本里没有,返回null,== null打印true。
故意写错:find 的结果不能直接当 String 用
# find 可能找不到,返回 String?,不能直接当 String 用。
import "@std/regex.spr" as regex
let first: String = regex.find("[0-9]+", "abc")
print(first)SPR-TYPE-NULLABLE [TYPE] main.spr:4:21: Nullable value is not assignable to String (initializer); check for null first (expected String, actual String?)SPR-TYPE-NULLABLE 又一次出现:find 可能找不到,结果是 String?。要么先判 null,要么换用 find_all——找不到时它是空列表,不是 null。
学过其他语言?
- 模式语法就是 Java 的
java.util.regex:\d、\w、(?<name>...)、量词都一样。 - "没找到"不是异常也不是空串,而是
String?,编译器逼你处理。 - 每次调用都会重新编译模式;放在循环里之前先想想。要复用编译结果,可以先用 Java 的
Pattern(第 21 章)。
本章小结
- 标准库用
@std/名字.spr导入,不需要声明依赖。 @std/files:read_utf8/read_lines读,write_utf8写,atomic_write_utf8原子替换,list/walk列目录,temp_file临时文件;失败抛Error,函数里调用要声明throws。@std/json管文本和值;@std/json_codec的required_*/optional_*按类型取字段,错误带$路径;optional_*的结果是T?。- 日期是 ISO 文本,时间戳是毫秒;
dates.parse/plus_days/days_between/is_valid/day_of_week,time.format_utc/parse_utc/utc_now/sleep。 @std/regex:find(String?)、find_all、replace_all、matches(整段)、find_groups、split。
动手练习
练习 1:找出所有数字
从文本 "I have 3 cats, 12 dogs and 1 fish" 里找出所有数字,打印这个列表和数字的个数。
提示:[0-9]+ 表示"一个或多个数字";find_all 返回 List[String],列表有 .size()。
参考答案
# 练习 1:找出文本里所有的数字。
import "@std/regex.spr" as regex
let text = "I have 3 cats, 12 dogs and 1 fish"
let numbers = regex.find_all("[0-9]+", text)
print(numbers)
print(numbers.size())[3, 12, 1]
3练习 2:把 JSON 数组里的金额加起来
下面这段 JSON 是一个数组,每条有一个 amount。把所有 amount 加起来并打印总和。
[{"amount": 12}, {"amount": 30}, {"amount": 5}]提示:codec.root_array(...) 给每个元素一个 reader,codec.required_int(row, "amount") 取整数。
参考答案
# 练习 2:把 JSON 数组里每条的 amount 加起来。
import "@std/json.spr" as json
import "@std/json_codec.spr" as codec
let text = "[{\"amount\": 12}, {\"amount\": 30}, {\"amount\": 5}]"
var total = 0
for row in codec.root_array(json.parse(text)):
total += codec.required_int(row, "amount")
print(total)47练习 3:日期加减
从 "2026-10-08" 出发,打印 30 天后的日期,以及到年底("2026-12-31")还有多少天。
提示:plus_days(date, 天数) 和 days_between(start, end) 都直接收 ISO 文本。
参考答案
# 练习 3:算 30 天后的日期和到年底的天数。
import "@std/dates.spr" as dates
let start = "2026-10-08"
print(dates.plus_days(start, 30))
print(dates.days_between(start, "2026-12-31"))2026-11-07
84练习 4:读回带空行的文件
把 "one\n\ntwo\n" 写进一个临时文件,再按行读回来:打印行数,并判断第二行是不是空行。最后删掉文件。
提示:write_utf8 里写 \n 就是换行;read_lines 的元素不带换行符。注意末尾那个换行符也会产生一个空行。
参考答案
# 练习 4:写一个带空行的临时文件,数数读回来有几行、第二个是不是空行。
import "@std/files.spr" as files
let path = files.temp_file()
files.write_utf8(path, "one\n\ntwo\n")
let lines = files.read_lines(path)
print(lines.size())
print(lines[1] == "")
files.remove_file(path)4
true下一章:调用 Java。
