help

README

🌳 Go Bonzai™ Default help Command

This is the default help originally included with the Go Bonzai package itself but factored out so that it's Version tag could be consistent with other Bonzai branches (which correspond to git tags by convention). This also allows other (potentially better) help.Cmd to be developed without a substantial bias one way or another.

Install

package z

import (
	Z "github.com/rwxrob/bonzai/z"
	"github.com/rwxrob/help"
)

var Cmd = &Z.Cmd{
	Name:     `z`,
	Commands: []*Z.Cmd{help.Cmd}, // usually first
}

Other Examples

• https://github.com/rwxrob/z - the one that started it all

Documentation

Index

• Variables
• func ForTerminal(x *Z.Cmd, section string)

Variables

var Cmd = &Z.Cmd{
	Name:      `help`,
	Version:   `v0.3.2`,
	Copyright: `Copyright 2021 Robert S Muhlestein`,
	License:   `Apache-2.0`,
	Summary:   `display help similar to man page format`,
	Usage:     `[SECTION|all]`,
	Params: []string{
		"name", "title", "summary", "params", "commands", "description",
		"examples", "legal", "copyright", "license", "site", "source",
		"issues", "contact", "version", "help",
	},
	Comp: new(comp),
	Description: `
		The *help* command provide generic help documentation by looking at
		the different fields of the given command associated with it. To get
		specific help provide the command for which help is wanted before
		the help command. The exact section of help can also be specified as
		an parameter after the help command itself. `,

	Other: []Z.Section{
		{`SECTIONS`, `
        Sections are modeled after UNIX "man" pages:

            all           - display all sections (default)
            help          - displays this help
            name          - name of command
            title         - name with summary
            summary       - one line summary of command
            params        - params are like commands, but not
            commands      - commands under this command
            description   - long description of command
            examples      - verbatim examples (coming soon)
            legal         - version, copyright, license combined
            copyright     - legal copyright statement
            license       - SPDX license identifier
            site          - URL home of {{.Name}}
						source        - cloneable source URL (usually git)
						issues        - URL where issues are reported
						contact       - site, source, issues combined
            version       - semantic version matching git tag

        Other custom sections may have been added by Bonzai branch
        authors as well (such as this one).

			 `,
		},
	},

	Call: func(x *Z.Cmd, args ...string) error {

	ZERO:
		if len(args) == 0 {
			args = append(args, "all")
		}

		if args[0] == `help` {
			x.Caller = x
			args = args[1:]
			goto ZERO
		}

		ForTerminal(x.Caller, args[0])
		return nil
	},
}

Cmd provides help documentation for the caller allowing the specific section of help wanted to be passed as a tab-completable parameter.

Functions

func ForTerminal

func ForTerminal(x *Z.Cmd, section string)

ForTerminal converts the collective help documentation of the given command into curses terminal-friendly output and prints the help for the specified section. If the special "all" section is passed all sections will be displayed. The style is similar to UNIX manual pages and supports terminal formatting including color.. Documentation must be in BonzaiMark markup (see Z.Format). Emphasis is omitted if the terminal is not interactive (see Z.Emph).