glint

Types

ArgsCount

Specify the expected number of unnamed arguments with this type and the glint.unnamed_args function

pub type ArgsCount {
  EqArgs(Int)
  MinArgs(Int)
}

Constructors

```
EqArgs(Int)
```
Specifies that a command must accept a specific number of unnamed arguments
```
MinArgs(Int)
```
Specifies that a command must accept a minimum number of unnamed arguments

Command

opaque </>

The type representing a glint command.

To create a new command, use the glint.command funcion.

pub opaque type Command(a)

Flag

opaque </>

Glint’s typed flags.

Flags can be created using any of:

glint.int_flag
glint.ints_flag
glint.float_flag
glint.floats_flag
glint.string_flag
glint.strings_flag
glint.bool_flag

pub opaque type Flag(a)

Flags

opaque </>

Flags passed as input to a command.

pub opaque type Flags

Glint

opaque </>

A container type for config and commands.

This will be the main interaction point when setting up glint. To create a new one use glint.new.

pub opaque type Glint(a)

NamedArgs

opaque </>

A container for named arguments available to commands at runtime.

pub opaque type NamedArgs

PrettyHelp

</>

PrettyHelp defines the header colours to be used when styling help text

pub type PrettyHelp {
  PrettyHelp(usage: Colour, flags: Colour, subcommands: Colour)
}

Constructors

PrettyHelp(usage: Colour, flags: Colour, subcommands: Colour)

Runner

</>

Functions that execute when glint commands are run.

pub type Runner(a) =
  fn(NamedArgs, List(String), Flags) -> a

Functions

add

</>

pub fn add(
  to glint: Glint(a),
  at path: List(String),
  do command: Command(a),
) -> Glint(a)

Adds a new command to be run at the specified path.

If the path is [], the root command is set with the provided function and flags.

Note: all command paths are sanitized by stripping whitespace and removing any empty string elements.

glint.new()
|> glint.add(at: [], do: root_command())
|> glint.add(at: ["subcommand"], do: subcommand())
...

as_module

</>

pub fn as_module(glint: Glint(a)) -> Glint(a)

Adjust the generated help text to reflect that the current glint app should be run as a gleam module.

Use in conjunction with glint.with_name to get usage text output like gleam run -m <name>

command

</>

pub fn command(
  do runner: fn(NamedArgs, List(String), Flags) -> a,
) -> Command(a)

Create a Command(a) from a Runner(a).

Example:

use <- glint.command_help("Some awesome help text")
use named_arg <- glint.named_arg("some_arg")
use <- glint.unnamed_args(glint.EqArgs(0))
...
use named, unnamed, flags <- glint.command()
let my_arg = named_arg(named)
...

command_help

</>

pub fn command_help(
  of desc: String,
  with f: fn() -> Command(a),
) -> Command(a)

Attach a helptext description to a Command(a)

This function allows for user-supplied newlines in long text strings. Individual newline characters are instead converted to spaces. This is useful for developers to format their help text in a more readable way in the source code.

For formatted text to appear on a new line, use 2 newline characters. For formatted text to appear in a new paragraph, use 3 newline characters.

default_pretty_help

</>

pub fn default_pretty_help() -> PrettyHelp

Default colouring for help text.

mint (r: 182, g: 255, b: 234) colour for usage

pink (r: 255, g: 175, b: 243) colour for flags

buttercup (r: 252, g: 226, b: 174) colour for subcommands

flag

</>

pub fn flag(
  of flag: Flag(a),
  with f: fn(fn(Flags) -> Result(a, Snag)) -> Command(b),
) -> Command(b)

Add a Flag(a) to a Command(a)

The provided callback is provided a function to fetch the current flag fvalue from the command input Flags.

This function is most ergonomic as part of a use chain when building commands.

Example:

...
use repeat <- glint.flag(
  glint.int_flag("repeat")
  |> glint.flag_default(1)
  |> glint.flag_help("Repeat the message n-times")
)
...
use named, unnamed, flags <- glint.command()
let repeat_value = repeat(flags)

flag_constraint

</>

pub fn flag_constraint(
  builder: Flag(a),
  constraint: fn(a) -> Result(a, Snag),
) -> Flag(a)

Attach a constraint to a flag.

As constraints are just functions, this works well as both part of a pipeline or with use.

Pipe:

glint.int_flag("my_flag")
|> glint.flag_help("An awesome flag")
|> glint.flag_constraint(fn(i) {
  case i < 0 {
    True -> snag.error("must be greater than 0")
    False -> Ok(i)
  }})

Use:

use i <- glint.flag_constraint(
  glint.int_flag("my_flag")
  |> glint.flag_help("An awesome flag")
)
case i < 0 {
  True -> snag.error("must be greater than 0")
  False -> Ok(i)
}

flag_default

</>

pub fn flag_default(for flag: Flag(a), of default: a) -> Flag(a)

Set the default value for a flag.

Example:

glint.int_flag("awesome_flag")
|> glint.flag_default(1)

flag_help

</>

pub fn flag_help(
  for flag: Flag(a),
  of description: String,
) -> Flag(a)

Attach a help text description to a flag.

For formatted text to appear on a new line, use 2 newline characters. For formatted text to appear in a new paragraph, use 3 newline characters.

Example:

glint.int_flag("awesome_flag")
|> glint.flag_help("Some great text!")

float_flag

</>

pub fn float_flag(named name: String) -> Flag(Float)

Initialise a float flag.

floats_flag

</>

pub fn floats_flag(named name: String) -> Flag(List(Float))

Initialise a float list flag.

get_flag

</>

pub fn get_flag(
  from flags: Flags,
  for flag: Flag(a),
) -> Result(a, Snag)

Gets the value for the associated flag.

This function should only ever be used when fetching flags set at the group level. For local flags please use the getter functions provided when calling glint.flag.

global_help

</>

pub fn global_help(
  in glint: Glint(a),
  of description: String,
) -> Glint(a)

Set help text for the application as a whole.

Help text set with this function wil be printed at the top of the help text for every command. To set help text specifically for the root command please use glint.command_help or glint.path_help([],...)

For formatted text to appear on a new line, use 2 newline characters. For formatted text to appear in a new paragraph, use 3 newline characters.

group_flag

</>

pub fn group_flag(
  in glint: Glint(a),
  at path: List(String),
  of flag: Flag(b),
) -> Glint(a)

Add a flag for a group of commands. The provided flags will be available to all commands at or beyond the provided path

int_flag

</>

pub fn int_flag(named name: String) -> Flag(Int)

Initialise an int flag.

ints_flag

</>

pub fn ints_flag(named name: String) -> Flag(List(Int))

Initialise an int list flag.

named_arg

</>

pub fn named_arg(
  named name: String,
  with f: fn(fn(NamedArgs) -> String) -> Command(a),
) -> Command(a)

Add a list of named arguments to a Command(a). The value can be retrieved from the command’s NamedArgs

These named arguments will be matched with the first N arguments passed to the command.

IMPORTANT:

Matched named arguments will not be present in the commmand’s unnamed args list
All named arguments must match for a command to succeed.

Example:

...
use first_name <- glint.named_arg("first name")
...
use named, unnamed, flags <- glint.command()
let first = first_name(named)

new

</>

pub fn new() -> Glint(a)

Create a new glint instance.

path_help

</>

pub fn path_help(
  in glint: Glint(a),
  at path: List(String),
  put description: String,
) -> Glint(a)

Set the help text for a specific command path.

This function is intended to allow users to set the help text of commands that might not be directly instantiated, such as commands with no business logic associated to them but that have subcommands.

Using this function should almost never be necessary, in most cases you should use glint.command_help insstead.

pretty_help

</>

pub fn pretty_help(
  glint: Glint(a),
  pretty: PrettyHelp,
) -> Glint(a)

Enable custom colours for help text headers.

For a pre-made style, pass in glint.default_pretty_help

run

</>

pub fn run(from glint: Glint(a), for args: List(String)) -> Nil

Run a glint app and print any errors enountered, or the help text if requested. This function ignores any value returned by the command that was run. If you would like to do handle the command output please see the glint.run_and_handle function.

IMPORTANT: This function exits with code 1 if an error was encountered. If this behaviour is not desired please disable it with glint.without_exit

run_and_handle

</>

pub fn run_and_handle(
  from glint: Glint(a),
  for args: List(String),
  with handle: fn(a) -> b,
) -> Nil

Run a glint app with a custom handler for command output. This function prints any errors enountered or the help text if requested.

IMPORTANT: This function exits with code 1 if an error was encountered. If this behaviour is not desired please disable it with glint.without_exit

string_flag

</>

pub fn string_flag(named name: String) -> Flag(String)

Initialise a string flag.

strings_flag

</>

pub fn strings_flag(named name: String) -> Flag(List(String))

Intitialise a string list flag.

unnamed_args

</>

pub fn unnamed_args(
  of count: ArgsCount,
  with f: fn() -> Command(a),
) -> Command(a)

Specify a specific number of unnamed args that a given command expects.

Use in conjunction with glint.ArgsCount to specify either a minimum or a specific number of args.

Example:

...
// for a command that accets only 1 unnamed argument:
use <- glint.unnamed_args(glint.EqArgs(1))
...
named, unnamed, flags <- glint.command()
let assert Ok([arg]) = unnamed

with_column_gap

</>

pub fn with_column_gap(glint: Glint(a), gap: Int) -> Glint(a)

Adjusts the size of the gap between columns in the help output.

Default: 2.

with_indent_width

</>

pub fn with_indent_width(glint: Glint(a), width: Int) -> Glint(a)

Adjusts the indent width used to indent content under the usage, flags, and subcommands headings in the help output.

Default: 4.

with_max_output_width

</>

pub fn with_max_output_width(
  glint: Glint(a),
  width: Int,
) -> Glint(a)

Adjusts the output width at which help text will wrap onto a new line.

Default: 80.

with_min_first_column_width

</>

pub fn with_min_first_column_width(
  glint: Glint(a),
  width: Int,
) -> Glint(a)

Adjusts the minimum width of the column containing flag and command names in the help output.

Default: 20.

with_name

</>

pub fn with_name(glint: Glint(a), name: String) -> Glint(a)

Give the current glint application a name.

The name specified here is used when generating help text for the current glint instance.

without_exit

</>

pub fn without_exit(glint: Glint(a)) -> Glint(a)

By default, Glint exits with error status 1 when an error is encountered (eg. invalid flag or command not found)

Calling this function disables that feature.