kindly - v0.1.0

kindly

Provides Kindly’s main API for defining, selecting, and running project tasks through a Handbook.

When run as an app, Kindly finds the current project’s Handbook, or interactively offers to create a new one, and runs selected tasks from it.

Types

Handbook

opaque </>

The main Kindly data type, a named collection of tasks.

pub opaque type Handbook

IoStream

</>

A type for referring to Standard IO streams.

pub type IoStream {
  Stdin
  Stdout
  Stderr
}

Constructors 

  • Stdin
  • Stdout
  • Stderr

Never

</>

A type that never returns.

pub type Never

Promise

</>

A JavaScript Promise, re-exported from gleam_javascript for convenience.

For further information view the MDN documentation.

pub type Promise(a) =
  promise.Promise(a)

Task

</>

The main Kindly unit type.

pub type Task {
  Task(
    doc: String,
    tags: set.Set(String),
    action: fn(List(String), List(Task)) -> promise.Promise(
      Result(Nil, Nil),
    ),
    group_doc: option.Option(String),
  )
}

Constructors

Theme

</>

A type for styles applied to Kindly output.

pub type Theme {
  Theme(
    highlight: fn(String) -> String,
    heading: fn(String) -> String,
    tag: fn(String) -> String,
    first_tag: fn(String) -> String,
    given_tag: fn(String) -> String,
    flag: fn(String) -> String,
    parameter: fn(String) -> String,
    time: fn(String) -> String,
    tab: String,
  )
}

Constructors 

  • Theme(
  highlight: fn(String) -> String,
  heading: fn(String) -> String,
  tag: fn(String) -> String,
  first_tag: fn(String) -> String,
  given_tag: fn(String) -> String,
  flag: fn(String) -> String,
  parameter: fn(String) -> String,
  time: fn(String) -> String,
  tab: String,
)

Values

ansi

</> 
pub fn ansi(
  to content: String,
  apply styles: List(Int),
) -> String

Returns the given content with ANSI styles applied, ending with a style reset.

Returns the given content unstyled when the NO_COLOR or NO_COLOUR environment variable is truthy; likewise, if kindly’s output is piped, unless the COLOR or COLOUR environment variable is always.

command

</> 
pub fn command(
  run bin: String,
  with args: List(String),
) -> promise.Promise(Result(Nil, Nil))

Runs the given external binary with any given arguments.

The command is executed as transparently as possible (capturing nothing).

Returns a Result(Nil, Nil) indicating the command’s success.

command_step

</> 
pub fn command_step(
  run bin: String,
  with args: List(String),
  then do: fn() -> promise.Promise(Result(Nil, Nil)),
) -> promise.Promise(Result(Nil, Nil))

Combines step and command, enabling function chains akin to shell && sequences.

default_theme

</> 
pub fn default_theme() -> Theme

Returns Kindly’s default display Theme.

This theme uses a selection of the terminal’s configured colours.

get_env

</> 
pub fn get_env(name name: String) -> Result(String, Nil)

Results in the value of the given environment variable on success, or Nil if the variable is unset.

gleam_theme

</> 
pub fn gleam_theme() -> Theme

Returns a Gleam-inspired Theme.

group

</> 
pub fn group(
  handbook: Handbook,
  doc doc: String,
  tags group_tags: List(String),
  apply f: fn(Handbook) -> Handbook,
) -> Handbook

Adds a Task group to the Handbook.

Kindly’s main help menu compresses the display of grouped tasks under the given doc and prepends the given group_tags for all grouped tasks.

Conceptually similar to map, but with the aforementioned structural conveniences.

handbook

</> 
pub fn handbook(for name: String) -> Handbook

Returns a new Kindly Handbook with the given project name.

is_terminal

</> 
pub fn is_terminal(io_stream: IoStream) -> Bool

Returns a Bool indicating whether the given Standard IO stream is a terminal (TTY).

just

</> 
pub fn just(
  run bin: String,
  with args: List(String),
) -> fn(a) -> promise.Promise(Result(Nil, Nil))

Returns a function that discards its input and just runs command with the given arguments.

map

</> 
pub fn map(
  handbook: Handbook,
  with f: fn(Handbook) -> Handbook,
) -> Handbook

Modifies the Handbook with the given function.

Can be used in the main Handbook builder pipeline, for example, to keep tasks together with logic used to generate them.

now

</> 
pub fn now() -> Int

Returns a monotonic timestamp for the current time in milliseconds, rounded down.

plain_theme

</> 
pub fn plain_theme() -> Theme

Returns a Theme that uses the terminal’s default display style.

reject

</> 
pub fn reject() -> promise.Promise(Result(Nil, Nil))

Promises to return an Error(Nil) result. Useful for ending a multistep Task in failure.

resolve

</> 
pub fn resolve() -> promise.Promise(Result(Nil, Nil))

Promises to return an Ok(Nil) result. Useful for ending a multistep Task successfully.

set_env

</> 
pub fn set_env(name name: String, value value: String) -> Nil

Sets an environment variable to the given value.

step

</> 
pub fn step(
  f: fn() -> promise.Promise(Result(a, b)),
  then do: fn(a) -> promise.Promise(Result(c, d)),
) -> promise.Promise(Result(c, Nil))

Calls and awaits the given function’s Result. On success, promises to return the callback function’s Result. If either Result is an Error, an Error(Nil) is promised instead.

Enables chaining function calls such that each step can only run after the previous step succeeded.

styler

</> 
pub fn styler(
  will_apply styles: List(Int),
) -> fn(String) -> String

Returns a function that styles a String with the given ANSI codes.

task

</> 
pub fn task(
  handbook: Handbook,
  doc doc: String,
  tags tags: List(String),
  action action: fn(List(String)) -> promise.Promise(
    Result(Nil, Nil),
  ),
) -> Handbook

Adds a Task to the Handbook.

The given action is provided a List of argument strings and must return a Promise(Result(Nil, Nil)) indicating success.

task_with_tasks

</> 
pub fn task_with_tasks(
  handbook: Handbook,
  doc doc: String,
  tags tags: List(String),
  action action: fn(List(String), List(Task)) -> promise.Promise(
    Result(Nil, Nil),
  ),
) -> Handbook

Adds a Task to the Handbook, differing from a standard task in that its action is given the handbook’s complete list of tasks in addition to any runtime arguments.

As with task, the given action is also provided a List of argument strings and must return a Promise(Result(Nil, Nil)) indicating success.

theme

</> 
pub fn theme(handbook: Handbook, with theme: Theme) -> Handbook

Applies the given Theme to Kindly output.

unset_env

</> 
pub fn unset_env(name name: String) -> Nil

Ensures the given environment variable is no longer set.

✨ Search Document