io

import io

This module provides interfaces for working with to I/O stream and TTYs as well as expose the operating system standard I/O for easy access.

Some I/O operations that should belong to this module have been merged as core features and offered as built-in functions for Zuri. Specifically file I/O features that can be accessed via the built-in file() function.

The standard I/O streams are also files and you can call almost all file methods on them. Whenever a file method is not supported, you’ll get an error message telling you that such operation is not supported for standard streams.

Example

The following example shows how to use the io module for accepting user name and printing the result.

import io

var name = io.readline('What is your name?')
echo name

The io API

Every public name in io, wherever it is declared. Each links to the page that documents it.

Submodules

Constants

SEEK_SET

io.SEEK_SET: int = 0

Set I/O position from the beginning.

SEEK_CUR

io.SEEK_CUR: int = 1

Set I/O position from the current position.

SEEK_END

io.SEEK_END: int = 2

Set I/O position from the end.

stdin

io.stdin: file

Stdin is a file handle to the standard input file of the system.

It is opened in binary mode ('rb'), so stdin.read() and stdin.gets() return bytes, never a string. Whatever is piped into a program is arbitrary data, and decoding it as text before the program has asked for text can only lose information.

Call .to_string() on the result when the input really is text:

import io

var raw = io.stdin.read()          # bytes
var text = raw.to_string()         # decoded, replacing bad bytes

to_string() substitutes U+FFFD for undecodable bytes rather than raising. To reject malformed input instead, inspect the bytes yourself before decoding.

stdout

io.stdout: file

Stdout is a file handle to the standard output file of the system.

Writes accept either a string or bytes, so unlike stdin there is no text/binary distinction to make here.

stderr

io.stderr: file

Stderr is a file handle to the standard error file of the system.

is_repl

io.is_repl: bool

Returns true if the current environment is the Zuri REPL, false otherwise.

Functions

capture_begin()

io.capture_begin()

Begins capturing standard output.

From this call until the matching capture_end(), everything Zuri writes to standard output is collected into a buffer instead of reaching the terminal. That covers echo, print(), and writes through io.stdout. It does not cover io.stderr, output written by a child process started with os.spawn(), or bytes a native module writes straight to the descriptor.

Captures nest. Each capture_begin() opens a new frame and the innermost open frame receives everything, so an inner capture never leaks into the one around it.

Capture is per-thread: one opened inside an isolate collects only that isolate’s own output.

A frame that is never closed is flushed to the terminal when the program ends, so output is never silently lost. Prefer capture() unless you need the output of a body that raises.

import io

io.capture_begin()
echo 'not printed yet'
var text = io.capture_end()

echo 'captured: ' + text.trim('\n')

captured: not printed yet

capture_end()

io.capture_end()

Ends the innermost capture and returns everything it collected.

The text comes back exactly as written, trailing newline included. Bytes that are not valid UTF-8 decode to U+FFFD rather than raising, so a whole frame is never lost over one stray byte.

Returns — string: the captured output, or nil when no capture was open.

capture_depth()

io.capture_depth() -> int

The number of capture frames currently open. 0 means output is going to the terminal.

Returns int

capture()

io.capture(body: function) -> string

Runs body with standard output captured, and returns everything it printed.

import io

def greet(name) {
  echo 'Hello, ${name}!'
}

var out = io.capture(@{ greet('Ada') })
echo out.length()

12

Parameters

• body (function)

Returns string

Note: when body raises, the capture is closed and the error is re-raised, but whatever was collected before it is discarded. Use capture_begin()/capture_end() around your own catch when you need both.

flush()

io.flush(file)

Flushes the content of the given file handle

putc()

io.putc(c)

Writes character c to the screen.

Parameters

• char|number — c

getc()

io.getc(length)

Reads character(s) from standard input.

When length is given, gets length number of characters else, gets a single character.

length counts bytes, not codepoints, so asking for fewer bytes than a multi-byte character occupies yields a replacement character rather than half of one.

Returns — char|string

getch()

io.getch()

Reads a single character from standard input without printing to standard output.

Returns — char|string

readline()

io.readline(message, secure, obscure_text) -> string

Reads an entire line from standard input. If a message is given, the message will be printed before it begins to wait for a user input. If secure is true, the user’s input will not be printing and obscure_text will be printed instead.

Parameters

• message (?string)
• secure (?bool)
• obscure_text (?string) — Default value is *.

Returns string

Note: Newlines will not be added automatically for messages.

2021, Richard Ore and Zuri contributors