usage.go

// gum/usage.go

package gum

import (
	"fmt"
	"io"
	"os"
	"sort"
	"strings"
	"text/tabwriter"
)

var (
	doubleSpace = []byte("\n\n")
	newLine     = []byte("\n")
	indent      = []byte("  ")
	tab         = []byte("\t")
)

// PrintUsage generates and prints the help text for a command to stdout.
func (c *Command) PrintUsage() {
	io.WriteString(os.Stdout, c.Usage())
}

// Usage generates and returns the help text for a command as a string.
// This function is heavily optimized to reduce memory allocations.
func (c *Command) Usage() string {
	var b strings.Builder

	if c.description != "" {
		b.WriteString(c.description)
		b.Write(doubleSpace)
	}

	b.WriteString("USAGE:\n")
	b.Write(indent)
	b.WriteString(c.path())
	for _, arg := range c.args {
		b.WriteString(" <")
		b.WriteString(arg.Name)
		b.WriteString(">")
	}
	allOpts := c.getAllOptions()
	if len(allOpts) > 0 {
		b.WriteString(" [options]")
	}
	if len(c.commands) > 0 {
		b.WriteString(" <command>")
	}
	b.Write(doubleSpace)

	if len(c.args) > 0 {
		b.WriteString("ARGUMENTS:\n")
		tw := tabwriter.NewWriter(&b, 0, 0, 3, ' ', 0)
		for _, arg := range c.args {
			tw.Write(indent)
			io.WriteString(tw, arg.Name)
			tw.Write(tab)
			io.WriteString(tw, arg.Description)
			tw.Write(newLine)
		}
		tw.Flush()
		b.Write(newLine)
	}

	if len(c.commands) > 0 {
		b.WriteString("COMMANDS:\n")
		tw := tabwriter.NewWriter(&b, 0, 0, 3, ' ', 0)
		uniqueCmds := make([]*Command, 0, len(c.commands))
		seen := make(map[*Command]bool, len(c.commands))
		for _, cmd := range c.commands {
			if !seen[cmd] {
				uniqueCmds = append(uniqueCmds, cmd)
				seen[cmd] = true
			}
		}
		sort.Slice(uniqueCmds, func(i, j int) bool { return uniqueCmds[i].Name < uniqueCmds[j].Name })
		for _, cmd := range uniqueCmds {
			tw.Write(indent)
			allNames := append([]string{cmd.Name}, cmd.Aliases...)
			io.WriteString(tw, strings.Join(allNames, ", "))
			tw.Write(tab)
			io.WriteString(tw, cmd.description)
			tw.Write(newLine)
		}
		tw.Flush()
		b.Write(newLine)
	}

	if len(allOpts) > 0 {
		b.WriteString("OPTIONS:\n")
		tw := tabwriter.NewWriter(&b, 0, 0, 3, ' ', 0)
		sort.Slice(allOpts, func(i, j int) bool { return allOpts[i].Names[0] < allOpts[j].Names[0] })
		for _, opt := range allOpts {
			tw.Write(indent)
			io.WriteString(tw, strings.Join(opt.Names, ", "))
			tw.Write(tab)
			io.WriteString(tw, opt.Description)
			if opt.DefaultValue != nil {
				io.WriteString(tw, " (default: ")
				// Use Sprintf for safe quoting, a small trade-off for correctness.
				fmt.Fprintf(tw, "%q", *opt.DefaultValue)
				io.WriteString(tw, ")")
			}
			tw.Write(newLine)
		}
		tw.Flush()
		b.Write(newLine)
	}

	if c.example != "" {
		b.WriteString("EXAMPLE:\n")
		b.Write(indent)
		b.WriteString(c.example)
		b.Write(newLine)
	}

	if c.extraUsage != "" {
		b.WriteString(strings.TrimSpace(c.extraUsage))
		b.Write(newLine)
	}
	return b.String()
}

// path calculates the full command path (e.g., "app remote add").
func (c *Command) path() string {
	if c.parent == nil {
		return c.Name
	}
	pathParts := make([]string, 0, 4)
	curr := c
	for curr != nil {
		pathParts = append(pathParts, curr.Name)
		curr = curr.parent
	}
	// Reverse the parts
	for i, j := 0, len(pathParts)-1; i < j; i, j = i+1, j-1 {
		pathParts[i], pathParts[j] = pathParts[j], pathParts[i]
	}
	return strings.Join(pathParts, " ")
}

// getAllOptions collects all options from the command and its parents.
func (c *Command) getAllOptions() []*Option {
	options := make([]*Option, 0, len(c.options)+4)
	seen := make(map[*Option]bool)
	curr := c
	for curr != nil {
		for _, opt := range curr.options {
			if !seen[opt] {
				options = append(options, opt)
				seen[opt] = true
			}
		}
		curr = curr.parent
	}
	return options
}