command

README

Command

A simple package to create simple command line interfaces.

Why?

There are plenty of CLI packages in the wild. A look at https://go.libhunt.com or https://github.com/avelino/awesome-go will atest to such. Many will opt for https://github.com/spf13/cobra and rightly so. What I wanted however was a simple declarative api for creating commands and executing them rather than builder patterns or command generators. And thus command was born.

Usage

NOTE: The API is still unstable. Expect breaking changes at anytime. You have been warned.

A simple example with a command.List.

package main

import (
  "fmt"
  "os"

  "bitbucket.org/antizealot1337/command"
)

func main() {
  err := cmd.Run(os.Args[1:])

  switch err {
  case nil:
    // All good here
  case command.ErrNoArgs:
    // The user did not provide any command args
  case command.ErrNoCmd:
    // The user provided a command but it didn't match
  default:
    // A command had an error we can handle here
  }
}

var cmds = command.List{
  &command.Basic{
    Name: "greet",
    Desc: "Display a greeting",
    Run:  func(args []string) error {
      if len(args) == 0 {
        return fmt.Errorf("greet error: noone to greet")
      }

      for _, arg := range args {
        fmt.Printf("Hello, %s!\n", arg)
      }

      return nil
    },
  },
  &command.Subs{
    Name:  "enterprise",
    Short: "ent",
    Desc:  "Stuff for the enterpise to do",
    Cmds:  command.List{
      &command.Basic{
        Name: "warp",
        Desc: "Go to warp speed",
        Run:  func([]string) error {
          fmt.Println("She can't take much more cap'n")
          return nil
        },
      },
      &command.Basic{
        Name: "torpedo",
        Desc: "Fire photon torpedo",
        Run:  func([]string) error {
          fmt.Println("Target destroyed")
          return nil
        },
      },
      &command.Basic{
        Name: "hail",
        Desc: "Open a channel",
        Run:  func([]string) error {
          fmt.Println("Hailing frequencies open captain")
          return nil
        },
      },
      &command.Basic{
        Name: "scan",
        Desc: "Run scan",
        Run:  func([]string) error {
          fmt.Println("Captain, I'm picking up some unusual readings")
          return nil
        },
      },
    },
  },
}

License

Licensed under the terms of the MIT license. See LICENSE for more details.

Documentation

Index

• Variables
• type Basic
  • func (b *Basic) Execute(args []string) error
  • func (b *Basic) Matches(name string) bool
• type Command
• type List
  • func (l List) PrintCommands()
  • func (l List) Run(args []string) error
• type Subs
  • func (s *Subs) Execute(args []string) error
  • func (s *Subs) Matches(name string) bool

Variables

var (
	// ErrNoArgs is returned when a List attempts to run with no args provided.
	ErrNoArgs = errors.New("no args")

	// ErrNoCmd is returned when a List cannot find a command to run.
	ErrNoCmd = errors.New("command not found")
)

var ErrExeFail = errors.New("failed to execute command (no Run)")

ErrExeFail is an error returned from Execute when Command cannot run du to an symantic error (usually a missing func for a struct).

Types

type Basic

type Basic struct {
	Name  string
	Short string
	Desc  string
	Run   func(args []string) error

} //struct

Basic is a basic Command.

func (*Basic) Execute

func (b *Basic) Execute(args []string) error

Execute the Basic Command with the provided args.

func (*Basic) Matches

func (b *Basic) Matches(name string) bool

Matches checks to see if the Basic Command matches the given name.

type Command

type Command interface {
	Matches(name string) bool
	Execute(args []string) error

} //interface

Command represents a command provided at the command line (i.e. programname command).

type List

type List []Command

List is a collection of Commands.

func (List) PrintCommands

func (l List) PrintCommands()

PrintCommands prints the Commands.

func (List) Run

func (l List) Run(args []string) error

Run iterates through the List of Commands checking if one is to be run.

type Subs

type Subs struct {
	Name  string
	Short string
	Desc  string
	Cmds  List

} //struct

Subs is a command with sub commands. It takes no action by itself. It only tries to executes one of the Cmds.

func (*Subs) Execute

func (s *Subs) Execute(args []string) error

Execute the Basic Command with the provided args.

func (*Subs) Matches

func (s *Subs) Matches(name string) bool

Matches checks to see if the Subs Command matches the given name.