EYG separates the *declaration* of an effect (in your script: perform Foo(...)) from its *implementation* (provided by the runner). The CLI in this repository (packages/gleam_cli) implements the effects below.

For scripts that need value-based restrictions around Fetch and the result-returning file-system effects, see overlay.access.

File system

ReadFile

Read a slice of a file at a given byte offset.

match perform ReadFile({path: "data.txt", offset: 0, limit: 1000000}) {
  Ok(bytes) -> {
    match !string_from_binary(bytes) {
      Ok(text) -> { text }
      Error(_) -> { !never(perform Abort("not valid utf-8")) }
    }
  }
  Error(reason) -> { !never(perform Abort(reason)) }
}

Returns Result(Binary, String).

WriteFile

Overwrite a file with new contents (creating it if necessary).

perform WriteFile({path: "out.txt", contents: !string_to_binary("hello")})

Returns Result({}, String).

DeleteFile

Delete a file at the given path. Deleting a file that does not exist is an error, surfaced via the Result return type — callers that want delete-idempotency should match Error(_) and ignore.

perform DeleteFile("scratch.txt")

Returns Result({}, String).

AppendFile

Append bytes to a file. Safe for concurrent appends.

perform AppendFile({path: "log.txt", contents: !string_to_binary("a line\n")})

Returns Result({}, String).

ReadDirectory

List entries in a directory. Excludes . and ...

match perform ReadDirectory(".") {
  Ok(entries) -> { entries }
  Error(reason) -> { !never(perform Abort(reason)) }
}

Returns Result(List({name: String, type: Directory({}) | File({size: Int})}), String).

For a recursive walk, see eyg_packages/fs/index.eyg's list and list_files helpers.

I/O

Now

Returns the current wall-clock time as Unix epoch milliseconds.

let millis = perform Now({})

Argument is unit ({}). Returns Int.

Print

Write a string to stdout. No newline is added.

perform Print("hello\n")

Returns {}.

Random

Returns a uniformly random integer greater than 0 and less than max.

let dice = !int_add(perform Random(6), 1)

Argument is unit ({}). Returns Int.

Sleep

Suspends the script for the given number of milliseconds. Other effects in flight still progress.

let _ = perform Sleep(1000)  // wait 1 second

Argument is Int (milliseconds). Returns unit ({}).

Env

Read a process environment variable.

match perform Env("HOME") {
  Some(value) -> { value }
  None({}) -> { "" }
}

Argument is String (the variable name). Returns Option(String).

Network

Fetch

Make an HTTP request.

let request = {
  method: GET({}),
  scheme: HTTP({}),
  host: "example.com",
  port: None({}),
  path: "",
  query: None({}),
  headers: [],
  body: !string_to_binary("")
}
match perform Fetch(request) {
  Ok({status, headers, body}) -> { status }
  Error(reason) -> { !never(perform Abort(reason)) }
}

Returns Result({status: Int, headers: List(...), body: Binary}, String).

Parsing

DecodeJSON

Parse a JSON binary into a flat list of {term, depth} events.

match perform DecodeJSON(!string_to_binary("{\"x\": 1}")) {
  Ok(events) -> { events }
  Error(reason) -> { !never(perform Abort(reason)) }
}

Each event's term is one of: True | False | Null | Integer i | String s | Number {…} | Array | Object | Field name.

Cryptography

Hash

Compute a cryptographic digest of a binary.

let digest = perform Hash({algorithm: SHA256({}), bytes: !string_to_binary("abc")})

Returns Binary (the raw digest).

Authenticated services

Each of these performs a spotless OAuth flow the first time it's used and caches the token. The lift / lower shape matches Fetch, but the request is rewritten to point at the service's API host with the bearer token attached.

let request = {
  method: GET({}),
  scheme: HTTPS({}),
  host: "api.github.com",
  port: None({}),
  path: "/user",
  query: None({}),
  headers: [],
  body: !string_to_binary("")
}
perform GitHub(request)