claphelp

README

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:

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

Documentation

Index

• Variables
• func Load()
• func PrettyErrors(exitCode int, errors []error)
• func PrettyUsage()

Variables

var OutWriter io.Writer = os.Stdout

Functions

func Load

func Load()

Load is a convenience function that enables claphelp pretty printing

func PrettyErrors

func PrettyErrors(exitCode int, errors []error)

PrettyErrors prints the provided errors and exits with the exitCode Set claptrap.HandleError to this function to get pretty-printed errors

func PrettyUsage

func PrettyUsage()

Set claptrap.Usage to this function to get pretty-printed Usage info.