usage

package
v12.32.0+incompatible Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 13, 2021 License: Apache-2.0 Imports: 8 Imported by: 1

Documentation

Overview

Package usage provides methods and structs for generating usage info for command-line tools

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type About 

type About struct {
	App        string // App is application name
	Version    string // Version is current application version in semver notation
	Release    string // Release is current application release
	Build      string // Build is current application build
	Desc       string // Desc is short info about application
	Year       int    // Year is year when owner company was founded
	License    string // License is name of license
	Owner      string // Owner is name of owner (company/developer)
	BugTracker string // BugTracker is URL of bug tracker

	// Function for checking application updates
	UpdateChecker UpdateChecker
}

About contains info about application

func (*About) Render 

func (a *About) Render()

Render prints version info to console

Example 
about := About{
	App:     "MySupperApp",
	Desc:    "My super golang utility",
	Version: "1.0.1",
	Release: "-44",
	Build:   "17746", // Number of build or commit hash
	Year:    2009,    // Year when company was founded
	License: "MIT",
	Owner:   "John Dow <john@domain.com>",
}

about.Render()

Output:

type Command 

type Command struct {
	Name         string
	Desc         string
	Group        string
	Args         []string
	BoundOptions []string
}

type Example 

type Example struct {
	Cmd  string
	Desc string
	Raw  bool
}

type Info 

type Info struct {
	CommandsColorTag string // CommandsColor contains default commands color
	OptionsColorTag  string // OptionsColor contains default options color
	Breadcrumbs      bool   // Use bread crumbs for commands and options output

	Name    string
	Args    []string
	Spoiler string

	Commands []*Command
	Options  []*Option
	Examples []*Example
	// contains filtered or unexported fields
}

Info contains info about commands, options, and examples

func NewInfo 

func NewInfo(args ...string) *Info

NewInfo creates new info struct

Example 
// If the first argument (name) is empty, we use the name of the file
// for info generation
info := NewInfo("")

// You can hardcode the name of the app if you want
info = NewInfo("myapp")

// You can define one or more arguments handled by your program
info = NewInfo("", "files…")
info = NewInfo("", "input", "num-files", "output")

info.Render()

Output:

func (*Info) AddCommand 

func (i *Info) AddCommand(a ...string)

AddCommand adds command (name, description, args)

Example 
info := NewInfo("", "items…")

// You can define command arguments names
info.AddCommand("add", "Add item", "file")

// Also, you can mark optional arguments using ? prefix
info.AddCommand("remove", "Remove item", "file", "?mode")
info.AddCommand("list", "List items")

// You can add custom commands groups
info.AddGroup("External Commands")

info.AddCommand("publish", "Publish items")

// render all data
info.Render()

Output:

func (*Info) AddExample 

func (i *Info) AddExample(a ...string)

AddExample adds example of application usage

Example 
info := NewInfo("", "items…")

info.AddCommand("add", "Add item", "file")
info.AddCommand("remove", "Remove item", "file", "?mode")

// First part with application name will be automatically added
info.AddExample("add file.dat")

// This is example with description
info.AddExample("remove file.dat", "Remove file.dat")

// render all data
info.Render()

Output:

func (*Info) AddGroup 

func (i *Info) AddGroup(group string)

AddGroup adds new command group

Example 
info := NewInfo("", "items…")

// You can add custom commands groups
info.AddGroup("External Commands")

// ... and add commands to this group
info.AddCommand("publish", "Publish items")

// You can define option (output) and payload (file) name
info.AddOption("o:output", "Output", "file")

// render all data
info.Render()

Output:

func (*Info) AddOption 

func (i *Info) AddOption(a ...string)

AddOption adds option (name, description, args)

Example 
info := NewInfo("", "items…")

// AddOption supports options in format used in options package
info.AddOption("v:version", "Print version")

// You can define option (output) and payload (file) name
info.AddOption("o:output", "Output", "file")

// render all data
info.Render()

Output:

func (*Info) AddRawExample 

func (i *Info) AddRawExample(a ...string)

AddRawExample adds example of application usage without command prefix

Example 
info := NewInfo("", "items…")

info.AddCommand("add", "Add item", "file")
info.AddCommand("remove", "Remove item", "file", "?mode")

// Raw example (without application name) without description
info.AddRawExample("add file.dat")

// Raw example (without application name) with description
info.AddRawExample("remove file.dat", "Remove file.dat")

// render all data
info.Render()

Output:

func (*Info) AddSpoiler 

func (i *Info) AddSpoiler(spoiler string)

AddSpoiler adds spoiler

Example 
info := NewInfo("", "items…")

// Spoiler will be shown before all commands and options
info.AddSpoiler("This is my supadupa utility")

// render all data
info.Render()

Output:

func (*Info) BoundOptions 

func (i *Info) BoundOptions(cmd string, options ...string)

BoundOptions bounds command with options

Example 
info := NewInfo("", "items…")

info.AddCommand("publish", "Publish items")

info.AddOption("o:output", "Output", "file")

// Link command and options (will be used for completion generation)
info.BoundOptions("publish", "o:output")

// render all data
info.Render()

Output:

func (*Info) GetCommand 

func (i *Info) GetCommand(name string) *Command

GetCommand tries to find command with given name

Example 
info := NewInfo("", "items…")

// You can define command arguments names
info.AddCommand("add", "Add item", "file")

// Also, you can mark optional arguments using ? prefix
info.AddCommand("remove", "Remove item", "file", "?mode")
info.AddCommand("list", "List items")

cmd := info.GetCommand("list")

fmt.Println(cmd.Desc)

Output:

List items

func (*Info) GetOption 

func (i *Info) GetOption(name string) *Option

GetOption tries to find option with given name

Example 
info := NewInfo("", "items…")

// AddOption supports options in format used in options package
info.AddOption("v:version", "Print version")

// You can define option argument name
info.AddOption("o:output", "Output file", "file")

opt := info.GetOption("o:output")

fmt.Println(opt.Desc)

Output:

Output file

func (*Info) Render 

func (i *Info) Render()

Render prints usage info to console

Example 
info := NewInfo("", "items…")

// Spoiler will be shown before all commands and options
info.AddSpoiler("This is my supadupa utility")

// You can define command arguments names
info.AddCommand("add", "Add item", "file")

// Also, you can mark optional arguments using ? prefix
info.AddCommand("remove", "Remove item", "file", "?mode")
info.AddCommand("list", "List items")

// You can add custom commands groups
info.AddGroup("External Commands")

info.AddCommand("publish", "Publish items")

info.AddOption("--help", "Print help content")

// AddOption supports options in format used in options package
info.AddOption("v:version", "Print version")

// You can define option argument name
info.AddOption("o:output", "Output", "file")

// Link command and options (will be used for completion generation)
info.BoundOptions("publish", "o:output")

// First part with application name will be automatically added
info.AddExample("add file.dat")

// This is example with description
info.AddExample("remove file.dat", "Remove file.dat")

// Raw example without description
info.AddRawExample("add file.dat")

// Raw example with description
info.AddRawExample("remove file.dat", "Remove file.dat")

// render all data
info.Render()

Output:

type Option 

type Option struct {
	Short string
	Long  string
	Desc  string
	Arg   string
}

type UpdateChecker 

type UpdateChecker struct {
	Data      string
	CheckFunc func(app, version, data string) (string, time.Time, bool)
}

UpdateChecker is a base for all update checkers

Source Files

View all Source files

Directories

Path Synopsis
completion
bash
Package bash provides methods for generating bash completion
 Package bash provides methods for generating bash completion
fish
Package fish provides methods for generating fish completion
 Package fish provides methods for generating fish completion
zsh
Package zsh provides methods for generating zsh completion
 Package zsh provides methods for generating zsh completion
Package man contains methods for man pages generation
 Package man contains methods for man pages generation
Package update contains update checkers for different services
 Package update contains update checkers for different services

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.