Repository files navigation

Anextremely tiny and simple wrapper around the awesomegum.

This is intended forbabashka and JVM clojure and provides an idiomatic and data driven wrapper around the CLI tool.

• Gum should beinstalled
• Babashka or the Clojure JVM runtime, latest recommended

Add this to yourbb.edn ordeps.edn:

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

Sample babashka usage:

bb -Sdeps '{:deps {io.github.lispyclouds/bblgum {:git/sha "df647fb50f32e05b26e46e58d7249b4798e469e6"}}}' \   -e "(require '[bblgum.core :as b]) (b/gum :input :placeholder \"User name:\")"

This follows the samesection on the gum repo and all params should work verbatim.Rungum <cmd> --help to discover all the params and args.

This lib only hasone public fn:bblgum.core/gum.

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)

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

Examples:

;; Command only:(b/gum:file);; Command with args:(b/gum:choose ["arg1""arg2"]);; Command with opts:(b/gum:file:directorytrue);; 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 togum

All other opts are passed to the CLI. Consultgum 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 thelow level API.

Example with special options:

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

(b/gum:choose ["foo""bar""baz"]:no-limittrue){:status0:result ("foo""baz")}

(b/gum:write)

(b/gum:filter:in (clojure.java.io/input-stream"flavours.txt"))(b/gum:filter:in (clojure.java.io/input-stream"flavours.txt"):no-limittrue);; 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"]))

(b/gum:confirm:as:bool)

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

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

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

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

All of the rest of the options and usecasesshould work ™. Please raise issues/PRs for any improvements. Much appreciated!

• 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 etcwhen 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.

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 likefilter
• 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 likeconfirm
  • :ignored is useful forpager. Ignoring the parsing of the output helps the pager actually draw things
  • Defaults to a seq of strings
• Override the default gum path ofgum by passing it via:gum-path

Thegum 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.

(b/gum {:cmd:choose:opts {:no-limittrue}:args ["foo""bar""baz"]}){:status0:result ("foo""baz")}

Copyright © 2023- Rahul De.

Distributed under the MIT License. See LICENSE.