usage

package
v12.120.0 Latest Latest
Warning

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

 Go to latest Published: Apr 29, 2024 License: Apache-2.0 Imports: 9 Imported by: 39

Documentation

Overview

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

Index

Examples

Constants

View Source 
const (
	DEFAULT_COMMANDS_COLOR_TAG     = "{y}"
	DEFAULT_OPTIONS_COLOR_TAG      = "{g}"
	DEFAULT_EXAMPLE_DESC_COLOR_TAG = "{&}{s-}"
	DEFAULT_APP_NAME_COLOR_TAG     = "{c*}"
	DEFAULT_APP_VER_COLOR_TAG      = "{c}"
	DEFAULT_APP_REL_COLOR_TAG      = "{s}"
	DEFAULT_APP_BUILD_COLOR_TAG    = "{s-}"
)
View Source 
const (
	VERSION_FULL    = "full"
	VERSION_SIMPLE  = "simple"
	VERSION_MAJOR   = "major"
	VERSION_MINOR   = "minor"
	VERSION_PATCH   = "patch"
	VERSION_RELEASE = "release"
	VERSION_BUILD   = "build"
)

Variables

This section is empty.

Functions

This section is empty.

Types

type About 

type About struct {
	App        string // App is app name
	Version    string // Version is current app version in semver notation
	Release    string // Release is current app release
	Build      string // Build is current app build
	Desc       string // Desc is short info about app
	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

	AppNameColorTag string // AppNameColorTag contains default app name color tag
	VersionColorTag string // VersionColorTag contains default app version color tag
	ReleaseColorTag string // ReleaseColorTag contains default app release color tag
	BuildColorTag   string // BuildColorTag contains default app build color tag

	ReleaseSeparator string // ReleaseSeparator contains symbol for version and release separation (default: -)
	DescSeparator    string // DescSeparator contains symbol for version and description separation (default: -)

	Environment Environment // Environment contains info about environment

	// Function for checking app updates
	UpdateChecker UpdateChecker
}

About contains info about app

func (*About) Print added in v12.61.0 

func (a *About) Print(infoType ...string)

Print prints version info

Example 
about := About{
	App:     "MySupperApp",
	Desc:    "My super golang utility",
	Version: "1.0.1",
	Release: "β4",
	Build:   "git:ce9d5c6", // Number of build or commit hash
	Year:    2009,          // Year when company was founded
	License: "MIT",
	Owner:   "SUPPA DUPPA LLC <opensource@suppaduppa.com>",

	Environment: Environment{
		{"Client", "1.8.1"},
		{"Server", "4.x"},
		{"Encoder", "h265/AV1"},
	},

	AppNameColorTag: "{r*}", // Use custom color for application name
	VersionColorTag: "{r}",  // Use custom color for application version
}

about.Print()
// or print raw version
about.Print(VERSION_FULL)

Output:

type Command 

type Command struct {
	Name         string   // Name is command name
	Desc         string   // Desc is command description
	Group        string   // Group is command group name
	Args         []string // Args is slice with arguments
	BoundOptions []string // BoundOptions is slice with long names of related options

	ColorTag string // ColorTag contains default color tag
	// contains filtered or unexported fields
}

Command contains info about supported command

func (*Command) Print added in v12.61.0 

func (c *Command) Print()

Print prints info about command

func (*Command) String 

func (c *Command) String() string

String returns a string representation of the command

type Environment added in v12.65.0 

type Environment []EnvironmentInfo

type EnvironmentInfo added in v12.65.0 

type EnvironmentInfo struct {
	Name    string
	Version string
}

type Example 

type Example struct {
	Cmd  string // Cmd is command usage example
	Desc string // Desc is usage description
	Raw  bool   // Raw is raw example flag (without automatic binary name appending)
	// contains filtered or unexported fields
}

Example contains usage example

func (*Example) Print added in v12.61.0 

func (e *Example) Print()

Print prints usage example

type Info 

type Info struct {
	AppNameColorTag     string // AppNameColorTag contains default app name color tag
	CommandsColorTag    string // CommandsColorTag contains default commands color tag
	OptionsColorTag     string // OptionsColorTag contains default options color tag
	ExampleDescColorTag string // ExampleDescColorTag contains default example description color tag

	Breadcrumbs bool // Breadcrumbs is flag for using bread crumbs for commands and options output

	Name    string   // Name is app name
	Args    []string // Args is slice with app arguments
	Spoiler string   // Spoiler contains additional info

	Commands []*Command // Commands is list of supported commands
	Options  []*Option  // Options is list of supported options
	Examples []*Example // Examples is list of usage examples
	// 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 customize some colors
info.AppNameColorTag = "{c}"
info.CommandsColorTag = "{y}"
info.OptionsColorTag = "{m}"

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

info.Print()

Output:

func (*Info) AddCommand 

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

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")

// Print data
info.Print()

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")

// Print data
info.Print()

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")

// Print data
info.Print()

Output:

func (*Info) AddOption 

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

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")

// Print data
info.Print()

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")

// Print data
info.Print()

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")

// Print data
info.Print()

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")

// Print data
info.Print()

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) Print added in v12.61.0 

func (i *Info) Print()

Print prints usage info

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")

// Print data
info.Print()

Output:

type Option 

type Option struct {
	Short string // Short is short option name (with one minus prefix)
	Long  string // Long is long option name (with two minuses prefix)
	Desc  string // Desc is option description
	Arg   string // Arg is option argument

	ColorTag string // ColorTag contains default color tag
	// contains filtered or unexported fields
}

Option contains info about supported option

func (*Option) Print added in v12.61.0 

func (o *Option) Print()

Print prints info about option

func (*Option) String 

func (o *Option) String() string

String returns a string representation of the option

type UpdateChecker 

type UpdateChecker struct {
	Payload   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

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.