gocmd

package module
v3.0.0+incompatible Latest Latest
Warning

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

 Go to latest Published: Feb 12, 2018 License: MIT Imports: 6 Imported by: 21

README

gocmd

Release Build Status Coverage Report GoDoc

A Go library for building command line applications.

Features

  • Advanced command line arguments handling
    • Subcommand handling
    • Short and long command line arguments
    • Multiple arguments (repeated or delimited)
    • Support for environment variables
    • Well formatted usage printing
    • Auto usage and version printing
    • Unknown argument handling
  • Output tables in the terminal
  • Template support for config files
  • No external dependency

Installation

go get github.com/devfacet/gocmd

Usage

A basic app

See basic for full code.

func main() {
	flags := struct {
		Help      bool `short:"h" long:"help" description:"Display usage" global:"true"`
		Version   bool `short:"v" long:"version" description:"Display version"`
		VersionEx bool `long:"vv" description:"Display version (extended)"`
		Echo      struct {
			Settings bool `settings:"true" allow-unknown-arg:"true"`
		} `command:"echo" description:"Print arguments"`
		Math struct {
			Sqrt struct {
				Number float64 `short:"n" long:"number" required:"true" description:"Number"`
			} `command:"sqrt" description:"Calculate square root"`
			Pow struct {
				Base     float64 `short:"b" long:"base" required:"true" description:"Base"`
				Exponent float64 `short:"e" long:"exponent" required:"true" description:"Exponent"`
			} `command:"pow" description:"Calculate base exponential"`
		} `command:"math" description:"Math functions"`
	}{}

	cmd, err := gocmd.New(gocmd.Options{
		Name:        "basic",
		Version:     "1.0.0",
		Description: "A basic app",
		Flags:       &flags,
		AutoHelp:    true,
		AutoVersion: true,
		AnyError:    true,
	})
	if err != nil {
		log.Fatal(err)
	}

	// Echo command
	if cmd.FlagArgs("Echo") != nil {
		fmt.Printf("%s\n", strings.TrimRight(strings.TrimLeft(fmt.Sprintf("%v", cmd.FlagArgs("Echo")[1:]), "["), "]"))
		return
	}

	// Math command
	if cmd.FlagArgs("Math") != nil {
		if cmd.FlagArgs("Math.Sqrt") != nil {
			fmt.Println(math.Sqrt(flags.Math.Sqrt.Number))
		} else if cmd.FlagArgs("Math.Pow") != nil {
			fmt.Println(math.Pow(flags.Math.Pow.Base, flags.Math.Pow.Exponent))
		} else {
			log.Fatal("invalid math command")
		}
		return
	}
}

cd examples/basic/
go build .

$ ./basic
Usage: basic [options...] COMMAND [options...]

A basic app

Options:
  -h, --help         	Display usage
  -v, --version      	Display version
      --vv           	Display version (extended)

Commands:
  echo               	Print arguments
  math               	Math functions
    sqrt             	Calculate square root
      -n, --number   	Number
    pow              	Calculate base exponential
      -b, --base     	Base
      -e, --exponent 	Exponent

Build

go build .

Test

./test.sh

Release

git add CHANGELOG.md # update CHANGELOG.md
./release.sh v1.0.0  # replace "v1.0.0" with new version

git ls-remote --tags # check the new tag

Contributing

  • Code contributions must be through pull requests
  • Run tests, linting and formatting before a pull request
  • Pull requests can not be merged without being reviewed
  • Use "Issues" for bug reports, feature requests and discussions
  • Do not refactor existing code without a discussion
  • Do not add a new third party dependency without a discussion
  • Use semantic versioning and git tags for versioning

License

Licensed under The MIT License (MIT)
For the full copyright and license information, please view the LICENSE.txt file.

Documentation

Overview

Package gocmd is a library for building command line applications

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Cmd 

type Cmd struct {
	// contains filtered or unexported fields
}

Cmd represents a command

func New 

func New(o Options) (*Cmd, error)

New returns a command by the given options

Example (Command) 
os.Args = []string{"gocmd.test", "math", "sqrt", "-n=9"}

flags := struct {
	Help      bool `short:"h" long:"help" description:"Display usage" global:"true"`
	Version   bool `short:"v" long:"version" description:"Display version"`
	VersionEx bool `long:"vv" description:"Display version (extended)"`
	Echo      struct {
		Settings bool `settings:"true" allow-unknown-arg:"true"`
	} `command:"echo" description:"Print arguments"`
	Math struct {
		Sqrt struct {
			Number float64 `short:"n" long:"number" required:"true" description:"Number"`
		} `command:"sqrt" description:"Calculate square root"`
		Pow struct {
			Base     float64 `short:"b" long:"base" required:"true" description:"Base"`
			Exponent float64 `short:"e" long:"exponent" required:"true" description:"Exponent"`
		} `command:"pow" description:"Calculate base exponential"`
	} `command:"math" description:"Math functions"`
}{}

cmd, err := gocmd.New(gocmd.Options{
	Name:        "basic",
	Version:     "1.0.0",
	Description: "A basic app",
	Flags:       &flags,
	AutoHelp:    true,
	AutoVersion: true,
	AnyError:    true,
})
if err != nil {
	log.Fatal(err)
}

// Echo command
if cmd.FlagArgs("Echo") != nil {
	fmt.Printf("%s\n", strings.TrimRight(strings.TrimLeft(fmt.Sprintf("%v", cmd.FlagArgs("Echo")[1:]), "["), "]"))
	return
}

// Math command
if cmd.FlagArgs("Math") != nil {
	if cmd.FlagArgs("Math.Sqrt") != nil {
		fmt.Println(math.Sqrt(flags.Math.Sqrt.Number))
	} else if cmd.FlagArgs("Math.Pow") != nil {
		fmt.Println(math.Pow(flags.Math.Pow.Base, flags.Math.Pow.Exponent))
	} else {
		log.Fatal("invalid math command")
	}
	return
}

Output:

3
Example (Usage) 
os.Args = []string{"gocmd.test"}

_, err := gocmd.New(gocmd.Options{
	Name:        "basic",
	Version:     "1.0.0",
	Description: "A basic app",
	Flags: &struct {
		Help      bool `short:"h" long:"help" description:"Display usage" global:"true"`
		Version   bool `short:"v" long:"version" description:"Display version"`
		VersionEx bool `long:"vv" description:"Display version (extended)"`
		Echo      struct {
			Settings bool `settings:"true" allow-unknown-arg:"true"`
		} `command:"echo" description:"Print arguments"`
		Math struct {
			Sqrt struct {
				Number float64 `short:"n" long:"number" required:"true" description:"Number"`
			} `command:"sqrt" description:"Calculate square root"`
			Pow struct {
				Base     float64 `short:"b" long:"base" required:"true" description:"Base"`
				Exponent float64 `short:"e" long:"exponent" required:"true" description:"Exponent"`
			} `command:"pow" description:"Calculate base exponential"`
		} `command:"math" description:"Math functions"`
	}{},
	AutoHelp:    true,
	AutoVersion: true,
	AnyError:    true,
})
if err != nil {
	log.Fatal(err)
}

Output:

Usage: basic [options...] COMMAND [options...]

A basic app

Options:
  -h, --help         	Display usage
  -v, --version      	Display version
      --vv           	Display version (extended)

Commands:
  echo               	Print arguments
  math               	Math functions
    sqrt             	Calculate square root
      -n, --number   	Number
    pow              	Calculate base exponential
      -b, --base     	Base
      -e, --exponent 	Exponent
Example (Version) 
os.Args = []string{"gocmd.test", "-vv"}

_, err := gocmd.New(gocmd.Options{
	Name:        "basic",
	Version:     "1.0.0",
	Description: "A basic app",
	Flags: &struct {
		Version   bool `short:"v" long:"version" description:"Display version"`
		VersionEx bool `long:"vv" description:"Display version (extended)"`
	}{},
	AutoVersion: true,
})
if err != nil {
	log.Fatal(err)
}

Output:

App name    : basic
App version : 1.0.0
Go version  : vTest

func (*Cmd) Description 

func (cmd *Cmd) Description() string

Description returns the description of the command

func (*Cmd) FlagArgs 

func (cmd *Cmd) FlagArgs(name string) []string

FlagArgs returns the flag arguments by the given flag name

func (*Cmd) FlagErrors 

func (cmd *Cmd) FlagErrors() []error

FlagErrors returns the list of the flag errors

func (*Cmd) FlagValue 

func (cmd *Cmd) FlagValue(name string) interface{}

FlagValue returns the flag value by the given flag name

func (*Cmd) LookupFlag 

func (cmd *Cmd) LookupFlag(name string) ([]string, bool)

LookupFlag returns the flag arguments by the given flag name

func (*Cmd) Name 

func (cmd *Cmd) Name() string

Name returns the name of the command

func (*Cmd) PrintUsage 

func (cmd *Cmd) PrintUsage()

PrintUsage prints usage

func (*Cmd) PrintVersion 

func (cmd *Cmd) PrintVersion(extra bool)

PrintVersion prints version information

Example 
cmd, err := gocmd.New(gocmd.Options{
	Version: "1.0.0",
})
if err == nil {
	cmd.PrintVersion(false)
}

Output:

1.0.0

func (*Cmd) Version 

func (cmd *Cmd) Version() string

Version returns the version of the command

type Options 

type Options struct {
	// Name is the command name
	Name string
	// Version is the command version
	Version string
	// Description is the command description
	Description string
	// Flags hold user defined command line arguments and commands
	Flags interface{}
	// AutoHelp prints the usage content
	AutoHelp bool
	// AutoVersion prints the version content
	AutoVersion bool
	// AnyError checks all the errors and returns the first one
	AnyError bool
}

Options represents the options that can be set when creating a new command

Source Files

View all Source files

Directories

Path Synopsis
examples
basic command
A basic app
 A basic app
Package flagset provides functions for handling command line arguments
 Package flagset provides functions for handling command line arguments
Package table provides functions for handling tables in terminal
 Package table provides functions for handling tables in terminal
Package template provides functions for handling templates
 Package template provides functions for handling templates

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.