IO Module

Input/output operations for console, files, directories, and paths.

IO operations are side-effecting and interact with the outside world. File system access is disabled by default for security — enable it with KEEL_IO_DISABLED=0. Console operations are always allowed.

Common patterns

import IO

-- Console output
IO.println "Hello, world!"
IO.eprintln "Warning: something happened"

-- File operations (return Result)
let content = IO.readFile "data.txt"       -- Result String IOError
IO.writeFile "out.txt" "hello"              -- Result Unit String
IO.appendFile "log.txt" "new line\n"        -- Result Unit String

-- Path manipulation (pure, always available)
IO.joinPath "/home" "user"                   -- "/home/user"
IO.extension "photo.jpg"                    -- Just "jpg"
IO.fileName "/path/to/file.txt"             -- "file.txt"

Return types

File and directory operations return Result to handle errors:

readFile : String -> Result String IOError — content or error message
writeFile : String -> String -> Result Unit String — success or error message
fileSize : String -> Result Int IOError — size in bytes or error message

Path functions that may not have an answer return Maybe:

parentDir : String -> Maybe String
extension : String -> Maybe String

Security

Variable	Effect
`KEEL_IO_DISABLED=0`	Enable file/directory IO
`KEEL_IO_READ_ONLY=1`	Allow only read operations
`KEEL_IO_SANDBOX=/path`	Restrict to a directory

Functions

Console

`IO.print`

a -> ()

Print a value to stdout without a newline.

Example:

import IO

IO.print "Hello"

-- outputs: Hello

Try it

Notes: Flushes stdout after printing.

See also: IO.println, IO.eprint

`IO.println`

a -> ()

Print a value to stdout with a newline.

Example:

import IO

IO.println "Hello"

-- outputs: Hello\

Try it

See also: IO.print, IO.eprintln

`IO.eprint`

a -> ()

Print a value to stderr without a newline.

Example:

import IO

IO.eprint "Error"

Try it

Notes: Flushes stderr after printing.

See also: IO.eprintln, IO.print

`IO.eprintln`

a -> ()

Print a value to stderr with a newline.

Example:

import IO

IO.eprintln "Error occurred"

Try it

See also: IO.eprint, IO.println

`IO.readLine`

() -> Result String IOError

Read a line from input. Returns Ok with the line (without newline), or Err on failure.

Example:

import IO

IO.readLine ()

Try it

Notes: Takes Unit argument to trigger execution.

The input source depends on the host. In the CLI/REPL it reads the process's stdin. Under a Jupyter kernel it reads from the notebook frontend (an input box appears). If the frontend declines input (allow_stdin: false) or input is otherwise unavailable, it returns Err IOError::Interrupted. A user interrupt (the stop button) while waiting aborts the cell — it is not delivered as a catchable Err.

See also: IO.println

Files

`IO.readFile`

String -> Result String IOError

Read the entire contents of a file as a string.

Example:

import IO

IO.readFile "config.txt"

Try it

See also: IO.writeFile, IO.appendFile

`IO.writeFile`

String -> String -> Result () IOError

Write a string to a file, creating or truncating it.

Example:

import IO

IO.writeFile "output.txt" "Hello, World!"

Try it

Notes: Overwrites existing file contents.

See also: IO.readFile, IO.appendFile

`IO.appendFile`

String -> String -> Result () IOError

Append a string to a file, creating it if it doesn't exist.

Example:

import IO

IO.appendFile "log.txt" "New entry\n"

Try it

See also: IO.writeFile, IO.readFile

`IO.fileExists`

String -> Bool

Check if a file or directory exists at the given path.

Example:

import IO

IO.fileExists "config.txt"

-- True or False

Try it

See also: IO.isFile, IO.isDir

`IO.removeFile`

String -> Result () IOError

Delete a file at the given path.

Example:

import IO

IO.removeFile "temp.txt"

Try it

Notes: Use removeDir for directories.

See also: IO.removeDir, IO.removeDirAll

`IO.copyFile`

String -> String -> Result () IOError

Copy a file from source to destination.

Example:

import IO

IO.copyFile "src.txt" "dst.txt"

Try it

See also: IO.renameFile

`IO.renameFile`

String -> String -> Result () IOError

Rename or move a file from source to destination.

Example:

import IO

IO.renameFile "old.txt" "new.txt"

Try it

See also: IO.copyFile

File info

`IO.isDir`

String -> Bool

Check if the path is a directory.

Example:

import IO

IO.isDir "/home/user"

-- True

Try it

See also: IO.isFile, IO.fileExists

`IO.isFile`

String -> Bool

Check if the path is a file.

Example:

import IO

IO.isFile "config.txt"

-- True

Try it

See also: IO.isDir, IO.fileExists

`IO.fileSize`

String -> Result Int IOError

Get the size of a file in bytes.

Example:

import IO

IO.fileSize "data.bin"

-- Ok 1024

Try it

See also: IO.isFile

Directories

`IO.listDir`

String -> Result [String] IOError

List the contents of a directory.

Example:

import IO

IO.listDir "."

-- Ok ["file1.txt", "subdir", ...]

Try it

Notes: Returns file names only, not full paths.

See also: IO.isDir

`IO.currentDir`

() -> Result String IOError

Get the current working directory.

Example:

import IO

IO.currentDir ()

-- Ok "/home/user/project"

Try it

Notes: Takes Unit argument to trigger execution.

See also: IO.setCurrentDir

`IO.setCurrentDir`

String -> Result () IOError

Set the current working directory.

Example:

import IO

IO.setCurrentDir "/home/user"

Try it

See also: IO.currentDir

`IO.createDir`

String -> Result () IOError

Create a single directory.

Example:

import IO

IO.createDir "newdir"

Try it

Notes: Fails if parent doesn't exist. Use createDirAll for nested creation.

See also: IO.createDirAll, IO.removeDir

`IO.createDirAll`

String -> Result () IOError

Create a directory and all parent directories.

Example:

import IO

IO.createDirAll "a/b/c"

Try it

Notes: No error if directory already exists.

See also: IO.createDir, IO.removeDirAll

`IO.removeDir`

String -> Result () IOError

Remove an empty directory.

Example:

import IO

IO.removeDir "emptydir"

Try it

Notes: Fails if directory is not empty. Use removeDirAll to remove with contents.

See also: IO.removeDirAll, IO.removeFile

`IO.removeDirAll`

String -> Result () IOError

Remove a directory and all its contents.

Example:

import IO

IO.removeDirAll "project"

Try it

Notes: Use with caution - this is recursive and permanent!

See also: IO.removeDir, IO.removeFile

Paths (pure)

`IO.joinPath`

String -> String -> String

Join two path segments together.

Example:

import IO

IO.joinPath "/home/user" "file.txt"

-- "/home/user/file.txt"

Try it

Notes: Handles path separators correctly for the platform.

See also: IO.parentDir, IO.fileName

`IO.parentDir`

String -> Maybe String

Get the parent directory of a path.

Example:

import IO

IO.parentDir "/home/user/file.txt"

-- Just "/home/user"

Try it

See also: IO.fileName, IO.joinPath

`IO.fileName`

String -> Maybe String

Get the file name from a path.

Example:

import IO

IO.fileName "/home/user/file.txt"

-- Just "file.txt"

Try it

See also: IO.parentDir, IO.extension

`IO.extension`

String -> Maybe String

Get the extension from a path.

Example:

import IO

IO.extension "file.txt"
-- Just "txt"

Try it

Notes: Does not include the leading dot.

See also: IO.fileName

`IO.absolutePath`

String -> Result String IOError

Convert a path to an absolute path.

Example:

import IO

IO.absolutePath "./file.txt"

-- Ok "/home/user/project/file.txt"

Try it

Notes: Resolves symlinks and normalizes the path.

See also: IO.joinPath