cli

README

cli

A simple library for writing applications with a command line interface.

import mellium.im/cli

License

The package may be used under the terms of the BSD 2-Clause License a copy of which may be found in the file LICENSE.md.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you shall be licensed as above, without any additional terms or conditions.

Documentation

Overview

Package cli can be used to create modern command line interfaces.

User interfaces created with Command and CommandSet take the form of the application name followed by the subcommand which may do its own parsing on all arguments after it. For instance, if recreating the "git" command it might have a subcommand called "commit" and each could have their own flags:

git -config mygit.config commit -interactive

See the examples for the definition of this command.

Example

package main

import (
	"flag"
	"fmt"
	"os"

	"mellium.im/cli"
)

func commitCmd(cfg *string) *cli.Command {
	commitFlags := flag.NewFlagSet("commit", flag.ExitOnError)
	commitFlags.SetOutput(os.Stdout)
	help := commitFlags.Bool("h", false, "Print this commands help output…")
	interactive := commitFlags.Bool("interactive", false, "Run commit in interactive mode.")
	if cfg == nil {
		empty := ""
		cfg = &empty
	}

	return &cli.Command{
		Usage: `commit [-h] [-interactive] …`,
		Description: `Records changes to the repository.

Stores the current contents of the index in a new commit…`,
		Flags: commitFlags,
		Run: func(c *cli.Command, args ...string) error {
			_ = commitFlags.Parse(args)

			fmt.Printf("Using config file: %s\n", *cfg)
			if *interactive {
				fmt.Println("Interactive mode enabled.")
			}
			if *help {
				c.Help()
			}
			return nil
		},
	}
}

func main() {
	globalFlags := flag.NewFlagSet("git", flag.ExitOnError)
	cfg := globalFlags.String("config", "gitconfig", "A custom config file to load")

	cmds := &cli.Command{
		Usage: "git",
		Flags: globalFlags,
		Commands: []*cli.Command{
			commitCmd(cfg),
		},
	}

	// In a real main function, this would probably be os.Args[1:]
	cmds.Exec("-config", "mygit.config", "commit", "-interactive", "-h")

}

Output:

Using config file: mygit.config
Interactive mode enabled.
Usage: commit [-h] [-interactive] …

Options:

  -h	Print this commands help output…
  -interactive
    	Run commit in interactive mode.

Records changes to the repository.

Stores the current contents of the index in a new commit…

Example (Articles)

package main

import (
	"fmt"

	"mellium.im/cli"
)

// Returns a help article about the config file format.
func articleHelp() *cli.Command {
	return &cli.Command{
		Usage: `article`,
		Description: `Help article about help articles.

Help articles are "commands" that do not provide any functionality. They
only exist so that their description can be shown using the help command
(or your own help system):

    $ ./yourcmd help articlename`,
	}
}

func main() {
	cmds := &cli.Command{
		Usage: "git <command>",
		Commands: []*cli.Command{
			commitCmd(nil),
			articleHelp(),
		},
	}
	cmds.Commands = append(cmds.Commands, cli.Help(cmds))
	fmt.Println("$ git help")
	cmds.Exec("help")

	fmt.Print("$ git help article\n\n")
	cmds.Exec("help", "article")

}

Output:

$ git help
Usage: git <command>

Commands:

	commit	Records changes to the repository.
	help	Print articles and detailed information about subcommands.

Articles:

	article	Help article about help articles.
$ git help article

Help article about help articles.

Help articles are "commands" that do not provide any functionality. They
only exist so that their description can be shown using the help command
(or your own help system):

    $ ./yourcmd help articlename

Example (Subcommands)

package main

import (
	"fmt"

	"mellium.im/cli"
)

func main() {
	cmds := &cli.Command{
		Usage: "go <command>",
		Run: func(c *cli.Command, args ...string) error {
			fmt.Println("Ran go")
			return nil
		},
		Commands: []*cli.Command{{
			Usage: `mod <command> [arguments]`,
			Description: `Go mod provides access to operations on modules.

Note that support for modules is built into all the go commands…`,
			Run: func(c *cli.Command, args ...string) error {
				fmt.Println("Ran go mod")
				return nil
			},
			Commands: []*cli.Command{{
				Usage: `tidy [-v]`,
				Description: `Add missing and remove unused modules.

Tidy makes sure go.mod matches the source code in the module…`,
				Run: func(c *cli.Command, args ...string) error {
					fmt.Println("Ran go mod tidy")
					return nil
				},
			}},
		}},
	}
	cmds.Commands = append(cmds.Commands, cli.Help(cmds))
	fmt.Println("$ go help")
	cmds.Exec("help")

	fmt.Print("$ go help mod\n\n")
	cmds.Exec("help", "mod")

	fmt.Print("$ go help mod tidy\n\n")
	cmds.Exec("help", "mod", "tidy")

	fmt.Print("$ go\n\n")
	cmds.Exec()

	fmt.Print("$ go mod\n\n")
	cmds.Exec("mod")

	fmt.Print("$ go mod tidy\n\n")
	cmds.Exec("mod", "tidy")

}

Output:

$ go help
Usage: go <command>

Commands:

	mod	Go mod provides access to operations on modules.
	help	Print articles and detailed information about subcommands.
$ go help mod

Usage: mod <command> [arguments]

Go mod provides access to operations on modules.

Note that support for modules is built into all the go commands…
Commands:

	tidy	Add missing and remove unused modules.
$ go help mod tidy

Usage: tidy [-v]

Add missing and remove unused modules.

Tidy makes sure go.mod matches the source code in the module…
$ go

Ran go
$ go mod

Ran go mod
$ go mod tidy

Ran go mod tidy

Index

• Variables
• type Command
  • func Help(cs *Command) *Command
  • func (c *Command) Exec(args ...string) error
  • func (c *Command) Help()
  • func (c *Command) Name() string
  • func (c *Command) ShortDesc() string

Examples

• Package
• Package (Articles)
• Package (Subcommands)
• Help

Variables

var (
	ErrInvalidCmd = errors.New("cli: no such command")
	ErrNoRun      = errors.New("cli: no run function was specified for the command")
)

Types

type Command

type Command struct {
	// Usage always starts with the name of the command, followed by a description
	// of its usage. For more information, see the Name method.
	Usage string

	// Description starts with a short, one line description. It can optionally be
	// followed by a blank line and then a longer description or help info.
	Description string

	// Flags is a flag set that provides options that are specific to this
	// subcommand.
	Flags *flag.FlagSet

	// Commands is a set of subcommands.
	Commands []*Command

	// The action to take when this command is executed. The args will be the
	// remaining command line args after all flags have been parsed.
	// Run is normally called by a CommandSet and shouldn't be called directly.
	Run func(c *Command, args ...string) error
}

Command represents a new subcommand.

func Help

func Help(cs *Command) *Command

Help returns a Command that prints help information about its command set to the command's Help output, or information about a specific command if one is provided as an argument.

For example, in a program called "git" running:

git help commit

would print information about the "commit" subcommand.

Example

cmds := &cli.Command{
	Usage: "git [options] command",
}
cmds.Commands = []*cli.Command{
	commitCmd(nil),
	cli.Help(cmds),
}
cmds.Exec("help")

Output:

Usage: git [options] command

Commands:

	commit	Records changes to the repository.
	help	Print articles and detailed information about subcommands.

func (*Command) Exec

func (c *Command) Exec(args ...string) error

Exec attempts to run the command that matches the first argument passed in (or the current command if the command has no name but does have a Run function). It parses unparsed flags for each subcommand it encounters. If no command matches, ErrInvalidCmd is returned. If a command matches and there are flags, but no run function has been provided, ErrNoRun is returned.

func (*Command) Help

func (c *Command) Help()

Help writes the usage line, flags, and description for the command to the flag set's output or to stdout if Flags is nil.

func (*Command) Name

func (c *Command) Name() string

Name returns the first word of c.Usage which will be the name of the command. For example with a usage line of:

commit [options]

Name returns "commit".

func (*Command) ShortDesc

func (c *Command) ShortDesc() string

ShortDesc returns the first line of c.Description. For example, given the description:

Stores the current contents of the index.

The content to be added can be specified in several ways: …

ShortDescr returns "Stores the current contents of the index."