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

Relative filesystem paths are resolved from directory of the source expression that performs the effect. Inline code, shared and published modules have no source directory using a relative path will always fail. Use perform CWD({}) to build an absolute path for reading relative to a scripts running location.

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.

CWD

Return the Current Working Directory (CWD) where the eyg process was started.

let cwd = perform CWD({})

Argument is unit ({}). Returns Ok(String) | Error({}).

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)