command

README

Command

Package command implements a command line interface for applications that host multiple children commands similar to go and git.

This work is based on the go tool command interface and the cobra package.

Getting started

The common pattern of that applications like go and git is:

APPNAME COMMAND --FLAG(s) ARGUMENT(s)

Each interaction with the application is implemented as a command. A command usually runs an action, or alternatively it can provide multiple children commands, or a help topic. Flags can be given to modify the command's action and arguments usually are the objects in which the actions are executed.

In package command the commands are implemented by the type Command. No constructor is required to create a new command. Just initialize the usage and documentation fields. To define the command's action implement the Run function. To define the flags used by the command implement SetFlag function and use method Flags to retrieve the current flag set of the command.

Here is an example of a command initialization:

var hello = &command.Command{
  Usage: "hello [--utf8] [--message <message>]",
  Short: "print a greeting message",
  Long: `
Command hello prints a greeting "hello, world" message.

Flags are:

  -utf8
    Show an utf message.

  --message <message>
    Use the indicated message instead of "world" message.
  `,
  Run: func(c *command.Command, args []string) error {
    if utf {
      fmt.Fprintf(c.Stdout(), "hello, 世界\n")
      return nil
    }
    fmt.Fprintf(c.Stdout(), "hello, %s\n", msg)
    return nil
  },
  SetFlags: func(c *command.Command) {
    // Define flag usage in the Long field
    c.Flags().BoolVar(&utf, "utf8", false, "")
    c.Flags().StringVar(&msg, "message", "world", "")
  },
}

To add children commands use the Add method.

To run a command with a given set of arguments, use the method Execute. This method provide flag parsing, and default help for the command.

Usually, a root command is executed using the arguments from the command line. Use the method Main:

// App is the current application
// (i.e. the root command).
var app = &command.Command{
  Usage: "myapp <command> [<argument>...]",
  Short: "a demonstration application for Command package",
}

func init() {
  // add commands
  app.Add(hello)
}

func main() {
  app.Main()
}

If a command does not have defined a Run function, and does not have any children, it is called a help topic, and is used only for documentation.

See directory examples/myapp for a demonstration application.

Package command is intentionally simple, for a very detailed package see the cobra package.

Authorship and license

Copyright © 2022 J. Salvador Arias jsalarias@gmail.com. All rights reserved. Distributed under BSD2 licenses that can be found in the LICENSE file.

This work is based on:

• Go tool source code. Available at https://cs.opensource.google/go/go. Copyright 2011 The Go Authors.
• Cobra package source code. Available at https://github.com/spf13/cobra. Copyright 2013 Steve Francia.

Documentation

Overview

Package command implements a command line interface for applications that host multiple children commands similar to go and git.

The common pattern of that applications is: APPNAME COMMAND --FLAG(s) ARGUMENT(s)

Each interaction with the application is implemented as a command. A command usually runs an action, or alternatively it can provide multiple children commands, or a help topic. Flags can be given to modify the command's action and arguments usually are the objects in which the actions are executed.

No constructor is required to create a new command. Just initialize the usage and documentation fields. To define the command's action implement the Run function. To define the flags used by the command implement SetFlag function and use method Flags to retrieve the current flag set of the command. To add children commands use the Add method.

To run a command with a given set of arguments, use the method Execute.

Index

• type Command
  • func (c *Command) Add(child *Command)
  • func (c *Command) Execute(args []string) error
  • func (c *Command) Flags() *flag.FlagSet
  • func (c *Command) Main()
  • func (c *Command) SetStderr(w io.Writer)
  • func (c *Command) SetStdin(r io.Reader)
  • func (c *Command) SetStdout(w io.Writer)
  • func (c *Command) Stderr() io.Writer
  • func (c *Command) Stdin() io.Reader
  • func (c *Command) Stdout() io.Writer
  • func (c *Command) UsageError(msg string) error

Types

type Command

type Command struct {
	// Usage is the usage message of the Command
	// including flags and arguments.
	// (do not include any parent Command).
	//
	// Recommended syntax is as follows:
	//	[]  indicates an optional flag or argument.
	//	<>  indicates a value to be set by the user,
	//	    for example <file>.
	//	... indicates that multiple values
	//	    of the previous argument can be specified.
	//
	// The first word of the usage message
	// is taken to be the Command's name.
	Usage string

	// Short is a short description
	// (on a single line)
	// of the Command.
	Short string

	// Long is a long description
	// of the Command.
	Long string

	// Run runs the Command.
	// The args are the unparsed arguments.
	Run func(c *Command, args []string) error

	// SetFlags is the function used
	// to define the flags specific to the command.
	// Use method Flags to retrieve
	// the FlagSet of the command.
	SetFlags func(c *Command)
	// contains filtered or unexported fields
}

A Command is a command in an application like 'run' in 'go run'.

When creating a Command always set up the Command's usage field. To provide help messages define a short and long description of the Command.

func (*Command) Add

func (c *Command) Add(child *Command)

Add adds a child command to a Command. This function panics if the child command is invalid:

• because it is nil
• because it does not have a name
• because there is a child command with the same name
• because the child already has a parent
• because the command is already a child of the child command

func (*Command) Execute

func (c *Command) Execute(args []string) error

Execute executes the Command with the arguments after the Command's name.

func (*Command) Flags

func (c *Command) Flags() *flag.FlagSet

Flags returns the current flag set of the Command.

func (*Command) Main

func (c *Command) Main()

Main executes a Command using the IS command line arguments. If an error happens when executing the Command, it will print the error in the programs' standard error, and finish the application.

Main will panic if the Command is not a root Command.

func (*Command) SetStderr

func (c *Command) SetStderr(w io.Writer)

SetStderr sets the Command's standard error.

func (*Command) SetStdin

func (c *Command) SetStdin(r io.Reader)

SetStdin sets the Command's standard input.

func (*Command) SetStdout

func (c *Command) SetStdout(w io.Writer)

SetStdout sets the Command's standard output.

func (*Command) Stderr

func (c *Command) Stderr() io.Writer

Stderr returns the Command's standard error. By default returns its parent stderr or os.Stderr if parent is nil.

func (*Command) Stdin

func (c *Command) Stdin() io.Reader

Stdin returns the Command's standard input. By default returns its parent stdin or os.Stdin if parent is nil.

func (*Command) Stdout

func (c *Command) Stdout() io.Writer

Stdout returns the Command's standard output. By default returns its parent stdout or os.Stdout if parent is nil.

func (*Command) UsageError

func (c *Command) UsageError(msg string) error

UsageError should be returned by Run function when an error on an argument is found.