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 AKA(x *Z.Cmd) string
• func D(a string) string
• func ForTerminal(x *Z.Cmd, section string)
• func S(a string) string

Examples

• D
• S

Variables

var Cmd = &Z.Cmd{
	Name:    `help`,
	Version: `v0.5.2`,
	Aliases: []string{`-h`, `--help`, `--h`, `/?`},
	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", "shortcuts", "aka",
	},
	Comp: new(comp),
	Description: `
		The {{aka}} command provides generic help documentation by looking at
		the different fields of the given command associated with it. To get
		specific help provided by 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. Not all sections
				are necessarily available depending on what has been
				implemented:

            all           - display all sections (default)
            aka|aliases   - display common aliases
            help          - displays this help
            name          - name of command
            title         - name with summary
            summary       - one line summary of command
            shortcuts     - shorter versions of command branches
            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
		}

		injectDynamic(x)

		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 AKA

func AKA(x *Z.Cmd) string

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 help template command as well.

func D

func D(a string) string

D (Description) function returns all lines from the string starting with the third from the top. This assumes S (Summary) is used and separated by a blank line. This allows maintenance of large Descriptions in embedded files in a way that allows easier internationalization during compilation.

Example

package main

import (
	"fmt"

	"github.com/rwxrob/help"
)

func main() {
	text1 := "here is the summary\n\nFirst line of D"
	text2 := "here is the summary\r\n\r\nFirst line of D"
	text3 := "here is the summary\n\nFirst line of D\nSecond line of D"
	fmt.Print(help.D(text1))
	fmt.Print(help.D(text2))
	fmt.Print(help.D(text3))
}

Output:

First line of D
First line of D
First line of D
Second line of D

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).

ForTerminal will detect a system pager and use it if found.

func S

func S(a string) string

S (Summary) function returns the first line of the string. Usually the string passed is an embedded file passed as a string.

Example

package main

import (
	"fmt"

	"github.com/rwxrob/help"
)

func main() {
	text1 := "here is the summary\n"
	text2 := "here is the summary\r"
	text3 := "here is the summary"
	text4 := "here is the summary\nanother line"
	fmt.Println(help.S(text1))
	fmt.Println(help.S(text2))
	fmt.Println(help.S(text3))
	fmt.Println(help.S(text4))
}

Output:

here is the summary
here is the summary
here is the summary
here is the summary