Standard library · Basics

io

Reading from the keyboard, reading and writing files, and writing to standard error.

import io

Most programs have to read something and write something. The io package holds the simplest ways to do it: read one line from the user, read or write a whole file in one go, or work through an open file piece by piece.

The functions that take a file name, such as ReadFile, open and close the file themselves. The functions that take a File* work on a file you opened yourself with os.Open; remember to close it with Close.

Use io for the everyday jobs. For checking whether a path exists, listing folders, deleting or renaming files, go to fs; for building paths, fs.path; for formatted output, fmt.

Things that catch people out:

  • A missing file is not an error here. ReadFile returns an empty string, and Lines returns a vector with one empty string in it, so an empty file and a missing one look the same. When the difference matters, check first with os.Exists.
  • Lines are split on \n only. A file saved with Windows line endings keeps a \r at the end of each line from Lines and Readline; trim the line before comparing it.
  • Sizes are counted in bytes, not characters. Outside ASCII one character takes several bytes, so reading a file in chunks can split a character across two chunks.
  • The text functions work on str, which ends at the first zero byte. Binary files such as images are cut short there, so keep this package for text.

Reading a settings file

A small key = value file is the most common thing a program reads at start up. Lines gives you the file as a vector of lines, so the loop only has to skip blank lines and comments and cut each line at the first =. Warnings about bad lines go to standard error with EPrintln, so they never mix with the program's real output.

io-guide-config.salam
import io
import str

func main:
    io.WriteFile("app.conf", "# server settings\nport = 8080\n\nhost = localhost\nworkers = 4\n")
    mut settings := HashMap {} as HashMap<str, str>
    defer settings.Free()
    lines := io.Lines("app.conf")
    defer lines.Free()
    each line in lines:
        if line == "" or str.StartsWith(line, "#"):
            continue
        end
        eq_at := str.IndexOf(line, "=")
        if eq_at < 0:
            io.EPrintln("skipping a line without '=': " + line)
            continue
        end
        key := str.Trim(str.Substr(line, 0, eq_at))
        value := str.Trim(str.Substr(line, eq_at + 1, line.Len() - eq_at - 1))
        settings.Put(key, value)
    end
    println "host:", settings.Get("host")
    println "port:", settings.Get("port").ToInt() + 1
    println "settings read:", settings.Size()
end
Outputhost: localhost port: 8081 settings read: 3

Every value comes back as text; convert it where you use it, here with to_int. Lines returns a fresh vector, so free it with defer as soon as you have it. For a structured format with nesting, use encoding.json or config instead of parsing by hand.

Appending to a log

AppendFile opens the file, adds the text at the end and closes it again on every call, so the log is complete on disk even if the program stops halfway. That makes it a good fit for a log or an audit trail. Both WriteFile and AppendFile return minus one when the file cannot be opened, which is worth checking when the path comes from the user or from a setting.

io-guide-log.salam
import io

func log(path: str, level: str, message: str):
    if io.AppendFile(path, "[" + level + "] " + message + "\n") < 0:
        io.EPrintln("cannot write to " + path)
    end
end

func main:
    path := "app.log"
    io.WriteFile(path, "")
    log(path, "info", "server started")
    log(path, "warn", "disk is 91% full")
    log(path, "info", "request served")
    log(path, "error", "database did not answer")
    mut problems := 0
    lines := io.Lines(path)
    defer lines.Free()
    each line in lines:
        if line.StartsWith("[warn]") or line.StartsWith("[error]"):
            problems++
            println line
        end
    end
    println lines.Len(), "lines,", problems, "need attention"
end
Output[warn] disk is 91% full [error] database did not answer 4 lines, 2 need attention

Here WriteFile with an empty string starts a new log each time the program runs. Leave that line out and the log keeps growing across runs.

Reading a large file in pieces

ReadFile and Lines hold the whole file in memory. For a file of hundreds of megabytes, open it yourself with os.Open and read a fixed number of bytes at a time with Read. An empty string means the end of the file. Check the handle against null before using it: that is how os.Open says the file could not be opened.

io-guide-chunks.salam
import io
import os

func main:
    io.WriteFile("big.txt", "0123456789".Repeat(25))
    f := os.Open("big.txt", "rb")
    if f == null:
        io.EPrintln("cannot open big.txt")
        ret 1
    end
    defer io.Close(f)
    mut total := 0
    mut chunks := 0
    until true:
        piece := io.Read(f, 64 as u64)
        if piece == "":
            break
        end
        chunks++
        total += piece.Len()
        println "chunk", chunks, "has", piece.Len(), "bytes"
    end
    println "read", total, "bytes in", chunks, "chunks"
    ret 0
end
Outputchunk 1 has 64 bytes chunk 2 has 64 bytes chunk 3 has 64 bytes chunk 4 has 58 bytes read 250 bytes in 4 chunks

The size is in bytes, so a chunk boundary can fall in the middle of a multi-byte character. When you only count or copy bytes this does not matter. When you need whole lines, read with Readline instead, as in the next section.

Processing a file line by line

Readline returns one line at a time without its line ending, so only the current line is in memory. Read the header once, then loop until the empty string that marks the end of the file.

io-guide-csv.salam
import io
import os
import str

func main:
    io.WriteFile("sales.csv", "item,qty,price\npen,3,12\nnotebook,2,45\nbag,1,180\n")
    f := os.Open("sales.csv", "rb")
    defer io.Close(f)
    header := io.Readline(f)
    println "columns:", header
    mut total := 0
    mut line := io.Readline(f)
    until line != "":
        cols := str.Split(line, ",")
        cost := cols.Get(1).ToInt() * cols.Get(2).ToInt()
        println cols.Get(0), cost
        total += cost
        cols.Free()
        line = io.Readline(f)
    end
    println "total:", total
end
Outputcolumns: item,qty,price pen 36 notebook 90 bag 180 total: 306

One catch: an empty line in the middle of the file also comes back as an empty string, and this loop would stop there. If your files can contain blank lines, compare the position with the file size, or read with Lines when the file is small enough. For real CSV with quoted fields, use encoding.csv.

Which function for which job

JobFunction
Read a small file wholeReadFile, or Lines for a vector of lines
Replace a fileWriteFile, or WriteLines from a vector
Add to the end of a fileAppendFile
Read a big file without loading itos.Open, then Read or Readline, then Close
Copy one open file into anotherCopy
Ask the user for a lineInput
Report an error or warningEPrint and EPrintln

Functions

Input

func Input(): str
Reads one line from standard input, usually the keyboard, and returns it without the line ending. It is the same thing input "" does. The example below waits for you to type, so here it is only compiled and not run.
io-Input.salam
import io

func main:
    print "What is your name? "
    name := io.Input()
    println "Welcome,", name
end

Read

func Read(f: File*, size: u64): str
Reads up to size bytes from the current position in the file. At the end of the file it returns an empty string.
io-Read.salam
import io
import os

func main:
    io.WriteFile("data.txt", "salam\ndonya\npayan\n")
    f := os.Open("data.txt", "rb")
    println io.Readline(f)
    println io.Read(f, 3 as u64)
    io.Seek(f, 0, 0)
    print io.ReadAll(f)
    io.Close(f)
end
Outputsalam don salam donya payan

Readline

func Readline(f: File*): str
Reads one line from the file, without the \n at its end (a \r before it stays). At the end of the file it returns an empty string, and so does a blank line, so a loop that stops on "" also stops at the first blank line.

The example for this item is shown with the ones above: io-Read.salam

Write

func Write(f: File*, data: str): int
Writes a string to an open file and returns the number of bytes written, or minus one when the handle is null.
io-Write.salam
import io
import os

func main:
    f := os.Open("report.txt", "wb")
    n := io.Write(f, "today's report\n")
    io.Close(f)
    println "bytes written:", n
    src := os.Open("report.txt", "rb")
    dst := os.Open("copy.txt", "wb")
    println "copied:", io.Copy(dst, src), "bytes"
    io.Close(src)
    io.Close(dst)
    print io.ReadFile("copy.txt")
end
Outputbytes written: 15 copied: 15 bytes today's report

Seek

func Seek(f: File*, offset: i64, whence: int): int
Moves the reading and writing position in a file. offset is a distance in bytes and whence says where to count from: zero is the start of the file, one is the current position and two is the end. It returns zero on success and minus one on failure.

The example for this item is shown with the ones above: io-Read.salam

Close

func Close(f: File*)
Closes the file. Every file you open has to be closed once, and defer is a good place for it.

The example for this item is shown with the ones above: io-Read.salam

ReadFile

func ReadFile(path: str): str
Reads the whole content of a file in one go. If the file does not exist, or cannot be read, it returns an empty string.
io-ReadFile.salam
import io

func main:
    path := "note.txt"
    io.WriteFile(path, "first line\n")
    io.AppendFile(path, "second line\n")
    print io.ReadFile(path)
    println io.ReadFile("a file that is not there.txt") == ""
end
Outputfirst line second line true

WriteFile

func WriteFile(path: str, data: str): int
Creates the file, or empties it if it already exists, and writes the string into it. It returns the number of bytes written, or minus one if the file could not be opened.

The example for this item is shown with the ones above: io-ReadFile.salam

AppendFile

func AppendFile(path: str, data: str): int
Adds the string to the end of the file, leaving what was already there alone. If the file does not exist it is created. Like WriteFile it returns a byte count or minus one.

The example for this item is shown with the ones above: io-ReadFile.salam

Lines

func Lines(path: str): Vector<str>
Reads a file and returns its lines in a vector. The whole text is trimmed first, so blank lines at the end disappear, and so does any indentation on the very first line. A missing file gives one empty line. Release the vector with free when you are done with it.
io-Lines.salam
import io

func main:
    mut lines := Vector {} as Vector<str>
    defer lines.Free()
    lines.Push("apple")
    lines.Push("pomegranate")
    lines.Push("grape")
    written := io.WriteLines("fruit.txt", lines)
    println "wrote:", written, "bytes"
    read := io.Lines("fruit.txt")
    defer read.Free()
    each i, line in read:
        println i + 1, line
    end
end
Outputwrote: 24 bytes 1 apple 2 pomegranate 3 grape

EPrint

func EPrint(s: str)
Writes a string to standard error, without a line break. Errors and warnings belong here rather than in the program's real output.
io-EPrint.salam
import io

func main:
    println "this goes to standard output"
    io.EPrint("warning: ")
    io.EPrintln("this message goes to standard error")
    print "no line break yet..."
    io.Flush()
    println ""
end
Outputthis goes to standard output warning: this message goes to standard error no line break yet...

EPrintln

func EPrintln(s: str)
Like EPrint, but moves to the next line after the message.

The example for this item is shown with the ones above: io-EPrint.salam

Flush

func Flush()
Writes out whatever is still sitting in the output buffer. Useful when you have written something with print that has no line ending and want the user to see it at once.

The example for this item is shown with the ones above: io-EPrint.salam

ReadAll

func ReadAll(f: File*): str
Reads everything left from the current position to the end of the file.

The example for this item is shown with the ones above: io-Read.salam

Copy

func Copy(dst: File*, src: File*): i64
Writes everything left in the file src into the file dst and returns the number of bytes copied. It suits large files, since it never holds the whole file in memory.

The example for this item is shown with the ones above: io-Write.salam

WriteLines

func WriteLines(path: str, lines: Vector<str>): int
Writes each element of a vector as one line of the file. An existing file is rewritten. It returns a byte count, or minus one.

The example for this item is shown with the ones above: io-Lines.salam