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)
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, )
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)
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 Flag
s 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 Flag
s 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.FlagBuilder
s you wish to convert to flag.Flag
s
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.FlagBuilder
s you wish to convert to flag.Flag
s
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 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