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(fn(name) { fn(age) { 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
, we follow these
steps:
- First, we invoke
clip.command
, providing a function to be called with our parsed options. This function needs to be provided in a curried style, meaning a two argument function looks likefn(a) { fn(b) { do_stuff(a, b) } }
. - We use the
|>
operator along withclip.opt
,clip.flag
, andclip.arg
to parse our command line arguments and provide them as parameters to the function given toclip.command
. - We use
clip.add_help
to generate help text for our command. The user can view this help text via the--help,-h
flag. - Finally, we run our parser with
clip.run
, giving it the command we have built and the arguments to parse. We recommend using theargv
library to access these arguments for 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 create these with theclip/opt
module and add them to your command with theclip.opt
function. - A
Flag
is an option without a value, like--verbose
. If provided, it producesTrue
, if not provided it producesFalse
. You create these 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 create these 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.