help.go

package main

import (
	"bytes"
	"fmt"
	"strings"
	gotemplate "text/template"
)

func help(arg string) (s string) {
	switch arg {
	case "":
		s = helpGeneric()
	case "templates":
		s = helpTemplates()
	case "logfiles":
		s = helpLogfiles()
	case "colors":
		s = helpColors()
	case "placeholders":
		s = helpPlaceholders()
	default:
		s = helpPlaceholder(arg)
	}
	s = trimWhitespace(s, wsBOF, wsEOF)
	return
}

func helpGeneric() string {
	s := `
{{.app}} {{.version}}
Author: Alex Diaconu <xuoe@pm.me>

{{.app}} annotates the output of a command with additional information and
writes the result to a rotatable file.

Usage:
    {{.app}} [OPTIONS] <command> [arguments...]
    <command> | {{.app}} [OPTIONS]
    <command> | {{.app}} [OPTIONS] <command> [arguments...]

Options:
    -1, --stdout TEMPLATE  Set the standard output template ('' to discard the stream).
    -2, --stderr TEMPLATE  Set the standard error template (same as above).
    -f, --file FILE        Log both output streams to FILE.
    -s, --max-size SIZE    Limit the size of FILE to SIZE (e.g., 100kb, 1M, 1Gb, 32b).
    -c, --max-count COUNT  Limit the number of logfiles to COUNT.
    -n, --name NAME        Replace the default session name with NAME.
    -q, --quiet            Don't echo anything, but log to FILE if requested.
    -a, --ansi STREAMS     Allow ANSI escape sequences on STREAMS, which can be any
                           combination of the characters '1', '2' and 'f' (default: 12),
                           while '' and '-' disable the feature entirely.

    -v, --version          Show version information.
    -h, --help [TOPIC]...  Show this help message, or help for TOPIC, which can be any of:
                           "colors", "logfiles", "templates", "placeholders" or <placeholder>.

Environment:
    {{.app | upcase }}_OPTS       May contain any of the options listed above.
    {{.app | upcase }}_STDOUT     Sets the --stdout option.
    {{.app | upcase }}_STDERR     Sets the --stderr option.
    {{.app | upcase }}_TIMESTAMP  Overrides the default timestamp ({{ .timestamp }}).

    Note that flags set via environment variables are reset by their
    command-line equivalents.`
	fns := gotemplate.FuncMap{
		"upcase": strings.ToUpper,
	}
	data := map[string]string{
		"app":       app,
		"version":   version,
		"timestamp": defaultTimestampFormat,
	}
	return renderHelp("generic", s, fns, data)
}

func helpTemplates() string {
	ps := defaultPlaceholders()
	ps.constant("name", "example")
	stdout, _ := newTemplate("stdout", defaultStdoutTemplate, ps)
	stderr, _ := newTemplate("stderr", defaultStderrTemplate, ps)
	fns := gotemplate.FuncMap{
		"bold":   bold,
		"italic": italic,
		"stdout": stdout.renderString,
		"stderr": stderr.renderString,
		"render": func(s string) (string, error) {
			t, err := newTemplate(s, s, ps)
			if err != nil {
				panic(err)
			}
			return t.renderString("")
		},
	}
	data := map[string]interface{}{
		"stdout": defaultStdoutTemplate,
		"stderr": defaultStderrTemplate,
		"app":    app,
	}
	s := `
By default, {{.app}} defines a set of templates for both standard output and
standard error:

{{bold "*stdout*"}} is "{{.stdout}}", which renders as:
             {{stdout "sample output text"}}

{{bold "*stderr*"}} is "{{.stderr}}", which renders as:
             {{stderr "sample output text"}}

The words surrounded by curly braces are {{italic "placeholders"}}, which are evaluated
and replaced for each line of output generated by the underlying command.
Placeholder arguments are parsed as shell words (i.e., words are separated by
whitespace and may be surrounded in quotes). Placeholders may be nested, e.g.,
"{fg red '{rjust 10 {upcase example}}'}" prints "{{render "{fg red '{rjust 10 {upcase example}}'}"}}". Also note
the single quotes around {rjust}; without them, the whitespace generated
by {rjust} would be discarded.

See {{bold "--help placeholders"}} for a list of supported placeholders.

If a template is set to the empty string, text originating from the
corresponding output is no longer printed. If just the text is desired,
use '{text}' on its own. If both templates are set to an empty string,
{{.app}} aborts.
`
	return renderHelp("templates", s, fns, data)
}

func helpLogfiles() string {
	s := `
In addition to printing the annotated output streams of the underlying command,
{{.app}} can also merge them into a logfile when {{flag "file"}} is specified.

If {{flag "max-size"}} is also specified, it serves as a hint to {{.app}} to truncate the
logfile when the given size limit is reached. Note that {{.app}} always writes out
whole lines, which can force truncation prior to the size limit being reached
if the line doesn't fit within the remaining space.

If {{flag "max-count"}} is specified alongside {{flag "max-size"}} and the size limit is reached,
{{.app}} will rename the main logfile to <logfile>.<suffix> and create an empty file
under the initial name. Logfiles are ordered by age, newest to oldest (0 to {{flag "max-count"}}).
Note that {{.app}} assumes ownership of all files that match <logfile>.<suffix>, and
attempts to keep them ordered even when the order is altered by external actions.

If the {{flag "ansi"}} flag does not include the letter 'f' (defaults to '12'), ANSI codes
will not be written to logfiles.
	`
	fns := gotemplate.FuncMap{
		"bold":   bold,
		"italic": italic,
		"flag":   func(s string) string { return bold("--" + s) },
	}
	data := map[string]string{
		"app": app,
	}
	return renderHelp("logfiles", s, fns, data)
}

func renderHelp(name, s string, fns gotemplate.FuncMap, data interface{}) string {
	t := gotemplate.Must(gotemplate.New(name).Funcs(fns).Parse(s))
	var out bytes.Buffer
	if err := t.Execute(&out, data); err != nil {
		panic(err)
	}
	return out.String()
}

func helpPlaceholders() string {
	indent := reduceInt(0, placeholderNames, func(max int, s string) int {
		if max > len(s) {
			return max
		}
		return len(s)
	})
	var sb strings.Builder
	for _, p := range placeholderNames {
		msg := placeholderDefs[p].help
		msg = msg[:strings.Index(msg, "\n")]
		fmt.Fprintf(&sb, "%-*s %s\n", indent+1, p, msg)
	}
	fmt.Fprintf(&sb, "\nSee --help <placeholder> for placeholder-specific details.")
	return sb.String()
}

func helpPlaceholder(p string) string {
	return placeholderDefs[p].help
}

func helpColors() string {
	return strings.Join(codes.keys("bg"), "\n")
}