cli

README

cli

Package cli wraps the standard flag package for a cleaner command line interface.

Installing

1. Get package:

   go get -u github.com/gowww/cli
   

2. Import it in your code:

   import "github.com/gowww/cli"
   

Usage

Henceforth, by "command" we mean "subcommand" (like the build part in go build)…

The order in which you define commands and flags is important!
When you define a main flag, it will be added to the top-level flag set but also to all commands already defined.

Obviously, each command can also define its own flags.

For the sake of clarity for the developer and ease of use for the final user, the usage pattern is simple and always the same : program [command] [flags]. No flags before command, and no commands of commands.

Example

package main

import "github.com/gowww/cli"

var (
	flagForMain    string // Flag "-m"
	flagForCommand string // Flag "-c"
	flagForAll     string // Flag "-a"
)

func main() {
	cli.SetUsageText("Command line interface example.")

	cli.String(&flagForMain, "m", "", "Example flag for main function.")

	cli.Command("command", command, "Example command.").
		String(&flagForCommand, "c", "", `Example flag for this command only.`)

	cli.String(&flagForAll, "a", "", "Example flag for main function and all commands defined previously.")

	cli.Parse()
}

func command() {
	// Do the command job.
}

Usage output

For example -help

Command line interface example.

Usage:

	example [command] [flags]

Commands:

	command  Example command.

Flags:

	-a  Example flag for main function and all commands defined previously.
	-m  Example flag for main function.

For example command -help

Example command.

Usage:

	example command [flags]

Flags:

	-a  Example flag for main function and all commands defined previously.
	-c  Example flag for this command only.

Documentation

Overview

Package cli wraps the standard flag package for a cleaner command line interface.

Example

package main

import "github.com/gowww/cli"

var (
	flagForMain    string // Flag "-m"
	flagForCommand string // Flag "-c"
	flagForAll     string // Flag "-a"
)

func main() {
	cli.SetUsageText("Command line interface example.")

	cli.String(&flagForMain, "m", "", "Example flag for main function.")

	cli.Command("command", command, "Example command.").
		String(&flagForCommand, "c", "", `Example flag for this command only.`)

	cli.String(&flagForAll, "a", "", "Example flag for main function and all commands defined previously.")

	cli.Parse()
}

func command() {
	// Do the command job.
}

Index

• func Arg(i int) string
• func Args() []string
• func Bool(p *bool, name string, value bool, usage string)
• func CleanLines(n int)
• func Duration(p *time.Duration, name string, value time.Duration, usage string)
• func Float64(p *float64, name string, value float64, usage string)
• func Int(p *int, name string, value int, usage string)
• func Int64(p *int64, name string, value int64, usage string)
• func Parse()
• func Parsed() bool
• func SetUsageSuffix(s string)
• func SetUsageText(s string)
• func String(p *string, name string, value string, usage string)
• func SubArgs() []string
• func Uint(p *uint, name string, value uint, usage string)
• func Uint64(p *uint64, name string, value uint64, usage string)
• func Usage()
• type CommandUnit
  • func Command(name string, f func(), usageText string) *CommandUnit
  • func (c *CommandUnit) Bool(p *bool, name string, value bool, usage string) *CommandUnit
  • func (c *CommandUnit) Duration(p *time.Duration, name string, value time.Duration, usage string) *CommandUnit
  • func (c *CommandUnit) Float64(p *float64, name string, value float64, usage string) *CommandUnit
  • func (c *CommandUnit) Int(p *int, name string, value int, usage string) *CommandUnit
  • func (c *CommandUnit) Int64(p *int64, name string, value int64, usage string) *CommandUnit
  • func (c *CommandUnit) SetUsageSuffix(s string) *CommandUnit
  • func (c *CommandUnit) String(p *string, name string, value string, usage string) *CommandUnit
  • func (c *CommandUnit) Uint(p *uint, name string, value uint, usage string) *CommandUnit
  • func (c *CommandUnit) Uint64(p *uint64, name string, value uint64, usage string) *CommandUnit
• type Flag
  • func (f *Flag) NameWithDefValue() string

Examples

• Package

Functions

func Arg

func Arg(i int) string

Arg returns the i'th non-flag CLI argument.

func Args

func Args() []string

Args returns the non-flag CLI arguments.

func Bool

func Bool(p *bool, name string, value bool, usage string)

Bool defines a bool flag with specified name, default value, and usage string. The argument p points to a bool variable in which to store the value of the flag.

func CleanLines

func CleanLines(n int)

CleanLines removes n lines from terminal.

func Duration

func Duration(p *time.Duration, name string, value time.Duration, usage string)

Duration defines a time.Duration flag with specified name, default value, and usage string. The argument p points to a time.Duration variable in which to store the value of the flag. The flag accepts a value acceptable to time.ParseDuration.

func Float64

func Float64(p *float64, name string, value float64, usage string)

Float64 defines a float64 flag with specified name, default value, and usage string. The argument p points to a float64 variable in which to store the value of the flag.

func Int

func Int(p *int, name string, value int, usage string)

Int defines an int flag with specified name, default value, and usage string. The argument p points to an int variable in which to store the value of the flag.

func Int64

func Int64(p *int64, name string, value int64, usage string)

Int64 defines an int64 flag with specified name, default value, and usage string. The argument p points to an int64 variable in which to store the value of the flag.

func Parse

func Parse()

Parse parses the command arguments.

func Parsed

func Parsed() bool

Parsed reports whether the command-line flags have been parsed.

func SetUsageSuffix

func SetUsageSuffix(s string)

SetUsageSuffix sets the suffix added to the the usage line. It can be used to documentate command arguments.

func SetUsageText

func SetUsageText(s string)

SetUsageText sets the CLI description for the usage help.

func String

func String(p *string, name string, value string, usage string)

String defines a string flag with specified name, default value, and usage string. The argument p points to a string variable in which to store the value of the flag.

func SubArgs

func SubArgs() []string

SubArgs returns the arguments after "--".

func Uint

func Uint(p *uint, name string, value uint, usage string)

Uint defines a uint flag with specified name, default value, and usage string. The argument p points to a uint variable in which to store the value of the flag.

func Uint64

func Uint64(p *uint64, name string, value uint64, usage string)

Uint64 defines a uint64 flag with specified name, default value, and usage string. The argument p points to a uint64 variable in which to store the value of the flag.

func Usage

func Usage()

Usage prints the CLI usage.

Types

type CommandUnit

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

A CommandUnit is a CLI command with name, usage and flags.

func Command

func Command(name string, f func(), usageText string) *CommandUnit

Command adds a new command to the CLI. f is the function that will be executed when the command is called. usageText is the command description for the usage help.

func (*CommandUnit) Bool

func (c *CommandUnit) Bool(p *bool, name string, value bool, usage string) *CommandUnit

Bool defines a bool flag with specified name, default value, and usage string. The argument p points to a bool variable in which to store the value of the flag.

func (*CommandUnit) Duration

func (c *CommandUnit) Duration(p *time.Duration, name string, value time.Duration, usage string) *CommandUnit

Duration defines a time.Duration flag with specified name, default value, and usage string. The argument p points to a time.Duration variable in which to store the value of the flag. The flag accepts a value acceptable to time.ParseDuration.

func (*CommandUnit) Float64

func (c *CommandUnit) Float64(p *float64, name string, value float64, usage string) *CommandUnit

Float64 defines a float64 flag with specified name, default value, and usage string. The argument p points to a float64 variable in which to store the value of the flag.

func (*CommandUnit) Int

func (c *CommandUnit) Int(p *int, name string, value int, usage string) *CommandUnit

Int defines an int flag with specified name, default value, and usage string. The argument p points to an int variable in which to store the value of the flag.

func (*CommandUnit) Int64

func (c *CommandUnit) Int64(p *int64, name string, value int64, usage string) *CommandUnit

Int64 defines an int64 flag with specified name, default value, and usage string. The argument p points to an int64 variable in which to store the value of the flag.

func (*CommandUnit) SetUsageSuffix

func (c *CommandUnit) SetUsageSuffix(s string) *CommandUnit

SetUsageSuffix sets the suffix added to the the usage line. It can be used to documentate command arguments.

func (*CommandUnit) String

func (c *CommandUnit) String(p *string, name string, value string, usage string) *CommandUnit

String defines a string flag with specified name, default value, and usage string. The argument p points to a string variable in which to store the value of the flag.

func (*CommandUnit) Uint

func (c *CommandUnit) Uint(p *uint, name string, value uint, usage string) *CommandUnit

Uint defines a uint flag with specified name, default value, and usage string. The argument p points to a uint variable in which to store the value of the flag.

func (*CommandUnit) Uint64

func (c *CommandUnit) Uint64(p *uint64, name string, value uint64, usage string) *CommandUnit

Uint64 defines a uint64 flag with specified name, default value, and usage string. The argument p points to a uint64 variable in which to store the value of the flag.

type Flag

type Flag struct {
	flag.Flag
}

A Flag represents the state of a flag.

func (*Flag) NameWithDefValue

func (f *Flag) NameWithDefValue() string

NameWithDefValue returns the name of the flag with its default value.