rad/task

Tasks represent commands that can be invoked from the rad command line interface.

A collection of tasks that can be handled by rad.do_main is called a Workbook.

Types

Formatter

A type that describes an external source code formatter.

If a Task uses formatters as its Iterable, that task will run the gleam formatter along with any formatters defined in your gleam.toml config via the rad.formatters table array.

Examples

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

pub type Formatter {
  Formatter(name: String, check: List(String), run: List(String))
}

Constructors

Formatter(name: String, check: List(String), run: List(String))

Parser

</>

A value for the config and manifest fields of every Task.

A new Task defined in a Workbook, won’t ask its Runner to access the gleam.toml or manifest.toml files (None). This can be changed using the with_config and/or with_manifest builder functions (Expected).

At runtime, when a Runner sees that its Task needs some Toml data, it can fetch it once (Parsed) and use it repeatedly . A trainer does this for its Runner automatically.

pub type Parser {
  Expected
  None
  Parsed(Toml)
}

Constructors

```
Expected
```
```
None
```
```
Parsed(Toml)
```

Result

</>

The standard return type for a Task.

Contains a string of output on success, or a Snag on failure.

pub type Result =
  gleam.Result(String, Snag)

Runner

</>

A function that takes CommandInput and a given Task and does any number of things with them.

pub type Runner(a) =
  fn(CommandInput, Task(a)) -> a

Task

</>

The basic configuration unit for the rad command line interface.

A Task can be conveniently built up using the following functions: new, followed by any number of shortdoc, flag, flags, parameter, parameters, with_config, with_manifest, and for combined with arguments, formatters, packages, targets, or, or a custom Iterable-generating function.

Any number of tasks can be added to a new or existing Workbook, such as the standard workbook, to compose a custom Workbook that can be given to rad.do_main.

pub type Task(a) {
  Task(
    path: List(String),
    run: Runner(a),
    for: Iterable(a),
    delimiter: String,
    shortdoc: String,
    flags: List(Flag),
    parameters: List(#(String, String)),
    config: Parser,
    manifest: Parser,
  )
}

Constructors

Task(
  path: List(String),
  run: Runner(a),
  for: Iterable(a),
  delimiter: String,
  shortdoc: String,
  flags: List(Flag),
  parameters: List(#(String, String)),
  config: Parser,
  manifest: Parser,
)

Tasks

</>

A list in which each item is a Task that returns a Result.

pub type Tasks =
  List(Task(Result))

Functions

arguments

</>

pub fn arguments() -> Iterable(a)

Returns an Iterable that tells a Runner how to run for each of a list of input arguments.

An Iterable can be attached to a given Task using the for builder function.

basic

</>

pub fn basic(command: List(String)) -> fn(
  CommandInput,
  Task(Result(String, Snag)),
) -> Result(String, Snag)

Returns a basic Runner that runs its Task using the given command.

Basic runners are used for tasks defined in gleam.toml.

delimit

</>

pub fn delimit(iterable task: Task(a), with delimiter: String) -> Task(
  a,
)

Returns a new Task with the given delimiter string.

This string is printed between items when a task runs for multiple iterations.

flag

</>

pub fn flag(into task: Task(a), called name: String, explained description: String, expect flag_fun: fn(
    String,
    b,
    String,
  ) -> #(String, Contents), default value: b) -> Task(a)

Returns a new Task with the given input Flag appended.

A Flag defines an optional argument that its Task accepts from command line input.

flags

</>

pub fn flags(into task: Task(a), add flags: List(
    #(String, Contents),
  )) -> Task(a)

Returns a new Task with the given list of input flags appended.

A Flag defines an optional argument that its Task accepts from command line input.

for

</>

pub fn for(do task: Task(a), each iter_fun: fn() -> Iterable(a)) -> Task(
  a,
)

Returns a new Task with the given iter_fun, a function that returns an Iterable telling the Runner which items to iterate over and how input should be mapped at the beginning of each iteration.

formatters

</>

pub fn formatters() -> Iterable(a)

Returns an Iterable that tells a Runner how to run for each project Formatter. The Gleam Formatter is always included.

An Iterable can be attached to a given Task using the for builder function.

gleam

</>

pub fn gleam(arguments: List(String)) -> fn(
  CommandInput,
  Task(Result(String, Snag)),
) -> Result(String, Snag)

Returns a Runner that runs the gleam build tool with the given arguments.

Gleam runners can be used for tasks defined in a Workbook.

new

</>

pub fn new(at path: List(String), run runner: fn(
    CommandInput,
    Task(Result(String, Snag)),
  ) -> Result(String, Snag)) -> Task(Result(String, Snag))

Returns a new Task with the given path and runner, which is assisted by a trainer to reduce boilerplate code for common scenarios.

The path is a list of words that, when given in sequence using rad’s command line interface, invoke the Task, which will then be processed together with any other input arguments and run by the runner. For example, if rad is invoked from the command line with rad hearts gleam, it will try to run a Task with the path: ["hearts", "gleam"].

or

</>

pub fn or(true_fun: fn() -> Iterable(a), cond flag_name: String, else false_fun: fn() ->
    Iterable(a)) -> fn() -> Iterable(a)

Returns a function that generates a given Iterable when the Runner’s CommandInput contains a boolean input flag called flag_name with a True value, or another Iterable otherwise.

An Iterable can be attached to a given Task using the for builder function.

packages

</>

pub fn packages() -> Iterable(a)

Returns an Iterable that tells a Runner how to run for each project dependency and the project itself.

An Iterable can be attached to a given Task using the for builder function.

parameter

</>

pub fn parameter(into task: Task(a), with usage: String, of description: String) -> Task(
  a,
)

Returns a new Task with the given parameter documentation appended.

Parameter docs are used by the help function to describe what extra arguments do for a given Task.

parameters

</>

pub fn parameters(into task: Task(a), add parameters: List(
    #(String, String),
  )) -> Task(a)

Returns a new Task with the given list of parameter documentation pairs appended.

Parameter docs are used by the help function to describe what extra arguments do for a given Task.

path

</>

pub fn path(into task: Task(a), insert path: List(String)) -> Task(
  a,
)

Returns a new Task with the given path.

runner

</>

pub fn runner(into task: Task(Result(String, Snag)), insert runner: fn(
    CommandInput,
    Task(Result(String, Snag)),
  ) -> Result(String, Snag)) -> Task(Result(String, Snag))

Returns a new Task with the given runner, which is assisted by a trainer to reduce boilerplate code for common scenarios.

shortdoc

</>

pub fn shortdoc(into task: Task(a), insert description: String) -> Task(
  a,
)

Returns a new Task with the given short documentation string.

sort

</>

pub fn sort(tasks: List(Task(Result(String, Snag)))) -> List(
  Task(Result(String, Snag)),
)

Sort Tasks alphabetically by path.

targets

</>

pub fn targets() -> Iterable(a)

Returns an Iterable that tells a Runner how to run for each compilation target.

An Iterable can be attached to a given Task using the for builder function.

tasks_from_config

</>

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

Parses gleam.toml for tasks defined in the [[rad.tasks]] table array.

A defined Task must have path and run key/values, and may optionally have a shortdoc key/value.

trainer

</>

pub fn trainer(runner: fn(
    CommandInput,
    Task(Result(String, Snag)),
  ) -> Result(String, Snag)) -> fn(
  CommandInput,
  Task(Result(String, Snag)),
) -> Result(String, Snag)

Returns a Runner that works with a given runner to run its Task one or more times.

If the Task contains an Iterable, all runs are attempted regardless of any failures along the way; however, the end Result will only be successful if no errors are produced.

Trainer runners are used for tasks defined in a Workbook.

with_config

</>

pub fn with_config(task: Task(a)) -> Task(a)

Returns a new Task that wants the gleam.toml configuration file’s Parsed Toml data, to be used by the Task’s Runner.

Note that a Runner will need to handle this requirement at runtime in order to succeed. A trainer does this for its Runner automatically.

with_manifest

</>

pub fn with_manifest(task: Task(a)) -> Task(a)

Returns a new Task that wants the manifest.toml file’s Parsed Toml data, to be used by the Task’s Runner.

Note that a Runner will need to handle this requirement at runtime in order to succeed. A trainer does this for its Runner automatically.