https://github.com/drewolson/clip

A CLI option parser for Gleam
https://github.com/drewolson/clip

Last synced: about 1 month ago
JSON representation

A CLI option parser for Gleam

• Host: GitHub
• URL: https://github.com/drewolson/clip
• Owner: drewolson
• License: other
• Created: 2024-09-10T13:02:07.000Z (3 months ago)
• Default Branch: main
• Last Pushed: 2024-10-23T23:06:38.000Z (about 2 months ago)
• Last Synced: 2024-10-24T12:24:06.122Z (about 2 months ago)
• Language: Gleam
• Homepage:
• Size: 61.5 KB
• Stars: 17
• Watchers: 1
• Forks: 3
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md
  • License: LICENSE

Awesome Lists containing this project

• awesome-gleam - clip - [📚](https://hexdocs.pm/clip/) - A CLI Option Parser for Gleam (Packages / Command Line)

README

        
# clip - A CLI option parser for Gleam

[![Package Version](https://img.shields.io/hexpm/v/clip)](https://hex.pm/packages/clip)

[![Hex Docs](https://img.shields.io/badge/hex-docs-ffaff3)](https://hexdocs.pm/clip/)

`clip` is a library for parsing command line interface options.

## Simple Example

```gleam

import argv

import clip

import clip/help

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.help(help.simple("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:

1. First, invoke `clip.command` providing a function to be called with your

   parsed options. This function can be built using the

   [parameter syntax](https://github.com/drewolson/clip/tree/main/examples/parameter-syntax).

   Alternatively, you can directly provide a curried function, meaning a two argument

   function looks like `fn(a) { fn(b) { do_stuff(a, b) } }`.

2. Next, use the `|>` operator along with `clip.opt`, `clip.flag`, and

   `clip.arg` to parse command line arguments and provide them as parameters to

   the function given to `clip.command`.

3. Optionally use `clip.help` and `clip/help` to generate help text for your

   command. The user can view this help text via the `--help,-h` flag.

4. Finally, run your parser with `clip.run`, giving it the command you have

   built and the list arguments to parse. I recommend using the `argv` library

   to access these arguments from both erlang and javascript.

## Types of Options

`clip` provides three types of options:

1. An `Option` is a named option with a value, like `--name "Drew"`. You create

   `Option`s with the `clip/opt` module and add them to your command with the

   `clip.opt` function.

2. A `Flag` is a named option without a value, like `--verbose`. If provided, it

   produces `True`, if not provided it produces `False`. You create `Flag`s with

   the `clip/flag` module and add them to your command with the `clip.flag`

   function.

3. An `Argument` is a positional value passed to your command. You create

   `Argument`s with the `clip/arg` module and add them to your command with the

   `clip.arg`, `clip.arg_many`, and `clip.arg_many1` functions.

Take a look at the

[examples](https://github.com/drewolson/clip/tree/main/examples) for more information.