Skip to content

Files and folders

A file(p) endpoint names one file by a path written in the program. The io.fs module lists what a folder holds, so a program finds its files first and then reads them. A program imports it, import io.fs, and reaches it as fs, or binds its functions, from io.fs import *.

The programs on this page list a small tree in the file-system examples:

examples/fs/tree/
  assets/logo.txt        5 bytes
  assets/style.css      19 bytes
  data/2026/q1.csv      21 bytes
  data/2026-notes.md    17 bytes
  data/birds.csv        28 bytes

A path

A Path is a place in a file system, written as text: segments separated by /. It is part of io, so it needs no import. Its operations read the text and never the file system, so they are pure:

p = Path("examples/fs/tree").join("data").join("birds.csv")
[p.text, p.name(), p.stem(), p.extension() | unwrap_or("?"), p.parent() | map(q => q.text) | unwrap_or("?")]
["examples/fs/tree/data/birds.csv", "birds.csv", "birds", "csv", "examples/fs/tree/data"]

parent() is none for a path of one segment, and extension() is none for a last segment with no .:

Path("data").parent()
none

Paths are ordered by their segments, compared in turn, each by its text. 2026/q1.csv sorts before 2026-notes.md, although - sorts before / as text, since the first segments 2026 and 2026-notes.md already differ:

[Path("data/2026-notes.md"), Path("data/2026/q1.csv")] | sort | map(p => p.text)
["data/2026/q1.csv", "data/2026-notes.md"]

This is the order of a sorted walk, and every listing below gives it.

A folder

folder(path) is the Folder at a path, a String or a Path. A folder is an endpoint that holds files and folders, as a database holds tables. Constructing one opens, stats and resolves nothing, and a relative path resolves as a file's does (where a relative path resolves):

from io.fs import *

folder("examples/fs/tree")
Folder(path = Path(text = "examples/fs/tree"))

io.fs is not in the prelude. Without the import, folder is an unknown name, reported before the program runs:

folder("examples/fs/tree")
check error[unknown-name]: `folder` is declared in the module `io.fs`: write `from io.fs import folder`
 --> <expression>:1:1
  |
1 | folder("examples/fs/tree")
  | ^^^^^^^^^^^^^^^^^^^^^^^^^^

A folder is not a Seq itself. Three effectful steps list it, each reading the file system once, where it is written, and each giving a Seq<Entry>. entries gives what is directly in the folder, sorted by name, an entry whose name opens with . included:

from io.fs import *

folder("examples/fs/tree/data") | entries | map(e => [e.name, e.kind])
[["2026", "folder"], ["2026-notes.md", "file"], ["birds.csv", "file"]]

walk gives every entry below the folder, the folder itself excluded: depth first, each folder's entries sorted by name, and each folder followed at once by what it holds:

from io.fs import *

folder("examples/fs/tree") | walk | map(e => e.path.text.trim_prefix("examples/fs/tree/"))
["assets", "assets/logo.txt", "assets/style.css", "data", "data/2026", "data/2026/q1.csv", "data/2026-notes.md", "data/birds.csv"]

The order is never the file system's: the same tree walks the same way on every machine. It is also the order a vault reads its cards in; the vault skips entries whose name opens with ., and walk lists them.

An entry

An Entry is one thing a folder holds. It has five fields:

Field Type What it holds
path Path the listed folder's path joined with the entry's path below it
name String the last segment
kind String "file", "folder" or "link"
size Int, optional a file's length in bytes; absent for a folder or a link
modified Instant, optional the time the entry was last modified, a link's own and not its target's; absent where the platform records none
from io.fs import *

folder("examples/fs/tree")
| walk
| filter(e => e.name == "birds.csv")
| map(e => [e.path.text, e.kind, str(e.size)])
[["examples/fs/tree/data/birds.csv", "file", "28"]]

modified is an Instant, so it compares with an instant the program writes and sorts the entries by time. A listing reads it once, with the rest of the entry, so the files changed since a cut-off are a filter over it:

from io.fs import *

cutoff = Instant("2020-01-01T00:00:00Z")
folder("examples/fs/tree/data")
| entries
| filter(e => e.modified | map(t => t >= cutoff) | unwrap_or(false))
| map(e => e.name)
["2026", "2026-notes.md", "birds.csv"]

The times themselves are the file system's, so they differ from one checkout of a tree to the next; a program that must give the same answer on every machine does not read them.

size is optional, so a sum over it states what a folder counts as:

from io.fs import *

folder("examples/fs/tree")
| walk
| filter(e => e.kind == "file")
| map(e => e.size | unwrap_or(0))
| sum
90

A link is reported with the kind "link" and not followed.

A glob

A Glob is a pattern over paths, matched against a path relative to the folder it is applied to. * matches within one segment, ** any number of whole segments, none included, ? one character other than /, [abc] one character of the set and [a-z] one of the range. matches reads the text and never the file system:

from io.fs import *

[
    Glob("data/*.csv").matches(Path("data/birds.csv")),
    Glob("data/*.csv").matches(Path("data/2026/q1.csv")),
    Glob("data/**/*.csv").matches(Path("data/2026/q1.csv")),
]
[true, false, true]

The glob step gives the entries of walk whose path below the folder matches, in walk order:

from io.fs import *

folder("examples/fs/tree") | glob(Glob("**/*.csv")) | map(e => e.path.text)
["examples/fs/tree/data/2026/q1.csv", "examples/fs/tree/data/birds.csv"]

A pattern that does not parse, an unclosed [ or a ** that is not a whole segment, is an evaluation error where Glob constructs it:

from io.fs import *

Glob("data/a**.csv")
execute failure[invalid-argument]: "data/a**.csv" is not a glob: `**` stands for whole segments, alone between `/`
 --> <expression>:3:1
  |
3 | Glob("data/a**.csv")
  | ^^^^^^^^^^^^^^^^^^^^

Reading what was found

An entry's path is one file reads as written, so a listing feeds source (reading with source). Every row of every CSV file directly in data/:

from io.fs import *

folder("examples/fs/tree/data")
| glob(Glob("*.csv"))
| flat_map(e => source(file(e.path), Csv))
[{count: "2", species: "heron"}, {count: "1", species: "owl"}]

A path that may not be there

Listing a folder that does not exist, or is not a folder, is an evaluation error naming its path:

from io.fs import *

folder("examples/fs/nowhere") | entries
execute failure[io-failure]: examples/fs/nowhere: no folder is there
 --> <expression>:3:33
  |
3 | folder("examples/fs/nowhere") | entries
  |                                 ^^^^^^^

exists and entry test a path without an error. exists is false where nothing is there, and entry is some(Entry) or none:

import io.fs

[
    str(Path("examples/fs/tree/data").exists()),
    str(Path("examples/fs/tree/missing").exists()),
    Path("examples/fs/tree/data").entry() | map(e => e.kind) | unwrap_or("?"),
    str(Path("examples/fs/tree/missing.csv").entry()),
]
["true", "false", "folder", "none"]

What a host grants

entries, walk, glob, exists and entry are effectful, and hql check reports a function that uses one:

from io.fs import *

fn csv_files() : Seq<Entry> = folder("examples/fs/tree") | glob(Glob("**/*.csv"))
csv_files() | size
csv_files is Effectful: it uses `glob`
Int

A listing is granted exactly where reading a file at the same path is (effects and what a host allows): anywhere under hql eval, hql run and the REPL, and under hql render only below the document's own directory. The reference states each operation of io.fs.