{"id":13609210,"url":"https://github.com/lispyclouds/bblgum","last_synced_at":"2025-04-05T07:05:50.215Z","repository":{"id":65407287,"uuid":"591775358","full_name":"lispyclouds/bblgum","owner":"lispyclouds","description":"An extremely tiny and simple wrapper around charmbracelet/gum","archived":false,"fork":false,"pushed_at":"2025-03-18T07:58:54.000Z","size":35,"stargazers_count":154,"open_issues_count":0,"forks_count":5,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-03-29T06:08:46.146Z","etag":null,"topics":["babashka","charmbracelet","charmcli","clojure","gum","tui"],"latest_commit_sha":null,"homepage":"","language":"Clojure","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lispyclouds.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-01-21T20:33:13.000Z","updated_at":"2025-03-23T12:19:31.000Z","dependencies_parsed_at":"2025-02-12T09:12:34.255Z","dependency_job_id":"584a0178-3461-4ed0-ae75-76b68b7a9d78","html_url":"https://github.com/lispyclouds/bblgum","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lispyclouds%2Fbblgum","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lispyclouds%2Fbblgum/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lispyclouds%2Fbblgum/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lispyclouds%2Fbblgum/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lispyclouds","download_url":"https://codeload.github.com/lispyclouds/bblgum/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247299832,"owners_count":20916190,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["babashka","charmbracelet","charmcli","clojure","gum","tui"],"created_at":"2024-08-01T19:01:33.308Z","updated_at":"2025-04-05T07:05:50.209Z","avatar_url":"https://github.com/lispyclouds.png","language":"Clojure","funding_links":[],"categories":["Clojure"],"sub_categories":[],"readme":"# bblgum\n\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg?style=flat)](https://choosealicense.com/licenses/mit/)\n[![bb compatible](https://raw.githubusercontent.com/babashka/babashka/master/logo/badge.svg)](https://book.babashka.org#badges)\n\nAn _extremely_ tiny and simple wrapper around the awesome [gum](https://github.com/charmbracelet/gum).\n\nThis is intended for [babashka](https://babashka.org/) and JVM clojure and provides an idiomatic and data driven wrapper around the CLI tool.\n\n## Requirements\n- Gum should be [installed](https://github.com/charmbracelet/gum#installation)\n- Babashka or the Clojure JVM runtime, latest recommended\n\n## Usage\n\nAdd this to your `bb.edn` or `deps.edn`:\n```edn\n{:deps {io.github.lispyclouds/bblgum {:git/sha \"28efb3ce4c71738d0c3c9bdd965a291c5d3e7465\"}}}\n```\n\nSample babashka usage:\n```console\n$ bb -Sdeps '{:deps {io.github.lispyclouds/bblgum {:git/sha \"28efb3ce4c71738d0c3c9bdd965a291c5d3e7465\"}}}' \\\n     -e \"(require '[bblgum.core :as b]) (b/gum :input :placeholder \\\"User name:\\\")\"\n```\n\n## Interaction\n\nThis follows the same [section](https://github.com/charmbracelet/gum#interaction) on the gum repo and all params should work verbatim.\nRun `gum \u003ccmd\u003e --help` to discover all the params and args.\n\nThis lib only has _one_ public fn: `bblgum.core/gum`.\n\n## Standard Usage\n`gum` tries to closely mimic the usage of the CLI tool, so it works like `(gum :COMMAND)`,\n`(gum :COMMAND [ARGS])` or `(gum :COMMAND [ARGS] :OPTION VALUE :OPTION2 VALUE)`\n\n```clojure\n(require '[bblgum.core :as b])\n```\n\nExamples:\n```clojure\n;; Command only:\n(b/gum :file)\n\n;; Command with args:\n(b/gum :choose [\"arg1\" \"arg2\"])\n\n;; Command with opts:\n(b/gum :file :directory true)\n\n;; Command with opts and args:\n(b/gum :choose [\"arg1\" \"arg2\"] :header \"Choose an option\")\n```\n\nThere are several special opts, that are handled by the library:\n\n- `:in`: An input stream than can be passed to gum\n- `:as`: Coerce the output. Currently supports :bool, :ignored or defaults to a seq of strings\n- `:gum-path`: Path to the gum binary. Defaults to `gum`\n\nAll other opts are passed to the CLI. Consult `gum CMD --help` to see available options.\nTo pass flags like `--directory` use `:directory true`. **Always use full names of the options**.\n\n**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).\n\nExample with special options:\n```clojure\n(gum :table :in (clojure.java.io/input-stream f) :height 10)\n```\n\n### Usage Examples\n\n#### input\n```clojure\n(b/gum :choose [\"foo\" \"bar\" \"baz\"] :no-limit true)\n\n{:status 0 :result (\"foo\" \"baz\")}\n```\n\n#### write\n```clojure\n(b/gum :write)\n```\n\n#### filter\n```clojure\n(b/gum :filter :in (clojure.java.io/input-stream \"flavours.txt\"))\n\n(b/gum :filter :in (clojure.java.io/input-stream \"flavours.txt\") :no-limit true)\n\n;; Since bblgum uses babashka/process, the following are possible as well\n(b/gum :filter :in \"a string that will be streamed into the stdin char by char\")\n\n(b/gum :filter :in (clojure.string/join \"\\n\" [\"can\" \"be\" \"used\" \"as\" \"a\" \"filtering\" \"choose\" \"alternative\"]))\n```\n\n#### confirm\n\n```clojure\n(b/gum :confirm :as  :bool)\n```\n\n#### file\n\n```clojure\n(b/gum :file [\"src\"])\n```\n\n#### pager\n\n```clojure\n(b/gum :pager :as :ignored :in (clojure.java.io/input-stream \"README.md\"))\n```\n\n#### spin\n\n```clojure\n(b/gum :spin [\"sleep\" \"5\"] :spinner \"line\" :title \"Buying Bubble Gum...\")\n```\n\n#### table\n\n```clojure\n(b/gum :table :in (clojure.java.io/input-stream \"flavours.csv\"))\n```\n\nAll of the rest of the options and usecases _should work_ ™. Please raise issues/PRs for any improvements. Much appreciated!\n\n## Caveats\n\n- 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**.\n  To use this from an editor REPL:\n    - First start the REPL in a terminal, for example in bb for nREPL on port 1667: `bb nrepl-server 1667`.\n    - Connect to the port from the editor of your choice, for example with neovim and conjure: `:ConjureConnect 1667`.\n    - 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.\n\n## Low-level API\nThis was standard in previous versions of gum, we kept it for full backward compatibility.\n\nConvention:\n- The main command should be passed as a keyword or string to `:cmd`. Required\n- Passing opts:\n  - The --opts are to be passed as `:opts`\n  - Use the full forms of the opts: `--spinner` not `-s`\n  - Seqs can be passed to opts taking multiple params as well\n  - Pass boolean flags like `--password` as `{:password true}`\n- All positional args to be passed as `:args`.\n- An input stream can be passed to `:in`. Useful for commands like [filter](https://github.com/charmbracelet/gum#filter)\n- Corece the output:\n  - Treat non-zero exit codes from gum as a booleans passing `:as :bool`\n  - Ignore it with `:ignored`. This ignores parsing of the stdout\n  - `:bool` is useful for commands like [confirm](https://github.com/charmbracelet/gum#confirm)\n  - `:ignored` is useful for [pager](https://github.com/charmbracelet/gum#pager). Ignoring the parsing of the output helps the pager actually draw things\n  - Defaults to a seq of strings\n- Override the default gum path of `gum` by passing it via `:gum-path`\n\nThe `gum` fn returns a map of exit status of calling gum and the result either as a seq of lines or coerced via `:as`.\nExceptions are not thrown unless calling gum itself does, the status code is intended for programming for failures.\n\n\n```clojure\n(b/gum {:cmd :choose\n        :opts {:no-limit true}\n        :args [\"foo\" \"bar\" \"baz\"]})\n\n{:status 0 :result (\"foo\" \"baz\")}\n```\n\n\n## License\n\nCopyright © 2023- Rahul De.\n\nDistributed under the MIT License. See LICENSE.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flispyclouds%2Fbblgum","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flispyclouds%2Fbblgum","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flispyclouds%2Fbblgum/lists"}