Skip to content

Input & Output

A program talks to the world outside it through std::io and std::process. It prints to standard output, reports problems on standard error, reads standard input, reads its arguments and environment, and runs other programs. When it ends, its exit status tells the shell whether it worked. Reading and writing files is the Files chapter, and HTTP covers sending requests and serving them.

io.print writes a value and a newline, io.write writes it with no newline, and io.inspect writes it the way dbg shows values, as Nomi code:

import std::io

fn main()
    io.print("hello")
    io.write("no newline, ")
    io.write("so this continues the line\n")
    io.inspect({name: "Ada", langs: ["en", "fr"]})
    io.print((1, "x"))
end

io.print and io.write take any value whose type has Display, and io.inspect takes any value at all. The last line shows the difference: a string inside a tuple prints as its text through Display, and as "x" through Debug.

A program’s output often goes to another program or a file. Warnings and failures go to standard error instead, so they still reach the person at the terminal. io.eprint and io.ewrite are io.print and io.write for standard error.

A function that leaves the choice of stream to its caller takes a Writer. io.stdout, io.stderr and io.stdin are the three standard streams as values. Writer.print and Writer.write return a Result, because a stream can fail, for example when the program reading it has stopped:

import std::io.{self, Error, Writer}

/// Write a report to whichever stream the caller picks.
fn report(to: Writer, count: Int) -> Result<Unit, Error>
    to |> Writer.print("${count} items")
end

fn main() -> Result<Unit, Error>
    report(io.stdout, 3)?
    report(io.stderr, 0)?
    Ok(Unit)
end

In a terminal both lines appear, but nomi run report.nomi > /dev/null shows only the second. This page shows both streams in one box.

A test checks what such a function writes with Writer.collect(fn w -> report(w, 3)), which hands it a writer into memory and returns a pair: what the function returned, and the bytes it wrote.

io.read_line reads one line of standard input, without its newline. It returns Ok(Some(line)), Ok(None) when the input has ended, or an Err when reading fails. A loop over the input stops at None:

import std::io

// The lines of standard input that are not blank, until it ends.
fn count_lines(count: Int) -> Result<Int, io.Error>
    case io.read_line()?
        Some("") -> count_lines(count)
        Some(_)  -> count_lines(count + 1)
        None     -> Ok(count)
    end
end

fn main()
    run = io.capture("milk\n\neggs\nbread\n", fn -> count_lines(0))
    dbg run.value
end

A page has no keyboard, so main hands count_lines its input with io.capture, as a test does. Run with nomi run, count_lines(0) would read what you type, or a file sent with nomi run count.nomi < list.txt.

A program reads its command-line arguments and environment variables in boot, from its Startup: startup.args is a List<String>, and startup.env is a Map<String, String>. boot keeps what the program needs in its app struct:

import std::io

struct App
    args: List<String>
end

fn boot(startup: Startup) -> Result<App, String>
    Ok(App{args: startup.args})
end

fn main()
    io.print("${Iter.count(App.args)} arguments: ${String.join(App.args, ", ")}")
end

nomi run args.nomi a b prints 2 arguments: a, b. Only boot sees Startup, so the rest of the program reads the environment through the app struct, and a test can give it different arguments on its group’s boot line.

A program that returns from main exits with status 0. One whose main returns an Err prints error: and the error, and exits with status 1, as Pattern Matching shows.

To exit with another status, return Exit from std::process. Its message is printed to standard error as it is, with no error: before it, and its code is the exit status:

import
    std::io
    std::process.Exit
end

fn main() -> Result<Unit, Exit>
    io.eprint("checking the arguments")
    Err(Exit{code: 2, message: "usage: count <file>"})
end

In a terminal, this prints its two lines to standard error and exits with status 2. The page shows the status under them. code defaults to 1 and message to "", which prints nothing. code is an ExitCode, 0 to 255, so Exit{code: 300} does not compile; check a computed code with ExitCode.try_from. A boot that returns an Exit ends the program the same way, before main runs.

There is no function that exits on the spot. Returning an Exit, through ? from deep in the program if needed, ends the program as returning from main does: deferred calls run and supervised tasks finish first.

A program runs another, such as git or a formatter, with a Command: the program’s name and its arguments. No shell reads them, so "a b" reaches the program as one argument and * is not expanded. process.output runs the command to its end and returns an Output: its status, and the bytes it wrote to stdout and stderr.

A program that runs and fails is not an error. Its exit code is in the status, and Status.is_success says whether it was 0. An Err means the program could not be started at all, such as NotFound when nothing on the PATH has its name:

import
    std::io
    std::process.{self, Command, Status}
    std::process::testing.{self, Answer}
end

/// The current git branch, or `None` when git fails, as it does outside a
/// repository.
fn current_branch() -> Result<Maybe<String>, io.Error>
    command = Command{program: "git", args: ["branch", "--show-current"]}
    out = process.output(command)?

    if Status.is_success(out.status) then
        Ok(Some(String.trim(Bytes.to_string(out.stdout)!)))
    else
        Ok(None)
    end
end

fn main()
    in_repo = testing.run([Answer{program: "git", stdout: "main\n"}], current_branch)
    dbg in_repo.value

    outside = testing.run(
        [Answer{program: "git", code: 128, stderr: "fatal: not a git repository\n"}],
        current_branch,
    )

    dbg outside.value
end

The page cannot start programs, so main runs current_branch under std::process::testing, which responds to each command from a list of Answers instead of starting it, as a test does. For the same reason, nomi build refuses to build a program that starts others for WebAssembly.

Two other functions run a command. process.run lets the program write straight to your program’s own output and returns only its status, as a build step would. process.spawn(command) starts the program and returns it as a Child, whose input you write and whose output you read as it goes. defer Child.kill(child) on the next line kills it if it is still running when the function ends.

Concurrency is next. It runs several tasks at once.