glint

Types

ArgsCount

Specify the expected number of 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 arguments
```
MinArgs(Int)
```
Specifies that a command must accept a minimum number of arguments

Command

</>

A glint command

pub opaque type Command(a)

Constraint

</>

Constraint type for verifying flag values

pub type Constraint(a) =
  fn(a) -> SnagResult(a)

Flag

</>

A type that facilitates the creation of FlagEntrys

pub opaque type Flag(a)

Flags

</>

FlagEntry names and their associated values

pub opaque type Flags

Glint

</>

Glint container type for config and commands

pub opaque type Glint(a)

NamedArgs

</>

pub opaque type NamedArgs

Out

</>

Ok type for command execution

pub type Out(a) {
  Out(a)
  Help(String)
}

Constructors

```
Out(a)
```
Container for the command return value
```
Help(String)
```
Container for the generated help string

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)

Result

</>

SnagResult type for command execution

pub type Result(a) =
  gleam.Result(Out(a), String)

Runner

</>

Functions that execute as part of glint commands.

Named Arguments that a command expects will be present in the first parameter and accessible by .

Flags passed to glint are provided as the flags field.

Function type to be run by glint.

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

Functions

add

</>

pub fn add(
  to glint: Glint(a),
  at path: List(String),
  do contents: 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.

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_help

</>

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

Attach a helptext description to a Command(a)

default_pretty_help

</>

pub fn default_pretty_help() -> PrettyHelp

Default pretty help heading colouring 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

each

</>

pub fn each(
  constraint: fn(a) -> Result(a, Snag),
) -> fn(List(a)) -> Result(List(a), Snag)

each is a convenience function for applying a Constraint(a) to a List(a). This is useful because the default behaviour for constraints on lists is that they will apply to the list as a whole.

For example, to apply one_of to all items in a List(Int):

[1, 2, 3, 4] |> one_of |> each

execute

</>

pub fn execute(
  glint: Glint(a),
  args: List(String),
) -> Result(Out(a), String)

Determines which command to run and executes it.

Sets any provided flags if necessary.

Each value prefixed with -- is parsed as a flag.

This function does not print its output and is mainly intended for use within glint itself. If you would like to print or handle the output of a command please see the run_and_handle function.

get_bool

</>

pub fn get_bool(
  from flags: Flags,
  for name: String,
) -> Result(Bool, Snag)

Gets the current value for the associated bool flag

get_float

</>

pub fn get_float(
  from flags: Flags,
  for name: String,
) -> Result(Float, Snag)

Gets the current value for the associated float flag

get_floats

</>

pub fn get_floats(
  from flags: Flags,
  for name: String,
) -> Result(List(Float), Snag)

Gets the current value for the associated floats flag

get_int

</>

pub fn get_int(
  from flags: Flags,
  for name: String,
) -> Result(Int, Snag)

Gets the current value for the associated int flag

get_ints

</>

pub fn get_ints(
  from flags: Flags,
  for name: String,
) -> Result(List(Int), Snag)

Gets the current value for the associated ints flag

get_string

</>

pub fn get_string(
  from flags: Flags,
  for name: String,
) -> Result(String, Snag)

Gets the current value for the associated string flag

get_strings

</>

pub fn get_strings(
  from flags: Flags,
  for name: String,
) -> Result(List(String), Snag)

Gets the current value for the associated strings flag

group_flag

</>

pub fn group_flag(
  in glint: Glint(a),
  at path: List(String),
  for name: 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

name

</>

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

Give the current glint application a name

named_arg

</>

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

Add a list of named arguments to a Command These named arguments will be matched with the first N arguments passed to the command All named arguments must match for a command to succeed This works in combination with CommandInput.named_args which will contain the matched args in a Dict(String,String)

IMPORTANT: Matched named arguments will not be present in CommandInput.args

new

</>

pub fn new() -> Glint(a)

Creates a new command tree.

none_of

</>

pub fn none_of(disallowed: List(a)) -> fn(a) -> Result(a, Snag)

none_of returns a Constraint that ensures the parsed flag value is not one of the disallowed values.

one_of

</>

pub fn one_of(allowed: List(a)) -> fn(a) -> Result(a, Snag)

one_of returns a Constraint that ensures the parsed flag value is one of the allowed values.

pretty_help

</>

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

Enable custom colours for help text headers For a pre-made colouring use default_pretty_help()

run

</>

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

A wrapper for execute that prints 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 something with the command output please see the run_and_handle function.

run_and_handle

</>

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

A wrapper for execute that prints any errors enountered or the help text if requested. This function calls the provided handler with the value returned by the command that was run.

string

</>

pub fn string() -> Flag(String)

initialise a string flag builder

strings

</>

pub fn strings() -> Flag(List(String))

intitialise a string list flag builder

unnamed_args

</>

pub fn unnamed_args(
  args: ArgsCount,
  f: fn() -> Command(a),
) -> Command(a)

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

update_flags

</>

pub fn update_flags(
  in flags: Flags,
  with flag_input: String,
) -> Result(Flags, Snag)

Updates a flag value, ensuring that the new value can satisfy the required type. Assumes that all flag inputs passed in start with – This function is only intended to be used from glint.execute_root