Files, processes and time

This chapter is a tour of the modules that talk to the operating system: std.fs for files and folders, std.os for the environment, std.process for other programs and std.time for clocks and dates. They work in the same way on Windows and on Linux, and they report errors with exceptions.

#Files

import std.fs

i32 main() {
    fs.createFolders("data/logs")
    fs.writeText("data/notes.txt", "first line\n")
    fs.appendText("data/notes.txt", "second line\n")

    string text = fs.readText("data/notes.txt")
    for (string line in text.trimEnd().split("\n")) {
        println("> {}", line)
    }
    println("{} bytes", fs.size("data/notes.txt"))

    fs.copy("data/notes.txt", "data/copy.txt")
    fs.rename("data/copy.txt", "data/old.txt")
    println("{} {}", fs.isFile("data/old.txt"), fs.isFolder("data/logs"))

    fs.removeAll("data")
    println("{}", fs.exists("data"))
    ret 0
}

> first line
> second line
23 bytes
true true
false

A file that cannot be read or written is an exception, with a message that says which and why:

import std.fs

i32 main() {
    try {
        string text = fs.readText("missing.txt")
    } catch (Exception e) {
        println("{}", e.message())
    }
    ret 0
}

cannot read 'missing.txt': no such file or folder

#The environment

std.os gives the name of the system, "windows" or "linux", the variables of the environment and the current folder; os.exit(code) ends the program at once. The arguments of the program arrive in main:

import std.os

i32 main(list<string> args) {
    for (i64 i = 1; i < args.len(); i++) {
        println("argument {}: {}", i, args[i])
    }
    if (os.hasEnv("CROMO_GUIDE_EXAMPLE")) {
        println("{}", os.env("CROMO_GUIDE_EXAMPLE"))
    }
    ret 0
}

argument 1: alpha
argument 2: beta

args[0] is the name of the program, as in C.

#Other programs

process.run runs a program, waits for it, and gives its exit code, its output and its errors:

import std.process

i32 main() {
    process.Output result = process.run("git", ["status", "--short"])
    if (result.code != 0) {
        eprintln("git failed: {}", result.err)
        ret 1
    }
    print("{}", result.out)
    ret 0
}

The program is looked for in the folders of the PATH, and the arguments are passed as they are, without a shell that interprets them. An exit code other than 0 is a value to check; a program that cannot start is an exception.

process.start starts a program without waiting, and gives a process.Process to talk with it: write and closeInput for its standard input, read and readAll for its output, wait for its end and kill to stop it.

#Time

import std.time

i32 main() {
    time.Instant start = time.now()
    time.msleep(50)
    time.Duration waited = start.elapsed()
    println("at least 50 ms: {}", waited.milliseconds() >= 50)

    time.DateTime now = time.utcNow()
    println("the year has four digits: {}", now.year >= 1000)
    ret 0
}

at least 50 ms: true
the year has four digits: true

• time.now() reads a clock that only goes forward, for measuring; elapsed() and since() give a Duration, with seconds(), milliseconds(), microseconds() and the field nanoseconds.
• utcNow() and localNow() give a DateTime, with its fields from the year to the nanosecond, the offset from UTC in minutes, and text() in the format of ISO 8601: 2026-10-30T18:21:33+01:00.
• sleep, msleep and usleep pause; in a task, the thread runs other tasks meanwhile.

#Summary

• std.fs reads and writes files and folders; errors are exceptions with a clear message.
• std.os gives the environment; the arguments arrive in main(list<string> args).
• std.process runs other programs, without a shell.
• std.time measures durations and gives the date and time.