Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/lispyclouds/bblgum

An extremely tiny and simple wrapper around charmbracelet/gum
https://github.com/lispyclouds/bblgum

babashka charmbracelet charmcli clojure gum tui

Last synced: 6 days ago
JSON representation

An extremely tiny and simple wrapper around charmbracelet/gum

Awesome Lists containing this project

README 

        
# bblgum



[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg?style=flat)](https://choosealicense.com/licenses/mit/)

[![bb compatible](https://raw.githubusercontent.com/babashka/babashka/master/logo/badge.svg)](https://babashka.org)



An _extremely_ tiny and simple wrapper around the awesome [gum](https://github.com/charmbracelet/gum).



This is intended for [babashka](https://babashka.org/) and JVM clojure and provides an idiomatic and data driven wrapper around the CLI tool.



## Requirements

- Gum should be [installed](https://github.com/charmbracelet/gum#installation)

- Babashka or the Clojure JVM runtime, latest recommended



## Usage



Add this to your `bb.edn` or `deps.edn`:

```edn

{:deps {io.github.lispyclouds/bblgum {:git/sha "1d4de3d49b84f64d1b71930fa1161f8d2622a4d9"}}}

```



Sample babashka usage:

```console

$ bb -Sdeps '{:deps {io.github.lispyclouds/bblgum {:git/sha "1d4de3d49b84f64d1b71930fa1161f8d2622a4d9"}}}' \

     -e "(require '[bblgum.core :as b]) (b/gum :input :placeholder \"User name:\")"

```



## Interaction



This follows the same [section](https://github.com/charmbracelet/gum#interaction) on the gum repo and all params should work verbatim.

Run `gum  --help` to discover all the params and args.



This lib only has _one_ public fn: `bblgum.core/gum`.



## Standard Usage

`gum` tries to closely mimic the usage of the CLI tool, so it works like `(gum :COMMAND)`,

`(gum :COMMAND [ARGS])` or `(gum :COMMAND [ARGS] :OPTION VALUE :OPTION2 VALUE)`



```clojure

(require '[bblgum.core :as b])

```



Examples:

```clojure

;; Command only:

(b/gum :file)



;; Command with args:

(b/gum :choose ["arg1" "arg2"])



;; Command with opts:

(b/gum :file :directory true)



;; Command with opts and args:

(b/gum :choose ["arg1" "arg2"] :header "Choose an option")

```



There are several special opts, that are handled by the library:



- `:in`: An input stream than can be passed to gum

- `:as`: Coerce the output. Currently supports :bool, :ignored or defaults to a seq of strings

- `:gum-path`: Path to the gum binary. Defaults to `gum`



All other opts are passed to the CLI. Consult `gum CMD --help` to see available options.

To pass flags like `--directory` use `:directory true`. **Always use full names of the options**.



**Note**: In the event of a name collision with a special opt and a command opt, use the [low level API](https://github.com/lispyclouds/bblgum#low-level-api).



Example with special options:

```clojure

(gum :table :in (clojure.java.io/input-stream f) :height 10)

```



### Usage Examples



#### input

```clojure

(b/gum :choose ["foo" "bar" "baz"] :no-limit true)



{:status 0 :result ("foo" "baz")}

```



#### write

```clojure

(b/gum :write)

```



#### filter

```clojure

(b/gum :filter :in (clojure.java.io/input-stream "flavours.txt"))



(b/gum :filter :in (clojure.java.io/input-stream "flavours.txt") :no-limit true)



;; Since bblgum uses babashka/process, the following are possible as well

(b/gum :filter :in "a string that will be streamed into the stdin char by char")



(b/gum :filter :in (clojure.string/join "\n" ["can" "be" "used" "as" "a" "filtering" "choose" "alternative"]))

```



#### confirm



```clojure

(b/gum :confirm :as  :bool)

```



#### file



```clojure

(b/gum :file ["src"])

```



#### pager



```clojure

(b/gum :pager :as :ignored :in (clojure.java.io/input-stream "README.md"))

```



#### spin



```clojure

(b/gum :spin ["sleep" "5"] :spinner "line" :title "Buying Bubble Gum...")

```



#### table



```clojure

(b/gum :table :in (clojure.java.io/input-stream "flavours.csv"))

```



All of the rest of the options and usecases _should work_ ™. Please raise issues/PRs for any improvements. Much appreciated!



## Caveats



- Since this uses gum which expects an interactive TTY like terminal, this is not possible to be used from editor REPLs like Conjure, CIDER, Calva etc **when jacked-in**.

  To use this from an editor REPL:

    - First start the REPL in a terminal, for example in bb for nREPL on port 1667: `bb nrepl-server 1667`.

    - Connect to the port from the editor of your choice, for example with neovim and conjure: `:ConjureConnect 1667`.

    - Perform the usual REPL interactions and all the gum output would appear on the terminal and not your editor but the result should be on the editor as expected.



## Low-level API

This was standard in previous versions of gum, we kept it for full backward compatibility.



Convention:

- The main command should be passed as a keyword or string to `:cmd`. Required

- Passing opts:

  - The --opts are to be passed as `:opts`

  - Use the full forms of the opts: `--spinner` not `-s`

  - Seqs can be passed to opts taking multiple params as well

  - Pass boolean flags like `--password` as `{:password true}`

- All positional args to be passed as `:args`.

- An input stream can be passed to `:in`. Useful for commands like [filter](https://github.com/charmbracelet/gum#filter)

- Corece the output:

  - Treat non-zero exit codes from gum as a booleans passing `:as :bool`

  - Ignore it with `:ignored`. This ignores parsing of the stdout

  - `:bool` is useful for commands like [confirm](https://github.com/charmbracelet/gum#confirm)

  - `:ignored` is useful for [pager](https://github.com/charmbracelet/gum#pager). Ignoring the parsing of the output helps the pager actually draw things

  - Defaults to a seq of strings

- Override the default gum path of `gum` by passing it via `:gum-path`



The `gum` fn returns a map of exit status of calling gum and the result either as a seq of lines or coerced via `:as`.

Exceptions are not thrown unless calling gum itself does, the status code is intended for programming for failures.



```clojure

(b/gum {:cmd :choose

        :opts {:no-limit true}

        :args ["foo" "bar" "baz"]})



{:status 0 :result ("foo" "baz")}

```



## License



Copyright © 2023- Rahul De.



Distributed under the MIT License. See LICENSE.