Files, commands and timers
Apps need to do more than draw: save files, run tools, load data from the network, do something a few seconds from now, or crunch numbers without freezing the window. This page covers the built-in functions for that.
Some of them finish right away (the file functions). The others take a
callback, a block Tessel runs later, when the work is done. Callbacks always
run on the UI thread, between frames, so they can change state directly, and
the window updates afterwards:
app Weather(width: 360, height: 200) { state report = "Press Refresh"
Text(report) Button("Refresh") { report = "Loading…" fetch(url: "https://example.com/weather.txt") { text in report = text ?? "Could not load the weather" } }}While the download runs, the app stays responsive.
Every function on this page that ends with such a block can also be used
with await, which reads top to bottom instead of
nesting:
Button("Refresh") { report = "Loading…" let text = await fetch(url: "https://example.com/weather.txt") report = text ?? "Could not load the weather"}The two forms do the same thing. The examples below use blocks; see Waiting with async and await for the other.
The file functions work immediately and return a result you can check:
| Function | Returns | What it does |
|---|---|---|
readFile(path) | String? | The file’s text, or nil if it can’t be read. |
writeFile(path:text:) | Bool | Writes text to the file, replacing what was there. true if it worked. |
fileExists(path) | Bool | Whether a file or folder exists at path. |
isFolder(path) | Bool | Whether path is a folder. |
listFolder(path) | [String]? | The names of the files and folders inside, sorted; nil if the folder can’t be read. |
createFolder(path) | Bool | Creates a folder, and any missing folders above it. |
renameFile(from:to:) | Bool | Renames or moves a file or folder. |
deleteFile(path) | Bool | Deletes a file. It doesn’t delete folders. |
currentFolder() | String | The folder the program was started from. |
appendFile(path:text:) | Bool | Adds text to the end of the file. |
copyFile(from:to:) | Bool | Copies a file. |
fileSize(path) | Int? | The file’s size in bytes. |
modifiedTime(path) | Float? | When the file last changed. |
readData(path) | Data? | The file’s raw bytes, for files that aren’t text. |
readData(path, from:count:) | Data? | Up to count bytes, starting at byte from. Only those bytes are read. |
writeData(path:data:) | Bool | Writes raw bytes to the file. |
appendData(path:data:) | Bool | Adds raw bytes to the end of the file. |
Relative paths are relative to currentFolder(), the folder the program was
started from. That’s fine for tools, but an app started from the Finder or
the Start menu can’t count on it: keep its files in
appDataFolder("YourApp") or
documentsFolder(), and build paths
with joinPath.
To save structs, lists and other values rather than plain text, turn them
into JSON with toJson and read them back with fromJson; see
Saving data as JSON.
A simple notes app that loads its text when it starts and saves on request:
app Notes(width: 400, height: 240) { state text = "" state status = ""
VStack { TextField("Write something", text: text) HStack { Button("Save") { save() } Text(status).color(.secondary) } } .padding(16) .onAppear { text = readFile("notes.txt") ?? "" }
fn save() { status = if writeFile(path: "notes.txt", text: text) { "Saved" } else { "Couldn't save" } }}readFile and listFolder return optionals, because a missing file is
normal; use ?? or if let to handle it (see Optionals).
Listing a folder:
let names = listFolder(currentFolder()) ?? []for name in names { if !name.hasPrefix(".") { print(name) }}Reading part of a big file
Section titled “Reading part of a big file”readData(path, from:count:) reads only part of a file: up to count bytes,
starting at byte from. Only those bytes go into memory, so a program can
work through a file bigger than memory, such as a video or a disk image, a
piece at a time. Near the end you get fewer bytes, and at the end you get
none. This counts the zero bytes in a file, a megabyte at a time:
fn main() { let path = "disk.img" let size = fileSize(path) ?? 0 let piece = 1048576 var zeros = 0 var from = 0 while from < size { if let data = readData(path, from: from, count: piece) { zeros += data.bytes.filter { b in b == 0 }.count } from += piece } print("{zeros} of {size} bytes are zero")}In an app, do this in background work, which
can call readData like any other code.
The file functions work in any program, including one with fn main()
instead of an app.
Documents and custom file types
Section titled “Documents and custom file types”Many apps work on documents: the user saves their work to a file, and opens
it again later. openFile and saveFile show the system’s standard open and
save dialogs and give you the path the user picked, or nil if they
cancelled. You then read or write the file with readFile and writeFile.
This notes app saves each note in its own file, with the extension .note:
app Notes(width: 420, height: 220) { state title = "" state body = "" state status = "New note"
VStack(spacing: 8, alignment: .leading) { TextField("Title", text: title) TextField("Text", text: body) HStack { Button("Open…") { open() } Button("Save…") { save() } Text(status).color(.secondary) } } .padding(16)
fn save() { let text = "title={title}\nbody={body}\n" if let path = saveFile(title: "Save note", name: "{title}.note", types: ["note"]) { status = if writeFile(path: path, text: text) { "Saved" } else { "Couldn't save" } } }
fn open() { if let path = openFile(title: "Open note", types: ["note"]) { if let text = readFile(path) { for line in text.lines() { if line.hasPrefix("title=") { title = line.substring(from: 6, to: line.count) } else if line.hasPrefix("body=") { body = line.substring(from: 5, to: line.count) } } status = "Opened" } else { status = "Couldn't read the file" } } }}A few things to notice:
-
types: ["note"]makes the open dialog show only.notefiles, and makes the save dialog add.notewhen the user types a name without it. Write extensions without the dot. You can list several; the first one is the one added when saving. -
name:suggests a file name in the save dialog. -
If the user cancels, the dialog returns
nil, so theif letdoes nothing. -
The file format is up to you. Here each line is
key=value, which is easy to write with string interpolation and to read back withlines,hasPrefixandsubstring. A saved note looks like this:title=Groceriesbody=milk, eggsThis simple format holds one line per field, which is why the note’s text is a single-line
TextField.
The dialogs are for apps: call them from something the user does, like a button or a keyboard shortcut. In a headless test, no dialog opens; the test script says what each dialog returns instead. See File dialogs for the details.
Environment variables
Section titled “Environment variables”environment(name) returns an environment variable’s value, or nil if it
isn’t set:
let home = environment("HOME") ?? currentFolder()let tessel = environment("TESSEL_EXE") ?? "tessel"Running other programs
Section titled “Running other programs”runCommand starts another program and hands you its output line by line:
app Runner(width: 420, height: 300) { state output: [String] = [] state running: Int? = nil
HStack { Button("List files") { start() }.disabled(running != nil) Button("Stop") { stop() }.disabled(running == nil) } Scroll { VStack(spacing: 2, alignment: .leading) { for line in output { Text(line).font(size: 12) } } }
fn start() { output = [] running = runCommand(path: "ls", args: ["-1"], onOutput: { line in output.append(line) }) { code in output.append("Finished with exit code {code}") running = nil } }
fn stop() { if let id = running { stopCommand(id) } }}runCommand(path:args:onOutput:onExit:) takes:
path:the program to run. It’s started directly, not through a shell, so write the program and its arguments separately (no pipes or*patterns). A name without a folder, like"ls", is looked up in the system’sPATH.args:the arguments, as a list of strings. Optional.onOutput:called with each line the program prints, without the line break. Both normal output and error output arrive here.onExit:called with the program’s exit code once it has finished, after all of its output. By convention, 0 means success.
onExit is the last parameter, so it’s usually written as a trailing block.
Instead of blocks, you can also pass functions declared in the app:
Button("List files") { runCommand(path: "ls", onOutput: remember, onExit: finished)}
fn remember(_ line: String) { output.append(line)}
fn finished(_ code: Int) { output.append("Finished with exit code {code}")}The program runs in the background. It can’t read input from the user (its
standard input is empty). runCommand returns an Int id right away; pass it
to stopCommand(id) to stop the program. Its onExit still runs (on macOS,
with the exit code -1).
If the program can’t be started at all (for example, it doesn’t exist),
onOutput receives one line starting with error: can't start, and onExit
gets -1.
The Tessel IDE uses runCommand to run tessel check,
tessel build and your program, and shows their output in its console.
Downloading text with fetch
Section titled “Downloading text with fetch”fetch(url:done:) loads a URL in the background and calls done with the text,
or with nil if it failed:
fetch(url: "https://example.com/data.txt") { text in if let text = text { lines = text.lines() } else { status = "Download failed" }}It supports http:// and https:// URLs, and file:// for a local file.
Talking to a web server with request
Section titled “Talking to a web server with request”request(url:method:headers:body:done:) sends any HTTP request and gives
its block the whole response, an
HttpResponse:
struct Todo { title: String done: Bool = false}
app Todos(width: 360, height: 300) { state todos: [Todo] = [] state status = ""
VStack(spacing: 8, alignment: .leading) { Button("Load") { load() } Button("Add") { add("Buy milk") } Text(status).color(.secondary) for todo in todos { Text(todo.title) } } .padding(16)
fn load() { request(url: "https://example.com/api/todos") { response in if !response.ok { status = "Couldn't load (status {response.status})" } else if let loaded: [Todo] = fromJson(response.text) { todos = loaded } else { status = "The server sent something unexpected" } } }
fn add(_ title: String) { request(url: "https://example.com/api/todos", method: "POST", headers: ["Content-Type": "application/json"], body: toJson(Todo(title: title))) { response in status = if response.ok { "Added" } else { "Couldn't add: {response.status} {response.error}" } } }}Everything but url and the block is optional: method is "GET" unless
you say otherwise, and there are no extra headers and no body. The response
has:
status: the HTTP status code, like200or404, andok: whether it’s a success (200 to 299). An error status is still a response, so its body is there too, for the server’s explanation.textanddata: the body as text, and as bytes.headers: the response headers, with lower-case names.error: if the server couldn’t be reached at all, why. Thenstatusis0.finalUrl: the URL that answered.requestfollows redirects, so this can differ from the one you asked for. Resolve relative links in the answer against it.
request also reads file:// URLs. Like a web server, it honours a
Range header: headers: ["Range": "bytes=1000-1999"] gives status 206 and
only those bytes, and only they are read from the disk.
toJson and fromJson
turn your structs into the JSON that most web APIs use, and back.
Reading a body as it arrives
Section titled “Reading a body as it arrives”Some answers never end: internet radio, or a live feed. Others are big, and
you want to start on them before the end. Give request an onData: block,
and it gets the body in pieces, as Data, while it arrives. An onHeaders:
block gets the status and headers first, before any of the body:
app Radio(width: 300, height: 120) { state station = "" state received = 0 state playing: Int? = nil
VStack(spacing: 8) { Text("{station}: {received / 1024} KB") Button("Listen") { playing = request(url: "https://radio.example.com/stream", headers: ["Icy-MetaData": "1"], onHeaders: { r in station = r.headers["icy-name"] ?? "Radio" }, onData: { piece in received += piece.count }) { r in station = if r.error == "" { "Ended" } else { "Lost: {r.error}" } playing = nil } } Button("Stop") { if let id = playing { cancelRequest(id) playing = nil } } } .padding(16)}- The pieces come in order, on the UI thread, after
onHeadersand beforedone. - With
onData,donestill runs when the body ends, but itstextanddataare empty: the body went toonData, and isn’t kept. So an endless stream doesn’t fill up memory. - If your blocks fall behind, the pieces that wait are joined into one. Once about 1 MB waits, reading pauses until your app catches up.
cancelRequeststops a stream: no more pieces come, anddonedoesn’t run.
Downloading files
Section titled “Downloading files”download(url:to:progress:done:) saves a URL straight to a file, and can
report how far it has got:
app Downloader(width: 360, height: 160) { state progress = 0.0 state status = "Ready"
VStack(spacing: 8) { Text(status) Text("{Int(progress * 100.0)}%").font(size: 24) Button("Download") { status = "Downloading…" let file = joinPath(documentsFolder(), "tessel.zip") download(url: "https://example.com/tessel.zip", to: file, progress: { fraction in progress = fraction }) { ok in status = if ok { "Saved to {file}" } else { "Download failed" } } } } .padding(16)}progress is optional. It gets a fraction from 0.0 to 1.0 as the file
arrives (when the server says how big the file is). done gets whether it
worked. A failed download leaves no partial file behind.
download can also send headers:, like request, for a server that wants
a key or a cookie. An onHeaders: block gets the answer’s status and
headers (an HttpResponse with no body) before the file arrives:
download(url: "https://example.com/report.pdf", to: file, headers: ["Authorization": "Bearer {token}"], onHeaders: { r in size = r.headers["content-length"] ?? "?"}) { ok in status = if ok { "Saved" } else { "Download failed" }}Both request and download return an id. To give one up while it’s under
way (the user pressed Cancel, or left the page that needed it), pass the id to
cancelRequest. Its done block then
never runs, and a cancelled download leaves no file: its .part file is
gone as soon as cancelRequest returns.
WebSockets
Section titled “WebSockets”A WebSocket is a connection that stays open, so the server can send messages
at any time: for chat, live prices, or notifications.
openWebSocket(url:onMessage:onClose:) connects and returns an id;
sendWebSocket(id, text:) sends a message, and closeWebSocket(id) hangs
up:
app Chat(width: 360, height: 400) { state socket: Int? = nil state messages: [String] = [] state draft = ""
VStack(spacing: 8, alignment: .leading) { HStack { Button("Connect") { connect() }.disabled(socket != nil) Button("Disconnect") { disconnect() }.disabled(socket == nil) } for message in messages { Text(message) } TextField("Message", text: draft).onSubmit { if let id = socket { sendWebSocket(id, text: draft) draft = "" } } } .padding(16)
fn connect() { socket = openWebSocket(url: "wss://example.com/chat", onMessage: { text in messages.append(text) }) { reason in messages.append("Disconnected: {reason}") socket = nil } }
fn disconnect() { if let id = socket { closeWebSocket(id) } }}onMessage runs for each message from the server. onClose runs once when
the connection ends, for whatever reason: you closed it, the server did, or
it couldn’t connect in the first place. Messages are text; send JSON with
toJson to exchange structured data.
For servers that speak in bytes rather than text, give openWebSocket an
onData: block, which gets each binary message as Data, and send with
sendWebSocketData.
Sockets and servers
Section titled “Sockets and servers”For talking to things that aren’t web servers, and for being talked to,
there are sockets: connectTCP opens a
TCP connection to any program, listenTCP
accepts connections, openUDP sends and
receives packets (and joins multicast groups, to find other programs on
the local network), and serveHTTP makes
your app a web server: a page opened on a phone can drive it. They work
like WebSockets: an Int id, blocks that run on the UI thread, and an app
or fn main program that keeps running while one is open. See
Sockets and servers.
Running code later with after
Section titled “Running code later with after”after(seconds:action:) runs a block once, after a delay:
Button("Save") { save() showSaved = true after(seconds: 2) { showSaved = false }}The delay is a Float, so after(seconds: 0.5) { … } works. A timer made
with after can’t be cancelled once started. If it might no longer be wanted
when it fires, have the block check a state value first.
Repeating with every
Section titled “Repeating with every”every(seconds:action:) runs a block again and again, and returns an id
that stopTimer takes to stop it. A stopwatch:
app Stopwatch(width: 300, height: 180) { state tenths = 0 state timer: Int? = nil
VStack(spacing: 12) { Text("{tenths / 10}.{tenths % 10}").font(size: 40, weight: .bold) HStack { Button("Start") { start() }.disabled(timer != nil) Button("Stop") { stop() }.disabled(timer == nil) Button("Reset") { tenths = 0 } } } .padding(16)
fn start() { timer = every(seconds: 0.1) { tenths += 1 } }
fn stop() { if let id = timer { stopTimer(id) timer = nil } }}The first run is one interval after every is called. The block can also
stop its own timer, once it has done its job.
Heavy work in the background
Section titled “Heavy work in the background”Everything in an app’s blocks runs on the UI thread, the one that draws the
window. Something that takes a long time there, like a big calculation,
freezes the window until it’s done. background(work:done:) runs it on
another thread instead, and hands the result to a block back on the UI
thread:
fn primesBelow(limit: Int) -> [Int] { var sieve: [Bool] = [] for _ in 0..limit { sieve.append(true) } var primes: [Int] = [] for i in 2..limit { if sieve[i] { primes.append(i) for k in i..(limit - 1) / i + 1 { sieve[i * k] = false } } } primes}
app Primes(width: 360, height: 200) { state limit = 200000 state status = "Idle" state busy = false
VStack(spacing: 12) { Text(status) Button("Count") { busy = true status = "Counting…" let n = limit background(work: { primesBelow(limit: n) }) { primes in status = "{primes.count} primes below {n}" busy = false } } .disabled(busy) } .padding(24)}While the primes are counted, the window stays responsive. Then the block
after background gets the list, and like every callback, it can change
state: the window shows 17984 primes below 200000.
The work: block runs at the same time as the rest of the app, so it
mustn’t touch anything the app might be changing. Tessel makes this safe by
copying: work gets its own copies of the values it uses, and the block
after it gets a copy of the result. For that to work:
workcan’t usestate, bindings, fields of the app or view, or its functions (fns declared inside theapporview). Top-level functions likeprimesBeloware fine, and so are local values.- The values it uses, and its result, must be plain data that
toBinarycould save: numbers, strings, lists, dictionaries, your structs and enums, and so on, but not functions.
That’s why the example copies limit into let n first. Using limit
directly is an error:
error: background work can't use `limit`: `limit` is `state`, which the app keeps changing --> main.tsl:28:30 |28 | background(work: { primesBelow(limit: limit) }) { primes in | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | = help: copy what it needs first, like `let input = limit`, and use thatThe copy is made when background is called, so changing limit afterwards
doesn’t affect work that has already started.
The work: block ends with its result, like a function. It can be several
lines long, and return works in it too:
let points = shape.pointsbackground(work: { if points.isEmpty { return 0.0 } var total = 0.0 for p in points { total += p.x * p.y } total}) { area in result = area}Progress, and cancelling
Section titled “Progress, and cancelling”Work that takes a while should say how far it is, and let the user stop it.
Give the work: block a name for its job, work: { job in … }; then:
job.progress(fraction, note: "…")reports how far it is (usually from 0 to 1, with an optional note), to aprogress:block that runs on the UI thread and can changestate;job.isCancelled()says whether the job was cancelled, so the work can stop early;backgroundreturns the job (aBackgroundJob), whosecancel()cancels it.
fn countPrimes(limit: Int, job: BackgroundJob) -> Int { var count = 0 for n in 2..limit { if n % 1000 == 0 { if job.isCancelled() { return count } job.progress(Float(n) / Float(limit), note: "{count} so far") } var prime = true var d = 2 while d * d <= n { if n % d == 0 { prime = false break } d += 1 } if prime { count += 1 } } count}
app Primes(width: 360, height: 200) { state status = "Idle" state fraction = 0.0 state job: BackgroundJob? = nil
VStack(spacing: 12) { Text(status) Text("{(fraction * 100).formatted(decimals: 0)}%") HStack { Button("Count") { status = "Counting…" job = background(work: { job in countPrimes(limit: 2000000, job: job) }, progress: { f, note in fraction = f status = note }) { count in status = "{count} primes" job = nil } } .disabled(job != nil) Button("Cancel") { job?.cancel() job = nil status = "Cancelled" } .disabled(job == nil) } } .padding(24)}Reports can come much faster than the window can show them, so the
progress: block gets the latest one each time the app gets round to it,
skipping those in between; the last report always arrives before the result.
After cancel(), neither block runs again: the work sees isCancelled(),
stops, and what it returns is dropped. The job can be passed on to the
functions doing the work, like countPrimes here, and kept in state to
cancel it later.
Callbacks in a program without an app
Section titled “Callbacks in a program without an app”fetch, request, download, WebSockets, sockets, runCommand, after,
every and background also work in a program with fn main() and no
app. When main returns, the program doesn’t end right away: it keeps
running until no timers, requests, downloads, open WebSockets or sockets,
commands or background work are left, running their callbacks as they come
in, and then exits.
fn main() { after(seconds: 1) { print("one second later") } runCommand(path: "echo", args: ["hello"], onOutput: { line in print("echo printed: {line}") }) { code in print("echo finished with {code}") } print("main is done")}This prints:
main is doneecho printed: helloecho finished with 0one second laterA timer started with every keeps the program running until it’s stopped
with stopTimer, an open WebSocket, socket or listener until it’s closed,
and a request with onData until its body ends or it’s cancelled. To end the program
right away, call exit.
Testing code that waits
Section titled “Testing code that waits”When you test an app with a headless script, time doesn’t pass
by itself: the wait command moves the clock forward and fires the timers
that are due, including every timers. wait also first lets running
fetch, request, download, runCommand and background calls finish,
so tests don’t depend on how fast the machine is. A request with onData
may never end, so wait treats it like an open WebSocket or socket: it
lets pieces arrive for a moment (half a second, or as long as the wait) and
goes on. Use waitfor to wait for what the pieces bring about.