clip - A CLI option parser for Gleam
clip
is a library for parsing command line interface options.
Simple Example
import argv
import clip
import clip/opt
import gleam/io
import gleam/string
type Person {
Person(name: String, age: Int)
}
fn command() {
clip.command({
use name <- clip.parameter
use age <- clip.parameter
Person(name, age)
})
|> clip.opt(opt.new("name") |> opt.help("Your name"))
|> clip.opt(opt.new("age") |> opt.int |> opt.help("Your age"))
}
pub fn main() {
let result =
command()
|> clip.add_help("person", "Create a person")
|> clip.run(argv.load().arguments)
case result {
Error(e) -> io.println_error(e)
Ok(person) -> person |> string.inspect |> io.println
}
}
$ gleam run -- --help
Compiled in 0.00s
Running cli.main
person -- Create a person
Usage:
person [OPTIONS]
Options:
(--name NAME) Your name
(--age AGE) Your age
[--help,-h] Print this help
$ gleam run -- --name Drew --age 42
Compiled in 0.00s
Running cli.main
Person("Drew", 42)
Using clip
clip
is an “applicative style” options parser. To use clip
, follow these
steps:
- First, invoke
clip.command
providing a function to be called with your parsed options. This function can be built using the parameter syntax. Alternatively, you can directly provide a curried function, meaning a two argument function looks likefn(a) { fn(b) { do_stuff(a, b) } }
. - Next, use the
|>
operator along withclip.opt
,clip.flag
, andclip.arg
to parse command line arguments and provide them as parameters to the function given toclip.command
. - Optionally use
clip.add_help
to generate help text for your command. The user can view this help text via the--help,-h
flag. - Finally, run your parser with
clip.run
, giving it the command you have built and the list arguments to parse. I recommend using theargv
library to access these arguments from both erlang and javascript.
Types of Options
clip
provides three types of options:
- An
Option
is a named option with a value, like--name "Drew"
. You createOption
s with theclip/opt
module and add them to your command with theclip.opt
function. - A
Flag
is a named option without a value, like--verbose
. If provided, it producesTrue
, if not provided it producesFalse
. You createFlag
s with theclip/flag
module and add them to your command with theclip.flag
function. - An
Argument
is a positional value passed to your command. You createArgument
s with theclip/arg
module and add them to your command with theclip.arg
,clip.arg_many
, andclip.arg_many1
functions.
Take a look at the examples for more information.