Skip to content

io

Jump to bottom
Ivan Pidhurskyi edited this page Nov 26, 2025 · 1 revision

IO Library

The IO library provides file and string input/output operations for OSL.

Types

type port
type ostringport // subtype of port

Ports represent input/output streams for reading and writing.

Functions

File Operations:

Writing:

Reading:

  • read(port) - Read all content until EOF
  • read(port, n) - Read n bytes
  • readline(port) - Read a single line

String Ports:

  • openstring(string) - Create input port from string
  • openstring() - Create output string port
  • str(ostringport) - Get accumulated string from output port

Iterator:

  • lines(port) - Iterator for reading file line by line
### `open(filename str, mode str) -> port` Opens a file with the specified mode. The mode string consists of characters that determine the open flags:
  • "r" - Open for reading
  • "w" - Open for writing (creates file, truncates if exists)
  • "a" - Open for appending (creates file if doesn't exist)
  • "+" - Open for both reading and writing
  • "b" - Binary mode
  • "e" - Exclusive mode (fail if file exists)
### `close(p port)` Closes an input or output port.
### `write(p port, s str)`

Writes a string to the output port without adding a newline.

### `writeln(p port, s str)`

Writes a string to the output port followed by a newline.

### `flush(p port)`

Flushes the output buffer of a port, ensuring all pending writes are committed.

...

Reading Operations

read (all content)

read(port port) -> maybe(str)

Reads all remaining content from the port until EOF. Returns Nothing() if at EOF, otherwise returns Some(content).

Example:

file = open("data.txt", "r")
match read(file) in
| Some(content) -> print(content)
| Nothing() -> print("File is empty")
close(file)

read (n bytes)

read(port port, n num) -> maybe(str)

Reads up to n bytes from the port. Returns Nothing() if at EOF, otherwise returns Some(content).

Example:

file = open("data.txt", "r")
match read(file, 100) in
| Some(chunk) -> print("Read " + str(length(chunk)) + " bytes")
| Nothing() -> print("End of file")
close(file)

readline

readline(port) -> maybe(str)

Reads a single line from the port (excluding the newline character). Returns Nothing() if at EOF, otherwise returns Some(line).

Example:

file = open("data.txt", "r")
match readline(file) in
| Some(line) -> print("First line: " + line)
| Nothing() -> print("File is empty")
close(file)

Line Iterator

lines

type lines = { file port }
next(it lines) -> maybe(str)

An iterator type that allows reading a file line by line.

Example:

file = open("data.txt", "r")
for line in lines{file: file} {
  print(line)
}
close(file)

String Ports

String ports allow reading from and writing to in-memory strings.

openstring (input)

openstring(s str) -> port

Creates an input port that reads from a string.

Example:

input = openstring("line 1\nline 2\nline 3")
match readline(input) in
| Some(line) -> print(line)  ; Prints: "line 1"
| Nothing() -> print("Empty")

openstring (output)

openstring() -> ostringport

Creates an output string port for writing to a string buffer.

Example:

output = openstring()
write(output, "Hello, ")
write(output, "World!")
result = str(output)  ; result is "Hello, World!"

str

str(ostringport) -> str

Retrieves the accumulated string content from an output string port.

Example:

output = openstring()
writeln(output, "Line 1")
writeln(output, "Line 2")
content = str(output)
print(content)
; Prints:
; Line 1
; Line 2

Complete Examples

Reading a file line by line

file = open("data.txt", "r")
for line in lines{file: file} {
  print("Line: " + line)
}
close(file)

Writing multiple lines

file = open("output.txt", "w")
writeln(file, "Header")
writeln(file, "=======")
writeln(file, "Content goes here")
close(file)

Reading file in chunks

file = open("large_file.bin", "rb")
loop {
  match read(file, 4096) in
  | Some(chunk) -> process(chunk)
  | Nothing() -> break
}
close(file)

Using string ports for formatting

buffer = openstring()
write(buffer, "Result: ")
write(buffer, str(42))
write(buffer, " items")
message = str(buffer)
print(message)  ; Prints: "Result: 42 items"

Notes

  • Ports should always be closed after use to free system resources
  • read() and readline() return maybe types to handle EOF gracefully
  • String ports are useful for building strings incrementally or parsing strings as streams
  • The lines iterator automatically handles line-by-line reading without manual EOF checking

Clone this wiki locally