clipper

package module
v0.0.24 Latest Latest
Warning

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

 Go to latest Published: Feb 7, 2023 License: MIT Imports: 11 Imported by: 3

README

clipper

A simple Go package to parse command-line arguments getopt(3) style. Designed especially for making CLI based libraries with ease. It has built-in support for sub-commands, long and short flag name combination (for example --version <==> -v), --flag=<value> syntax, inverted flag (for example --no-clean), variadic arguments for long-style flags(_for example --dir... /data1 /data2), etc.

Main advantage - state might be reset to initial state (to default values and set unchanged). So can be simple reused in embedded interactive CLI.

Based on clapper, but typed (not string for all) and has more features.

Can be simple extended for additional types (see Value interface, base on extended pflag).

Documentation

pkg.go.dev

Installation

$ go get "github.com/msaf1980/go-clipper"

Usage

// cmd.go
package main

import (
	"fmt"
	"os"

	"github.com/msaf1980/go-clipper"
)

var (
	VERSION = "0.0.1"
)

func main() {

	var (
		rootForce, rootVerbose bool
		rootDir   string
		root                   []string

		infoVerbose, infoNoClean bool
		infoVersion, infoOutput  string

		list, listDir []string
		listVerbose int
	)

	// create a new registry
	registry := clipper.NewRegistry("programm description message")

	// register the root command
	if _, ok := os.LookupEnv("NO_ROOT"); !ok {
		rootCommand, _ := registry.Register("", "root help") // root command
		// rootCommand.AddArg("output", "")                    //
		rootCommand.AddFlag("force", "f", &rootForce, "flag help")             // --force, -f | default value: "false"
		rootCommand.AddFlag("verbose", "v", &rootVerbose, "flag help")         // --verbose, -v | default value: "false"
		rootCommand.AddString("dir", "d", "/var/users", &rootDir, "flag help") // --dir <value> | default value: "/var/users"
		rootCommand.AddStringArgs(-1, &root, "args help") // root unnamed args
		rootCommand.AddVersionHelper("version", "V", registry.Description, VERSION)
	}

	// register the `info` sub-command
	infoCommand, _ := registry.Register("info", "info help")              // sub-command
	infoCommand.AddFlag("verbose", "v", &infoVerbose, "flag help")        // --verbose, -v | default value: "false"
	infoCommand.AddString("version", "V", "", &infoVersion, "flag help"). // --version, -V | default value: "false"
									SetValidValues([]string{"", "1.0.1", "2.0.0"}). // valid versions
									SetRequired(true)                               // version are required
	infoCommand.AddString("output", "o", "./", &infoOutput, "flag help") // --output, -o <value> | default value: "./"
	infoCommand.AddFlag("no-clean", "N", &infoNoClean, "flag help")      // --no-clean | default value: "true"

	listCommand, _ := registry.Register("list", "list help")                     // sub-command
	listCommand.AddStringArray("dir", "d", []string{"a"}, &listDir, "flag help") // --output, -o <value> | default value: "./"
	listCommand.AddStringArgs(-1, &list, "args help")
	listCommand.AddCounterFlag("verbose", "v", &listVerbose, "multi-flag verbose") // --verbose, -v | default value: 0

	// register the `ghost` sub-command
	ghostCommand, _ := registry.Register("ghost", "ghost help")
	ghostCommand.AddVersionHelper("version", "V", registry.Description, VERSION)

	/*----------------*/

	// parse command-line arguments
	command, err := registry.Parse(os.Args[1:])

   	// For interactive use (don't exit after help print, check helpRequested and break command execution if set)
   	// command, helpRequested, err := registry.ParseInteract(os.Args[1:], false)
   	// if !helpRequested {
   	// // execute command
   	//     ..
   	// }

	/*----------------*/

	// check for error
	if err != nil {
		fmt.Printf("error => %#v\n", err)
		return
	}

    // get executed sub-command name
	fmt.Printf("sub-command => %#v\n  Dump variables\n", command)
	c := registry.Commands[command]
	for _, name := range c.OptsOrder {
		opt := c.Opts[name]
		fmt.Printf("    %s=%q\n", name, opt.Value.String())
	}
	// get unnamed args
	if args := c.Args.String(); args != "" {
		fmt.Printf("    args=%s\n", args)
	}}
}

In the above example, we have registred a root command and an info command. The registry can parse arguments passed to the command that executed this program.

Example 1

When the root command is executed with no command-line arguments.

$ go run demo/cmd.go

sub-command => ""
  Dump variables
    force="false"
    verbose="false"
    version=""
    dir="/var/users"
    args=[]
Example 2

When the root command is executed but not registered.

$ NO_ROOT=TRUE go run demo/cmd.go

error => clipper.ErrorUnknownCommand{Name:""}
Example 3

When the root command is executed with short/long flag names as well as by changing the positions of the arguments.

$ go run demo/cmd.go userinfo -V 1.0.1 -v --force --dir ./sub/dir
$ go run demo/cmd.go -V 1.0.1 --verbose --force userinfo --dir ./sub/dir
$ go run demo/cmd.go -V 1.0.1 -v --force --dir ./sub/dir userinfo
$ go run demo/cmd.go --version 1.0.1 --verbose --force --dir ./sub/dir userinfo

sub-command => ""
  Dump variables
    force="true"
    verbose="true"
    version="1.0.1"
    dir="./sub/di"
    args=[userinfo]
Example 4

When an unregistered flag is provided in the command-line arguments.


$ go run demo/cmd.go userinfo -V 1.0.1 -v --force --d ./sub/dir
error => clipper.ErrorUnknownFlag{Name:"--d"}

$ go run demo/cmd.go userinfo -V 1.0.1 -v --force --directory ./sub/dir
error => clipper.ErrorUnknownFlag{Name:"--directory"}
Example 5

When information was intended to be a sub-command but not registered and the root command accepts arguments.

$ go run demo/cmd.go information --force

sub-command => ""
  Dump variables
    force="true"
    verbose="false"
    version=""
    dir="/var/users"
    args=[information]
Example 6

When an unnamed args (not allowed) is provided in the command-line arguments.

$ go run demo/cmd.go info student -V -v --output ./opt/dir

error => clipper.ErrorUnsupportedFlag{Name:"student"}
Example 7

When a command is executed with an inverted flag (flag that starts with --no- prefix).

$ go run demo/cmd.go info -V -v --output ./opt/dir --no-clean

sub-command => "info"
  Dump variables
    verbose="true"
    version=""
    output="./opt/dir"
    clean="false
Example 8

When the position of argument values are changed and variadic arguments are provided.

$ go run demo/cmd.go list student --dir... /data1 /data2

sub-command => "list"
  Dump variables
    dir="[/data1,/data2]"
    args=[student]
Example 9

When a sub-command is registered without any flags.

$ go run demo/cmd.go ghost -v thatisuday -V 2.0.0 teachers

error => clipper.ErrorUnknownFlag{Name:"-v"}
Example 10

When a sub-command is registered without any arguments.

$ go run demo/cmd.go ghost
$ go run demo/cmd.go ghost thatisuday extra

sub-command => "ghost
Example 11

When the root command is not registered or the root command is registered with no arguments.

$ NO_ROOT=TRUE go run demo/cmd.go information
error => clipper.ErrorUnknownCommand{Name:"information"}

$ go run cmd.go ghost
sub-command => "ghost"
Example 12

When unsupported flag format is provided.

$ go run demo/cmd.go ---version 
error => clipper.ErrorUnsupportedFlag{Name:"---version"}

$ go run demo/cmd.go ---v=1.0.0 
error => clipper.ErrorUnsupportedFlag{Name:"---v"}

$ go run demo/cmd.go -version 
error => clipper.ErrorUnsupportedFlag{Name:"-version"}

$ go run demo/cmd.go list student -d... /data1 /data2
error => clipper.ErrorUnsupportedFlag{Name:"-d..."}

Contribution

A lot of improvements can be made to this library, one of which is the support for combined short flags, like -abc. If you are willing to contribute, create a pull request and mention your bug fixes or enhancements in the comment.

Documentation

Overview

Package clipper processes the command-line arguments of getopt(3) syntax. This package provides the ability to process the root command, sub commands, command-line arguments and command-line flags.

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrTypeMismatch = errors.New("type mismatch")
	ErrIPParse      = errors.New("failed to parse IP")
	ErrIPMaskParse  = errors.New("failed to parse IP mask")
)

Functions

func CheckLen 

func CheckLen(name string, length, min, max int) error

func PrintHelp 

func PrintHelp(registry *Registry, commandName string, commandConfig *CommandConfig, printCmdName bool)

func SplitQuoted added in v0.0.7 

func SplitQuoted(s string) []string

func WrapInvalidValue 

func WrapInvalidValue(prefix string, err error) error

Types

type Arg 

type Arg interface {
	Value

	SetMaxLen(max int) Arg
	MaxLen() int
	SetMinLen(min int) Arg
	MinLen() int
	CheckLen() error
}

type CommandConfig 

type CommandConfig struct {

	// name of the sub-command ("" for the root command)
	Name string

	Help string // help message for command

	// named command-line options order (for display help)
	OptsOrder []string

	// named command-line options or boolean flags
	Opts map[string]*Opt

	// Unnamed args
	Args Arg
	// help message for command unnamed arguments
	ArgsHelp string

	Callback func() error
	// contains filtered or unexported fields
}

CommandConfig type holds the structure and values of the command-line arguments of command.

func (*CommandConfig) AddBool 

func (commandConfig *CommandConfig) AddBool(name, shortName string, value bool, b *bool, help string) *Opt

AddBool registers an bool configuration with the command. The `name` argument represents the name of the argument. The `shortName` argument represents the short alias of the argument. If an argument with given `name` is already registered, then panic registered `*Opt` object returned.

func (*CommandConfig) AddBoolArray 

func (commandConfig *CommandConfig) AddBoolArray(name, shortName string, value []bool, p *[]bool, help string) *Opt

AddBoolArray registers an int argument configuration with the command. The `name` argument represents the name of the argument. The `shortName` argument represents the short alias of the argument. If an argument with given `name` is already registered, then panic registered `*Opt` object returned.

func (*CommandConfig) AddBoolArrayFromCSV 

func (commandConfig *CommandConfig) AddBoolArrayFromCSV(name, shortName string, value string, p *[]bool, help string) *Opt

AddBoolArrayFromCSV registers an int argument configuration with the command. The `name` argument represents the name of the argument. The `shortName` argument represents the short alias of the argument. If an argument with given `name` is already registered, then panic registered `*Opt` object returned.

func (*CommandConfig) AddBoolFromString added in v0.0.15 

func (commandConfig *CommandConfig) AddBoolFromString(name, shortName string, value string, b *bool, help string) *Opt

AddBoolFromString registers an bool configuration with the command. The `name` argument represents the name of the argument. The `shortName` argument represents the short alias of the argument. If an argument with given `name` is already registered, then panic registered `*Opt` object returned.

func (*CommandConfig) AddCounterFlag added in v0.0.24 

func (commandConfig *CommandConfig) AddCounterFlag(name, shortName string, c *int, help string) *Opt

AddCounterFlag registers an counter (direct) multi-flag with the command (for cases like -vvv). The `name` argument represents the name of the argument. The `shortName` argument represents the short alias of the argument. If an argument with given `name` is already registered, then panic registered `*Opt` object returned.

func (*CommandConfig) AddDuration 

func (commandConfig *CommandConfig) AddDuration(name, shortName string, value time.Duration, p *time.Duration, help string) *Opt

AddDuration registers an duration argument configuration with the command. The `name` argument represents the name of the argument. The `shortName` argument represents the short alias of the argument. If an argument with given `name` is already registered, then panic registered `*Opt` object returned.

func (*CommandConfig) AddFlag 

func (commandConfig *CommandConfig) AddFlag(name, shortName string, b *bool, help string) *Opt

AddFlag registers an bool (direct/inverted) flag with the command. The `name` argument represents the name of the argument. If value of the `name` argument starts with `no-` prefix, then it is a inverted flag. The `shortName` argument represents the short alias of the argument. If an argument with given `name` is already registered, then panic registered `*Opt` object returned.

func (*CommandConfig) AddFloat32 

func (commandConfig *CommandConfig) AddFloat32(name, shortName string, value float32, p *float32, help string) *Opt

AddFloat32 registers an float32 argument configuration with the command. The `name` argument represents the name of the argument. The `shortName` argument represents the short alias of the argument. If an argument with given `name` is already registered, then panic registered `*Opt` object returned.

func (*CommandConfig) AddFloat64 

func (commandConfig *CommandConfig) AddFloat64(name, shortName string, value float64, p *float64, help string) *Opt

AddFloat64 registers an float64 argument configuration with the command. The `name` argument represents the name of the argument. The `shortName` argument represents the short alias of the argument. If an argument with given `name` is already registered, then panic registered `*Opt` object returned.

func (*CommandConfig) AddIP 

func (commandConfig *CommandConfig) AddIP(name, shortName string, value net.IP, p *net.IP, help string) *Opt

AddIP registers an int argument configuration with the command. The `name` argument represents the name of the argument. The `shortName` argument represents the short alias of the argument. If an argument with given `name` is already registered, then panic registered `*Opt` object returned.

func (*CommandConfig) AddIPArray 

func (commandConfig *CommandConfig) AddIPArray(name, shortName string, value []net.IP, p *[]net.IP, help string) *Opt

AddIPArray registers an int argument configuration with the command. The `name` argument represents the name of the argument. The `shortName` argument represents the short alias of the argument. If an argument with given `name` is already registered, then panic registered `*Opt` object returned.

func (*CommandConfig) AddIPArrayFromCSV 

func (commandConfig *CommandConfig) AddIPArrayFromCSV(name, shortName string, value string, p *[]net.IP, help string) *Opt

Addnet.IPArrayFromCSV registers an int argument configuration with the command. The `name` argument represents the name of the argument. The `shortName` argument represents the short alias of the argument. If an argument with given `name` is already registered, then panic registered `*Opt` object returned.

func (*CommandConfig) AddIPFromString 

func (commandConfig *CommandConfig) AddIPFromString(name, shortName string, value string, p *net.IP, help string) *Opt

AddIPFromString registers an int argument configuration with the command. The `name` argument represents the name of the argument. The `shortName` argument represents the short alias of the argument. If an argument with given `name` is already registered, then panic registered `*Opt` object returned.

func (*CommandConfig) AddInt 

func (commandConfig *CommandConfig) AddInt(name, shortName string, value int, p *int, help string) *Opt

AddInt registers an int argument configuration with the command. The `name` argument represents the name of the argument. The `shortName` argument represents the short alias of the argument. If an argument with given `name` is already registered, then panic registered `*Opt` object returned.

func (*CommandConfig) AddInt16 

func (commandConfig *CommandConfig) AddInt16(name, shortName string, value int16, p *int16, help string) *Opt

AddInt16 registers an int argument configuration with the command. The `name` argument represents the name of the argument. The `shortName` argument represents the short alias of the argument. If an argument with given `name` is already registered, then panic registered `*Opt` object returned.

func (*CommandConfig) AddInt32 

func (commandConfig *CommandConfig) AddInt32(name, shortName string, value int32, p *int32, help string) *Opt

AddInt32 registers an int argument configuration with the command. The `name` argument represents the name of the argument. The `shortName` argument represents the short alias of the argument. If an argument with given `name` is already registered, then panic registered `*Opt` object returned.

func (*CommandConfig) AddInt32Array 

func (commandConfig *CommandConfig) AddInt32Array(name, shortName string, value []int32, p *[]int32, help string) *Opt

AddInt32Array registers an int argument configuration with the command. The `name` argument represents the name of the argument. The `shortName` argument represents the short alias of the argument. If an argument with given `name` is already registered, then panic registered `*Opt` object returned.

func (*CommandConfig) AddInt32ArrayFromCSV 

func (commandConfig *CommandConfig) AddInt32ArrayFromCSV(name, shortName string, value string, p *[]int32, help string) *Opt

AddInt32ArrayFromCSV registers an int argument configuration with the command. The `name` argument represents the name of the argument. The `shortName` argument represents the short alias of the argument. If an argument with given `name` is already registered, then panic registered `*Opt` object returned.

func (*CommandConfig) AddInt64 

func (commandConfig *CommandConfig) AddInt64(name, shortName string, value int64, p *int64, help string) *Opt

AddInt64 registers an int argument configuration with the command. The `name` argument represents the name of the argument. The `shortName` argument represents the short alias of the argument. If an argument with given `name` is already registered, then panic registered `*Opt` object returned.

func (*CommandConfig) AddInt64Array added in v0.0.21 

func (commandConfig *CommandConfig) AddInt64Array(name, shortName string, value []int64, p *[]int64, help string) *Opt

AddInt64Array registers an int argument configuration with the command. The `name` argument represents the name of the argument. The `shortName` argument represents the short alias of the argument. If an argument with given `name` is already registered, then panic registered `*Opt` object returned.

func (*CommandConfig) AddInt64ArrayFromCSV added in v0.0.21 

func (commandConfig *CommandConfig) AddInt64ArrayFromCSV(name, shortName string, value string, p *[]int64, help string) *Opt

AddInt64ArrayFromCSV registers an int argument configuration with the command. The `name` argument represents the name of the argument. The `shortName` argument represents the short alias of the argument. If an argument with given `name` is already registered, then panic registered `*Opt` object returned.

func (*CommandConfig) AddInt64N added in v0.0.21 

func (commandConfig *CommandConfig) AddInt64N(name, shortName string, value int64, p *int64, help string) *Opt

AddInt64 registers an int argument configuration with the command. The `name` argument represents the name of the argument. The `shortName` argument represents the short alias of the argument. If an argument with given `name` is already registered, then panic registered `*Opt` object returned.

func (*CommandConfig) AddInt64NArray added in v0.0.21 

func (commandConfig *CommandConfig) AddInt64NArray(name, shortName string, value []int64, p *[]int64, help string) *Opt

AddInt64Array registers an int argument configuration with the command. The `name` argument represents the name of the argument. The `shortName` argument represents the short alias of the argument. If an argument with given `name` is already registered, then panic registered `*Opt` object returned.

func (*CommandConfig) AddInt64NFromString added in v0.0.21 

func (commandConfig *CommandConfig) AddInt64NFromString(name, shortName string, value string, p *int64, help string) *Opt

AddInt64N registers an int argument configuration with the command. The `name` argument represents the name of the argument. The `shortName` argument represents the short alias of the argument. The `value` argument represents initial value, with suffix of k (1e3), m (1e6), g (1e9), K (1024), M (1048576), G (1073741824) If an argument with given `name` is already registered, then panic registered `*Opt` object returned.

func (*CommandConfig) AddInt8 

func (commandConfig *CommandConfig) AddInt8(name, shortName string, value int8, p *int8, help string) *Opt

AddInt8 registers an int argument configuration with the command. The `name` argument represents the name of the argument. The `shortName` argument represents the short alias of the argument. If an argument with given `name` is already registered, then panic registered `*Opt` object returned.

func (*CommandConfig) AddInt8Array 

func (commandConfig *CommandConfig) AddInt8Array(name, shortName string, value []int8, p *[]int8, help string) *Opt

AddInt8Array registers an int argument configuration with the command. The `name` argument represents the name of the argument. The `shortName` argument represents the short alias of the argument. If an argument with given `name` is already registered, then panic registered `*Opt` object returned.

func (*CommandConfig) AddInt8ArrayFromCSV 

func (commandConfig *CommandConfig) AddInt8ArrayFromCSV(name, shortName string, value string, p *[]int8, help string) *Opt

AddInt8ArrayFromCSV registers an int argument configuration with the command. The `name` argument represents the name of the argument. The `shortName` argument represents the short alias of the argument. If an argument with given `name` is already registered, then panic registered `*Opt` object returned.

func (*CommandConfig) AddIntArray 

func (commandConfig *CommandConfig) AddIntArray(name, shortName string, value []int, p *[]int, help string) *Opt

AddIntArray registers an int argument configuration with the command. The `name` argument represents the name of the argument. The `shortName` argument represents the short alias of the argument. If an argument with given `name` is already registered, then panic registered `*Opt` object returned.

func (*CommandConfig) AddIntArrayFromCSV 

func (commandConfig *CommandConfig) AddIntArrayFromCSV(name, shortName string, value string, p *[]int, help string) *Opt

AddIntArrayFromCSV registers an int argument configuration with the command. The `name` argument represents the name of the argument. The `shortName` argument represents the short alias of the argument. If an argument with given `name` is already registered, then panic registered `*Opt` object returned.

func (*CommandConfig) AddMultiFlag 

func (commandConfig *CommandConfig) AddMultiFlag(name, shortName string, b *[]bool, help string) *Opt

AddMultiFlag registers an bool (direct/inverted) multi-flag with the command (for cases like -vvv). The `name` argument represents the name of the argument. If value of the `name` argument starts with `no-` prefix, then it is a inverted flag. The `shortName` argument represents the short alias of the argument. If an argument with given `name` is already registered, then panic registered `*Opt` object returned.

func (*CommandConfig) AddString 

func (commandConfig *CommandConfig) AddString(name, shortName string, value string, p *string, help string) *Opt

AddString registers an string argument configuration with the command. The `name` argument represents the name of the argument. The `shortName` argument represents the short alias of the argument. If an argument with given `name` is already registered, then panic registered `*Opt` object returned.

func (*CommandConfig) AddStringArgs 

func (commandConfig *CommandConfig) AddStringArgs(max int, p *[]string, help string) Arg

AddStringArgs set unnamed argument configuration with the command. The `max` argument represents maximum length of unnamed args (-1 - unlimited). `Arg` object returned.

func (*CommandConfig) AddStringArray 

func (commandConfig *CommandConfig) AddStringArray(name, shortName string, value []string, p *[]string, help string) *Opt

AddStringArray registers an string argument configuration with the command. The `name` argument represents the name of the argument. The `shortName` argument represents the short alias of the argument. If an argument with given `name` is already registered, then panic registered `*Opt` object returned.

func (*CommandConfig) AddStringArrayFromCSV 

func (commandConfig *CommandConfig) AddStringArrayFromCSV(name, shortName string, value string, p *[]string, help string) *Opt

AddStringArrayFromCSV registers an string argument configuration with the command. The `name` argument represents the name of the argument. The `shortName` argument represents the short alias of the argument. If an argument with given `name` is already registered, then panic registered `*Opt` object returned.

func (*CommandConfig) AddTime 

func (commandConfig *CommandConfig) AddTime(name, shortName string, value time.Time, p *time.Time, layout string, help string) *Opt

AddTime registers an duration argument configuration with the command. The `name` argument represents the name of the argument. The `shortName` argument represents the short alias of the argument. If an argument with given `name` is already registered, then panic registered `*Opt` object returned.

func (*CommandConfig) AddTimeFromString added in v0.0.4 

func (commandConfig *CommandConfig) AddTimeFromString(name, shortName string, value string, p *time.Time, layout string, help string) *Opt

AddTimeFromString registers an duration argument configuration with the command. The `name` argument represents the name of the argument. The `shortName` argument represents the short alias of the argument. If an argument with given `name` is already registered, then panic registered `*Opt` object returned.

func (*CommandConfig) AddUint 

func (commandConfig *CommandConfig) AddUint(name, shortName string, value uint, p *uint, help string) *Opt

AddUint registers an int argument configuration with the command. The `name` argument represents the name of the argument. The `shortName` argument represents the short alias of the argument. If an argument with given `name` is already registered, then panic registered `*Opt` object returned.

func (*CommandConfig) AddUint16 

func (commandConfig *CommandConfig) AddUint16(name, shortName string, value uint16, p *uint16, help string) *Opt

AddUint16 registers an int argument configuration with the command. The `name` argument represents the name of the argument. The `shortName` argument represents the short alias of the argument. If an argument with given `name` is already registered, then panic registered `*Opt` object returned.

func (*CommandConfig) AddUint16Array 

func (commandConfig *CommandConfig) AddUint16Array(name, shortName string, value []uint16, p *[]uint16, help string) *Opt

AddUint16Array registers an int argument configuration with the command. The `name` argument represents the name of the argument. The `shortName` argument represents the short alias of the argument. If an argument with given `name` is already registered, then panic registered `*Opt` object returned.

func (*CommandConfig) AddUint16ArrayFromCSV 

func (commandConfig *CommandConfig) AddUint16ArrayFromCSV(name, shortName string, value string, p *[]uint16, help string) *Opt

AddUint16ArrayFromCSV registers an int argument configuration with the command. The `name` argument represents the name of the argument. The `shortName` argument represents the short alias of the argument. If an argument with given `name` is already registered, then panic registered `*Opt` object returned.

func (*CommandConfig) AddUint32 

func (commandConfig *CommandConfig) AddUint32(name, shortName string, value uint32, p *uint32, help string) *Opt

AddUint32 registers an int argument configuration with the command. The `name` argument represents the name of the argument. The `shortName` argument represents the short alias of the argument. If an argument with given `name` is already registered, then panic registered `*Opt` object returned.

func (*CommandConfig) AddUint32Array 

func (commandConfig *CommandConfig) AddUint32Array(name, shortName string, value []uint32, p *[]uint32, help string) *Opt

AddUint32Array registers an int argument configuration with the command. The `name` argument represents the name of the argument. The `shortName` argument represents the short alias of the argument. If an argument with given `name` is already registered, then panic registered `*Opt` object returned.

func (*CommandConfig) AddUint32ArrayFromCSV 

func (commandConfig *CommandConfig) AddUint32ArrayFromCSV(name, shortName string, value string, p *[]uint32, help string) *Opt

AddUint32ArrayFromCSV registers an int argument configuration with the command. The `name` argument represents the name of the argument. The `shortName` argument represents the short alias of the argument. If an argument with given `name` is already registered, then panic registered `*Opt` object returned.

func (*CommandConfig) AddUint64 

func (commandConfig *CommandConfig) AddUint64(name, shortName string, value uint64, p *uint64, help string) *Opt

AddUint64 registers an int argument configuration with the command. The `name` argument represents the name of the argument. The `shortName` argument represents the short alias of the argument. If an argument with given `name` is already registered, then panic registered `*Opt` object returned.

func (*CommandConfig) AddUint64Array 

func (commandConfig *CommandConfig) AddUint64Array(name, shortName string, value []uint64, p *[]uint64, help string) *Opt

AddUint64Array registers an int argument configuration with the command. The `name` argument represents the name of the argument. The `shortName` argument represents the short alias of the argument. If an argument with given `name` is already registered, then panic registered `*Opt` object returned.

func (*CommandConfig) AddUint64ArrayFromCSV 

func (commandConfig *CommandConfig) AddUint64ArrayFromCSV(name, shortName string, value string, p *[]uint64, help string) *Opt

AddUint64ArrayFromCSV registers an int argument configuration with the command. The `name` argument represents the name of the argument. The `shortName` argument represents the short alias of the argument. If an argument with given `name` is already registered, then panic registered `*Opt` object returned.

func (*CommandConfig) AddUint64N added in v0.0.21 

func (commandConfig *CommandConfig) AddUint64N(name, shortName string, value uint64, p *uint64, help string) *Opt

AddUint64N registers an int argument configuration with the command. The `name` argument represents the name of the argument. The `shortName` argument represents the short alias of the argument. If an argument with given `name` is already registered, then panic registered `*Opt` object returned.

func (*CommandConfig) AddUint64NArray added in v0.0.21 

func (commandConfig *CommandConfig) AddUint64NArray(name, shortName string, value []uint64, p *[]uint64, help string) *Opt

AddUint64NArray registers an int argument configuration with the command. The `name` argument represents the name of the argument. The `shortName` argument represents the short alias of the argument. If an argument with given `name` is already registered, then panic registered `*Opt` object returned.

func (*CommandConfig) AddUint64NArrayFromCSV added in v0.0.21 

func (commandConfig *CommandConfig) AddUint64NArrayFromCSV(name, shortName string, value string, p *[]uint64, help string) *Opt

AddUint64ArrayFromCSV registers an int argument configuration with the command. The `name` argument represents the name of the argument. The `shortName` argument represents the short alias of the argument. If an argument with given `name` is already registered, then panic registered `*Opt` object returned.

func (*CommandConfig) AddUint64NFromString added in v0.0.21 

func (commandConfig *CommandConfig) AddUint64NFromString(name, shortName string, value string, p *uint64, help string) *Opt

AddUint64N registers an int argument configuration with the command. The `name` argument represents the name of the argument. The `shortName` argument represents the short alias of the argument. The `value` argument represents initial value, with suffix of k (1e3), m (1e6), g (1e9), K (1024), M (1048576), G (1073741824) If an argument with given `name` is already registered, then panic registered `*Opt` object returned.

func (*CommandConfig) AddUint8 

func (commandConfig *CommandConfig) AddUint8(name, shortName string, value uint8, p *uint8, help string) *Opt

AddUint8 registers an int argument configuration with the command. The `name` argument represents the name of the argument. The `shortName` argument represents the short alias of the argument. If an argument with given `name` is already registered, then panic registered `*Opt` object returned.

func (*CommandConfig) AddUint8Array 

func (commandConfig *CommandConfig) AddUint8Array(name, shortName string, value []uint8, p *[]uint8, help string) *Opt

AddUint8Array registers an int argument configuration with the command. The `name` argument represents the name of the argument. The `shortName` argument represents the short alias of the argument. If an argument with given `name` is already registered, then panic registered `*Opt` object returned.

func (*CommandConfig) AddUint8ArrayFromCSV 

func (commandConfig *CommandConfig) AddUint8ArrayFromCSV(name, shortName string, value string, p *[]uint8, help string) *Opt

AddUint8ArrayFromCSV registers an int argument configuration with the command. The `name` argument represents the name of the argument. The `shortName` argument represents the short alias of the argument. If an argument with given `name` is already registered, then panic registered `*Opt` object returned.

func (*CommandConfig) AddUintArray 

func (commandConfig *CommandConfig) AddUintArray(name, shortName string, value []uint, p *[]uint, help string) *Opt

AddintArray registers an int argument configuration with the command. The `name` argument represents the name of the argument. The `shortName` argument represents the short alias of the argument. If an argument with given `name` is already registered, then panic registered `*Opt` object returned.

func (*CommandConfig) AddUintArrayFromCSV 

func (commandConfig *CommandConfig) AddUintArrayFromCSV(name, shortName string, value string, p *[]uint, help string) *Opt

AddintArrayFromCSV registers an int argument configuration with the command. The `name` argument represents the name of the argument. The `shortName` argument represents the short alias of the argument. If an argument with given `name` is already registered, then panic registered `*Opt` object returned.

func (*CommandConfig) AddValue 

func (commandConfig *CommandConfig) AddValue(name, shortName string, v Value, isMultiValue bool, help string) *Opt

AddValue registers an argument configuration with the command. The `name` argument represents the name of the argument. The `shortName` argument represents the short alias of the argument. If an argument with given `name` is already registered, then panic registered `*Opt` object returned.

func (*CommandConfig) AddVersionHelper 

func (commandConfig *CommandConfig) AddVersionHelper(name, shortName, description, version string)

AddVersion method registers a version callback.

func (*CommandConfig) Addint16Array 

func (commandConfig *CommandConfig) Addint16Array(name, shortName string, value []int16, p *[]int16, help string) *Opt

AddInt16Array registers an int argument configuration with the command. The `name` argument represents the name of the argument. The `shortName` argument represents the short alias of the argument. If an argument with given `name` is already registered, then panic registered `*Opt` object returned.

func (*CommandConfig) Addint16ArrayFromCSV 

func (commandConfig *CommandConfig) Addint16ArrayFromCSV(name, shortName string, value string, p *[]int16, help string) *Opt

AddInt16ArrayFromCSV registers an int argument configuration with the command. The `name` argument represents the name of the argument. The `shortName` argument represents the short alias of the argument. If an argument with given `name` is already registered, then panic registered `*Opt` object returned.

func (*CommandConfig) Addint64NArrayFromCSV added in v0.0.21 

func (commandConfig *CommandConfig) Addint64NArrayFromCSV(name, shortName string, value string, p *[]int64, help string) *Opt

AddInt64ArrayFromCSV registers an int argument configuration with the command. The `name` argument represents the name of the argument. The `shortName` argument represents the short alias of the argument. If an argument with given `name` is already registered, then panic registered `*Opt` object returned.

func (*CommandConfig) DisableArgs 

func (commandConfig *CommandConfig) DisableArgs() Arg

DisableArgs disable unnamed argument configuration with the command. registered `*Opt` object returned.

func (*CommandConfig) GetFlag added in v0.0.15 

func (commandConfig *CommandConfig) GetFlag(flag string) *Opt

Reset method reset values to it's default values.

func (*CommandConfig) Reset added in v0.0.11 

func (commandConfig *CommandConfig) Reset()

Reset method reset values to it's default values.

type ErrorInvalidValue 

type ErrorInvalidValue struct {
	Prefix string
	// contains filtered or unexported fields
}

ErrorWrapped represents an wrapped error

func (ErrorInvalidValue) Error 

func (e ErrorInvalidValue) Error() string

type ErrorLengthOverflow 

type ErrorLengthOverflow struct {
	Name  string
	Cmp   string
	Value int
}

ErrorUnsupportedValue represents an error when command-line arguments contain an unsupported value.

func (ErrorLengthOverflow) Error 

func (e ErrorLengthOverflow) Error() string

type ErrorRequiredFlag 

type ErrorRequiredFlag struct {
	Name string
}

ErrorRequiredFlag represents an error when command-line arguments not contain an required flag.

func (ErrorRequiredFlag) Error 

func (e ErrorRequiredFlag) Error() string

type ErrorUnknownCommand 

type ErrorUnknownCommand struct {
	Name string
}

ErrorUnknownCommand represents an error when command-line arguments contain an unregistered command.

func (ErrorUnknownCommand) Error 

func (e ErrorUnknownCommand) Error() string

type ErrorUnknownFlag 

type ErrorUnknownFlag struct {
	Name string
}

ErrorUnknownFlag represents an error when command-line arguments contain an unregistered flag.

func (ErrorUnknownFlag) Error 

func (e ErrorUnknownFlag) Error() string

type ErrorUnsupportedFlag 

type ErrorUnsupportedFlag struct {
	Name string
}

ErrorUnsupportedFlag represents an error when command-line arguments contain an unsupported flag.

func (ErrorUnsupportedFlag) Error 

func (e ErrorUnsupportedFlag) Error() string

type ErrorUnsupportedValue 

type ErrorUnsupportedValue struct {
	Name  string
	Value string
}

ErrorUnsupportedValue represents an error when command-line arguments contain an unsupported value.

func (ErrorUnsupportedValue) Error 

func (e ErrorUnsupportedValue) Error() string

type None 

type None struct{}

None is disabled value (can't set). (The default value is represented as a string.)

func (None) CheckLen 

func (None) CheckLen() error

func (None) Get 

func (None) Get() interface{}

func (None) MaxLen 

func (None) MaxLen() int

func (None) MinLen 

func (None) MinLen() int

func (None) Reset 

func (None) Reset(interface{})

func (None) Set 

func (None) Set(v string, _ bool) error

func (None) SetMaxLen 

func (n None) SetMaxLen(_ int) Arg

func (None) SetMinLen 

func (n None) SetMinLen(_ int) Arg

func (None) String 

func (None) String() string

func (None) Type 

func (None) Type() string

type Opt 

type Opt struct {
	Name           string // long name of the flag
	ShortName      string // short name of the flag
	EnvName        string // OS environment variable name
	Help           string // help message
	CompleterValue string // help for completer value (may be format, by default value type)
	IsMultiValue   bool   // helper for completer
	IsFlag         bool   // boolean flag (direct/inverted)
	IsInverted     bool   // inverted boolean flag
	// IsVariadic   bool   // true if can take multiple values
	IsRequired  bool            // required value
	ValidValues map[string]bool // valid values

	Changed bool  // if the user set the value (or if left to default)
	Value   Value // value as set
	// contains filtered or unexported fields
}

Opt type holds the structured information about a flag.

func (*Opt) AttachEnv added in v0.0.16 

func (o *Opt) AttachEnv(envName string) *Opt

AttachEnv set OS environment name, which used for set variable before parse other args `*Opt` object returned.

func (*Opt) GetCompeterValue added in v0.0.15 

func (o *Opt) GetCompeterValue() string

GetCompeterValue return comleter value

func (*Opt) Reset 

func (o *Opt) Reset()

Reset reset opt (changed flag is cleared)

func (*Opt) Set 

func (o *Opt) Set(s string) error

Set set Use with valid backend Value (may be slice) or values can be lost/corrupted `*Opt` object returned.

func (*Opt) SetCompeterValue added in v0.0.15 

func (o *Opt) SetCompeterValue(competerValue string) *Opt

SetCompeterValue return comleter value `*Opt` object returned.

func (*Opt) SetRequired 

func (o *Opt) SetRequired(required bool) *Opt

SetRequired enable/disable required `*Opt` object returned.

func (*Opt) SetUsage 

func (o *Opt) SetUsage(usage string) *Opt

SetUsage enable/disable required `*Opt` object returned.

func (*Opt) SetValidValues 

func (o *Opt) SetValidValues(validValues []string) *Opt

SetValidValues set values for validate `*Opt` object returned.

func (*Opt) Validate 

func (o *Opt) Validate(s string) (isValid bool)

type Registry 

type Registry struct {
	Commands    map[string]*CommandConfig
	Description string // help message
}

Registry holds the configuration of the registered commands.

func NewRegistry 

func NewRegistry(description string) *Registry

NewRegistry returns new instance of the "Registry"

func (*Registry) Completer 

func (registry *Registry) Completer(line string) (c []string)

Completer return slice of completer variants with prepended initial line

func (*Registry) Parse 

func (registry *Registry) Parse(values []string) (commandName string, err error)

Parse method parses command-line arguments and returns an appropriate command name, registered in the registry. If -h or --help flag found, program will be exited with code 0. If command is not registered, it return `ErrorUnknownCommand` error. If there is an error parsing a flag, it can return an `ErrorUnknownFlag` or `ErrorUnsupportedFlag` error.

func (*Registry) ParseInteract 

func (registry *Registry) ParseInteract(values []string, dryRun bool) (commandName string, helpExit bool, err error)

ParseInteract method parses command-line arguments and returns an appropriate command name, registered in the registry. If -h or --help flag found, return helpExit with `true` value`. The `dryRun` argument set test mode (no value changed). If command is not registered, it return `ErrorUnknownCommand` error. If there is an error parsing a flag, it can return an `ErrorUnknownFlag` or `ErrorUnsupportedFlag` error.

func (*Registry) ParseOpt 

func (registry *Registry) ParseOpt(values []string, exitOnHelp bool, dryRun bool) (commandName string, helpExit bool, err error)

ParseOpt method parses command-line arguments and returns an appropriate command name, registered in the registry. The `helpExit` argument set interactive mode (if -h or --help flag found, return helpExit with `true` value`). The `dryRun` argument set test mode (no value changed). If command is not registered, it return `ErrorUnknownCommand` error. If there is an error parsing a flag, it can return an `ErrorUnknownFlag` or `ErrorUnsupportedFlag` error.

func (*Registry) Register 

func (registry *Registry) Register(name string, help string) (*CommandConfig, bool)

Register method registers a command. The "name" argument should be a simple string. If "name" is an empty string, it is considered as a root command. If a command is already registered, the registered `*CommandConfig` object is returned. If the command is already registered, second return value will be `true`.

func (*Registry) RegisterHelp added in v0.0.22 

func (registry *Registry) RegisterHelp(name string, help string, printCmdName, exitOnHelp bool)

AddHelp method register a help command callback.

func (*Registry) RegisterWithCallback added in v0.0.22 

func (registry *Registry) RegisterWithCallback(name string, help string, callback func() error) (*CommandConfig, bool)

RegisterWithCallback method registers a command. The "name" argument should be a simple string. If "name" is an empty string, it is considered as a root command. If a command is already registered, the registered `*CommandConfig` object is returned. If the command is already registered, second return value will be `true`.

func (*Registry) Reset 

func (registry *Registry) Reset()

Reset method reset all values to it's default values.

func (*Registry) ResetCommand added in v0.0.13 

func (registry *Registry) ResetCommand(commandName string)

ResetCommand method reset values in command scope to it's default values.

type Value 

type Value interface {
	String() string
	Set(s string, doAppend bool) error
	Reset(interface{})
	Type() string
	Get() interface{}
}

Value is the interface to the dynamic value stored in a flag. (The default value is represented as a string.)

Source Files

View all Source files

Directories

Path Synopsis

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.