usage

package
v12.46.0 Latest Latest
Warning

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

 Go to latest Published: May 16, 2022 License: Apache-2.0 Imports: 8 Imported by: 24

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_APP_NAME_COLOR_TAG = "{c*}"
	DEFAULT_APP_VER_COLOR_TAG  = "{c}"
)

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

	AppNameColorTag string // AppNameColorTag contains default app name color tag
	VersionColorTag string // VersionColorTag contains default app version color tag

	// 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>",

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

about.Render()

Output:

type Command 

type Command struct {
	Name         string   // Name is command name
	Desc         string   // Desc is command description
	Group        string   // Group is 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) Render 

func (c *Command) Render()

Render renders info about command

func (*Command) String 

func (c *Command) String() string

String returns a string representation of the command

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

func (e *Example) Render()

Render renders 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
	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.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 // 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) Render 

func (o *Option) Render()

Render renders 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
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.