Standard Effects

The built-in effect operations that ship with Loon.

IO

Basic input and output. These are the operations you reach for when you need to print something, read from the console, or work with files. They are all effect operations, which means they can be intercepted and handled if you need to, for example, test code that does IO without actually touching the filesystem.

println : Str -> ()

Print a string followed by a newline to stdout.

print : Str -> ()

Print a string to stdout without a trailing newline.

read-line : () -> Str

Read a line of input from stdin.

read-file : Str -> Str

Read the entire contents of a file as a string.

write-file : Str -> Str -> ()

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

Fail

Structured error handling via effects. When you call fail, execution aborts unless something higher up in the call stack handles it. The try function is the most common way to catch failures: wrap a computation in try and you get back a Result you can pattern match on.

fail : Str -> a

Raise an error with a message. Aborts unless handled.

try : (() -> a) -> Result a Str

Run a computation, catching any fail effect as Err.

[let result [try [fn [] [fail "oops"]]]]
[match result
  [Ok val]  [println val]
  [Err msg] [println [str "error: " msg]]]

Async

Lightweight concurrency. spawn kicks off a background task and gives you a handle to it. When you need the result, call await on that handle. This is a simple model that avoids callback spaghetti while still letting you do real concurrent work.

spawn : (() -> a) -> Task a

Spawn a concurrent task that runs in the background.

await : Task a -> a

Block until a task completes and return its result.

[let t [spawn [fn [] [+ 1 2]]]]
[println [await t]]  ; 3

Process

Operations for interacting with the operating system. Run external commands, read environment variables, or grab the command-line arguments your program was invoked with.

exec : Str -> #[Str] -> Result Str Str

Run an external command with arguments. Returns stdout on success.

env : Str -> Option Str

Read an environment variable. Returns None if unset.

args : () -> #[Str]

Return the command-line arguments as a vector of strings.

Net

Networking primitives for HTTP and TCP. fetch handles outgoing HTTP requests, while serve lets you spin up an HTTP server with a simple request handler function. If you need lower-level control, listen gives you raw TCP connections.

fetch : Str -> Map -> Result Str Str

Make an HTTP request. The map contains method, headers, and body.

listen : Int -> (Conn -> ()) -> ()

Listen for TCP connections on a port and handle each one.

serve : Int -> (Request -> Response) -> ()

Start an HTTP server on a port with a request handler.

Physics

Physical constants and material properties as swappable effects. Use handle to provide values for a specific environment — different materials, planets, or simulation contexts.

gravity : () -> Acceleration

Return gravitational acceleration for the current environment.

yield-strength : () -> Pressure

Return the yield strength of the current material.

elastic-modulus : () -> Pressure

Return the elastic (Young's) modulus of the current material.

density : () -> Density

Return the density of the current material.

temperature : () -> Temperature

Return the ambient temperature.

thermal-conductivity : () -> ThermalConductivity

Return the thermal conductivity of the current material.

[handle [analyze beam 10.0kN]
  [Physics.gravity] [resume [unit 9.81 :m]]
  [Physics.yield-strength] [resume 250.0MPa]
  [Physics.density] [resume [unit 7850.0 :kg]]]

Sim

Simulation operations for structural and thermal analysis. Handlers can be analytical formulas, numerical solvers, or surrogate models — the caller does not need to know which.

stress : geometry -> material -> load -> Pressure

Compute stress for a given geometry, material, and load.

deflection : geometry -> material -> load -> Length

Compute deflection under load.

natural-freq : geometry -> material -> Frequency

Compute the natural frequency of a structure.

thermal-field : geometry -> material -> sources -> Temperature

Compute the temperature field for given heat sources.