standard

The standard rad workbook module exemplifies how to create a custom workbook.gleam module for your own project.

By providing main and workbook functions in your project’s workbook.gleam file, you can extend rad’s standard workbook with your own or write one entirely from scratch, optionally making it and your Runners available for any dependent projects!

All Runner functions return the task.Result type, which is a String on success or a Snag on failure. As such, this documentation describes the side effects of the standard workbook’s runners, whether they occur in another Runner or rad.do_main (either of which might print a non-empty Result), or directly.

Constants

ignore_glob

</>

pub const ignore_glob: String

Directories that are omitted when printing, watching, etc.

Functions

config

</>

pub fn config(
  input: CommandInput,
  task: Task(Result(String, Snag)),
) -> Result(String, Snag)

Prints project configuration values from gleam.toml as stringified JSON.

Input arguments are taken to be a breadcrumb trail of TOML keys, and a subset of the configuration is printed upon successful traversal.

docs_build

</>

pub fn docs_build(
  input: CommandInput,
  task: Task(Result(String, Snag)),
) -> Result(String, Snag)

Renders HTML documentation for local Gleam packages.

Any number of packages, or --all, can be given as input arguments; if none are given, the current project’s documentation is rendered.

docs_serve

</>

pub fn docs_serve(
  input: CommandInput,
  task: Task(Result(String, Snag)),
) -> Result(String, Snag)

Serves HTML documentation for local Gleam packages.

Any number of packages, or --all, can be given as input arguments to render before serving; if none are given, the current project’s documentation is rendered.

The build/dev/docs/ directory is by default served at http://localhost:7000/ with support for live reloading. Host, port, and live reloading support can all be altered via input flags. For example, setting --host=0.0.0.0 allows the server to respond to external requests.

format

</>

pub fn format(
  input: CommandInput,
  task: Task(Result(String, Snag)),
) -> Result(String, Snag)

Formats your project’s source code, or verifies that it has already been formatted when given the --check flag.

Gleam code in the src and test directories, and any of their subdirectories, is formatted by default.

Additional Formatters can be defined in your project’s gleam.toml configuration file.

Examples

[[rad.formatters]]
name = "javascript"
check = ["rome", "ci", "--indent-style=space", "src", "test"]
run = ["rome", "format", "--indent-style=space", "--write", "src", "test"]

All valid Formatters are run or checked in sequence regardless of any errors along the way, but they must all be valid and successful for this Runner to succeed.

main

</>

pub fn main() -> Nil

Runs rad.do_main with rad’s standard workbook.

You can use your project’s gleam.toml config to have rad run your own workbook.gleam module’s main function. Similar to importing a Gleam module, the path is relative to the module’s src directory and should omit the .gleam extension.

Examples

[rad]
workbook = "my/workbook"

Note that rad’s standard workbook module is run by default, with no config necessary.

name

</>

pub fn name(
  input: CommandInput,
  task: Task(Result(String, Snag)),
) -> Result(String, Snag)

Prints stylized names for packages found in your project’s gleam.toml configuration file.

Any number of packages, or --all, can be given as input arguments; if none are given, the current project’s name is printed.

The style can be set with the --display, --color, and --background flags, which are passed to shellout.style.

Can be useful as a building block in other Runners.

origin

</>

pub fn origin(
  input: CommandInput,
  task: Task(Result(String, Snag)),
) -> Result(String, Snag)

Prints the repository URL for the git remote named origin.

Requires the git command to be available on the system.

ping

</>

pub fn ping(
  input: CommandInput,
  task: Task(Result(String, Snag)),
) -> Result(String, Snag)

Fetches the HTTP status codes for the given URIs.

All URIs are checked in sequence regardless of any errors along the way, but all status codes must be successful for this Runner to succeed.

root

</>

pub fn root(
  input: CommandInput,
  task: Task(Result(String, Snag)),
) -> Result(String, Snag)

Prints help information, or rad’s version when given the --version flag.

shell

</>

pub fn shell(
  input: CommandInput,
  task: Task(Result(String, Snag)),
) -> Result(String, Snag)

Launches an interactive shell, or REPL, with all of your project’s modules and dependencies preloaded and available.

The input argument specifies the type of shell to run, defaulting to erl, the Erlang shell, if none is given. Valid shells include deno, erl (or erlang), iex (or elixir), and node (or nodejs).

The syntax for accessing modules depends on the chosen shell.

Erlang

1> gleam@io:println("Hi from Erlang").
Hi from Erlang
nil

Elixir

iex(1)> :gleam@io.println("Hi from Elixir")
Hi from Elixir
nil

JavaScript

> $gleam$io.println("Hi from JavaScript")
Hi from JavaScript
undefined

tests

</>

pub fn tests(
  input: CommandInput,
  task: Task(Result(String, Snag)),
) -> Result(String, Snag)

Runs your project’s unit tests for all specified target/runtimes.

Accepts the --target input flag.

Note that default target/runtimes can also be specified in your project’s gleam.toml configuration file.

Examples

[rad]
targets = ["erlang", "javascript"]

tree

</>

pub fn tree(
  input: CommandInput,
  task: Task(Result(String, Snag)),
) -> Result(String, Snag)

Prints your project’s file structure using a tree representation.

Some paths, such as .git and build (see ignore_glob), are ignored.

Requires the exa or tree command to be available on the system (in order of preference).

When running exa, a git status summary is shown for each file.

version

</>

pub fn version(
  input: CommandInput,
  task: Task(Result(String, Snag)),
) -> Result(String, Snag)

Prints stylized versions for packages found in your project’s gleam.toml configuration file.

Any number of packages, or --all, can be given as input arguments; if none are given, the current project’s version is printed.

If the --bare flag is given, only the version strings are printed.

The style can be set with the --display, --color, and --background flags, which are passed to shellout.style.

watch

</>

pub fn watch(
  input: CommandInput,
  task: Task(Result(String, Snag)),
) -> Result(String, Snag)

Watches your project’s files and runs commands when they change.

Some paths, such as .git and build (see ignore_glob), are ignored.

Requires the watchexec or inotifywait command to be available on the system (in order of preference).

Input arguments are taken to be a command to run when changes are detected. If no arguments are given, the command defaults to rad watch do.

Note that rad makes few assumptions about the local environment and will not run commands through any shell interpreter on its own. As such, one method of running multiple commands is to wrap them in a single command that invokes the shell interpreter of your choice.

Examples

> rad watch sh -c \
  'n() shuf -i99-156 -n1; clear; rad version --color=$(n),$(n),$(n)'

watch_do

</>

pub fn watch_do(
  input: CommandInput,
  task: Task(Result(String, Snag)),
) -> Result(String, Snag)

Runs several rad tasks in succession: renders the project’s HTML documentation, signals the documentation server to do a live reload for all known client connections, and runs the project’s tests for all specified targets.

Accepts the --no-docs, --port, and --target input flags.

This is the default action when running rad watch.

Note that default targets can also be specified in your project’s gleam.toml configuration file.

Examples

[rad]
targets = ["erlang", "javascript"]

workbook

</>

pub fn workbook() -> Dict(
  List(String),
  Task(Result(String, Snag)),
)

Returns rad’s standard Workbook, which can be used as a base when building your own.