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.
ReadFilereturns an empty string, andLinesreturns 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 withos.Exists. - Lines are split on
\nonly. A file saved with Windows line endings keeps a\rat the end of each line fromLinesandReadline; 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.
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()
endEvery 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.
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"
endHere 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.
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
endThe 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.
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
endOne 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
| Job | Function |
|---|---|
| Read a small file whole | ReadFile, or Lines for a vector of lines |
| Replace a file | WriteFile, or WriteLines from a vector |
| Add to the end of a file | AppendFile |
| Read a big file without loading it | os.Open, then Read or Readline, then Close |
| Copy one open file into another | Copy |
| Ask the user for a line | Input |
| Report an error or warning | EPrint and EPrintln |
Functions
Input
func Input(): strinput "" does. The example below waits for you to type, so here it is only compiled and not run.import io
func main:
print "What is your name? "
name := io.Input()
println "Welcome,", name
endRead
func Read(f: File*, size: u64): strsize bytes from the current position in the file. At the end of the file it returns an empty string.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)
endReadline
func Readline(f: File*): str\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): intnull.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")
endSeek
func Seek(f: File*, offset: i64, whence: int): intoffset 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*)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): strimport 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") == ""
endWriteFile
func WriteFile(path: str, data: str): intThe example for this item is shown with the ones above: io-ReadFile.salam
AppendFile
func AppendFile(path: str, data: str): intWriteFile 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>free when you are done with it.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
endEPrint
func EPrint(s: str)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 ""
endEPrintln
func EPrintln(s: str)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()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*): strThe example for this item is shown with the ones above: io-Read.salam
Copy
func Copy(dst: File*, src: File*): i64src 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>): intThe example for this item is shown with the ones above: io-Lines.salam