kex docs Standard Library 0.4.0-alpha kex.run ↗

Systemprelude

module System

The running process and the machine under it: exiting, and asking what platform this is.

System.OS          # => :macos
System.posix?      # => true
System.exit(1)     # ends the program with status 1

Deliberately NOT a capability, and OS/BITWIDTH stay pure. Faking the reported OS only exercises a program's branching, not the platform behaviour behind it: the file semantics, path rules and process handling that actually differ are unaffected by the atom. Testing those means running on the platform, which CI does across macOS, Ubuntu and Alpine. Mock.System existed for this and had exactly one caller: the spec that tested it (kexhq/kex#143).

type OperatingSystem

The operating system families a program may be running on.

A union of atoms rather than an ADT: these are plain tags, and a match over them is still exhaustive. Anything unmodelled is :unknown: the union is closed, so callers can cover it.

Variants

  • abstract
  • abstract
  • abstract
  • abstract
  • abstract
  • abstract
  • abstract
  • abstract

function exit

Ends the process immediately with exit status code.

The invoking shell receives the code, so this is how a command-line tool reports success or failure to whatever ran it: 0 means success, anything else means failure.

Nothing after the call runs, and no cleanup happens: close what needs closing first.

exit(code) : Integer -> Void
Parameters
code Integer
the exit status

Returns: Void —

Examples

Failing with a message

IO.printError("config not found")
System.exit(1)

Reporting a test run's result

System.exit(failures.empty? then 0 else 1)

constant OS OperatingSystem

The operating system family this program is running on.

Both backends answer with the same atom for the same machine. Prefer the macOS? / linux? / windows? / posix? predicates below when you are asking one yes-or-no question; use OS when you need to branch several ways.

constant BITWIDTH Integer

The machine's pointer width in bits: 64 on anything current, 32 on a small target.

Reported by the emulator on BEAM and by the pointer size in the tree walker, so both agree for one machine.

constant macOS? Bool

Returns true when running on macOS.

constant linux? Bool

Returns true when running on Linux.

constant windows? Bool

Returns true when running on Windows.

constant posix? Bool

Returns true when the platform follows POSIX conventions for paths, separators and shell behaviour.

Everything the toolchain runs on except Windows behaves POSIX-ly enough for paths, separators and shell conventions. An unknown system is NOT assumed to be POSIX.

function die

Ends the program with a fatal error message.

message goes to stderr behind a "fatal: " prefix and the exit status is 1. This is an abort, not an exception, so trying / rescue cannot catch it. Use it only where there is no recoverable answer. The prelude uses it for a negative repeat count, for instance.

Its result type is Never, the bottom type: die does not return, so a branch that dies takes the other branch's type, and if b == 0 then die("divide by zero") else a end is an Integer.

die is declared bare, like assert, so it is always in scope.

die() : Never
die(message) : String -> Never
Parameters
message String
the fatal message; omitted for a generic one

Returns: Never — never returns

Examples
die("unreachable state")   # stderr: fatal: unreachable state

Using it in a branch that must produce a value

let denominator = if divisor == 0 then die("divide by zero") else divisor end