glint

Types

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

Result type for command execution

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

A glint command

pub opaque type Command(a)

The input type for Runner.

Arguments passed to glint are provided as the args field.

Flags passed to glint are provided as the flags field.

If named arguments are specified at command creation, they will be accessible via the named_args field. IMPORTANT: Arguments matched by named_args will not be present in the args field.

pub type CommandInput {
  CommandInput(
    args: List(String),
    flags: FlagMap,
    named_args: dict.Dict(String, String),
  )
}

Constructors

  • CommandInput(
      args: List(String),
      flags: FlagMap,
      named_args: dict.Dict(String, String),
    )

Config for glint

pub type Config {
  Config(
    pretty_help: Option(PrettyHelp),
    name: Option(String),
    as_gleam_module: Bool,
  )
}

Constructors

  • Config(
      pretty_help: Option(PrettyHelp),
      name: Option(String),
      as_gleam_module: Bool,
    )

Glint container type for config and commands

pub opaque type Glint(a)

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 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)

Function type to be run by glint.

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

Constants

pub const default_config: Config = Config(
  pretty_help: None,
  name: None,
  as_gleam_module: False,
)

Default config

Functions

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.

pub fn as_gleam_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>

pub fn command(do runner: fn(CommandInput) -> a) -> Command(a)

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

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

pub fn description(
  cmd: Command(a),
  description: String,
) -> Command(a)

Attach a description to a Command(a)

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.

pub fn flag(
  cmd: Command(a),
  at key: String,
  of flag: FlagBuilder(b),
) -> Command(a)

Add a flag.Flag to a Command

pub fn flag_tuple(
  cmd: Command(a),
  with tup: #(String, FlagBuilder(b)),
) -> Command(a)

Add a flag.Flag to a Command` when the flag name and builder are bundled as a #(String, flag.FlagBuilder(a)).

This is merely a convenience function and calls glint.flag under the hood.

pub fn flags(
  cmd: Command(a),
  with flags: List(#(String, Flag)),
) -> Command(a)

Add multiple Flags to a Command, note that this function uses Flag and not FlagBuilder(_). The user will need to call flag.build before providing the flags here.

It is recommended to call glint.flag instead.

pub fn global_flag(
  glint: Glint(a),
  at key: String,
  of flag: FlagBuilder(b),
) -> Glint(a)

Deprecated: use group_flag with a path parameter of [] instead

Add global flags to the existing command tree This is the equivalent to calling glint.group_flag with a path parameter of [].

pub fn global_flag_tuple(
  glint: Glint(a),
  with tup: #(String, FlagBuilder(b)),
) -> Glint(a)

Deprecated: use group_flag_tuple with a path parameter of [] instead

Add global flags to the existing command tree. This is the equivalent to calling glint.group_flag_tuple with a path parameter of [].

pub fn global_flags(
  glint: Glint(a),
  flags: List(#(String, Flag)),
) -> Glint(a)

Deprecated: use group_flags with a path parameter of [] instead

Add global flags to the existing command tree.

Like glint.flags, this function requires Flags insead of FlagBuilder(_). This is the equivalent to calling glint.group_flags with a path parameter of [].

Note: use of this function requires calling flag.build yourself on any flag.FlagBuilders you wish to convert to flag.Flags It is recommended to use glint.global_flag instead.

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

pub fn group_flag_tuple(
  in glint: Glint(a),
  at path: List(String),
  of flag: #(String, FlagBuilder(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

This is a convenience function and calls glint.group_flag under the hood.

pub fn group_flags(
  in glint: Glint(a),
  at path: List(String),
  with flags: List(#(String, Flag)),
) -> Glint(a)

Add flags for groups of commands. It is recommended to use glint.group_flag instead if possible

The provided flags will be available to all commands at or beyond the provided path

Note: use of this function requires calling flag.build yourself on any flag.FlagBuilders you wish to convert to flag.Flags

pub fn help_flag() -> String

Function to create the help flag string Exported for testing purposes only

pub fn named_args(
  cmd: Command(a),
  args: List(String),
) -> 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

pub fn new() -> Glint(a)

Creates a new command tree.

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.

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.

pub fn unnamed_args(
  cmd: Command(a),
  count: ArgsCount,
) -> Command(a)

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

pub fn with_config(glint: Glint(a), config: Config) -> Glint(a)

Add the provided config to the existing command tree

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

Give the current glint application a name

pub fn with_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()

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

Disable custom colours for help text headers

Search Document