Warning
This README is being updated in preparation for glint v1.0.0. For documentation on the latest released glint versions please see hexdocs.
Gleam command-line argument parsing with flags and automatic help text.
To install from hex:
gleam add glintGlint has 3 main concepts (see below for more details): glint itself, commands and flags.
The general workflow involves
- creating a new glint instance with
glint.new - configuring it
- creating commands with
glint.command- attach flags with
glint.flag - set named args with
glint.named_arg - set unnamed args with
glint.unnamed_args
- attach flags with
- attach the commands to glint with
glint.add - run your glint app with
glint.runorglint.run_and_handle
Note:Help text is generated and printed whenever a glint command is called with the built-in flag --help. It is also printed after the error text when any errors are encountered due to invalid flags or arguments.
Help text descriptions can be attached to all of glint's components:
- attach global help text with
glint.global_help - attach comand help text with
glint.command_help - attach flag help text with
glint.flag_help - attach help text to a non-initialized command with
glint.path_help
You can import glint as a dependency and use it to build command-line applications like the following simplified version of the the hello world example.
// stdlib imports
import gleam/io
import gleam/list
import gleam/result
import gleam/string.{uppercase}
// external dep imports
import snag
import argv
// glint imports
import glint
// this function returns the builder for the caps flag
fn caps_flag() -> glint.Flag(Bool) {
// create a new boolean flag with key "caps"
// this flag will be called as --caps=true (or simply --caps as glint handles boolean flags in a bit of a special manner) from the command line
glint.bool_flag("caps")
// set the flag default value to False
|> glint.flag_default(False)
// set the flag help text
|> glint.flag_help("Capitalize the hello message")
}
/// the glint command that will be executed
///
fn hello() -> glint.Command(Nil) {
// set the help text for the hello command
use <- glint.command_help("Prints Hello, <NAME>!")
// register the caps flag with the command
// the `caps` variable there is a type-safe getter for the flag value
use caps <- glint.flag(caps_flag())
// start the body of the command
// this is what will be executed when the command is called
use _, args, flags <- glint.command()
// we can assert here because the caps flag has a default
// and will therefore always have a value assigned to it
let assert Ok(caps) = caps(flags)
// this is where the business logic of our command starts
let name = case args {
[] -> "Joe"
[name,..] -> name
}
let msg = "Hello, " <> name <> "!"
case caps {
True -> uppercase(msg)
False -> msg
}
|> io.println
}
pub fn main() {
// create a new glint instance
glint.new()
// with an app name of "hello", this is used when printing help text
|> glint.with_name("hello")
// with pretty help enabled, using the built-in colours
|> glint.with_pretty_help(glint.default_pretty_help())
// with a root command that executes the `hello` function
|> glint.add(at: [], do: hello)
// execute given arguments from stdin
|> glint.run(argv.load().arguments)
}glint is conceptually quite small, your general flow will be:
- create a new glint instance with
glint.new. - configure glint with functions like
glint.with_pretty_help. - add commands with
glint.add. - run your cli with
glint.run, run with a function to handle command output withglint.run_and_handle.
Note: Glint commands are most easily set up by chaining functions with use. (See the above example)
- Create a new command with
glint.command. - Set the command description with
glint.command_help. - Add a flag to a command with
glint.flag. - Create a named argumend with
glint.named_arg. - Set the expectation for unnamed args with
glint.unnamed_args.
Glint flags are a type-safe way to provide options to your commands.
-
Create a new flag with a typed flag constructor function:
glint.int_flag:glint.Flag(Int)glint.ints_flag:glint.Flag(List(Int))glint.float_flag:glint.Flag(Float)glint.floats_flag:glint.Flag(List(Floats))glint.string_flag:glint.Flag(String)glint.strings_flag:glint.Flag(List(String))glint.bool_flag:glint.Flag(Bool)
-
Set the flag description with
glint.flag_help -
Set the flag default value with
glint.flag_default, note: it is safe to uselet assertwhen fetching values for flags with default values. -
Add a flag to a command with
glint.flag. -
Add a
constraint.Constraint(a)to aglint.Flag(a)withglint.flag_constraint
Constraints are functions of shape fn(a) -> Result(a, snag.Snag) that are executed after a flag value has been successfully parsed, all constraints applied to a flag must succeed for that flag to be successfully processed.
Constraints can be any function so long as it satisfies the required type signature, and are useful for ensuring that data is correctly shaped before your glint commands are executed. This reduces unnecessary checks polluting the business logic of your commands.
Here is an example of a constraint that guarantees a processed integer flag will be a positive number.
Note that constraints can both nicely be set up via pipes (|>) or with use.
import glint
import snag
// ...
// with pipes
glint.int_flag("my_int")
|> glint.flag_default(0)
|> glint.constraint(fn(i){
case i < 0 {
True -> snag.error("cannot be negative")
False -> Ok(i)
}
})
// or
// with use
use i <- glint.flag_constraint(
glint.int_flag("my_int")
|> glint.flag_default(0)
)
case i < 0 {
True -> snag.error("cannot be negative")
False -> Ok(i)
}The glint/constraint module provides a few helpful utilities for applying constraints, namely
constraint.one_of: ensures that a value is one of some list of allowed values.constraint.none_of: ensures that a value is not one of some list of disallowed values.constraint.each: applies a constraint on individual items in a list of values (useful for applying constraints likeone_ofandnone_ofto lists.
The following example demonstrates how to constrain a glint.Flag(List(Int)) to only allow the values 1, 2, 3 or 4 by combining constraint.each with constraint.one_of
import glint
import glint/constraint
import snag
// ...
glint.ints_flag("my_ints")
|> glint.flag_default([])
|> glint.flag_constraint(
[1, 2, 3, 4]
|> constraint.one_of
|> constraint.each
)Glint works amazingly with these other packages:
- argv, use this for cross-platform argument fetching
- gleescript, use this to generate erlang escripts for your applications
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent