|
|
|
@ -1,6 +1,18 @@
|
|
|
|
|
# Design Considerations
|
|
|
|
|
# Style and Design
|
|
|
|
|
|
|
|
|
|
* **Promote high-level package library API calls over Cmd bloat**
|
|
|
|
|
* Use "deciduous tree" emoji 🌳 to mark Bonzai stuff
|
|
|
|
|
* Everything through `go fmt` or equiv, no exceptions
|
|
|
|
|
* In Vim `set textwidth=72` (not 80 to line numbers fit)
|
|
|
|
|
* Use `/* */` for package documentation comment, `//` elsewhere
|
|
|
|
|
* Smallest possible names for given scope while still clear
|
|
|
|
|
* Favor additional packages (possibly in `internal`) over long names
|
|
|
|
|
* Package globals that will be used a lot can be single capital
|
|
|
|
|
* Must be good reason to use more than 4 character pkg name
|
|
|
|
|
* Avoid unnecessary comments
|
|
|
|
|
|
|
|
|
|
## Design Considerations
|
|
|
|
|
|
|
|
|
|
**Promote high-level package library API calls over Cmd bloat**
|
|
|
|
|
|
|
|
|
|
Code belongs in package libraries, not Cmds.
|
|
|
|
|
|
|
|
|
@ -18,14 +30,14 @@
|
|
|
|
|
undesirable tight coupling --- even with channels --- between
|
|
|
|
|
specific commands.
|
|
|
|
|
|
|
|
|
|
* **Cmds should be very light**
|
|
|
|
|
**Cmds should be very light**
|
|
|
|
|
|
|
|
|
|
Most Cmds should assign their first-class Call function to one that
|
|
|
|
|
lightly wraps a similar function signature in a callable, high-level
|
|
|
|
|
library that works entirely independently from the bonzai package.
|
|
|
|
|
It's best to promote strong support for sustainable API packages.
|
|
|
|
|
|
|
|
|
|
* **Only bash completion and shell.Cmd planned**
|
|
|
|
|
**Only bash completion and shell.Cmd planned**
|
|
|
|
|
|
|
|
|
|
If it doesn't work with `complete -C` or equivalent then just run the
|
|
|
|
|
Bonzai command tree monolith as a temporary shell (shell.Cmd) and use
|
|
|
|
@ -52,15 +64,13 @@
|
|
|
|
|
shortcut aliases when completion is not available (h|help, for
|
|
|
|
|
example).
|
|
|
|
|
|
|
|
|
|
* **Bonzai commands may default to `shell.Cmd` or `help.Cmd`**
|
|
|
|
|
**Bonzai commands may default to `shell.Cmd` or `help.Cmd`**
|
|
|
|
|
|
|
|
|
|
These provide help information and optional interactive assistance
|
|
|
|
|
including tab completion in runtime environments that do not have
|
|
|
|
|
`complete -C foo foo` enabled.
|
|
|
|
|
|
|
|
|
|
*shell.Cmd is still under development and likely will be for a while*
|
|
|
|
|
|
|
|
|
|
* **Target users replacing shell scripts in "dot files" collections**
|
|
|
|
|
**Target users replacing shell scripts in "dot files" collections**
|
|
|
|
|
|
|
|
|
|
By creating a `cmd` subdirectory of a dot files repo a multi-call
|
|
|
|
|
Bonzai command named `cmd` can be easily maintained and added to just
|
|
|
|
@ -77,7 +87,7 @@
|
|
|
|
|
promotes the massive benefits of rapid applications development the
|
|
|
|
|
fullest extent.
|
|
|
|
|
|
|
|
|
|
* **Use either `foo.Cmd` or `cmd.Foo` convention**
|
|
|
|
|
**Use either `foo.Cmd` or `cmd.Foo` convention**
|
|
|
|
|
|
|
|
|
|
People may decide to put all their Bonzai commands into a single `cmd`
|
|
|
|
|
package or to put each command into its own package. Both are
|
|
|
|
@ -85,7 +95,7 @@
|
|
|
|
|
alias the packages as needed using Go's excellent package import
|
|
|
|
|
design.
|
|
|
|
|
|
|
|
|
|
* **Default capital "Z" import name**
|
|
|
|
|
**Default capital "Z" import name**
|
|
|
|
|
|
|
|
|
|
People can easily change the default "Z" import name to whatever else
|
|
|
|
|
if they don't like it (or worse, if has conflicts). But, we actually
|
|
|
|
@ -99,7 +109,7 @@
|
|
|
|
|
things into the Z package that would never be used outside a Bonzai
|
|
|
|
|
command, tree or `main.go` standalone.
|
|
|
|
|
|
|
|
|
|
* **Promote lower "z" personal Bonzai trees**
|
|
|
|
|
**Promote lower "z" personal Bonzai trees**
|
|
|
|
|
|
|
|
|
|
Just as "dotfiles" has become a convention, use of the simple "z"
|
|
|
|
|
GitHub repo should be promoted as a common, "ez" way to find people's
|
|
|
|
@ -107,7 +117,7 @@
|
|
|
|
|
also consistent with the capital "Z" import name of the `bonzai`
|
|
|
|
|
package.
|
|
|
|
|
|
|
|
|
|
* **Use simple regular expressions for usage**
|
|
|
|
|
**Use simple regular expressions for usage**
|
|
|
|
|
|
|
|
|
|
Bonzai takes a fundamentally different approach to the command line
|
|
|
|
|
and usage documentation. Any command line is a minimal domain specific
|
|
|
|
@ -119,7 +129,7 @@
|
|
|
|
|
wanting traditional usage notation can easily override the
|
|
|
|
|
`DefaultUsageFunc` with their own.
|
|
|
|
|
|
|
|
|
|
* **Prioritize output to VT100-compatible terminals**
|
|
|
|
|
**Prioritize output to VT100-compatible terminals**
|
|
|
|
|
|
|
|
|
|
Every modern terminal supports VT100 compatibility. If it doesn't,
|
|
|
|
|
people should just not use it. This means emphasis and formatting are
|
|
|
|
@ -127,7 +137,7 @@
|
|
|
|
|
package for the main output. Bonzai tree developers will likely want
|
|
|
|
|
terminal output helpers more than anything (yes even web rendering).
|
|
|
|
|
|
|
|
|
|
* **Secondary output to local web browser**
|
|
|
|
|
**Secondary output to local web browser**
|
|
|
|
|
|
|
|
|
|
Bonzai will eventually provide the option to enable use of the local
|
|
|
|
|
web browser instead of terminal output for help and other
|
|
|
|
@ -139,7 +149,7 @@
|
|
|
|
|
downloadable themes in this regard. In this way, Bonzai will provide
|
|
|
|
|
the web shell to encapsulate other web applications.
|
|
|
|
|
|
|
|
|
|
* **Prefer local web apps over other GUI platforms**
|
|
|
|
|
**Prefer local web apps over other GUI platforms**
|
|
|
|
|
|
|
|
|
|
While it is obviously possible to create any graphic application with
|
|
|
|
|
Bonzai, the creation of localized web applications should be the
|
|
|
|
@ -150,12 +160,12 @@
|
|
|
|
|
Every Bonzai binary is its own local web server which Go's rich
|
|
|
|
|
standard library to draw on.
|
|
|
|
|
|
|
|
|
|
* **[]Section instead of map[string]string for Other**
|
|
|
|
|
**[]Section instead of map[string]string for Other**
|
|
|
|
|
|
|
|
|
|
This allows composition notation and ensures the author has control of
|
|
|
|
|
how the Other sections appear.
|
|
|
|
|
|
|
|
|
|
* **Move `help.Cmd` into its own package**
|
|
|
|
|
**Move `help.Cmd` into its own package**
|
|
|
|
|
|
|
|
|
|
Although it breaks backward compatibility for many applications
|
|
|
|
|
updating between `v0.1` and `v0.2` the decision to put `help.Cmd` into
|
|
|
|
@ -169,7 +179,7 @@
|
|
|
|
|
and not Bonzai itself. It's conceivable that another `help.Cmd`
|
|
|
|
|
creator may wish another legal agreement.
|
|
|
|
|
|
|
|
|
|
* **Leave hidden default command params**
|
|
|
|
|
**Leave hidden default command params**
|
|
|
|
|
|
|
|
|
|
When the default command is invoked any of it's params will be
|
|
|
|
|
automatically passed as if the command specified them. But they are
|
|
|
|
@ -181,14 +191,14 @@
|
|
|
|
|
When and if dependencies on them become an issue it can be addressed
|
|
|
|
|
then.
|
|
|
|
|
|
|
|
|
|
* **Not exporting Dynamic FuncMap builtins**
|
|
|
|
|
**Not exporting Dynamic FuncMap builtins**
|
|
|
|
|
|
|
|
|
|
Since those builtins will land in `mark` subpackage eventually, don't
|
|
|
|
|
want to build any dependencies on them now that will break. The
|
|
|
|
|
builtins themselves can obviously be used immediately and has a much
|
|
|
|
|
smaller chance of changing in the future.
|
|
|
|
|
|
|
|
|
|
* **Reserve `--` for BonzaiShell pipe assignment**
|
|
|
|
|
**Reserve `--` for BonzaiShell pipe assignment**
|
|
|
|
|
|
|
|
|
|
The only operator of the BonzaiShell (that is not a Bonzai leaf
|
|
|
|
|
command allowing maximum extensibility) is the "into" (`--`) operator.
|
|
|
|
@ -202,6 +212,7 @@
|
|
|
|
|
look something like this (where lines with *any* space are line
|
|
|
|
|
continuations, unless they are `--`, which joins them as a pipe):
|
|
|
|
|
|
|
|
|
|
```bonzai
|
|
|
|
|
#!/usr/bin/env z
|
|
|
|
|
produce output with lines
|
|
|
|
|
--
|
|
|
|
@ -209,6 +220,7 @@
|
|
|
|
|
foo the line
|
|
|
|
|
--
|
|
|
|
|
prefix someprefix
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
The fact that `--` is observed by most shells as the "end of
|
|
|
|
|
arguments" mark makes it somewhat intuitive for regular shell users
|
|
|
|
@ -233,7 +245,7 @@
|
|
|
|
|
BonzaiShell to Bonzai Cmd code generator with very little effort at
|
|
|
|
|
that point.
|
|
|
|
|
|
|
|
|
|
* **Custom errors as package globals**
|
|
|
|
|
**Custom errors as package globals**
|
|
|
|
|
|
|
|
|
|
When it became clear that there are a number of canned error
|
|
|
|
|
conditions that we want to allow Cmd developers to use quickly and
|
|
|
|
@ -252,24 +264,52 @@
|
|
|
|
|
why the full `v1.0` is not expected until December 25th 2022, some
|
|
|
|
|
months after things should feel settled and finished).
|
|
|
|
|
|
|
|
|
|
* **Move package global Aliases/Shortcuts into Cmd**
|
|
|
|
|
**Move package global Aliases/Shortcuts into Cmd**
|
|
|
|
|
|
|
|
|
|
In Cmd they can be documented. They also tend to be long and eat up
|
|
|
|
|
too much of the command line when using them with completion. Better
|
|
|
|
|
to just have them in the help docs to lookup when the full path is
|
|
|
|
|
wanted.
|
|
|
|
|
|
|
|
|
|
## Style Guidelines
|
|
|
|
|
|
|
|
|
|
* Use "deciduous tree" emoji 🌳 to mark Bonzai stuff
|
|
|
|
|
* Everything through `go fmt` or equiv, no exceptions
|
|
|
|
|
* In Vim `set textwidth=72` (not 80 to line numbers fit)
|
|
|
|
|
* Use `/* */` for package documentation comment, `//` elsewhere
|
|
|
|
|
* Smallest possible names for given scope while still clear
|
|
|
|
|
* Favor additional packages (possibly in `internal`) over long names
|
|
|
|
|
* Package globals that will be used a lot can be single capital
|
|
|
|
|
* Must be good reason to use more than 4 character pkg name
|
|
|
|
|
* Avoid unnecessary comments
|
|
|
|
|
**Allow dashes, but discourage**
|
|
|
|
|
|
|
|
|
|
Being able to put a command anywhere in the commands tree path of
|
|
|
|
|
arguments will never be allowed since it is fundamentally against the
|
|
|
|
|
entire raison d'etre of Bonzai. We want people to memorize specific
|
|
|
|
|
paths and create the occasional alias and shortcut, not just through
|
|
|
|
|
whatever onto the command line hoping it will work. This is why `getopt`
|
|
|
|
|
things are so problematic, they all deal with the "end of options and
|
|
|
|
|
switch" and the "beginning of arguments" differently. Not Bonzai, where
|
|
|
|
|
the arguments are *always* consistent as well as the command paths.
|
|
|
|
|
Because of this, dashes should never be used by any Bonzai command or
|
|
|
|
|
alias. In fact, the only time a dash will exist is when passing on
|
|
|
|
|
arguments to the underlying command shell. For example, when delegating
|
|
|
|
|
to `gh` which requires it (although every effort should be made to
|
|
|
|
|
remake the entire UI for such things to be Bonzai friendly).
|
|
|
|
|
|
|
|
|
|
However, the no-getopt approach is so foreign to those training in
|
|
|
|
|
decades of this insanity that we need to support dashed aliases (and
|
|
|
|
|
other options) that will be intuitive to these people for a very long
|
|
|
|
|
time. Of particular note are things like `-h`, `--help`, `-help`, and
|
|
|
|
|
`/?` all of which are indelibly marked into most of our muscle memory.
|
|
|
|
|
will be intuitive to such people. The addition of support for aliases
|
|
|
|
|
that begin with dashes --- but that do not appear in the help
|
|
|
|
|
documentation --- is specifically to address this issue. Like all
|
|
|
|
|
aliases, the bash shell will dynamically change the `-h` into `help`
|
|
|
|
|
when the user taps tab prompting them with the correct word, but, also
|
|
|
|
|
like all aliases, if they execute the command with `-h` it will just
|
|
|
|
|
work.
|
|
|
|
|
|
|
|
|
|
Allowing dashed aliases does carry the risk that some will permanently
|
|
|
|
|
use them in their scripts. But not allowing them in most help
|
|
|
|
|
documentation should be enough to discourage it. Theoretically, it is
|
|
|
|
|
entirely possible to create a Bonzai command that does parse its
|
|
|
|
|
arguments and parameters using getopt notation. Having this freedom is a
|
|
|
|
|
part of FOSS and for those who insist is supported. It is simply
|
|
|
|
|
strongly discouraged by the Bonzai project itself which will make
|
|
|
|
|
specific design decisions based on the assumptions that dashes are never
|
|
|
|
|
used in command names. One such design decision is to use `--` as the
|
|
|
|
|
pipe operator in eventual `bonsh.Shell` command.
|
|
|
|
|
|
|
|
|
|
## Printing, Formatting, and Emphasis
|
|
|
|
|
|
|
|
|
@ -300,43 +340,8 @@
|
|
|
|
|
• `Z.PrintfInWrap(a string, f ...any)` - fmt.Print(Z.InWrapf(a string, f ...any))
|
|
|
|
|
• `Z.PrintfMark(a string, f ...any)` - fmt.Print(Z.Markf(a string, f ...any))
|
|
|
|
|
|
|
|
|
|
## 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.
|
|
|
|
|
|
|
|
|
|
## Shwag
|
|
|
|
|
|
|
|
|
|
Looking to get with
|
|
|
|
|
[https://www.trendhunter.com/trends/amuseable-bonsai-tree] to make a
|
|
|
|
|
plushy mascot.
|
|
|
|
|
|
|
|
|
|
## TODO
|
|
|
|
|
|
|
|
|
|
Here is a list of major things that are still needed before a v1.0
|
|
|
|
|
release:
|
|
|
|
|
|
|
|
|
|
* Complete default `help.Cmd`
|
|
|
|
|
* Complete `bonzai` helper command
|
|
|
|
|
* Initialize new branch including optional GitHub repo creation
|
|
|
|
|
* Vet a branch repo for orphan commands, etc.
|
|
|
|
|
* Cache/search list of package depending on `bonzai` as registry
|
|
|
|
|
* Complete final art
|
|
|
|
|
* Large logo for landing page
|
|
|
|
|
* Small logo for lists
|
|
|
|
|
* Animated emote suitable for Twitch
|
|
|
|
|
* Create a Bonzai™ merch outlet
|
|
|
|
|