ser1.net/claphelp/v2

claphelp

A pretty Usage-printer and manpage generator for programs that use the claptrap flags library.

Usage

package mytest

require ser1.net/claptrap/v4
require ser1.net/claphelp/v2

For pretty-print usage, in your project:

package main
import "ser1.net/claptrap/v4"
import "ser1.net/claphelp/v2"

func main() {
  reg := claptrap.Command("tripl", "Load a file a number of times")

  // Set up the flags normally, .Add, AdCommand, etc.
  reg.Add("!file", "a file name")
  reg.Add("--count", "-c", 3, "times to read the file")
  reg.Add("--action...", []string{"bytes", "words", "lines"}, "count the number of something in the file")

  // Override the usage and error printing functions
  claptrap.Usage = claphelp.PrettyUsage
  claptrap.HandleErrors = claphelp.PrettyErrors

  // Parse and use Usage as normal, e.g. reg.Parse(nil)
  claptrap.Usage()
}

Man page

To generate manpages, use the magic environment variable CLAPTRAP_USAGE_JSON with your program's Usage and pipe the output through claphelp's cmd/makeclapman:

Note: you do not need to import claphelp into your project if all you want to do is generate manpages. Base claptrap understands the CLAPTRAP_USAGE_JSON environment variable. You need to import claphelp only if you want pretty-print help/error messages.

$ go install ser1.net/claphelp/cmd/makeclapman
$ CLAPTRAP_USAGE_JSON=true myprogram | makeclapman

makeclapman will generate one man page per subcommand in your program; for example:

  root := claptrap.AddCommand("myprogram", "This is my program")
  help := root.AddCommand("help", "Show my program's usage")
  lotto := root.AddCommand("lotto", "Show winning lottery numbers")

will generate:

• myprogram.1
• myprogram-help.1
• myprogram-lotto.1

with "See also" references in all files.

For man pages, an author section can be added with the --author flag. If --description is specified, then the command description will be used for the synopsis, and the command-line description will be used for the DESCRIPTION section. A file can also be provided to include arbitrary sections; this file contains:

# SECTION NAME
Any text, included raw. This allows passing through manpage mark-up.

example-additional.txt has a more full example.

In go:generate

makeclapman can be used in a go:generate directive through the --run argument. For example:

//go:generate go run ser1.net/claphelp/v2/cmd/makeclapman@latest --run "./cmd/myprogram --help"

makeclapman will execute go run ./cmd/myprogram --help with the CLAPTRAP_USAGE_JSON=true environment variable and will consume and transform the output into man pages.