mirror of
https://github.com/rwxrob/bonzai
synced 2024-11-12 07:10:26 +00:00
200 lines
9.2 KiB
Markdown
200 lines
9.2 KiB
Markdown
# 🌳 Go Bonzai™ Command Compositor
|
|
|
|
[](https://godoc.org/github.com/rwxrob/bonzai)
|
|
[](LICENSE)
|
|
[](https://goreportcard.com/report/github.com/rwxrob/bonzai)
|
|
|
|
Meticulously manicured monolith and multicall binaries, built from
|
|
imported composite commands, on any device, with recursive, light-weight
|
|
tab completion, and richly rendered embedded documentation. Replace
|
|
messy collections of shell scripts, completion scripts, and separate man
|
|
pages with clean Go code compiled into a single, portable command.
|
|
|
|
## Getting Started
|
|
|
|
Copy or clone the example template:
|
|
|
|
👆 <https://github.com/rwxrob/bonzai-example>
|
|
|
|
Study the personal, script-replacing monolith/multicall that started it
|
|
all:
|
|
|
|
👆 <https://github.com/rwxrob/z>
|
|
|
|
## Go Bonzai!
|
|
|
|
|
|
|
|
Yes, "banzai" is something people yell going into battle, and battle is
|
|
exactly what it feels like to conquer your monstrous collection of shell
|
|
scripts, completion bloated rc files, and man pages (if you even got
|
|
that far).
|
|
|
|
"Bonsai" trees are well-manicured, meticulously crafted,
|
|
miniature *real* trees that rival their larger cousins, much like a
|
|
Bonzai composite command tree.
|
|
|
|
Bonzai trees are unlike anything you've likely encountered so far, no
|
|
getopt dashes, no ugly commander interface language to learn, no 12637
|
|
lines of shell tab completion bloat to source before your command will
|
|
complete, just well manicured
|
|
nested-tab-complete-with-magical-aliases-enabled commands organized into
|
|
rooted node trees for your command-line enjoyment. Your right-pinky will
|
|
be particularly grateful.
|
|
|
|
## "It's spelled bonsai/banzai."
|
|
|
|
We know. The domains were taken. Plus, this makes it more unique and
|
|
easier to find once you know the strange spelling we chose to use. Sorry
|
|
if that triggers your OCD.
|
|
|
|
If you must know, the primary motivator was the similarity to a
|
|
well-manicured tree (since it is for creating trees of composite
|
|
commands).
|
|
|
|
The misunderstood word "banzai" is 'a traditional Japanese idiom
|
|
meaning "ten thousand years" of long life,' a cheer used in
|
|
celebrations like "Hurrah" or "Viva".' So combining the notion of a
|
|
happy, well-manicured, beautiful tree and "ten thousand years of
|
|
long life" works out just fine for us.
|
|
|
|
And, yes, Buckaroo Banzai was always a favorite. We like to think he
|
|
would use Bonzai today to make amazing things and last for a long time
|
|
to defeat evil aliens and save the world.
|
|
|
|
It turns out that the "call to war" associated with Bonzai is not
|
|
entirely without merit as well. Bonzai is excellent for unorthodox,
|
|
rapid applications development (instead of writing scripts) and makes
|
|
short work of creating offensive and defensive tool kits all wrapping
|
|
into one nice Go multicall binary, popular for building single-binary
|
|
Linux container distros like BusyBox and Alpine, as well as root kits,
|
|
and other security tools
|
|
|
|
## "Why not just use Cobra?"
|
|
|
|
We get this question a lot, the answer is --- honest.
|
|
|
|
Just because something is popular (or first) doesn't mean it was well
|
|
designed. In fact, often inferior designs are rushed to market just to
|
|
gain adoption. Cobra seems to suffer from this. Discerning developers
|
|
and engineers have been not-so-quietly complaining about Cobra's
|
|
horrible design for years. It's time for something new. Read on if you
|
|
want the specific reasons.
|
|
|
|
* **Cobra tab completion is wasteful and error-prone.**
|
|
|
|
Cobra often requires sourcing thousands of lines of shell code every
|
|
time you run a new shell that needs to use a Cobra command with shell
|
|
tab completion (`kubectl` requires 12637). It is not uncommon for
|
|
operations people to be sourcing 100s of thousands of lines of shell
|
|
code just to enable basic completion that could have been enabled
|
|
easily with `complete -C` instead. Bonzai manages all completion in Go
|
|
instead of shell and therefore allows the modular addition of any
|
|
number of Completers including the standard file completion as well as
|
|
calculators, dates, and anything anyone can conceive of completing.
|
|
Completion is not dependent on any underlying operating system. Any
|
|
Bonzai command can provide its own completion algorithm or use one of
|
|
the many already provided. Cobra can never do this.
|
|
|
|
* **Cobra is not designed to be a command compositor at all.**
|
|
|
|
This is really unfortunate because the designers missed a golden
|
|
opportunity. Bonzai branches can be imported and composed into other
|
|
branches and monoliths with just a few lines of Go. Registries of
|
|
Bonzai commands can be easily inferred from dependencies on the
|
|
`bonzai` package and creators are free to compose their monoliths or
|
|
multicall binaries from a rich eco-system of Bonzai branches and
|
|
commands. Bonzai allows creation of Go multicall binary monoliths
|
|
(like BusyBox) to be made easily, and from a diverse, modular,
|
|
importable, composable sources. Such is simply not possible with Cobra
|
|
and never will be.
|
|
|
|
* **Cobra suffers from broken boomer "getopt" design.**
|
|
|
|
The world has finally realizing just how bad dashed arguments and
|
|
options have always been for good human-computer interactions from the
|
|
command line, perhaps because more regular people are using command
|
|
line interfaces, like chat apps from their laptops and phones. People
|
|
simply cannot remember all sorts of ungodly combinations of dashes and
|
|
equals signs hoping things will just work, and they certainly cannot
|
|
speak any getopt command into their phone and have it interpreted
|
|
correctly. With Bonzai they can. Bonzai UX is universal whether it be
|
|
from an Arch Linux command line or Slack app on an iPhone.
|
|
|
|
Bonzai takes a no-dashes approach with aliases promoting cleaner,
|
|
understandable command lines with context and promotion of domain
|
|
specific languages (created with PEGN, scan.X, or others) that easily
|
|
translate directly to chat and other command-line interfaces that most
|
|
humans can use without even looking up the documentation, which, by
|
|
the way, is embedded in any Bonzai command tree.
|
|
|
|
* **Cobra provides bad, brittle, command documentation.**
|
|
|
|
Cobra documentation is virtually unreadable in source form. And Cobra
|
|
provides no means of markup or use of color and doesn't even promote
|
|
the same look and feel of manual page documentation.
|
|
|
|
In contrast, Bonzai has its own subset of Markdown, BonzaiMark, which
|
|
respects the well established readability of manual pages, and allows
|
|
for the creation of elegant, templated documentation that can be
|
|
viewed from the command line or easily from a local browser on the
|
|
same computer running the command. Bonzai command documentation is as
|
|
easy to read in source form as the documentation itself.
|
|
|
|
Bonzai documentation is also dynamic. Rather than refer to a
|
|
configuration file the path to that specific file can be dynamically
|
|
included in the fully `text/template` enabled embedded documentation.
|
|
Cobra doesn't have anything even close to this.
|
|
|
|
* **Cobra suffers from crushing technical debt.**
|
|
|
|
The problems listed (and more) are never going to come out of Cobra.
|
|
Because it is filled with bad design decisions and was rushed to
|
|
market without serious consideration for its API, it is now doomed to
|
|
never lose its warts (kinda like JavaScript). There is no possible way
|
|
it can ever upgrade to address the very reasonable modern expectations
|
|
for good command line user experiences. No wonder you never see people
|
|
using Cobra for their replace-my-shell-scripts utilities. Cobra is
|
|
simply horrible for this. Thankfully, Bonzai is a fresh, extensible,
|
|
sustainable, human-friendly command compositor to take us into the
|
|
future of command line interfaces.
|
|
|
|
* **Cobra interfaces are nearly impossible to test.**
|
|
|
|
Ever tried creating tests for all the different Cobra option
|
|
combinations? It's a case study in the science of exponential problem
|
|
complexity. By using a rooted node tree of commands, which
|
|
observe cached variables or singular configuration, Bonzai makes short
|
|
work of writing even the highest-level of tests against the commands
|
|
themselves as if they were run by a user.
|
|
|
|
## What People Are Saying
|
|
|
|
> "It's like a modular, multicall BusyBox builder for Go with built in
|
|
> completion and embedded documentation support."
|
|
|
|
> "The utility here is that Bonzai lets you maintain your own personal
|
|
> 'toolbox' with built in auto-complete that you can assemble from
|
|
> various Go modules. Individual commands are isolated and unaware of
|
|
> each other and possibly maintained by other people." (tadasv123)
|
|
|
|
## Acknowledgements
|
|
|
|
The <https://twitch.tv/rwxrob> community has been constantly involved
|
|
with the development of this project, making suggestions about
|
|
everything from my use of `init()`, to the name "bonzai". While all their
|
|
contributions are too numerous to name specifically, they
|
|
more than deserve a huge thank you here.
|
|
|
|
## Legal
|
|
|
|
Copyright 2022 Robert S. Muhlestein (<mailto:rob@rwx.gg>)
|
|
SPDX-License-Identifier: Apache-2.0
|
|
|
|
"Bonzai" and "bonzai" are legal trademarks of Robert S. Muhlestein but
|
|
can be used freely to refer to the Bonzai™ project
|
|
<https://github.com/rwxrob/bonzai> without limitation. To avoid
|
|
potential developer confusion, intentionally using these trademarks to
|
|
refer to other projects --- free or proprietary --- is prohibited.
|