Documentation
¶
Index ¶
- Variables
- func AKA(x *bonzai.Cmd) string
- func Bonzai(x *bonzai.Cmd) (string, error)
- func CmdTree(x *bonzai.Cmd, depth int) string
- func Code(it any) string
- func Command(x *bonzai.Cmd) string
- func Commands(x *bonzai.Cmd) string
- func Fill(it any, f template.FuncMap, in string) (string, error)
- func HasEnv(x *bonzai.Cmd) bool
- func Long(x *bonzai.Cmd) (string, error)
- func Summary(x *bonzai.Cmd) string
- func Usage(x *bonzai.Cmd) string
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var DefaultBonzaiCmdTemplate string
var Map = template.FuncMap{ "exepath": run.Executable, "exename": run.ExeName, "execachedir": run.ExeCacheDir, "exestatedir": run.ExeStateDir, "execonfigdir": run.ExeConfigDir, "cachedir": futil.UserCacheDir, "confdir": futil.UserConfigDir, "homedir": futil.UserHomeDir, "statedir": futil.UserStateDir, "pathsep": func() string { return string(os.PathSeparator) }, "pathjoin": filepath.Join, "indent": to.Indented, "aka": AKA, "code": Code, "commands": Commands, "command": Command, "summary": Summary, "usage": Usage, "hasenv": HasEnv, "long": Long, }
Functions ¶
func AKA ¶ added in v0.12.0
AKA returns the name followed by all aliases in parenthesis joined with a forward bar (|) suitable for inlining within help documentation. It is available as aka in Map as well.
Example ¶
package main
import (
"fmt"
"github.com/rwxrob/bonzai"
"github.com/rwxrob/bonzai/mark"
)
func main() {
var help = &bonzai.Cmd{
Name: `help`,
Alias: `h|-h|-help|--help|/?`,
}
fmt.Println(mark.AKA(help))
out, _ := mark.Fill(help, mark.Map, `The {{aka .}} command.`)
fmt.Println(out)
}
Output: `help` (`h`|`-h`|`-help`|`--help`|`/?`) The `help` (`h`|`-h`|`-help`|`--help`|`/?`) command.
func Bonzai ¶ added in v0.11.0
Bonzai outputs a template filled with the commands from the funcs package of this package plus the fields and Funcs from the bonzai.Cmd structure passed. The overall template can be changed by assigning to DefaultBonzaiCmdTemplate.
See following for details:
- pkg/github.com/rwxrob/bonzai - pkg/github.com/rwxrob/bonzai/mark/funcs - pkg/text/template
Normally, the output from this command is then passed to anything that can render Markdown (usually charmbracelet/glamour). Any of the functions from the funcs library can be overridden by Cmd.Funcs instead.
func Code ¶ added in v0.12.0
Code returns a string with Markdown backticks surrounding it after converting it to a string with fmt.Printf. This is also available as "code" in Map. This fulfills a specific use case when a developer would like to use backticks in a bonzai.Cmd.Long or bonzai.Cmd.Short but cannot because backticks are already used to contain the multi-line text itself.
Example ¶
package main
import (
"fmt"
"github.com/rwxrob/bonzai/mark"
)
func main() {
long := `
I'll use the {{code "{{code}}"}} thing instead with something like
{{code "go mod init"}} since cannot use backticks.`
fmt.Println(mark.Code(`go mod init`))
out, _ := mark.Fill(nil, mark.Map, long)
fmt.Println(out)
}
Output: `go mod init` I'll use the `{{code}}` thing instead with something like `go mod init` since cannot use backticks.
func Command ¶ added in v0.12.0
Command returns the name of the command joined to any aliases at the end.
Example ¶
package main
import (
"fmt"
"github.com/rwxrob/bonzai"
"github.com/rwxrob/bonzai/mark"
)
func main() {
var subFooCmd = &bonzai.Cmd{
Name: `subfoo`,
Alias: `sf`,
Short: `under the foo command`,
}
var fooCmd = &bonzai.Cmd{
Name: `foo`,
Alias: `f`,
Short: `foo this command`,
Cmds: []*bonzai.Cmd{subFooCmd},
}
var barCmd = &bonzai.Cmd{
Name: `bar`,
Alias: `b`,
Short: `bar this command`,
}
var Cmd = &bonzai.Cmd{
Name: `mycmd`,
Alias: `my|cmd`,
Short: `my command short summary`,
Cmds: []*bonzai.Cmd{fooCmd, barCmd},
Def: fooCmd,
}
Cmd.Seek(`foo`, `subfoo`) // required for default detection
fmt.Println(mark.Commands(Cmd))
}
Output: foo - foo this command (default) subfoo - under the foo command bar - bar this command
func Commands ¶ added in v0.12.0
Commands generates and returns a formatted string representation of the commands and subcommands for the [Cmd] instance. It aligns [Cmd].Short summaries in the output for better readability, adjusting spaces based on the position of the dashes.
Example (Hidden) ¶
package main
import (
"fmt"
"github.com/rwxrob/bonzai"
"github.com/rwxrob/bonzai/mark"
)
func main() {
var subFooCmd = &bonzai.Cmd{
Name: `subfoo`,
Alias: `sf`,
Short: `under the foo command`,
}
var hiddenCmd = &bonzai.Cmd{
Name: `imhidden`,
Cmds: []*bonzai.Cmd{{Name: `some`}, {Name: `other`}},
}
var fooCmd = &bonzai.Cmd{
Name: `foo`,
Alias: `f`,
Short: `foo this command`,
Cmds: []*bonzai.Cmd{subFooCmd},
}
var barCmd = &bonzai.Cmd{
Name: `bar`,
Alias: `b`,
Short: `bar this command`,
}
var Cmd = &bonzai.Cmd{
Name: `mycmd`,
Alias: `my|cmd`,
Short: `my command short summary`,
Cmds: []*bonzai.Cmd{fooCmd, barCmd, hiddenCmd.AsHidden()},
Def: fooCmd,
}
Cmd.Seek(`foo`, `sssh`, `some`) // required for default detection
fmt.Println(mark.Commands(Cmd))
}
Output: foo - foo this command (default) subfoo - under the foo command bar - bar this command
func Fill ¶ added in v0.10.4
Fill processes the input string (in) as a pkg/text/template using the provided function map (f) and the data context (it). It returns the rendered output as a string or an error if any step fails. No functions beyond those passed are merged (unlike Usage).
Example ¶
package main
import (
"fmt"
"text/template"
"github.com/rwxrob/bonzai/mark"
)
type Thing struct {
Name string
Count int
}
func (a Thing) Summary() string {
return fmt.Sprintf("%v %v", a.Name, a.Count)
}
func main() {
/* cannot declare type with method within function, but this is it
type Thing struct {
Name string
Count int
}
func (a Thing) Summary() string {
return fmt.Sprintf("%v %v", a.Name, a.Count)
}
*/
thing := Thing{`Thing`, 20}
tmpl := `
{{hello}}, my name is {{.Name}} with {{.Count}}. Summary: {{.Summary}}`
funcs := template.FuncMap{}
funcs[`hello`] = func() string { return `Hello` }
out, err := mark.Fill(thing, funcs, tmpl)
if err != nil {
fmt.Println(err)
return
}
fmt.Println(out)
}
Output: Hello, my name is Thing with 20. Summary: Thing 20
func HasEnv ¶ added in v0.12.0
HasEnv returns true if command has declared any environment variables in its Vars. Note that inherited vars are not resolved to see if they resolved to environment variables (Var.E).
func Long ¶ added in v0.12.0
Long returns the Long description of the command if found dedented so that it is left justified completely. It is first filled using the Map merged with the Funcs from the passed command.
func Summary ¶ added in v0.12.0
Summary returns the Name joined by a long dash with the Short description if it has one.
Example ¶
package main
import (
"fmt"
"github.com/rwxrob/bonzai"
"github.com/rwxrob/bonzai/mark"
)
func main() {
var Cmd = &bonzai.Cmd{
Name: `mycmd`,
Short: `my command short summary`,
Do: bonzai.Nothing,
}
fmt.Print(mark.Summary(Cmd))
}
Output: `mycmd` - my command short summary
func Usage ¶ added in v0.8.0
Usage return the Command plus any available Usage information. If there is no usage, it is inferred.
Example (LongFirstName) ¶
package main
import (
"fmt"
"github.com/rwxrob/bonzai"
"github.com/rwxrob/bonzai/mark"
)
func main() {
var fooCmd = &bonzai.Cmd{
Name: `foo`,
//Short: `a foo`,
Do: func(*bonzai.Cmd, ...string) error {
return nil
},
}
var Cmd = &bonzai.Cmd{
Name: `help-test`,
Alias: `h|ht`,
Short: `just a help test`,
Opts: `some|-y|--yaml`,
Cmds: []*bonzai.Cmd{fooCmd, fooCmd.WithName(`foo2`)},
Def: fooCmd,
}
Cmd.Run(`foo`) // for default
out, _ := mark.Bonzai(Cmd)
fmt.Println(string(out))
}
Output: # NAME `help-test` - just a help test # USAGE h|ht|help-test COMMAND|some|-y|--yaml # COMMANDS foo - (default) foo2
Example (Middle) ¶
package main
import (
"fmt"
"github.com/rwxrob/bonzai"
"github.com/rwxrob/bonzai/mark"
)
func main() {
var subFooHiddenCmd = &bonzai.Cmd{
Name: `iamhidden`,
Short: `i am hidden`,
}
var subFooCmd = &bonzai.Cmd{
Name: `subfoo`,
Alias: `sf`,
Short: `under the foo command`,
}
var fooCmd = &bonzai.Cmd{
Name: `foo`,
Alias: `f`,
//Short: `foo this command`,
Cmds: []*bonzai.Cmd{subFooCmd, subFooHiddenCmd.AsHidden()},
// Cmds: []*bonzai.Cmd{subFooCmd, subFooHiddenCmd},
}
var barCmd = &bonzai.Cmd{
Name: `bar`,
Alias: `b`,
Short: `bar this command`,
}
var Cmd = &bonzai.Cmd{
Name: `mycmd`,
Alias: `my|cmd`,
Short: `my command short summary`,
Cmds: []*bonzai.Cmd{fooCmd, barCmd},
Long: `
Here is a long description.
On multiple lines.`,
}
_ = Cmd
Cmd.Run()
out, err := mark.Bonzai(fooCmd)
if err != nil {
fmt.Println(err)
}
fmt.Println(out)
}
Output: # NAME `foo` # USAGE f|foo COMMAND # COMMANDS subfoo - under the foo command
Example (MissingShort) ¶
package main
import (
"fmt"
"github.com/rwxrob/bonzai"
"github.com/rwxrob/bonzai/mark"
)
func main() {
var subFooHiddenCmd = &bonzai.Cmd{
Name: `iamhidden`,
Short: `i am hidden`,
}
var subFooCmd = &bonzai.Cmd{
Name: `subfoo`,
Alias: `sf`,
Short: `under the foo command`,
}
var fooCmd = &bonzai.Cmd{
Name: `foo`,
Alias: `f`,
//Short: `foo this command`,
Cmds: []*bonzai.Cmd{subFooCmd, subFooHiddenCmd.AsHidden()},
// Cmds: []*bonzai.Cmd{subFooCmd, subFooHiddenCmd},
}
var barCmd = &bonzai.Cmd{
Name: `bar`,
Alias: `b`,
Short: `bar this command`,
}
var Cmd = &bonzai.Cmd{
Name: `mycmd`,
Alias: `my|cmd`,
Short: `my command short summary`,
Cmds: []*bonzai.Cmd{fooCmd, barCmd},
Long: `
Here is a long description.
On multiple lines.`,
}
Cmd.Run()
out, _ := mark.Bonzai(Cmd)
fmt.Println(out)
}
Output: # NAME `mycmd` - my command short summary # USAGE my|cmd|mycmd COMMAND # COMMANDS foo subfoo - under the foo command bar - bar this command # DESCRIPTION Here is a long description. On multiple lines.
Example (WithHiddenCmds) ¶
package main
import (
"fmt"
"github.com/rwxrob/bonzai"
"github.com/rwxrob/bonzai/mark"
)
func main() {
var subFooHiddenCmd = &bonzai.Cmd{
Name: `iamhidden`,
Short: `i am hidden`,
}
var subFooCmd = &bonzai.Cmd{
Name: `subfoo`,
Alias: `sf`,
Short: `under the foo command`,
}
var fooCmd = &bonzai.Cmd{
Name: `foo`,
Alias: `f`,
Short: `foo this command`,
Cmds: []*bonzai.Cmd{subFooCmd, subFooHiddenCmd.AsHidden()},
// Cmds: []*bonzai.Cmd{subFooCmd, subFooHiddenCmd},
}
var barCmd = &bonzai.Cmd{
Name: `bar`,
Alias: `b`,
Short: `bar this command`,
}
var Cmd = &bonzai.Cmd{
Name: `mycmd`,
Alias: `my|cmd`,
Short: `my command short summary`,
Cmds: []*bonzai.Cmd{fooCmd, barCmd},
Long: `
Here is a long description.
On multiple lines.`,
}
Cmd.Run()
out, _ := mark.Bonzai(Cmd)
fmt.Println(string(out))
}
Output: # NAME `mycmd` - my command short summary # USAGE my|cmd|mycmd COMMAND # COMMANDS foo - foo this command subfoo - under the foo command bar - bar this command # DESCRIPTION Here is a long description. On multiple lines.
Types ¶
This section is empty.
Source Files
Directories